API Interface

API Interface#

Interface summaries#

class satlas2.interface.HFSModel(I: float, J: ArrayLike[float, float], ABC: ArrayLike[float, float, float, float, float, float], centroid: float = 0, fwhm: ArrayLike[float, float] = [50.0, 50.0], scale: float = 1.0, background_params: ArrayLike = [0.001], shape: str = 'voigt', use_racah: bool = True, use_saturation: bool = False, saturation: float = 0.001, sidepeak_params: dict = {'N': None, 'Offset': 0, 'Poisson': 0}, crystalballparams=None, pseudovoigtparams=None, asymmetryparams=None, name: str = 'HFModel__')[source]

Initializes a hyperfine spectrum Model with the given hyperfine parameters.

Parameters:

I (float) – Integer or half-integer value of the nuclear spin
J (ArrayLike) – A sequence of 2 spins, respectively the J value of the lower state and the J value of the higher state
ABC (ArrayLike) – A sequence of 2 A, 2 B and 2 C values, respectively for the lower and the higher state
centroid (float, optional) – The centroid of the spectrum, by default 0
fwhm (ArrayLike, length = 2, optional) – First element: The Gaussian FWHM of the Voigt profile, by default 50 Second element: The Lorentzian FWHM of the Voigt profile, by default 50
scale (float, optional) – The amplitude of the entire spectrum, by default 1.0
background_params (ArrayLike, optional) – The coefficients of the polynomial background, by default [0.001]
shape (str, optional) – Voigt only
use_racah (bool, optional) – Use individual amplitudes are setting the Racah intensities, by default True
use_saturation (bool, optional) – False only
saturation (float, optional) – No saturation
sidepeak_params (dict, optional) – keys:
N (int, optional) – Number of sidepeaks to be generated, by default None
Poisson (float, optional) – The poisson factor for the sidepeaks, by default 0
Offset (float, optional) – Offset in units of x for the sidepeak, by default 0
prefunc (callable, optional) – Transformation to be applied on the input before evaluation, by default None

Methods

`set_expr`(constraints)	Set the expression to be used for the given parameters.
`set_variation`(varyDict)	Sets the variation of the fitparameters as supplied in the dictionary.
`f`(x)	Calculate the response for an unshifted spectrum with background
`chisquare_fit`(x, y[, yerr, xerr, func, ...])	Perform a fit of this model to the data provided in this function.
`display_chisquare_fit`([scaled])	Generate a report of the fitting results.
`get_result`([selection])	Return the variable names, values and estimated error bars for the parameters as seperate lists.
`get_result_dict`([method, scaled])	Returns the fitted parameters in a dictionary of the form {name: [value, uncertainty]}.
`get_result_frame`([method, selected, bounds, ...])	Returns the data from the fit in a pandas DataFrame.

class satlas2.interface.SumModel(models: list, background_params: list, name: str = 'sum', source_name: str = 'source')[source]

Initializes a hyperfine spectrum for the sum of multiple Models with the given models and a step background.

Parameters:

models (ArrayLike, with instances of HFSModel as elements) – The models that should be summed
background_params (Dict with keys: 'values' and 'bounds' and values ArrayLike) – The bounds where the background changes stepwise in key ‘bounds’ The background values between the bounds i.e. {‘values’: [2,5], ‘bounds’:[-10]} means a background of 2 from -inf to -10, and a background of 5 from -10 to +inf
name (string, optional) – Name of this summodel
source_name (string, optional) – Name of the DataSource instance (from satlas2)

Methods

`f`(x)	Calculate the response for a spectrum
`chisquare_fit`(x, y[, yerr, xerr, func, ...])	Perform a fit of this model to the data provided in this function.
`display_chisquare_fit`([scaled])	Generate a report of the fitting results.
`get_result`([selection])	Return the variable names, values and estimated error bars for the parameters as seperate lists.
`get_result_dict`([method, scaled])	Returns the fitted parameters in a dictionary of the form {name of model in summodel : {name: [value, uncertainty]}}.
`get_result_frame`([method, selected, bounds, ...])	Returns the data from the fit in a pandas DataFrame.

satlas2.interface.chisquare_fit(model: HFSModel | SumModel, x: ArrayLike, y: ArrayLike, yerr: ArrayLike | callable, xerr: ArrayLike | None = None, method: str = 'leastsq')[source]

Perform a fit of the provided model to the data provided in this function.

Parameters:

model –
x (ArrayLike) – x-values of the data points
y (ArrayLike) – y-values of the data points
yerr (ArrayLike) – 1-sigma error on the y-values
xerr (ArrayLike, optional) – 1-sigma error on the x-values
method (str, optional) – Selects the method used by the lmfit.minimizer(), by default ‘leastsq’.
show_correl (bool, optional) – Show correlations between fitted parameters in fit message, by default True

Return type:

Instance of Fitter

Extensive interface#

Inheritance diagram of satlas2.interface

Implementation of the base HFSModel and SumModel classes, based on the syntax used in the original satlas

NOTE: THIS IS NOT FULLY BENCHMARKED/DEVELOPED SO BUGS MIGHT BE PRESENT, AND NOT ALL FUNCTIONALITIES OF THE ORIGINAL SATLAS ARE IMPLEMENTED

Bases: object

Initializes a hyperfine spectrum Model with the given hyperfine parameters.

Parameters:

I (float) – Integer or half-integer value of the nuclear spin
J (ArrayLike) – A sequence of 2 spins, respectively the J value of the lower state and the J value of the higher state
ABC (ArrayLike) – A sequence of 2 A, 2 B and 2 C values, respectively for the lower and the higher state
centroid (float, optional) – The centroid of the spectrum, by default 0
fwhm (ArrayLike, length = 2, optional) – First element: The Gaussian FWHM of the Voigt profile, by default 50 Second element: The Lorentzian FWHM of the Voigt profile, by default 50
scale (float, optional) – The amplitude of the entire spectrum, by default 1.0
background_params (ArrayLike, optional) – The coefficients of the polynomial background, by default [0.001]
shape (str, optional) – Voigt only
use_racah (bool, optional) – Use individual amplitudes are setting the Racah intensities, by default True
use_saturation (bool, optional) – False only
saturation (float, optional) – No saturation
sidepeak_params (dict, optional) – keys:
N (int, optional) – Number of sidepeaks to be generated, by default None
Poisson (float, optional) – The poisson factor for the sidepeaks, by default 0
Offset (float, optional) – Offset in units of x for the sidepeak, by default 0
prefunc (callable, optional) – Transformation to be applied on the input before evaluation, by default None

chisquare_fit(x: ArrayLike, y: ArrayLike, yerr: ArrayLike | callable | None = None, xerr: ArrayLike | None = None, func: callable | None = None, verbose: bool = False, hessian: bool = False, method: str = 'leastsq', show_correl: bool = True) → Tuple[bool, str][source]#

Perform a fit of this model to the data provided in this function.

Parameters:

x (ArrayLike) – x-values of the data points
y (ArrayLike) – y-values of the data-points
yerr (Union[ArrayLike, callable], optional) – 1-sigma error on the y-values, values or function to be used on f(x), by default None=sqrt(f(x))
xerr (ArrayLike, optional) – 1-sigma error on the x-values, by default None
func (callable, optional) – Not implemented
verbose (bool, optional) – Not implemented, by default False
hessian (bool, optional) – Not implemented, by default False
method (str, optional) – Selects the method used by the lmfit.minimizer(), by default ‘leastsq’

Returns:

Returns a boolean indicating the success of the fit, and the message accompanying it.

Return type:

Tuple[bool, str]

Raises:

NotImplementedError – When the chosen options for func, verbose and Hessian result is not implemented.

display_chisquare_fit(scaled: bool = True, **kwargs)[source]#

Generate a report of the fitting results.

The report contains the best-fit values for the parameters and their uncertainties and correlations.

Parameters:

scaled (bool, optional) – Whether the errors are scaled with reduced chisquared, by default True, and only True
show_correl (bool, optional) – Whether to show a list of sorted correlations, by default False
min_correl (float, optional) – Smallest correlation in absolute value to show, by default 0.1

Returns:

Multi-line text of fit report.

Return type:

str

f(x: ArrayLike) → ArrayLike[source]#

Calculate the response for an unshifted spectrum with background

Parameters:: x (ArrayLike) –
Return type:: ArrayLike

fix_ratio(value, target='upper', parameter='A')[source]#

get_result(selection: str = 'chisquare') → Tuple[list, list, list][source]#

Return the variable names, values and estimated error bars for the parameters as seperate lists.

Parameters:: selection (string, optional) – Selects if the chisquare (‘chisquare’ or ‘any’) or MLE values are used. Defaults to ‘chisquare’, and chisquare only
Returns:: names, values, uncertainties – Returns a 3-tuple of lists containing the names of the parameters, the values and the estimated uncertainties, scaled with the reduced chisquared.
Return type:: tuple of lists

get_result_dict(method: str = 'chisquare', scaled: bool = True) → dict[source]#

Returns the fitted parameters in a dictionary of the form {name: [value, uncertainty]}.

Parameters:

method ({'chisquare', 'mle'}) – Selects which parameters have to be returned, by default ‘chisquare’, and only ‘chisquare’
scaled (boolean) – Selects if, in case of chisquare parameters, the uncertainty has to be scaled by sqrt(reduced_chisquare). Defaults to True, and only True

Returns:

Dictionary of the form described above.

Return type:

dict

get_result_frame(method: str = 'chisquare', selected: bool = False, bounds: bool = False, vary: bool = False, scaled: bool = True) → DataFrame[source]#

Returns the data from the fit in a pandas DataFrame.

Parameters:

method (str, optional) – Selects which fitresults have to be loaded. Can be ‘chisquare’ or ‘mle’. Defaults to ‘chisquare’, and only ‘chisquare’.
selected (list of strings, optional) – Selects the parameters that have any string in the list as a substring in their name. Set to None to select all parameters. Defaults to None, and only None.
bounds (boolean, optional) – Selects if the boundary also has to be given. Defaults to False, and onlyb False.
vary (boolean, optional) – Selects if only the parameters that have been varied have to be supplied. Defaults to False, and only False.
scaled (boolean, optional) – Sets the uncertainty scaling with the reduced chisquare value. Default to True, and only True

Returns:

resultframe – Dateframe with MultiIndex, using the variable names as main column names and the two rows under for the value and the uncertainty

Return type:

DataFrame

set_expr(constraints: dict) → None[source]#

Set the expression to be used for the given parameters. The constraint should be a dict with following structure:

key: string: Parameter to constrain
value: ArrayLike, length = 2: First element: Factor to multiply Second element: Parameter that the key should be constrained to. {‘Au’:[‘0.5’,’Al’]} results in Au = 0.5*Al

set_variation(varyDict: dict) → None[source]#

Sets the variation of the fitparameters as supplied in the dictionary.

Parameters:: varyDict (dictionary) – A dictionary containing ‘key: True/False’ mappings with the parameter names as keys.

class satlas2.interface.SumModel(models: list, background_params: list, name: str = 'sum', source_name: str = 'source')[source]#

Bases: object

Initializes a hyperfine spectrum for the sum of multiple Models with the given models and a step background.

Parameters:

models (ArrayLike, with instances of HFSModel as elements) – The models that should be summed
background_params (Dict with keys: 'values' and 'bounds' and values ArrayLike) – The bounds where the background changes stepwise in key ‘bounds’ The background values between the bounds i.e. {‘values’: [2,5], ‘bounds’:[-10]} means a background of 2 from -inf to -10, and a background of 5 from -10 to +inf
name (string, optional) – Name of this summodel
source_name (string, optional) – Name of the DataSource instance (from satlas2)

Perform a fit of this model to the data provided in this function.

Parameters:

x (ArrayLike) – x-values of the data points
y (ArrayLike) – y-values of the data-points
yerr (Union[ArrayLike, callable], optional) – 1-sigma error on the y-values, values or function to be used on f(x), by default None=sqrt(f(x))
xerr (ArrayLike, optional) – 1-sigma error on the x-values, by default None
func (callable, optional) – Not implemented
verbose (bool, optional) – Not implemented, by default False
hessian (bool, optional) – Not implemented, by default False
method (str, optional) – Selects the method used by the lmfit.minimizer(), by default ‘leastsq’

Returns:

Returns a boolean indicating the success of the fit, and the message accompanying it.

Return type:

Tuple[bool, str]

Raises:

NotImplementedError – When the chosen options for func, verbose and Hessian result is not implemented.

display_chisquare_fit(scaled: bool = True, **kwargs) → str[source]#

Generate a report of the fitting results.

The report contains the best-fit values for the parameters and their uncertainties and correlations.

Parameters:

scaled (bool, optional) – Whether the errors are scaled with reduced chisquared, by default True, and only True
show_correl (bool, optional) – Whether to show a list of sorted correlations, by default False
min_correl (float, optional) – Smallest correlation in absolute value to show, by default 0.1

Returns:

Multi-line text of fit report.

Return type:

str

f(x: ArrayLike) → ArrayLike[source]#

Calculate the response for a spectrum

Parameters:: x (ArrayLike) –
Return type:: ArrayLike

get_result(selection: str = 'chisquare') → Tuple[list, list, list][source]#

Return the variable names, values and estimated error bars for the parameters as seperate lists.

Parameters:: selection (string, optional) – Selects if the chisquare (‘chisquare’ or ‘any’) or MLE values are used. Defaults to ‘chisquare’, and chisquare only
Returns:: names, values, uncertainties – Returns a 3-tuple of lists containing the names of the parameters. The first list each tuple element contains the names/values/uncertainties of the first model added to the summodel, etc. The last list in each tuple element contains the names/values/uncertainties for the step background The values and the estimated uncertainties are always scaled with the reduced chisquared.
Return type:: tuple of lists

get_result_dict(method: str = 'chisquare', scaled: bool = True) → dict[source]#

Returns the fitted parameters in a dictionary of the form {name of model in summodel : {name: [value, uncertainty]}}. Background values are under key ‘bkg’ in dictionary.

Parameters:

method ({'chisquare', 'mle'}) – Selects which parameters have to be returned, by default ‘chisquare’, and only ‘chisquare’
scaled (boolean) – Selects if, in case of chisquare parameters, the uncertainty has to be scaled by sqrt(reduced_chisquare). Defaults to True, and only True

Returns:

Dictionary of the form described above.

Return type:

dict

get_result_frame(method: str = 'chisquare', selected: bool = False, bounds: bool = False, vary: bool = False, scaled: bool = True) → DataFrame[source]#

Returns the data from the fit in a pandas DataFrame.

Parameters:

method (str, optional) – Selects which fitresults have to be loaded. Can be ‘chisquare’ or ‘mle’. Defaults to ‘chisquare’, and only ‘chisquare’.
selected (list of strings, optional) – Selects the parameters that have any string in the list as a substring in their name. Set to None to select all parameters. Defaults to None, and only None.
bounds (boolean, optional) – Selects if the boundary also has to be given. Defaults to False, and onlyb False.
vary (boolean, optional) – Selects if only the parameters that have been varied have to be supplied. Defaults to False, and only False.
scaled (boolean, optional) – Sets the uncertainty scaling with the reduced chisquare value. Default to True, and only True

Returns:

resultframe – Dateframe with MultiIndex, using the model name + variable names as main column names and the two rows under for the value and the uncertainty

Return type:

DataFrame

set_variation(varyDict: dict)[source]#

satlas2.interface.chisquare_fit(model: HFSModel | SumModel, x: ArrayLike, y: ArrayLike, yerr: ArrayLike | callable, xerr: ArrayLike | None = None, method: str = 'leastsq')[source]#

Perform a fit of the provided model to the data provided in this function.

Parameters:

model –
x (ArrayLike) – x-values of the data points
y (ArrayLike) – y-values of the data points
yerr (ArrayLike) – 1-sigma error on the y-values
xerr (ArrayLike, optional) – 1-sigma error on the x-values
method (str, optional) – Selects the method used by the lmfit.minimizer(), by default ‘leastsq’.
show_correl (bool, optional) – Show correlations between fitted parameters in fit message, by default True

Return type:

Instance of Fitter

API Interface

Contents

API Interface#

Interface summaries#

Extensive interface#