hyperspy package

Subpackages

Submodules

hyperspy.Release module

hyperspy.api module

hyperspy.axes module

hyperspy.component module

hyperspy.components1d module

hyperspy.components2d module

hyperspy.decorators module

hyperspy.defaults_parser module

hyperspy.events module

class hyperspy.events.Event(doc='', arguments=None)

Bases: object

arguments
connect(function, kwargs='all')

Connects a function to the event. Arguments: ———- function : callable

The function to call when the event triggers.
kwargs : {tuple or list, dictionary, ‘all’, ‘auto’}, default “all”
If “all”, all the trigger keyword arguments are passed to the function. If a list or tuple of strings, only those keyword arguments that are in the tuple or list are passed. If empty, no keyword argument is passed. If dictionary, the keyword arguments of trigger are mapped as indicated in the dictionary. For example, {“a” : “b”} maps the trigger argument “a” to the function argument “b”.

See also

disconnect()

connected

Connected functions.

disconnect(function)

Disconnects a function from the event. The passed function will be disconnected irregardless of which ‘nargs’ argument was passed to connect().

If you only need to temporarily prevent a function from being called, single callback suppression is supported by the suppress_callback context manager. :param function: :type function: function :param return_connection_kwargs: If True, returns the kwargs that would reconnect the function as

it was.

See also

connect(), suppress_callback()

suppress()

Use this function with a ‘with’ statement to temporarily suppress all events in the container. When the ‘with’ lock completes, the old suppression values will be restored.

>>> with obj.events.myevent.suppress():
...     # These would normally both trigger myevent:
...     obj.val_a = a
...     obj.val_b = b
>>> # Trigger manually once:
>>> obj.events.myevent.trigger()

See also

suppress_callback(), Events.suppress()

suppress_callback(function)

Use this function with a ‘with’ statement to temporarily suppress a single callback from being called. All other connected callbacks will trigger. When the ‘with’ lock completes, the old suppression value will be restored.

>>> with obj.events.myevent.suppress_callback(f):
...     # Events will trigger as normal, but `f` will not be called
...     obj.val_a = a
...     obj.val_b = b
>>> # Here, `f` will be called as before:
>>> obj.events.myevent.trigger()

See also

suppress(), Events.suppress()

trigger(**kwargs)

Triggers the event. If the event is suppressed, this does nothing. Otherwise it calls all the connected functions with the arguments as specified when connected.

See also

suppress(), suppress_callback(), Events.suppress()

class hyperspy.events.EventSupressor(*to_suppress)

Bases: object

Object to enforce a variety of suppression types simultaneously

Targets to be suppressed can be added by the function add(), or given in the constructor. Valid targets are:

  • Event: The entire Event will be suppressed
  • Events: All events in th container will be suppressed
  • (Event, callback): The callback will be suppressed in Event
  • (Events, callback): The callback will be suppressed in each event in
    Events where it is connected.
  • Any iterable collection of the above target types
>>> es = EventSupressor((event1, callback1), (event1, callback2))
>>> es.add(event2, callback2)
>>> es.add(event3)
>>> es.add(events_container1)
>>> es.add(events_container2, callback1)
>>> es.add(event4, (events_container3, callback2))
>>>
>>> with es.supress():
...     do_something()
add(*to_suppress)

Add one or more targets to be suppressed

Valid targets are:
  • Event: The entire Event will be suppressed
  • Events: All events in the container will be suppressed
  • (Event, callback): The callback will be suppressed in Event
  • (Events, callback): The callback will be suppressed in each event in Events where it is connected.
  • Any iterable collection of the above target types
suppress()

Use this function with a ‘with’ statement to temporarily suppress all events added. When the ‘with’ lock completes, the old suppression values will be restored.

See also

Events.suppress(), Event.suppress(), Event.suppress_callback()

class hyperspy.events.Events

Bases: object

Events container.

All available events are attributes of this class.

suppress()

Use this function with a ‘with’ statement to temporarily suppress all callbacks of all events in the container. When the ‘with’ lock completes, the old suppression values will be restored.

>>> with obj.events.suppress():
...     # Any events triggered by assignments are prevented:
...     obj.val_a = a
...     obj.val_b = b
>>> # Trigger one event instead:
>>> obj.events.values_changed.trigger()

See also

Event.suppress(), Event.suppress_callback()

hyperspy.exceptions module

exception hyperspy.exceptions.ByteOrderError(order='')

Bases: Exception

exception hyperspy.exceptions.DM3DataTypeError(value='')

Bases: Exception

exception hyperspy.exceptions.DM3FileVersionError(value='')

Bases: Exception

exception hyperspy.exceptions.DM3TagError(value='')

Bases: Exception

exception hyperspy.exceptions.DM3TagIDError(value='')

Bases: Exception

exception hyperspy.exceptions.DM3TagTypeError(value='')

Bases: Exception

exception hyperspy.exceptions.DataDimensionError(msg)

Bases: Exception

exception hyperspy.exceptions.ImageIDError(value='')

Bases: Exception

exception hyperspy.exceptions.ImageModeError(value='')

Bases: Exception

exception hyperspy.exceptions.MissingParametersError(parameters)

Bases: Exception

exception hyperspy.exceptions.NavigationDimensionError(navigation_dimension, expected_navigation_dimension)

Bases: Exception

exception hyperspy.exceptions.NavigationSizeError(navigation_size, expected_navigation_size)

Bases: Exception

exception hyperspy.exceptions.NoInteractiveError

Bases: Exception

exception hyperspy.exceptions.ShapeError(value)

Bases: Exception

exception hyperspy.exceptions.SignalDimensionError(output_dimension, expected_output_dimension)

Bases: Exception

exception hyperspy.exceptions.SignalSizeError(signal_size, expected_signal_size)

Bases: Exception

exception hyperspy.exceptions.VisibleDeprecationWarning

Bases: UserWarning

Visible deprecation warning. By default, python will not show deprecation warnings, so this class provides a visible one.

exception hyperspy.exceptions.WrongObjectError(is_str, must_be_str)

Bases: Exception

hyperspy.interactive module

class hyperspy.interactive.Interactive(f, event='auto', recompute_out_event='auto', *args, **kwargs)

Bases: object

Chainable operations on Signals that update on events.

recompute_out()
update()
hyperspy.interactive.interactive(f, event='auto', recompute_out_event='auto', *args, **kwargs)

Update operation result when a given event is triggered.

Parameters:
  • f (function or method) – A function that returns an object and that optionally can place the result in an object given through the out keyword.
  • event ({Event, "auto", None, iterable of events}) – Update the result of the operation when the event is triggered. If “auto” and f is a method of a Signal class instance its data_changed event is selected if the function takes an out argument. If None, update is not connected to any event. The default is “auto”. It is also possible to pass an iterable of events, in which case all the events are connected.
  • recompute_out_event ({Event, "auto", None, iterable of events}) – Optional argument. If supplied, this event causes a full recomputation of a new object. Both the data and axes of the new object are then copied over to the existing out object. Only useful for Signal or other objects that have an attribute axes_manager. If “auto” and f is a method of a Signal class instance its AxesManager any_axis_chaged event is selected. Otherwise the Signal data_changed event is selected. If None, recompute_out is not connected to any event. The default is “auto”. It is also possible to pass an iterable of events, in which case all the events are connected.
*args, **kwargs
Arguments and keyword arguments to be passed to f.

hyperspy.io module

hyperspy.logger module

hyperspy.logger.set_log_level(level)

Convenience function to set the log level of all hyperspy modules.

Note: The log level of all other modules are left untouched.

Parameters:level ({int | str}) –

The log level to set. Any values that logging.Logger.setLevel() accepts are valid. The default options are:

  • ‘CRITICAL’
  • ‘ERROR’
  • ‘WARNING’
  • ‘INFO’
  • ‘DEBUG’
  • ‘NOTSET’

For normal logging of hyperspy functions, you can set the log level like this:

>>> import hyperspy.api as hs
>>> hs.set_log_level('INFO')
>>> hs.load(r'my_file.dm3')
INFO:hyperspy.io_plugins.digital_micrograph:DM version: 3
INFO:hyperspy.io_plugins.digital_micrograph:size 4796607 B
INFO:hyperspy.io_plugins.digital_micrograph:Is file Little endian? True
INFO:hyperspy.io_plugins.digital_micrograph:Total tags in root group: 15
<Signal2D, title: My file, dimensions: (|1024, 1024)>

If you need the log output during the initial import of hyperspy, you should set the log level like this:

>>> from hyperspy.logger import set_log_level
>>> set_log_level('DEBUG')
>>> import hyperspy.api as hs
DEBUG:hyperspy.gui:Loading hyperspy.gui
DEBUG:hyperspy.gui:Current MPL backend: TkAgg
DEBUG:hyperspy.gui:Current ETS toolkit: qt4
DEBUG:hyperspy.gui:Current ETS toolkit set to: null

hyperspy.messages module

hyperspy.messages.alert(text)
hyperspy.messages.information(text)
hyperspy.messages.warning(text)
hyperspy.messages.warning_exit(text)

hyperspy.model module

hyperspy.roi module

hyperspy.samfire module

hyperspy.signal module

hyperspy.signals module

Module contents

HyperSpy: a multi-dimensional data analysis package for Python

Documentation is available in the docstrings and online at http://hyperspy.org/hyperspy-doc/current/index.html.

All public packages, functions and classes are in api. All other packages and modules are for internal consumption and should not be needed for data analysis.

When starting HyperSpy using the hyperspy script (e.g. by executing hyperspy in a console, using the context menu entries or using the links in the Start Menu, the api package is imported in the user namespace as hs, i.e. by executing the following:

>>> import hyperspy.api as hs

(Note that code snippets are indicated by three greater-than signs)

We recommend to import the HyperSpy API as above also when doing it manually. The docstring examples assume that hyperspy has been imported as hs, numpy as np and matplotlib.pyplot as plt.

More details in the api docstring.