网页 综合 更新时间 2026-11-17 07:00:00

Writing packages that extend HyperSpy — HyperSpy 2.5.0 documentation

自动蜘蛛 hyperspy.org 正文约 6000 字
Added in version 1.5: External packages can extend HyperSpy by registering signals, components and widgets.
External packages can extend HyperSpy by registering signals, components and widgets. Objects registered by external packages are “first-class citizens” i.e. they can be used, saved and loaded like any of those objects shipped with HyperSpy. Because of HyperSpy’s structure, we anticipate that most packages registering HyperSpy extensions will provide support for specific sorts of data.
Models can also be provided by external packages, but don’t need to be registered. Instead, they are returned by the create_model method of the relevant BaseSignal subclass, see for example, the exspy.signals.EDSTEMSpectrum.create_model() of the exspy.signals.EDSTEMSpectrum.
It is good practice to add all packages that extend HyperSpy to the list of known extensions regardless of their maturity level. In this way, we can avoid duplication of efforts and issues arising from naming conflicts. This repository also runs an integration test suite daily, which runs the test suite of all extensions to check the status of the ecosystem. See the corresponding section for more details.
At this point, it is worth noting that HyperSpy’s main strength is its amazing community of users and developers. We trust that the developers of packages that extend HyperSpy will play by the same rules that have made the Python scientific ecosystem successful. In particular, avoiding duplication of efforts and being good community players by contributing code to the best matching project are essential for the sustainability of our open software ecosystem.
In order to register HyperSpy extensions, you need to:
Add the following line to your package’s setup.py:
Create a hyperspy_extension.yaml configuration file in your module’s root directory.
Declare all new HyperSpy objects provided by your package in the hyperspy_extension.yaml file.
For a full example on how to create a package that extends HyperSpy, see the HyperSpy Sample Extension package.
HyperSpy provides most of its functionality through the different BaseSignal subclasses. A HyperSpy “signal” is a class that contains data for analysis and functions to perform the analysis in the form of class methods. Functions that are useful for the analysis of most datasets are in the BaseSignal class. All other functions are in specialized subclasses.
The flowchart below can help you decide where to add a new data analysis function. Notice that only if no suitable package exists for your function, you should consider creating your own.
To register a new BaseSignal subclass you must add it to the hyperspy_extension.yaml file, as in the following example:
Note that HyperSpy uses signal_type to determine which class is the most appropriate to deal with a particular sort of data. Therefore, the signal type must be specific enough for HyperSpy to find a single signal subclass match for each sort of data.
HyperSpy assumes that only one signal subclass exists for a particular signal_type. It is up to external package developers to avoid signal_type clashes, typically by collaborating in developing a single package per data type.
The optional signal_type_aliases are used to determine the most appropriate signal subclass when using set_signal_type(). For example, if the signal_type Electron Energy Loss Spectroscopy has an EELS alias, setting the signal type to EELS will correctly assign the signal subclass with Electron Energy Loss Spectroscopy signal type. It is good practice to choose a very explicit signal_type while leaving acronyms for signal_type_aliases.
Additionally, the optional key hidden: True can be defined if a signal should be registered with HyperSpy, but not listed by hyperspy.api.print_known_signal_types(). This option can be used if a signal subclass is needed for certain functionalities, such as casting to a different signal subclass, but should usually not be set directly by the user.
HyperSpy provides the hyperspy._components.expression.Expression component that enables easy creation of 1D and 2D components from mathematical expressions. Therefore, strictly speaking, we only need to create new components when they cannot be expressed as simple mathematical equations. However, HyperSpy is all about simplifying the interactive data processing workflow. Therefore, we consider that functions that are commonly used for model fitting, in general or specific domains, are worth adding to HyperSpy itself (if they are of common interest) or to specialized external packages extending HyperSpy.
The flowchart below can help you decide when and where to add a new hyperspy model hyperspy.component.Component for your function, should you consider creating your own.
All new components must be a subclass of hyperspy._components.expression.Expression. To register a new 1D component add it to the hyperspy_extension.yaml file as in the following example:
Equivalently, to add a new component 2D:
HyperSpy’s legacy components use their class name instead of a UUID as _id_name. This is for compatibility with old versions of the software. New components (including those provided through the extension mechanism) must use a UUID4 in order to i) avoid name clashes ii) make it easy to find the component online if e.g. the package is renamed or the component relocated.
The implementation of the convolution of components in subclasses of Model1D is explained in the extension gallery:
Implementation of a model supporting convolution of components
Component convolution
To generate GUIs of specific methods and functions, HyperSpy uses widgets and toolkeys:
widgets (typically ipywidgets or traitsui objects) generate GUIs,
toolkeys are functions which associate widgets to a signal method or to a module function.
An extension can declare new toolkeys and widgets. For example, the hyperspy-gui-traitsui and hyperspy-gui-ipywidgets provide widgets for toolkeys declared in HyperSpy.
To register a new toolkey:
访问原文 返回搜索 https://hyperspy.org/hyperspy-doc/current/dev_guide/writing_extensions.html
本页为82搜索生成的网页快照,内容来自站内索引;演示数据的原文链接仅作示例。