matcal.core.residuals

The residual module contains all classes and functions for residual calculation. Most are internal tools not intended for users. However, the classes related to residual weighting are user facing tools.

Classes

ConstantFactorWeighting(scale_factor)	This class when passed to an objective will multiply the residual by a constant scale factor.
IdentityWeighting()	This class when passed to an objective will return an unaltered residual.
InvertedLinearDataSizeNormalizer()	This class when passed to an objective will multiply the residual by the number of experimental data points in the data set.
InvertedSqrtDataSizeNormalizer()	This class when passed to an objective will multiply the residual by the square root of the number of experimental data points in the data set.
LinearDataSizeNormalizer()	This class when passed to an objective will divide the residual by the number of experimental data points in the data set.
LogResidualCalculator(*fields_of_interest)	Not intended for users.
NoiseWeightingConstant([weights_dict])	Apply a constant noise weighting across all data points for a given field.
NoiseWeightingFromFile(target_field)	This class when passed to an objective will divide the residual value by the respective noise field defined in the datafile.
NominalResidualCalculator(*fields_of_interest)	Not intended for users.
SqrtDataSizeNormalizer()	This class when passed to an objective will divide the residual by the square root of the number of experimental data points in the data set.
UserFunctionWeighting(independent_field, ...)	This class when passed to an objective will apply a user defined function to the residual.

class matcal.core.residuals.NominalResidualCalculator(*fields_of_interest)

Not intended for users. Calculates residual for two data classes being compared.

class matcal.core.residuals.LogResidualCalculator(*fields_of_interest)

Not intended for users. Calculates residual for two data classes being compared.

class matcal.core.residuals.SqrtDataSizeNormalizer

This class when passed to an objective will divide the residual by the square root of the number of experimental data points in the data set. The normalization is intended to reduce calibration bias that would favor data sets that contain more data points.

No additional information needs to be passed to this class.

class matcal.core.residuals.InvertedSqrtDataSizeNormalizer

This class when passed to an objective will multiply the residual by the square root of the number of experimental data points in the data set. The normalization is intended to reduce calibration bias that would favor data sets that contain more data points.

No additional information needs to be passed to this class.

class matcal.core.residuals.LinearDataSizeNormalizer

This class when passed to an objective will divide the residual by the number of experimental data points in the data set. The normalization is intended to reduce calibration bias that would favor data sets that contain more data points.

No additional information needs to be passed to this class.

class matcal.core.residuals.InvertedLinearDataSizeNormalizer

This class when passed to an objective will multiply the residual by the number of experimental data points in the data set. The normalization is intended to reduce calibration bias that would favor data sets that contain more data points.

No additional information needs to be passed to this class.

class matcal.core.residuals.ResidualWeightingBase

Base class for residual weights not intended for users.

class matcal.core.residuals.IdentityWeighting

This class when passed to an objective will return an unaltered residual. This is the default weighting.

class matcal.core.residuals.ConstantFactorWeighting(scale_factor)

This class when passed to an objective will multiply the residual by a constant scale factor. The goal of this weighting is to apply more or less emphasis to specific objectives during a calibration.

Parameters:

scale_factor (float) – The value to scale the residual vector by.

class matcal.core.residuals.UserFunctionWeighting(independent_field, target_field, weighting_function)

This class when passed to an objective will apply a user defined function to the residual. The goal of this weighting is to provide the user with a means to emphasize regions of their data.

Parameters:

• independent_field (str) – The name of the field to use as an independent field in the user function.

• target_field (str) – The name of the residual field to apply the weighting to.

• weighting_function (Callable) –

  Predefined function with a signature of (independent_field_data, target_field_data, target_field_residual) and returns a NumPy array the same length as the target_field_residual. the results of this function will replace the residual value in the evaluation.

  Note

  The residual values passed to this function are conditioned to be near unity, and thus one should not expect the values to be on the scale as the data. The independent field data will be on the scale the user supplied in the data originally.

class matcal.core.residuals.NoiseWeightingFromFile(target_field)

This class when passed to an objective will divide the residual value by the respective noise field defined in the datafile. This noise term will be conditioned and scaled in the same matter at the base field. The scaling and conditioning will be handled externally to this tool. The field to be weighted needs to be passed to this class. This class will expect another data field with “_noise” appended to the end of the field name.

Parameters:

target_field – The name of the field to weight.

class matcal.core.residuals.NoiseWeightingConstant(weights_dict: dict = None, **field_noise_levels)

Apply a constant noise weighting across all data points for a given field. This type of weighting is used to emphasize regions of lower noise and discount those of higher noise. This is useful if there are a large number of data sets, and to reduce the size of a residual, the repeat datasets can be collapsed into their mean values and weighted by their noise.

The residuals will be divided by the value of the noise. If no noise data exists or if the noise value is 0, a 1 should be passed.

Initialize weighting by noise. There are two ways to initialize the data. By passing keyword arguments with floats the weights are set for all fields across all experimental states. The second way is by passing a dictionary that nests the states and field names, allowing for different weights per state.

Parameters:

• weights_dict (dict) – a dictionary of field names and states that defines the noise weights. The dictionary should be structured [field_name][state_name] = value. This type of dictionary can be generated from a DataCollection ‘s report_statistics method.

• field_noise_levels – fieldname and noise value pairs. Will apply noise level across all experimental states.