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.

See also

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

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.

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.

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.