Reference / API reference / dorothy / dorothy.data / dorothy.data.normalizer

dorothy.data.normalizer¶

Median/IQR label normalization for stellar parameters.

Labels are normalized to zero median and unit IQR (interquartile range). The parameter named teff is normalized in log10 space. Error columns are scaled by the same IQR as their labels.

Classes

`LabelNormalizer`([parameters, stats, is_fitted])	Normalizer for stellar parameter labels using median/IQR scaling.
`ParameterStats`(name, median, iqr[, use_log, ...])	Statistics for a single stellar parameter.

class dorothy.data.normalizer.ParameterStats(name, median, iqr, use_log=False, log_median=None, log_iqr=None)[source]¶

Bases: object

Statistics for a single stellar parameter.

name¶: Parameter name (e.g., “teff”, “logg”, “fe_h”).

median¶: Median value for normalization.

iqr¶: Interquartile range (75th - 25th percentile).

use_log¶: Whether to apply log10 before normalization (for Teff).

log_median¶: Median of log10 values (only if use_log=True).

log_iqr¶: IQR of log10 values (only if use_log=True).

Raises:: ValueError – If use_log is set without log_median and log_iqr.

class dorothy.data.normalizer.LabelNormalizer(parameters=<factory>, stats=<factory>, is_fitted=False)[source]¶

Bases: object

Normalizer for stellar parameter labels using median/IQR scaling.

The normalization is

normalized = (value - median) / IQR

and for the parameter named teff

normalized = (log10(value) - log_median) / log_IQR.

Errors scale by the same IQR; the error of teff is first propagated to log10 space, sigma / (value ln 10).

parameters¶: List of parameter names to normalize.

stats¶: Dictionary mapping parameter names to their statistics.

is_fitted¶: Whether the normalizer has been fitted to data.

Raises:: ValueError – If parameters is empty.

Examples

>>> normalizer = LabelNormalizer()
>>> normalizer.fit(y_train)
>>> y_train_norm = normalizer.transform(y_train)
>>> y_pred_denorm = normalizer.inverse_transform(y_pred)

property n_parameters: int¶: Number of parameters being normalized.

fit(y, errors=None, mask=None)[source]¶

Fit the normalizer on training labels.

Computes median and IQR for each parameter. For the parameter named teff, also computes them in log10 space. A parameter with no unmasked value gets median 0 and IQR 1, with a warning.

Parameters:

y (ndarray) – Labels array of shape (n_samples, n_parameters).
errors (ndarray | None) – Optional error array of shape (n_samples, n_parameters). Only its shape is checked.
mask (ndarray | None) – Optional mask array of shape (n_samples, n_parameters). Labels are valid where > 0. Statistics use only valid values of each parameter.

Returns:

self, for method chaining.

Raises:

ValueError – If y is not 2-D with one column per parameter, errors or mask differ in shape from y, a valid value is NaN or infinite, a valid teff is not positive, or an IQR is zero.

Return type:

LabelNormalizer

transform(y, errors=None, mask=None)[source]¶

Normalize labels (and optionally errors).

Parameters:

y (ndarray) – Labels array of shape (n_samples, n_parameters).
errors (ndarray | None) – Optional error array of shape (n_samples, n_parameters).
mask (ndarray | None) – Optional mask array of shape (n_samples, n_parameters). Only its shape is checked; masked positions are normalized like the rest.

Returns:

If errors is None – float64 normalized labels of shape (n_samples, n_parameters). Otherwise a tuple of (normalized labels, normalized errors).

Raises:

RuntimeError – If normalizer has not been fitted.
ValueError – If y is not 2-D with one column per parameter, or errors or mask differ in shape from y.

Return type:

ndarray | tuple[ndarray, ndarray]

transform_labels(y)[source]¶

Normalize a 3-channel label array, leaving masked entries harmless.

Masked entries (mask <= 0) are replaced by the parameter’s training median (error 0) before transforming, so e.g. a masked Teff stored as 0 cannot become log10(0) = -inf. The mask channel is unchanged.

Parameters:

y (ndarray) – Labels of shape (n_samples, 3, n_params) = [values, errors, mask].

Returns:

Normalized labels, same shape, float32.

Raises:

RuntimeError – If normalizer has not been fitted.
ValueError – If y is not of shape (n_samples, 3, n_params).

Return type:

ndarray

inverse_transform(y_norm, errors_norm=None)[source]¶

Convert normalized predictions back to physical units.

Errors of teff convert as sigma = value * ln 10 * sigma_log10.

Parameters:

y_norm (ndarray) – Normalized predictions of shape (n_samples, n_parameters).
errors_norm (ndarray | None) – Optional normalized errors, same shape as y_norm.

Returns:

If errors_norm is None – float64 values of shape (n_samples, n_parameters). Otherwise a tuple of (values, errors).

Raises:

RuntimeError – If normalizer has not been fitted.
ValueError – If y_norm is not 2-D with one column per parameter.

Return type:

ndarray | tuple[ndarray, ndarray]

get_params_dict()[source]¶

Get normalization parameters as a dictionary.

Returns:: Parameter name -> dict with median and IQR, plus log_median and log_IQR for a log parameter. This is the format save() writes.
Raises:: RuntimeError – If normalizer has not been fitted.
Return type:: dict[str, dict[str, Any]]

save(path)[source]¶

Save normalizer parameters to a pickle file.

Parameters:: path (str | Path) – Path to save the pickle file.
Raises:: RuntimeError – If normalizer has not been fitted.

classmethod load(path, parameters=None)[source]¶

Load normalizer from a pickle file written by save().

Parameters:

path (str | Path) – Path to the pickle file. Only load files you trust.
parameters (list[str] | None) – Optional list of parameter names. If not provided, uses the parameters found in the saved file.

Returns:

Fitted LabelNormalizer instance.

Raises:

ValueError – If a requested parameter is not in the file.

Return type:

LabelNormalizer