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

A BaseSignal of floats

dof

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

Type

A BaseSignal of integers

red_chisq

Reduced chi-squared.

Type

BaseSignal instance

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

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

_as_signal_iter(data, component_list=None, show_progressbar=None)
_bounds_as_tuple()

Converts parameter bounds to tuples for least_squares()

_calculate_chisq()
_calculate_parameter_std(pcov, cost, ysize)
_close_plot()
_connect_parameters2update_plot(components)
_convert_variance_to_weights()
_disable_ext_bounding(components=None)
_disconnect_parameters2update_plot(components)
_enable_ext_bounding(components=None)
_errfunc4mpfit(p, fjac=None, x=None, y=None, weights=None)
_errfunc_sq(param, y, weights=None)
_fetch_values_from_p0(p_std=None)

Fetch the parameter values from the output of the optimizer self.p0

Parameters

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

_get_component(thing)
_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.

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

_model2plot(axes_manager, out_of_range2nans=True)
_model_function(param)
_on_navigating()

Same as fetch_stored_values but without update_on_resume since the model plot is updated in the figure update callback.

property _plot_active
_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.

Returns

Return type

None

_set_current_degrees_of_freedom()
_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.

Returns

Return type

None

_set_p0()
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.

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

Extend list by appending elements from the iterable.

fetch_stored_values(only_fixed=False, update_on_resume=True)

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

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.

fetch_values_from_array(array, array_std=None)

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

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.

Read more in the User Guide.

Parameters
  • optimizer (str or None, default None) –

    The optimization algorithm used to perform the fitting.

    • ”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.

  • 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", "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 in ["lm", "trf", ``"dogbox"].

  • bounded (bool, default False) – If True, performs bounded parameter optimization if supported by optimizer.

  • update_plot (bool, 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_info (bool, 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_info (bool, default True) – If True, returns the fitting results in the form of a scipy.optimize.OptimizeResult object.

  • fd_scheme (str {"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 "lm", "trf" or "dogbox".

  • **kwargs (keyword arguments) – 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

Return type

None

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.

See also

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.

Returns

Return type

None

See also

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

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_boundaries(bounded=True)
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(bounded=True)
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'])
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'])
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(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.

class hyperspy.model.ModelSpecialSlicers(model, isNavigation)

Bases: object

hyperspy.model._check_deprecated_optimizer(optimizer)

Can be removed in HyperSpy 2.0

hyperspy.model.reconstruct_component(comp_dictionary, **init_args)