hyperspy.model module

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 _components that are added to the model using the append() or extend(). There are many predefined components available in the in the _components module. If needed, new components can be created easily using the 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.

signal

It contains the data to fit.

Type:: BaseSignal instance

chisq

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

Type:: BaseSignal of float

dof

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

Type:: BaseSignal of int

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.

Type:: ModelComponents instance

set_signal_range, remove_signal range, reset_signal_range,

add signal_range.: Customize the signal range to fit.

fit, multifit: Fit the model to the data at the current position or the full dataset.

save_parameters2file, load_parameters_from_file: Save/load the parameter values to/from a file.

plot(): Plot the model and the data.

enable_plot_components, disable_plot_components: Plot each component separately. (Use after plot.)

set_current_values_to(): Set the current value of all the parameters of the given component as the value for all the dataset.

enable_adjust_position, disable_adjust_position: Enable/disable interactive adjustment of the position of the components that have a well defined position. (Use after plot).

fit_component(): Fit just the given component in the given signal range, that can be set interactively.

set_parameters_not_free, set_parameters_free: Fit the free status of several components and parameters at once.

See also

Model1D, Model2D

_bounds_as_tuple(): Converts parameter bounds to tuples for least_squares()

_disable_ext_bounding(components=None)

_enable_ext_bounding(components=None)

_fetch_values_from_p0(p_std=None)

Fetch the parameter values from the output of the optimizer self.p0, placing them in their appropriate component.parameter.value and …std

Parameters:: p_std (array, optional) – array containing the corresponding standard deviation.

property _free_parameters: Get the free parameters of active components.

_get_variance(only_current=True): Return the variance taking into account the channel_switches. If only_current=True, the variance for the current navigation indices is returned, otherwise the variance for all navigation indices is returned.

_linear_fit(optimizer='lstsq', calculate_errors=False, only_current=True, weights=None, **kwargs)

Multivariate linear fitting

Parameters:

optimizer (str, default is "lstsq") – ‘lstsq’ - Default, supports lazy signal ‘ridge_regression’ - Supports regularisation, doesn’t support lazy signal.
calculate_errors (bool, default is False) – If True, calculate the errors.
only_current (bool, default is True) – Fit the current index only, instead of the whole navigation space.
kwargs (dict, optional) – Keywords arguments are passed to sklearn.linear_model.ridge_regression().

Notes

More linear optimizers can be added in the future, but note that in order to support simultaneous fitting across the dataset, the optimizer must support “two-dimensional y” - see the b parameter in numpy.linalg.lstsq().

Currently, the overhead in calculating the component data takes about 100 times longer than actually running np.linalg.lstsq(). That means that going pixel-by-pixel, calculating the component data each time is not faster than the normal nonlinear methods. Linear fitting is hence currently only useful for fitting a dataset in the vectorized manner.

_load_dictionary(dic)

Load data from dictionary.

Parameters:

dic (dict) –

A dictionary containing at least the following fields:

_whitelist: a dictionary with keys used as references of save attributes, for more information, see load_from_dictionary()
components: a dictionary, with information about components of the model (see as_dictionary() documentation for more details)
any field from _whitelist.keys()

_on_navigating(): Same as fetch_stored_values but without update_on_resume since the model plot is updated in the figure update callback.

_set_boundaries(bounded=True)

Generate the boundary list.

Necessary before fitting with a boundary aware optimizer.

Parameters:: bounded (bool, default True) – If True, loops through the model components and populates the free parameter boundaries.
Return type:: None

_set_mpfit_parameters_info(bounded=True)

Generate the boundary list for mpfit.

Parameters:: bounded (bool, default True) – If True, loops through the model components and populates the free parameter boundaries.
Return type:: None

_set_p0(): Sets the initial values for the parameters used in the curve fitting functions

property active_components: List all nonlinear parameters.

append(thing)

Add component to Model.

Parameters:: thing (Component instance.) –

as_dictionary(fullcopy=True)

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

Parameters:

fullcopy (bool (optional, True)) – Copies of objects are stored, not references. If any found, functions will be pickled and signals converted to dictionaries

Returns:

dictionary – 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()

Return type:

dict

Examples

>>> s = signals.Signal1D(np.random.random((10,100)))
>>> m = s.create_model()
>>> l1 = components1d.Lorentzian()
>>> l2 = 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_list (list of HyperSpy components, 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_nan (bool) – If True the signal range outside of the fitted range is filled with nans. Default True.
show_progressbar (None or bool) – If True, display a progress bar. If None, the default from the preferences settings is used.
out ({None, 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

Return type:

An instance of the same class as BaseSignal.

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_list (list of components, 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.
mask (boolean numpy array or None, optional) – The operation won’t be performed where mask is True.

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

Creates a SAMFire object.

Parameters:

workers ({None, 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.
setup (bool) – if the setup should be run upon initialization.
**kwargs – Any that will be passed to the _setup and in turn SamfirePool.

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:

folder (str or None) – The path to the folder where the file will be saved. If None the current folder is used by default.
format (str) – The extension of the file format. It must be one of the fileformats supported by HyperSpy. The default is “hspy”.
save_std (bool) – If True, also the standard deviation will be saved.
only_free (bool) – If True, only the value of the parameters that are free will be exported.
only_active (bool) – 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_fixed (bool, optional) – If True, only the fixed parameters are fetched.
update_on_resume (bool, 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:

array (array) – 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()

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

Display or return interactive GUI element if available.

Parameters:

display (bool) – If True, display the user interface widgets. If False, return the widgets container in a dictionary, usually for customisation or testing.
toolkit (str, iterable of strings 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:: filename (str) –

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 https://github.com/hyperspy/hyperspy/issues/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:

mask (np.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_fixed (bool, default False) – If True, only the fixed parameters values will be updated when changing the positon.
autosave (bool, default False) – If True, the result of the fit will be saved automatically with a frequency defined by autosave_every.
autosave_every (int, default 10) – Save the result of fitting every given number of spectra.
show_progressbar (None or bool) – If True, display a progress bar. If None, the default from the preferences settings is used.
interactive_plot (bool, 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:
Currently None -> "flyback". The default argument will use the "flyback" iterpath, but shows a warning that this will change to "serpentine" in version 2.0.
**kwargs (keyword arguments) – Any extra keyword argument will be passed to the fit method. See the documentation for fit() for a list of valid arguments.

Return type:

None

See also

fit()

plot_results(only_free=True, only_active=True)

Plot the value of the parameters of the model

Parameters:

only_free (bool) – If True, only the value of the parameters that are free will be plotted.
only_active (bool) – 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, fancy=True)

Prints the current values of the parameters of all components.

Parameters:

only_free (bool) – If True, only components with free parameters will be printed. Within these, only parameters which are free will be printed.
only_active (bool) – If True, only values of active components will be printed
component_list (None or list of components.) – If None, print all components.
fancy (bool) – If True, attempts to print using html rather than text in the notebook.

property red_chisq

Reduced chi-squared. Calculated from self.chisq and self.dof.

Type:: BaseSignal

remove(thing)

Remove component from model.

Examples

>>> s = hs.signals.Signal1D(np.empty(1))
>>> m = s.create_model()
>>> g = hs.model.components1D.Gaussian()
>>> m.append(g)

You could remove g like this

>>> m.remove(g)

Like this:

>>> m.remove("Gaussian")

Or like this:

>>> m.remove(0)

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

Saves signal and its model to a file

Parameters:

file_name (str) – 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:: filename (str) –

Notes

This method can be used to save the current state of the model in a way that can be loaded back to recreate the 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 https://github.com/hyperspy/hyperspy/issues/341.

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

Sets the component ‘active’ parameter to a specified value

Parameters:

value (bool) – The new value of the ‘active’ parameter
component_list (list of hyperspy components, optional) – A list of components whose parameters will changed. The components can be specified by name, index or themselves.
only_current (bool, 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

>>> 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_list (None, or list of hyperspy components, 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_list (None or list of strings, 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_linear (Bool) – If True, will only set parameters that are linear to not free.
only_nonlinear (Bool) – If True, will only set parameters that are nonlinear to not free.

Examples

>>> 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_list (None, or list of hyperspy components, 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_list (None or list of strings, 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_linear (bool) – If True, will only set parameters that are linear to free.
only_nonlinear (bool) – If True, will only set parameters that are nonlinear to free.

Examples

>>> 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_name (string) – Name of the parameter whose value will be changed
value (number) – The new value of the parameter
component_list (list of hyperspy components, optional) – A list of components whose parameters will changed. The components can be specified by name, index or themselves.
only_current (bool, 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

>>> 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)

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.

hyperspy.model._check_deprecated_optimizer(optimizer): Can be removed in HyperSpy 2.0

hyperspy.model._twinned_parameter(parameter)

Used in linear fitting. Since twinned parameters are not free, we need to construct a mapping between the twinned parameter and the parameter component to which the (non-free) twinned parameter component value needs to be added.

Returns:

parameter when there is a twin and this twin is free
None when there is no twin or when the twin is not non-free itself, which
implies that the original parameter is not free