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

BaseSignal instance – It contains the data to fit.

chisq

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

dof

A BaseSignal of integers – Degrees of freedom of the signal (0 if not yet fit)

red_chisq

BaseSignal instance – Reduced chi-squared.

components

ModelComponents instance – 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.

append()

Append one component to the model.

extend()

Append multiple components to the model.

remove()

Remove component from model.

as_signal()

Generate a BaseSignal instance (possible multidimensional) from the model.

store_current_values()

Store the value of the parameters at the current position.

fetch_stored_values()

Fetch stored values of the parameters.

update_plot()

Force a plot update. (In most cases the plot should update automatically.)

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.

export_results()

Save the value of the parameters in separate files.

plot_results()

Plot the value of all parameters at all positions.

print_current_values()

Print the value of the parameters at the current position.

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.

set_parameters_value()

Set the value of a parameter in components in a model to a specified value.

as_dictionary()

Exports the model to a dictionary that can be saved in a file.

See also

Model1D, Model2D

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 complete dictionary of the model, which includes at)
  • least the following fields –
    components : list
    a list of dictionaries of components, one per
    _whitelist : dictionary
    a dictionary with keys used as references for saved attributes, for more information, see hyperspy.misc.export_dictionary.export_to_dictionary()
    • any field from _whitelist.keys() *

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, parallel=None)

Returns a recreation of the dataset using the model. The spectral range that is not fitted 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 spectral range that is not fitted is filled with nans. Default True.
  • show_progressbar (None or bool) – If True, display a progress bar. If None the default is set in preferences.
  • 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.
  • parallel (bool, int) – If True or more than 1, perform the recreation parallel using as many threads as specified. If True, as many threads as CPU cores available are used.
Returns:

spectrum
Return type:

An instance of the same class as spectrum.

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.
  • 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.
disable_plot_components()
enable_plot_components()
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) → None -- extend list by appending elements from the iterable
fetch_stored_values(only_fixed=False)

Fetch the value of the parameters that has been previously stored.

Parameters:only_fixed (bool, optional) – If True, only the fixed parameters are fetched.

See also

store_current_values()

fit(fitter='leastsq', method='ls', grad=False, bounded=False, ext_bounding=False, update_plot=False, **kwargs)

Fits the model to the experimental data.

The chi-squared, reduced chi-squared and the degrees of freedom are computed automatically when fitting. They are stored as signals, in the chisq, red_chisq and dof. Note that unless metadata.Signal.Noise_properties.variance contains an accurate estimation of the variance of the data, the chi-squared and reduced chi-squared cannot be computed correctly. This is also true for homocedastic noise.

Parameters:
  • fitter ({"leastsq", "mpfit", "odr", "Nelder-Mead",) –
    “Powell”, “CG”, “BFGS”, “Newton-CG”, “L-BFGS-B”, “TNC”,
    ”Differential Evolution”}

    The optimization algorithm used to perform the fitting. Default is “leastsq”.

    ”leastsq” performs least-squares optimization, and supports bounds on parameters.

    ”mpfit” performs least-squares using the Levenberg–Marquardt algorithm and supports bounds on parameters.

    ”odr” performs the optimization using the orthogonal distance regression algorithm. It does not support bounds.

    ”Nelder-Mead”, “Powell”, “CG”, “BFGS”, “Newton-CG”, “L-BFGS-B” and “TNC” are wrappers for scipy.optimize.minimize(). Only “L-BFGS-B” and “TNC” support bounds.

    ”Differential Evolution” is a global optimization method.

    ”leastsq”, “mpfit” and “odr” can estimate the standard deviation of the estimated value of the parameters if the “metada.Signal.Noise_properties.variance” attribute is defined. Note that if it is not defined, the standard deviation is estimated using a variance of 1. If the noise is heteroscedastic, this can result in a biased estimation of the parameter values and errors. If variance is a Signal instance of the same navigation_dimension as the signal, and method is “ls”, then weighted least squares is performed.

  • method ({'ls', 'ml'}) – Choose ‘ls’ (default) for least-squares and ‘ml’ for Poisson maximum likelihood estimation. The latter is not available when ‘fitter’ is “leastsq”, “odr” or “mpfit”.
  • grad (bool) – If True, the analytical gradient is used if defined to speed up the optimization.
  • bounded (bool) – If True performs bounded optimization if the fitter supports it.
  • update_plot (bool) – If True, the plot is updated during the optimization process. It slows down the optimization but it permits to visualize the optimization progress.
  • ext_bounding (bool) – If True, enforce bounding by keeping the value of the parameters constant out of the defined bounding area.
  • **kwargs (key word arguments) – Any extra key word argument will be passed to the chosen fitter. For more information read the docstring of the optimizer of your choice in scipy.optimize.

See also

multifit()

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)

L.insert(index, object) – 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) –

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 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, **kwargs)

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

Parameters:
  • mask (NumPy array, optional) – To mask (do not fit) at certain position pass a numpy.array of type bool where True indicates that the data will not be fitted at the given position.
  • fetch_only_fixed (bool) – If True, only the fixed parameters values will be updated when changing the positon. Default False.
  • autosave (bool) – If True, the result of the fit will be saved automatically with a frequency defined by autosave_every. Default False.
  • autosave_every (int) – Save the result of fitting every given number of spectra. Default 10.
  • show_progressbar (None or bool) – If True, display a progress bar. If None the default is set in preferences.
  • interactive_plot (bool) – 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).
  • **kwargs (key word arguments) – Any extra key word argument will be passed to the fit method. See the fit method documentation for a list of valid arguments.

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=True, skip_multi=False)

Print the value of each parameter of the model.

Parameters:
  • only_free (bool) – If True, only the value of the parameters that are free will be printed.
  • skip_multi (bool) – If True, parameters with attribute “__iter__” are not printed
red_chisq

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

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

Generate the boundary list.

Necessary before fitting with a boundary aware optimizer.

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_mpfit_parameters_info()
set_parameters_free(component_list=None, parameter_name_list=None)

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.

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

See also

set_parameters_not_free(), hyperspy.component.Component.set_parameters_free(), hyperspy.component.Component.set_parameters_not_free()

set_parameters_not_free(component_list=None, parameter_name_list=None)

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.

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

See also

set_parameters_free(), hyperspy.component.Component.set_parameters_free(), hyperspy.component.Component.set_parameters_not_free()

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 parameters array.

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

suspend_update(update_on_resume=True)

Prevents plot from updating until ‘with’ clause completes.

See also

update_plot()

update_plot(*args, **kwargs)

Update model plot.

The updating can be suspended using suspend_update.

See also

suspend_update()

class hyperspy.model.DummyComponentsContainer

Bases: object

class hyperspy.model.ModelComponents(model)

Bases: object

Container for model components.

Useful to provide tab completion when running in IPython.

class hyperspy.model.ModelSpecialSlicers(model, isNavigation)

Bases: object