swiftemulator.comparison.penalty module

Penalty functions and their specifications.

class swiftemulator.comparison.penalty.PenaltyCalculator[source]

Bases: object

Base class for the penalty functions.

Extend this with your own, following the following pattern:

  1. Configuration parameters for the penalty function are taken as initialisation parameters to the class.

  2. The observational data set to be matched to is passed to register_observation.

  3. The penalty function is calculated using the penalty() method, taking the exact arguments that are taken here, for an individual model.

Provided for convenience is penalties() which calculates the penalty function for all data in a ModelValues container.

observation: ObservationalData
interpolator_values: interp1d
interpolator_error: Optional[interp1d]
log_independent: bool
log_dependent: bool
independent_units: unyt_quantity
dependent_units: unyt_quantity
register_observation(observation: ObservationalData, log_independent: bool, log_dependent: bool, independent_units: unyt_quantity, dependent_units: unyt_quantity) → None[source]

Registers the observation for use in penalty with the class.

Parameters:

  • observation (ObservationalData) – Instance of the velociraptor observational data used for comparisons.

  • log_independent (bool) – Take the base-10 log of the independent data before comparison?

  • log_dependent (bool) – Take the base-10 log of the dependent data before comparison?

  • independent_units (unyt.unyt_quantity) – The units that the model was calculated in (independent)

  • dependent_units (unyt.unyt_quantity) – The units that the model was calculated in (dependent)

observation_interpolation()[source]

Produces the interpolation for the internal observation.

penalty(independent: array, dependent: array, dependent_error: Optional[array] = None) → List[float][source]

Calculate the penalty function, relative to the observational data, for this model. It is highly recommended that you evaluate the model at the same independent variables as the observational data. The observational data is linearly interpolated to find a prediction at the independent variables that you provide.

independent: np.array

The independent data.

dependent: np.array

The dependent data for comparison.

dependent_error: np.array, optional

The dependent errors, for comparison.

Returns:

The penalties for this model, between 0 and 1 each.

Return type:

penalty, List[float]

penalties(model: ModelValues, collate_with: Callable) → Dict[Hashable, float][source]

Calculate the penalty function for all models in the model values container.

It is highly recommended that you evaluate the model at the same independent variables as the observational data. The observational data is linearly interpolated to find a prediction at the independent variables that you provide.

Parameters:

  • model (ModelValues) – The set of model (values) to calculate the penalty function for.

  • collate_with (Callable) – A function that takes a numpy array and returns the ‘global’ penalty for a model given the input for all of the valid points in the array. Examples could be np.max, np.mean, np.median.

Returns:

penalties – Penalty functions for each of the models, with the key being the unique identifier.

Return type:

Dict[Hashable, float]

plot_penalty(low_independent: Union[unyt_quantity, float], high_independent: Union[unyt_quantity, float], low_dependent: Union[unyt_quantity, float], high_dependent: Union[unyt_quantity, float], filename: str, x_label: Optional[str] = None, y_label: Optional[str] = None, resolution: int = 128, marker: Optional[str] = None)[source]

Create a figure of the penalty function, over the limits given. Limits are given in log space if logged, linear space if not (with units required in that case).

class swiftemulator.comparison.penalty.L1PenaltyCalculator(offset: Union[unyt_quantity, float], lower: Union[unyt_quantity, float], upper: Union[unyt_quantity, float])[source]

Bases: PenaltyCalculator

Penalty calculator for an L1-type norm, i.e. a linear penalty function away from the data. This penalty function is capped after a (vertical) distance, provided with units if the provided observation is used in linear space, or provided as a logarithmic offset in dex if in log space.

Parameters:

  • offset (Union[unyt.unyt_quantity, float]) – The vertical offset at which to set the L1 norm to the maximum. This is required as the penalty function is not allowed to be unlimited.

  • lower (Union[unyt.unyt_quantity, float]) – The lowest independent value to calculate the model offset at.

  • upper (Union[unyt.unyt_quantity, float]) – The highest independent value to calculate the model offset at.

offset: Union[unyt_quantity, float]
lower: Union[unyt_quantity, float]
upper: Union[unyt_quantity, float]
observation_interpolation()[source]

Produces the interpolation for the internal observation.

penalty(independent: array, dependent: array, dependent_error: Optional[array] = None) → float[source]

Calculate the penalty function, relative to the observational data, for this model. It is highly recommended that you evaluate the model at the same independent variables as the observational data. The observational data is linearly interpolated to find a prediction at the independent variables that you provide.

independent: np.array

The independent data.

dependent: np.array

The dependent data for comparison.

dependent_error: np.array, optional

The dependent errors, for comparison.

Returns:

The penalties for this model, between 0 and 1 each.

Return type:

penalty, List[float]

class swiftemulator.comparison.penalty.L1PenaltyCalculatorOneSided(offset: Union[unyt_quantity, float], maximum_penalty: str, lower: Union[unyt_quantity, float], upper: Union[unyt_quantity, float])[source]

Bases: PenaltyCalculator

Penalty calculator for an L1-type norm, i.e. a linear penalty function away from the data, but one-sided only. Values above/below the line are given a maximal penalty.

This penalty function is capped after a (vertical) distance, provided with units if the provided observation is used in linear space, or provided as a logarithmic offset in dex if in log space.

Parameters:

  • offset (Union[unyt.unyt_quantity, float]) – The vertical offset at which to set the L1 norm to the maximum. This is required as the penalty function is not allowed to be unlimited.

  • maximum_penalty (str) – Give the maximum penalty above or below the line. Accepted values are “above” or “below” as strings.

  • lower (Union[unyt.unyt_quantity, float]) – The lowest independent value to calculate the model offset at.

  • upper (Union[unyt.unyt_quantity, float]) – The highest independent value to calculate the model offset at.

offset: Union[unyt_quantity, float]
maximum_penalty: str
lower: Union[unyt_quantity, float]
upper: Union[unyt_quantity, float]
observation_interpolation()[source]

Produces the interpolation for the internal observation.

penalty(independent: array, dependent: array, dependent_error: Optional[array] = None) → float[source]

Calculate the penalty function, relative to the observational data, for this model. It is highly recommended that you evaluate the model at the same independent variables as the observational data. The observational data is linearly interpolated to find a prediction at the independent variables that you provide.

independent: np.array

The independent data.

dependent: np.array

The dependent data for comparison.

dependent_error: np.array, optional

The dependent errors, for comparison.

Returns:

The penalties for this model, between 0 and 1 each.

Return type:

penalty, List[float]

class swiftemulator.comparison.penalty.L2PenaltyCalculator(offset: Union[unyt_quantity, float], lower: Union[unyt_quantity, float], upper: Union[unyt_quantity, float])[source]

Bases: PenaltyCalculator

Penalty calculator for an L2-type norm, i.e. a square penalty function away from the data. This penalty function is capped after a (vertical) distance, provided with units if the provided observation is used in linear space, or provided as a logarithmic offset in dex if in log space.

Parameters:

  • offset (Union[unyt.unyt_quantity, float]) – The vertical offset at which to set the L1 norm to the maximum. This is required as the penalty function is not allowed to be unlimited.

  • lower (Union[unyt.unyt_quantity, float]) – The lowest independent value to calculate the model offset at.

  • upper (Union[unyt.unyt_quantity, float]) – The highest independent value to calculate the model offset at.

offset: Union[unyt_quantity, float]
lower: Union[unyt_quantity, float]
upper: Union[unyt_quantity, float]
observation_interpolation()[source]

Produces the interpolation for the internal observation.

penalty(independent: array, dependent: array, dependent_error: Optional[array] = None) → float[source]

Calculate the penalty function, relative to the observational data, for this model. It is highly recommended that you evaluate the model at the same independent variables as the observational data. The observational data is linearly interpolated to find a prediction at the independent variables that you provide.

independent: np.array

The independent data.

dependent: np.array

The dependent data for comparison.

dependent_error: np.array, optional

The dependent errors, for comparison.

Returns:

The penalties for this model, between 0 and 1 each.

Return type:

penalty, List[float]

class swiftemulator.comparison.penalty.L1VariablePenaltyCalculator(offset_lower: Union[unyt_quantity, float], offset_upper: Union[unyt_quantity, float], offset_transition: Union[unyt_quantity, float], transition_width: Union[unyt_quantity, float], lower: Union[unyt_quantity, float], upper: Union[unyt_quantity, float], offset_below_above_ratio: float = 1.0)[source]

Bases: PenaltyCalculator

Penalty calculator for an L1-type norm, i.e. a linear penalty function away from the data. This penalty function is capped after a (vertical) distance, provided with units if the provided observation is used in linear space, or provided as a logarithmic offset in dex if in log space.

In this version the offset is variable, using a logistic curve.

Parameters:

  • offset_lower (Union[unyt.unyt_quantity, float]) – The vertical offset at which to set the L1 norm to the maximum, at the lower end of the independent range.

  • offset_upper (Union[unyt.unyt_quantity, float]) – The vertical offset at which to set the L1 norm to the maximum, at the upper end of the independent range.

  • offset_transition (Union[unyt.unyt_quantity, float]) – The independent variable at which you would like the offset to transition from offset_lower to offset_upper.

  • transition_width (Union[unyt.unyt_quantity, float]) – The width of the transition between offsets, centered around offset_transition.

  • lower (Union[unyt.unyt_quantity, float]) – The lowest independent value to calculate the model offset at.

  • upper (Union[unyt.unyt_quantity, float]) – The highest independent value to calculate the model offset at.

  • offset_below_above_ratio (float, optional) – Ratio of the allowed offset below or above the data. If this takes a value of less than 1.0, models below the data are penalised more (by that factor) than models above. Default: 1.0

offset_lower: Union[unyt_quantity, float]
offset_upper: Union[unyt_quantity, float]
offset_transition: Union[unyt_quantity, float]
transition_width: Union[unyt_quantity, float]
lower: Union[unyt_quantity, float]
upper: Union[unyt_quantity, float]
offset_below_above_ratio: float
observation_interpolation()[source]

Produces the interpolation for the internal observation.

penalty(independent: array, dependent: array, dependent_error: Optional[array] = None) → float[source]

Calculate the penalty function, relative to the observational data, for this model. It is highly recommended that you evaluate the model at the same independent variables as the observational data. The observational data is linearly interpolated to find a prediction at the independent variables that you provide.

independent: np.array

The independent data.

dependent: np.array

The dependent data for comparison.

dependent_error: np.array, optional

The dependent errors, for comparison.

Returns:

The penalties for this model, between 0 and 1 each.

Return type:

penalty, List[float]

class swiftemulator.comparison.penalty.L1SqueezePenaltyCalculator(offset_squeeze: Union[unyt_quantity, float], offset_normal: Union[unyt_quantity, float], offset_transition: Union[unyt_quantity, float], transition_width: Union[unyt_quantity, float], lower: Union[unyt_quantity, float], upper: Union[unyt_quantity, float], offset_below_above_ratio: float = 1.0)[source]

Bases: PenaltyCalculator

Penalty calculator for an L1-type norm, i.e. a linear penalty function away from the data. This penalty function is capped after a (vertical) distance, provided with units if the provided observation is used in linear space, or provided as a logarithmic offset in dex if in log space.

In this version the offset is variable, with it being ‘squeezed’ at a point over a width.

Parameters:

  • offset_squeeze (Union[unyt.unyt_quantity, float]) – The vertical offset at which to set the L1 norm to the maximum at the pinch point.

  • offset_normal (Union[unyt.unyt_quantity, float]) – The usual vertical offset at which to set the L1 norm to the maximum.

  • offset_transition (Union[unyt.unyt_quantity, float]) – The independent variable at which you would like the offset to transition from offset_lower to offset_upper.

  • transition_width (Union[unyt.unyt_quantity, float]) – The width of the transition between offsets, centered around offset_transition.

  • lower (Union[unyt.unyt_quantity, float]) – The lowest independent value to calculate the model offset at.

  • upper (Union[unyt.unyt_quantity, float]) – The highest independent value to calculate the model offset at.

  • offset_below_above_ratio (float, optional) – Ratio of the allowed offset below or above the data. If this takes a value of less than 1.0, models below the data are penalised more (by that factor) than models above. Default: 1.0

offset_squeeze: Union[unyt_quantity, float]
offset_normal: Union[unyt_quantity, float]
offset_transition: Union[unyt_quantity, float]
transition_width: Union[unyt_quantity, float]
lower: Union[unyt_quantity, float]
upper: Union[unyt_quantity, float]
offset_below_above_ratio: float
observation_interpolation()[source]

Produces the interpolation for the internal observation.

penalty(independent: array, dependent: array, dependent_error: Optional[array] = None) → float[source]

Calculate the penalty function, relative to the observational data, for this model. It is highly recommended that you evaluate the model at the same independent variables as the observational data. The observational data is linearly interpolated to find a prediction at the independent variables that you provide.

independent: np.array

The independent data.

dependent: np.array

The dependent data for comparison.

dependent_error: np.array, optional

The dependent errors, for comparison.

Returns:

The penalties for this model, between 0 and 1 each.

Return type:

penalty, List[float]

class swiftemulator.comparison.penalty.GaussianDataErrorsPenaltyCalculator(sigma_max: Union[unyt_quantity, float], lower: Union[unyt_quantity, float], upper: Union[unyt_quantity, float])[source]

Bases: PenaltyCalculator

Penalty calculator for observations that include errors. This penalty function uses a Gaussian distribution around the data, based on the observational errors. Capped at a input number of sigmas away from the data.

Parameters:

  • sigma_max (Union[unyt.unyt_quantity, float]) – The number of sigmas at which the function is capped.

  • lower (Union[unyt.unyt_quantity, float]) – The lowest independent value to calculate the model offset at.

  • upper (Union[unyt.unyt_quantity, float]) – The highest independent value to calculate the model offset at.

sigma_max: Union[unyt_quantity, float]
lower: Union[unyt_quantity, float]
upper: Union[unyt_quantity, float]
error_interpolator_values: interp1d
observation_interpolation()[source]

Produces the interpolation for the internal observation.

penalty(independent: array, dependent: array, dependent_error: Optional[array] = None) → List[float][source]

Calculate the penalty function, relative to the observational data, for this model. It is highly recommended that you evaluate the model at the same independent variables as the observational data. The observational data is linearly interpolated to find a prediction at the independent variables that you provide.

independent: np.array

The independent data.

dependent: np.array

The dependent data for comparison.

dependent_error: np.array, optional

The dependent errors, for comparison.

Returns:

The penalties for this model, between 0 and 1 each.

Return type:

penalty, List[float]

class swiftemulator.comparison.penalty.GaussianPercentErrorsPenaltyCalculator(percent_error: float, sigma_max: float, lower: Union[unyt_quantity, float], upper: Union[unyt_quantity, float])[source]

Bases: PenaltyCalculator

Penalty calculator that that uses Gaussian errors with widths based on the percentages difference between the model and the data.

Parameters:

  • percent_error (float) – percent error that sets the one-sigma deviation, in units of percent (0-100).

  • sigma_max (float) – The number of sigmas at which the function is capped.

  • lower (Union[unyt.unyt_quantity, float]) – The lowest independent value to calculate the model offset at.

  • upper (Union[unyt.unyt_quantity, float]) – The highest independent value to calculate the model offset at.

percent_error: float
sigma_max: float
lower: Union[unyt_quantity, float]
upper: Union[unyt_quantity, float]
observation_interpolation()[source]

Produces the interpolation for the internal observation.

penalty(independent: array, dependent: array, dependent_error: Optional[array] = None) → List[float][source]

Calculate the penalty function, relative to the observational data, for this model. It is highly recommended that you evaluate the model at the same independent variables as the observational data. The observational data is linearly interpolated to find a prediction at the independent variables that you provide.

independent: np.array

The independent data.

dependent: np.array

The dependent data for comparison.

dependent_error: np.array, optional

The dependent errors, for comparison.

Returns:

The penalties for this model, between 0 and 1 each.

Return type:

penalty, List[float]

class swiftemulator.comparison.penalty.GaussianDataErrorsPercentFloorPenaltyCalculator(percent_error: float, sigma_max: float, lower: Union[unyt_quantity, float], upper: Union[unyt_quantity, float])[source]

Bases: PenaltyCalculator

Penalty calculator that that uses Gaussian errors based on the observational data. Includes a floor based on a percent error. It will pick the worst out of the two. This is meant as a way to not fit better then the emulator allows, while also not constraining stronger than observations.

Parameters:

  • percent_error (float) – percent error that sets the one-sigma deviation, in units of percent (0-100).

  • sigma_max (float) – The number of sigmas at which the function is capped.

  • lower (Union[unyt.unyt_quantity, float]) – The lowest independent value to calculate the model offset at.

  • upper (Union[unyt.unyt_quantity, float]) – The highest independent value to calculate the model offset at.

percent_error: float
sigma_max: float
lower: Union[unyt_quantity, float]
upper: Union[unyt_quantity, float]
error_interpolator_values: interp1d
observation_interpolation()[source]

Produces the interpolation for the internal observation.

penalty(independent: array, dependent: array, dependent_error: Optional[array] = None) → List[float][source]

Calculate the penalty function, relative to the observational data, for this model. It is highly recommended that you evaluate the model at the same independent variables as the observational data. The observational data is linearly interpolated to find a prediction at the independent variables that you provide.

independent: np.array

The independent data.

dependent: np.array

The dependent data for comparison.

dependent_error: np.array, optional

The dependent errors, for comparison.

Returns:

The penalties for this model, between 0 and 1 each.

Return type:

penalty, List[float]

class swiftemulator.comparison.penalty.GaussianWeightedDataErrorsPercentFloorPenaltyCalculator(percent_error: float, sigma_max: float, weight: float, lower: Union[unyt_quantity, float], upper: Union[unyt_quantity, float])[source]

Bases: PenaltyCalculator

Penalty calculator that that uses Gaussian errors based on the observational data. Includes a floor based on a percent error. It will pick the worst out of the two. This is meant as a way to not fit better then the emulator allows, while also not constraining stronger than observations.

Parameters:

  • percent_error (float) – percent error that sets the one-sigma deviation, in units of percent (0-100).

  • sigma_max (float) – The number of sigmas at which the function is capped.

  • lower (Union[unyt.unyt_quantity, float]) – The lowest independent value to calculate the model offset at.

  • upper (Union[unyt.unyt_quantity, float]) – The highest independent value to calculate the model offset at.

  • weight (A general weight that scales the entire range of) – errors, but keeps relative weights intact.

percent_error: float
sigma_max: float
weight: float
lower: Union[unyt_quantity, float]
upper: Union[unyt_quantity, float]
error_interpolator_values: interp1d
observation_interpolation()[source]

Produces the interpolation for the internal observation.

penalty(independent: array, dependent: array, dependent_error: Optional[array] = None) → List[float][source]

Calculate the penalty function, relative to the observational data, for this model. It is highly recommended that you evaluate the model at the same independent variables as the observational data. The observational data is linearly interpolated to find a prediction at the independent variables that you provide.

independent: np.array

The independent data.

dependent: np.array

The dependent data for comparison.

dependent_error: np.array, optional

The dependent errors, for comparison.

Returns:

The penalties for this model, between 0 and 1 each.

Return type:

penalty, List[float]