hyperspy.axes module

class hyperspy.axes.AxesManager(axes_list)

Bases: traits.has_traits.HasTraits

Contains and manages the data axes.

It supports indexing, slicing, subscripting and iteration. As an iterator, iterate over the navigation coordinates returning the current indices. It can only be indexed and sliced to access the DataAxis objects that it contains. Standard indexing and slicing follows the “natural order” as in Signal, i.e. [nX, nY, …,sX, sY,…] where n indicates a navigation axis and s a signal axis. In addition AxesManager support indexing using complex numbers a + bj, where b can be one of 0, 1, 2 and 3 and a a valid index. If b is 3 AxesManager is indexed using the order of the axes in the array. If b is 1(2), indexes only the navigation(signal) axes in the natural order. In addition AxesManager supports subscription using axis name.

coordinates

Get and set the current coordinates if the navigation dimension is not 0. If the navigation dimension is 0 it raises AttributeError when attempting to set its value.

Type

tuple

indices

Get and set the current indices if the navigation dimension is not 0. If the navigation dimension is 0 it raises AttributeError when attempting to set its value.

Type

tuple

signal_axes, navigation_axes

Contain the corresponding DataAxis objects

Type

list

Examples

Create a spectrum with random data

>>> s = hs.signals.Signal1D(np.random.random((2,3,4,5)))
>>> s.axes_manager
<Axes manager, axes: (4, 3, 2|5)>
            Name |   size |  index |  offset |   scale |  units
================ | ====== | ====== | ======= | ======= | ======
     <undefined> |      4 |      0 |       0 |       1 | <undefined>
     <undefined> |      3 |      0 |       0 |       1 | <undefined>
     <undefined> |      2 |      0 |       0 |       1 | <undefined>
---------------- | ------ | ------ | ------- | ------- | ------
     <undefined> |      5 |        |       0 |       1 | <undefined>
>>> s.axes_manager[0]
<Unnamed 0th axis, size: 4, index: 0>
>>> s.axes_manager[3j]
<Unnamed 2nd axis, size: 2, index: 0>
>>> s.axes_manager[1j]
<Unnamed 0th axis, size: 4, index: 0>
>>> s.axes_manager[2j]
<Unnamed 3rd axis, size: 5>
>>> s.axes_manager[1].name = "y"
>>> s.axes_manager["y"]
<y axis, size: 3, index: 0>
>>> for i in s.axes_manager:
...     print(i, s.axes_manager.indices)
...
(0, 0, 0) (0, 0, 0)
(1, 0, 0) (1, 0, 0)
(2, 0, 0) (2, 0, 0)
(3, 0, 0) (3, 0, 0)
(0, 1, 0) (0, 1, 0)
(1, 1, 0) (1, 1, 0)
(2, 1, 0) (2, 1, 0)
(3, 1, 0) (3, 1, 0)
(0, 2, 0) (0, 2, 0)
(1, 2, 0) (1, 2, 0)
(2, 2, 0) (2, 2, 0)
(3, 2, 0) (3, 2, 0)
(0, 0, 1) (0, 0, 1)
(1, 0, 1) (1, 0, 1)
(2, 0, 1) (2, 0, 1)
(3, 0, 1) (3, 0, 1)
(0, 1, 1) (0, 1, 1)
(1, 1, 1) (1, 1, 1)
(2, 1, 1) (2, 1, 1)
(3, 1, 1) (3, 1, 1)
(0, 2, 1) (0, 2, 1)
(1, 2, 1) (1, 2, 1)
(2, 2, 1) (2, 2, 1)
(3, 2, 1) (3, 2, 1)
_am_indices_generator()
_append_axis(*args, **kwargs)
_array_indices_generator()
_axes_getter(y)
_convert_axes_to_same_units(axes, units, factor=0.25)
_get_axes_dicts(axes=None)
_get_axes_in_natural_order()
_get_axis_attribute_values(attr)
_get_data_slice(fill=None)

Return a tuple of slice objects to slice the data.

Parameters

fill (None or iterable of (int, slice)) – If not None, fill the tuple of index int with the given slice.

_get_dimension_str()
_get_navigation_axes_dicts()
_get_positive_index(axis)
_get_signal_axes_dicts()
property _navigation_shape_in_array
_on_index_changed()
_on_offset_changed()
_on_scale_changed()
_on_size_changed()
_on_slice_changed()
_remove_one_axis(axis)

Remove the given Axis.

Raises

ValueError – If the Axis is not present.

_repr_html_()
_set_axis_attribute_values(attr, values)

Set the given attribute of all the axes to the given value(s)

Parameters
  • attr (string) – The DataAxis attribute to set.

  • values (any) – If iterable, it must have the same number of items as axes are in this AxesManager instance. If not iterable, the attribute of all the axes are set to the given value.

property _signal_shape_in_array
_sort_axes()

Sort _axes to align them.

When the data are aligned with the axes the axes order in self._axes is [nav_n, nav_n-1, …, nav_0, sig_m, sig_m-1 …, sig_0]. This method sort the axes in this way. Warning: this doesn’t sort the data axes.

_update_attributes()
_update_max_index()
_update_trait_handlers(remove=False)
as_dictionary()
property axes_are_aligned_with_data

Verify if the data axes are aligned with the signal axes.

When the data are aligned with the axes the axes order in self._axes is [nav_n, nav_n-1, …, nav_0, sig_m, sig_m-1 …, sig_0].

Returns

aligned

Return type

bool

convert_units(axes=None, units=None, same_units=True, factor=0.25)

Convert the scale and the units of the selected axes. If the unit of measure is not supported by the pint library, the scale and units are not changed.

Parameters
  • axes ({int | string | iterable of DataAxis | None}) – Default = None Convert to a convenient scale and units on the specified axis. If int, the axis can be specified using the index of the axis in axes_manager. If string, argument can be navigation or signal to select the navigation or signal axes. The axis name can also be provided. If None, convert all axes.

  • units ({list of string of the same length than axes | str | None}) – Default = None If list, the selected axes will be converted to the provided units. If str, the navigation or signal axes will be converted to the provided units. If None, the scale and the units are converted to the appropriate scale and units to avoid displaying scalebar with >3 digits or too small number. This can be tweaked by the factor argument.

  • same_units (bool) – If True, force to keep the same units if the units of the axes differs. It only applies for the same kind of axis, navigation or signal. By default the converted units of the first axis is used for all axes. If False, convert all axes individually.

  • factor (float (default: 0.25)) – ‘factor’ is an adjustable value used to determine the prefix of the units. The product factor * scale * size is passed to the pint to_compact method to determine the prefix.

property coordinates

Get the coordinates of the navigation axes.

Returns

Return type

list

copy()
create_axes(axes_list)

Given a list of dictionaries defining the axes properties create the DataAxis instances and add them to the AxesManager.

The index of the axis in the array and in the _axes lists can be defined by the index_in_array keyword if given for all axes. Otherwise it is defined by their index in the list.

See also

_append_axis

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

gui_navigation_sliders(title='', display=True, toolkit=None)

Navigation sliders to control the index of the navigation axes.

Parameters
  • title (str) –

  • %s

  • %s

property indices

Get the index of the navigation axes.

Returns

Return type

list

key_navigator(event)

Set hotkeys for controlling the indices of the navigator plot

property navigation_extent
property navigation_indices_in_array
remove(axes)

Remove one or more axes

set_signal_dimension(value)

Set the dimension of the signal.

value
Type

int

Raises

ValueError – If value if greater than the number of axes or is negative.

property shape
show()
property signal_extent
property signal_indices_in_array
update_axes_attributes_from(axes, attributes=['scale', 'offset', 'units'])

Update the axes attributes to match those given.

The axes are matched by their index in the array. The purpose of this method is to update multiple axes triggering any_axis_changed only once.

Parameters
  • axes (iterable of DataAxis instances.) – The axes to copy the attributes from.

  • attributes (iterable of strings.) – The attributes to copy.

class hyperspy.axes.DataAxis(size, index_in_array=None, name=<undefined>, scale=1.0, offset=0.0, units=<undefined>, navigate=<undefined>)

Bases: traits.has_traits.HasTraits, hyperspy.axes.UnitConversion

_get_array_slices(slice_)

Returns a slice to slice the corresponding data axis without changing the offset and scale of the DataAxis.

Parameters

slice ({float, int, slice}) –

Returns

my_slice

Return type

slice

_get_index(value)
_get_name()
_get_positive_index(index)
_index_changed(name, old, new)
_parse_string_for_slice(value)
_slice_me(slice_)

Returns a slice to slice the corresponding data axis and change the offset and scale of the DataAxis accordingly.

Parameters

slice ({float, int, slice}) –

Returns

my_slice

Return type

slice

_update_slice(value)
_value_changed(name, old, new)
calibrate(value_tuple, index_tuple, modify_calibration=True)
copy()
get_axis_dictionary()
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.

index2value(index)
property index_in_array
property index_in_axes_manager
property offset_as_quantity
property scale_as_quantity
update_axis()
update_from(axis, attributes=['scale', 'offset', 'units'])

Copy values of specified axes fields from the passed AxesManager.

Parameters
  • axis (DataAxis) – The DataAxis instance to use as a source for values.

  • attributes (iterable container of strings.) – The name of the attribute to update. If the attribute does not exist in either of the AxesManagers, an AttributeError will be raised.

Returns

Return type

A boolean indicating whether any changes were made.

update_index_bounds()
value2index(value, rounding=<built-in function round>)

Return the closest index to the given value if between the limit.

Parameters

value (number or numpy array) –

Returns

index

Return type

integer or numpy array

Raises

ValueError – If any value is out of the axis limits.

value_range_to_indices(v1, v2)

Convert the given range to index range.

When an out of the axis limits, the endpoint is used instead.

Parameters
  • v1 (float) – The end points of the interval in the axis units. v2 must be greater than v1.

  • v2 (float) – The end points of the interval in the axis units. v2 must be greater than v1.

class hyperspy.axes.UnitConversion(units=<undefined>, scale=1.0, offset=0.0)

Bases: object

_convert_compact_units(factor=0.25, inplace=True)

Convert units to “human-readable” units, which means with a convenient prefix.

Parameters
  • factor (float (default: 0.25)) –

  • is an adjustable value used to determine the prefix of ('factor') –

  • units. The product factor * scale * size is passed to the (the) –

  • to_compact method to determine the prefix. (pint) –

_convert_units(converted_units, inplace=True)
_get_index_from_value_with_units(value)
_get_quantity(attribute='scale')
_ignore_conversion(units)
_set_quantity(value, attribute='scale')
convert_to_units(units=None, inplace=True, factor=0.25)

Convert the scale and the units of the current axis. If the unit of measure is not supported by the pint library, the scale and units are not modified.

Parameters
  • units ({str | None}) – Default = None If str, the axis will be converted to the provided units. If “auto”, automatically determine the optimal units to avoid using too large or too small numbers. This can be tweaked by the factor argument.

  • inplace (bool) – If True, convert the axis in place. if False return the scale, offset and units.

  • factor (float (default: 0.25)) – ‘factor’ is an adjustable value used to determine the prefix of the units. The product factor * scale * size is passed to the pint to_compact method to determine the prefix.

property units
hyperspy.axes.generate_axis(offset, scale, size, offset_index=0)

Creates an axis given the offset, scale and number of channels

Alternatively, the offset_index of the offset channel can be specified.

Parameters
  • offset (float) –

  • scale (float) –

  • size (number of channels) –

  • offset_index (int) – offset_index number of the offset

Returns

Return type

Numpy array

class hyperspy.axes.ndindex_nat(*shape)

Bases: numpy.ndindex

hyperspy.axes.serpentine_iter(shape)

Similar to np.ndindex, but yields indices in serpentine pattern, like snake game

Code by Stackoverflow user Paul Panzer, from https://stackoverflow.com/questions/57366966/