BaseModel

class hyperspy.model.BaseModel

Bases: list

Model and data fitting tools applicable to signals of both one and two dimensions.

Models of one-dimensional signals should use the Model1D and models of two-dimensional signals should use the Model2D.

A model is constructed as a linear combination of components1D or components2D that are added to the model using the append() or extend(). If needed, new components can be created easily created using using Expression code of existing components as a template.

Once defined, the model can be fitted to the data using fit() or multifit(). Once the optimizer reaches the convergence criteria or the maximum number of iterations the new value of the component parameters are stored in the components.

It is possible to access the components in the model by their name or by the index in the model. An example is given at the end of this docstring.

Attributes:

signalBaseSignal

The signal data to fit.

chisqBaseSignal

Chi-squared of the signal (or np.nan if not yet fit).

red_chisqBaseSignal

The Reduced chi-squared.

dofBaseSignal

Degrees of freedom of the signal (0 if not yet fit)

componentsModelComponents

The components of the model are attributes of this class.

Methods

append(thing)	Add component to Model.
extend(iterable)	Append multiple components to the model.
remove(thing)	Remove component from model.
set_signal_range_from_mask(mask)	Use the signal ranges as defined by the mask
fit([optimizer, loss_function, grad, ...])	Fits the model to the experimental data.
multifit([mask, fetch_only_fixed, autosave, ...])	Fit the data to the model at all positions of the navigation dimensions.
store_current_values()	Store the parameters of the current coordinates into the parameter.map array and sets the is_set array attribute to True.
fetch_stored_values([only_fixed, ...])	Fetch the value of the parameters that have been previously stored in parameter.map['values'] if parameter.map['is_set'] is True for those indices.
save_parameters2file(filename)	Save the parameters array in binary format.
load_parameters_from_file(filename)	Loads the parameters array from a binary file written with the save_parameters2file() function.
enable_plot_components()	Enable interactive adjustment of the position of the components that have a well defined position.
disable_plot_components()	Disable interactive adjustment of the position of the components that have a well defined position.
set_parameters_not_free([component_list, ...])	Sets the parameters in a component in a model to not free.
set_parameters_free([component_list, ...])	Sets the parameters in a component in a model to free.
set_parameters_value(parameter_name, value)	Sets the value of a parameter in components in a model to a specified value
as_signal([component_list, ...])	Returns a recreation of the dataset using the model.
export_results([folder, format, save_std, ...])	Export the results of the parameters of the model to the desired folder.
plot_results([only_free, only_active])	Plot the value of the parameters of the model
print_current_values([only_free, ...])	Prints the current values of the parameters of all components.
as_dictionary([fullcopy])	Returns a dictionary of the model, including all components, degrees of freedom (dof) and chi-squared (chisq) with values.

See also

hyperspy.models.model1d.Model1D, hyperspy.models.model2d.Model2D

property active_components

List all nonlinear parameters.

append(thing)

Add component to Model.

Parameters:

thingComponent

The component to add to the model.

as_dictionary(fullcopy=True)

Returns a dictionary of the model, including all components, degrees of freedom (dof) and chi-squared (chisq) with values.

Parameters:

fullcopybool, optional True

Copies of objects are stored, not references. If any found, functions will be pickled and signals converted to dictionaries

Returns:

dictionarydict

A dictionary including at least the following fields:

• components: a list of dictionaries of components, one per component

• _whitelist: a dictionary with keys used as references for saved attributes, for more information, see export_to_dictionary()

• any field from _whitelist.keys()

Examples

>>> s = hs.signals.Signal1D(np.random.random((10,100)))
>>> m = s.create_model()
>>> l1 = hs.model.components1D.Lorentzian()
>>> l2 = hs.model.components1D.Lorentzian()
>>> m.append(l1)
>>> m.append(l2)
>>> d = m.as_dictionary()
>>> m2 = s.create_model(dictionary=d)

as_signal(component_list=None, out_of_range_to_nan=True, show_progressbar=None, out=None, **kwargs)

Returns a recreation of the dataset using the model.

By default, the signal range outside of the fitted range is filled with nans.

Parameters:

component_listlist of Component, optional

If a list of components is given, only the components given in the list is used in making the returned spectrum. The components can be specified by name, index or themselves.

out_of_range_to_nanbool

If True the signal range outside of the fitted range is filled with nans. Default True.

show_progressbarNone or bool

If True, display a progress bar. If None, the default from the preferences settings is used.

outNone or BaseSignal

The signal where to put the result into. Convenient for parallel processing. If None (default), creates a new one. If passed, it is assumed to be of correct shape and dtype and not checked.

Returns:

BaseSignal

The model as a signal.

Examples

>>> s = hs.signals.Signal1D(np.random.random((10,100)))
>>> m = s.create_model()
>>> l1 = hs.model.components1D.Lorentzian()
>>> l2 = hs.model.components1D.Lorentzian()
>>> m.append(l1)
>>> m.append(l2)
>>> s1 = m.as_signal()
>>> s2 = m.as_signal(component_list=[l1])

assign_current_values_to_all(components_list=None, mask=None)

Set parameter values for all positions to the current ones.

Parameters:

component_listlist of Component, optional

If a list of components is given, the operation will be performed only in the value of the parameters of the given components. The components can be specified by name, index or themselves. If None (default), the active components will be considered.

masknumpy.ndarray of bool or None, optional

The operation won’t be performed where mask is True.

property chisq

Chi-squared of the signal (or np.nan if not yet fit).

property components

The components of the model are attributes of this class.

This provides a convenient way to access the model components when working in IPython as it enables tab completion.

create_samfire(workers=None, setup=True, **kwargs)

Creates a SAMFire object.

Parameters:

workersNone or int

the number of workers to initialise. If zero, all computations will be done serially. If None (default), will attempt to use (number-of-cores - 1), however if just one core is available, will use one worker.

setupbool

if the setup should be run upon initialization.

**kwargs

Any that will be passed to the _setup and in turn SamfirePool.

disable_plot_components()

Disable interactive adjustment of the position of the components that have a well defined position. Use after plot().

property dof

Degrees of freedom of the signal (0 if not yet fit)

enable_plot_components()

Enable interactive adjustment of the position of the components that have a well defined position. Use after plot().

ensure_parameters_in_bounds()

For all active components, snaps their free parameter values to be within their boundaries (if bounded). Does not touch the array of values.

export_results(folder=None, format='hspy', save_std=False, only_free=True, only_active=True)

Export the results of the parameters of the model to the desired folder.

Parameters:

folderstr or None

The path to the folder where the file will be saved. If None the current folder is used by default.

formatstr

The extension of the file format. It must be one of the fileformats supported by HyperSpy. The default is "hspy".

save_stdbool

If True, also the standard deviation will be saved.

only_freebool

If True, only the value of the parameters that are free will be exported.

only_activebool

If True, only the value of the active parameters will be exported.

Notes

The name of the files will be determined by each the Component and each Parameter name attributes. Therefore, it is possible to customise the file names modify the name attributes.

extend(iterable)

Append multiple components to the model.

Parameters:

iterable: iterable of `Component` instances.

fetch_stored_values(only_fixed=False, update_on_resume=True)

Fetch the value of the parameters that have been previously stored in parameter.map[‘values’] if parameter.map[‘is_set’] is True for those indices.

If it is not previously stored, the current values from parameter.value are used, which are typically from the fit in the previous pixel of a multidimensional signal.

Parameters:

only_fixedbool, optional

If True, only the fixed parameters are fetched.

update_on_resumebool, optional

If True, update the model plot after values are updated.

See also

store_current_values

fetch_values_from_array(array, array_std=None)

Fetch the parameter values from the given array, optionally also fetching the standard deviations.

Places the parameter values into both m.p0 (the initial values for the optimizer routine) and component.parameter.value and …std, for parameters in active components ordered by their position in the model and component.

Parameters:

arrayarray

array with the parameter values

array_std{None, array}

array with the standard deviations of parameters

fit(optimizer='lm', loss_function='ls', grad='fd', bounded=False, update_plot=False, print_info=False, return_info=True, fd_scheme='2-point', **kwargs)

Fits the model to the experimental data.

Read more in the User Guide.

Parameters:

optimizerstr or None, default None

The optimization algorithm used to perform the fitting.

• Non-linear optimizers:

  • "lm" performs least-squares optimization using the Levenberg-Marquardt algorithm, and supports bounds on parameters.

  • "trf" performs least-squares optimization using the Trust Region Reflective algorithm, and supports bounds on parameters.

  • "dogbox" performs least-squares optimization using the dogleg algorithm with rectangular trust regions, and supports bounds on parameters.

  • "odr" performs the optimization using the orthogonal distance regression (ODR) algorithm. It does not support bounds on parameters. See scipy.odr for more details.

  • All of the available methods for scipy.optimize.minimize() can be used here. See the User Guide documentation for more details.

  • "Differential Evolution" is a global optimization method. It does support bounds on parameters. See scipy.optimize.differential_evolution() for more details on available options.

  • "Dual Annealing" is a global optimization method. It does support bounds on parameters. See scipy.optimize.dual_annealing() for more details on available options. Requires scipy >= 1.2.0.

  • "SHGO" (simplicial homology global optimization) is a global optimization method. It does support bounds on parameters. See scipy.optimize.shgo() for more details on available options. Requires scipy >= 1.2.0.

• Linear optimizers:

  • "lstsq" - least square using numpy.linalg.lstsq().

  • "ols" - Ordinary least square using sklearn.linear_model.LinearRegression

  • "nnls" - Linear regression with positive constraints on the regression coefficients using sklearn.linear_model.LinearRegression

  • "ridge" - least square supporting regularisation using sklearn.linear_model.Ridge. The parameter alpha (default set to 0.01) controlling regularization strength can be passed as keyword argument, see sklearn.linear_model.Ridge for more information.

loss_function{"ls", "ML-poisson", "huber", callable()}, default "ls"

The loss function to use for minimization. Only "ls" is available if optimizer is one of "lm", "trf", "dogbox" or "odr".

• "ls" minimizes the least-squares loss function.

• "ML-poisson" minimizes the negative log-likelihood for Poisson-distributed data. Also known as Poisson maximum likelihood estimation (MLE).

• "huber" minimize the Huber loss function. The delta value of the Huber function is controlled by the huber_delta keyword argument (the default value is 1.0).

• callable supports passing your own minimization function.

grad{"fd", "analytical", callable(), None}, default "fd"

Whether to use information about the gradient of the loss function as part of the optimization. This parameter has no effect if optimizer is a derivative-free or global optimization method.

• "fd" uses a finite difference scheme (if available) for numerical estimation of the gradient. The scheme can be further controlled with the fd_scheme keyword argument.

• "analytical" uses the analytical gradient (if available) to speed up the optimization, since the gradient does not need to be estimated.

• callable should be a function that returns the gradient vector.

• None means that no gradient information is used or estimated. Not available if optimizer is one of "lm", "trf" or "dogbox".

boundedbool, default False

If True, performs bounded parameter optimization if supported by optimizer.

update_plotbool, default False

If True, the plot is updated during the optimization process. It slows down the optimization, but it enables visualization of the optimization progress.

print_infobool, default False

If True, print information about the fitting results, which are also stored in model.fit_output in the form of a scipy.optimize.OptimizeResult object.

return_infobool, default True

If True, returns the fitting results in the form of a scipy.optimize.OptimizeResult object.

fd_schemestr {"2-point", "3-point", "cs"}, default "2-point"

If grad='fd', selects the finite difference scheme to use. See scipy.optimize.minimize() for details. Ignored if optimizer is one of "lm", "trf" or "dogbox".

**kwargsdict

Any extra keyword argument will be passed to the chosen optimizer. For more information, read the docstring of the optimizer of your choice in scipy.optimize.

Returns:

None

See also

multifit, fit

Notes

The chi-squared and reduced chi-squared statistics, and the degrees of freedom, are computed automatically when fitting, only when loss_function="ls". They are stored as signals: chisq, red_chisq and dof.

If the attribute metada.Signal.Noise_properties.variance is defined as a Signal instance with the same navigation_dimension as the signal, and loss_function is "ls" or "huber", then a weighted fit is performed, using the inverse of the noise variance as the weights.

Note that for both homoscedastic and heteroscedastic noise, if metadata.Signal.Noise_properties.variance does not contain an accurate estimation of the variance of the data, then the chi-squared and reduced chi-squared statistics will not be be computed correctly. See the Setting the noise properties in the User Guide for more details.

gui(display=True, toolkit=None, **kwargs)

Display or return interactive GUI element if available.

Parameters:

displaybool

If True, display the user interface widgets. If False, return the widgets container in a dictionary, usually for customisation or testing.

toolkitstr, iterable of str or None

If None (default), all available widgets are displayed or returned. If string, only the widgets of the selected toolkit are displayed if available. If an interable of toolkit strings, the widgets of all listed toolkits are displayed or returned.

insert(**kwargs)

Insert object before index.

load_parameters_from_file(filename)

Loads the parameters array from a binary file written with the save_parameters2file() function.

Parameters:

filenamestr

The file name of the file to load it from.

See also

save_parameters2file, export_results

Notes

In combination with save_parameters2file(), this method can be used to recreate a model stored in a file. Actually, before HyperSpy 0.8 this is the only way to do so. However, this is known to be brittle. For example see hyperspy/hyperspy#341.

multifit(mask=None, fetch_only_fixed=False, autosave=False, autosave_every=10, show_progressbar=None, interactive_plot=False, iterpath=None, **kwargs)

Fit the data to the model at all positions of the navigation dimensions.

Parameters:

masknp.ndarray, optional

To mask (i.e. do not fit) at certain position, pass a boolean numpy.array, where True indicates that the data will NOT be fitted at the given position.

fetch_only_fixedbool, default False

If True, only the fixed parameters values will be updated when changing the positon.

autosavebool, default False

If True, the result of the fit will be saved automatically with a frequency defined by autosave_every.

autosave_everyint, default 10

Save the result of fitting every given number of spectra.

show_progressbarNone or bool

If True, display a progress bar. If None, the default from the preferences settings is used.

interactive_plotbool, default False

If True, update the plot for every position as they are processed. Note that this slows down the fitting by a lot, but it allows for interactive monitoring of the fitting (if in interactive mode).

iterpath{None, "flyback", "serpentine"}, default None

If "flyback":

At each new row the index begins at the first column, in accordance with the way numpy.ndindex generates indices.

If "serpentine":

Iterate through the signal in a serpentine, “snake-game”-like manner instead of beginning each new row at the first index. Works for n-dimensional navigation space, not just 2D.

If None:

Use the value of iterpath.

**kwargsdict

Any extra keyword argument will be passed to the fit method. See the documentation for fit() for a list of valid arguments.

Returns:

None

See also

fit

plot_results(only_free=True, only_active=True)

Plot the value of the parameters of the model

Parameters:

only_freebool

If True, only the value of the parameters that are free will be plotted.

only_activebool

If True, only the value of the active parameters will be plotted.

Notes

The name of the files will be determined by each the Component and each Parameter name attributes. Therefore, it is possible to customise the file names modify the name attributes.

print_current_values(only_free=False, only_active=False, component_list=None)

Prints the current values of the parameters of all components.

Parameters:

only_freebool

If True, only components with free parameters will be printed. Within these, only parameters which are free will be printed.

only_activebool

If True, only values of active components will be printed

component_listNone or list of Component

If None, print all components.

property red_chisq

The Reduced chi-squared.

Calculated from self.chisq and self.dof.

remove(thing)

Remove component from model.

Examples

>>> s = hs.signals.Signal1D(np.empty(1))
>>> m = s.create_model()
>>> g1 = hs.model.components1D.Gaussian()
>>> g2 = hs.model.components1D.Gaussian()
>>> m.extend([g1, g2])

You could remove g1 like this

>>> m.remove(g1)

Or like this:

>>> m.remove(0)

save(file_name, name=None, **kwargs)

Saves signal and its model to a file

Parameters:

file_namestr

Name of the file

name{None, str}

Stored model name. Auto-generated if left empty

**kwargs

Other keyword arguments are passed onto BaseSignal.save()

save_parameters2file(filename)

Save the parameters array in binary format.

The data is saved to a single file in numpy’s uncompressed .npz format.

Parameters:

filenamestr

The file name of the file it is saved to.

See also

load_parameters_from_file, export_results

Notes

This method can be used to save the current state of the model in a way that can be loaded back to recreate it using load_parameters_from_file(). Actually, as of HyperSpy 0.8 this is the only way to do so. However, this is known to be brittle. For example see hyperspy/hyperspy#341.

set_component_active_value(value, component_list=None, only_current=False)

Sets the component 'active' parameter to a specified value.

Parameters:

valuebool

The new value of the 'active' parameter

component_listlist of Component, optional

A list of components whose parameters will changed. The components can be specified by name, index or themselves.

only_currentbool, default False

If True, will only change the parameter value at the current position in the model. If False, will change the parameter value for all the positions.

Examples

>>> s = hs.signals.Signal1D(np.random.random((10,100)))
>>> m = s.create_model()
>>> v1 = hs.model.components1D.Voigt()
>>> v2 = hs.model.components1D.Voigt()
>>> m.extend([v1,v2])

>>> m.set_component_active_value(False)
>>> m.set_component_active_value(True, component_list=[v1])
>>> m.set_component_active_value(
...    False, component_list=[v1], only_current=True
... )

set_parameters_free(component_list=None, parameter_name_list=None, only_linear=False, only_nonlinear=False)

Sets the parameters in a component in a model to free.

Parameters:

component_listNone or list of Component, optional

If None, will apply the function to all components in the model. If list of components, will apply the functions to the components in the list. The components can be specified by name, index or themselves.

parameter_name_listNone or list of str, optional

If None, will set all the parameters to not free. If list of strings, will set all the parameters with the same name as the strings in parameter_name_list to not free.

only_linearbool

If True, will only set parameters that are linear to not free.

only_nonlinearbool

If True, will only set parameters that are nonlinear to not free.

See also

set_parameters_not_free

hyperspy.component.Component.set_parameters_free

hyperspy.component.Component.set_parameters_not_free

Examples

>>> s = hs.signals.Signal1D(np.random.random((10,100)))
>>> m = s.create_model()
>>> v1 = hs.model.components1D.Voigt()
>>> m.append(v1)

>>> m.set_parameters_free()
>>> m.set_parameters_free(
...    component_list=[v1], parameter_name_list=['area','centre']
... )
>>> m.set_parameters_free(only_linear=True)

set_parameters_not_free(component_list=None, parameter_name_list=None, only_linear=False, only_nonlinear=False)

Sets the parameters in a component in a model to not free.

Parameters:

component_listNone or list of Component, optional

If None, will apply the function to all components in the model. If list of components, will apply the functions to the components in the list. The components can be specified by name, index or themselves.

parameter_name_listNone or list of str, optional

If None, will set all the parameters to not free. If list of strings, will set all the parameters with the same name as the strings in parameter_name_list to not free.

only_linearbool

If True, will only set parameters that are linear to free.

only_nonlinearbool

If True, will only set parameters that are nonlinear to free.

See also

set_parameters_free

hyperspy.component.Component.set_parameters_free

hyperspy.component.Component.set_parameters_not_free

Examples

>>> s = hs.signals.Signal1D(np.random.random((10,100)))
>>> m = s.create_model()
>>> v1 = hs.model.components1D.Voigt()
>>> m.append(v1)
>>> m.set_parameters_not_free()

>>> m.set_parameters_not_free(
...     component_list=[v1], parameter_name_list=['area','centre']
... )
>>> m.set_parameters_not_free(only_linear=True)

set_parameters_value(parameter_name, value, component_list=None, only_current=False)

Sets the value of a parameter in components in a model to a specified value

Parameters:

parameter_namestr

Name of the parameter whose value will be changed

valuefloat or int

The new value of the parameter

component_listNone or list of Component, optional

A list of components whose parameters will changed. The components can be specified by name, index or themselves. If None, use all components of the model.

only_currentbool, default False

If True, will only change the parameter value at the current position in the model. If False, will change the parameter value for all the positions.

Examples

>>> s = hs.signals.Signal1D(np.random.random((10,100)))
>>> m = s.create_model()
>>> v1 = hs.model.components1D.Voigt()
>>> v2 = hs.model.components1D.Voigt()
>>> m.extend([v1,v2])

>>> m.set_parameters_value('area', 5)
>>> m.set_parameters_value('area', 5, component_list=[v1])
>>> m.set_parameters_value(
...    'area', 5, component_list=[v1], only_current=True
... )

set_signal_range_from_mask(mask)

Use the signal ranges as defined by the mask

Parameters:

masknumpy.ndarray of bool

A boolean array defining the signal range. Must be the same shape as the reversed signal_shape, i.e. signal_shape[::-1]. Where array values are True, signal will be fitted, otherwise not.

See also

hyperspy.models.model1d.Model1D.set_signal_range

hyperspy.models.model1d.Model1D.add_signal_range

hyperspy.models.model1d.Model1D.remove_signal_range

hyperspy.models.model1d.Model1D.reset_signal_range

Examples

>>> s = hs.signals.Signal2D(np.random.rand(10, 10, 20))
>>> mask = (s.sum() > 5)
>>> m = s.create_model()
>>> m.set_signal_range_from_mask(mask.data)

property signal

The signal data to fit.

store(name=None)

Stores current model in the original signal

Parameters:

name{None, str}

Stored model name. Auto-generated if left empty

store_current_values()

Store the parameters of the current coordinates into the parameter.map array and sets the is_set array attribute to True.

If the parameters array has not being defined yet it creates it filling it with the current parameters at the current indices in the array.

suspend_update(update_on_resume=True)

Prevents plot from updating until ‘with’ clause completes.

See also

update_plot

update_plot(render_figure=False, update_ylimits=False, **kwargs)

Update model plot.

The updating can be suspended using suspend_update.

See also

suspend_update

class hyperspy.model.ModelComponents(model)

Bases: object

Container for model components.

Useful to provide tab completion when running in IPython.