diff --git a/doc/index.rst b/doc/index.rst index a48c7607f..d76b0a4ee 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -56,6 +56,7 @@ Contents user_guide/introduction.rst user_guide/signal_axis.rst user_guide/signal_tools.rst + user_guide/streak_images.rst user_guide/fitting_luminescence.rst user_guide/utilities.rst user_guide/metadata_structure.rst diff --git a/doc/user_guide/images/streakmap.svg b/doc/user_guide/images/streakmap.svg new file mode 100644 index 000000000..819ec3641 --- /dev/null +++ b/doc/user_guide/images/streakmap.svg @@ -0,0 +1,592 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/user_guide/introduction.rst b/doc/user_guide/introduction.rst index 6452f1e13..162f6e5a7 100644 --- a/doc/user_guide/introduction.rst +++ b/doc/user_guide/introduction.rst @@ -125,8 +125,8 @@ signal types (or inheriting) signal types. The hierarchy of the LumiSpy signal types and their inheritance from HyperSpy is summarized in the following diagram: -| └── :external:class:`hyperspy.signal.BaseSignal` -| ├── :external:class:`hyperspy._signals.signal1d.Signal1D` +| └── :external:class:`hyperspy.api.signals.BaseSignal` +| ├── :external:class:`hyperspy.api.signals.Signal1D` | │ └── :class:`~.signals.luminescence_spectrum.LumiSpectrum` | │ │ ├── :class:`~.signals.cl_spectrum.CLSpectrum` | │ │ │ ├── :class:`~.signals.cl_spectrum.CLSEMSpectrum` @@ -134,11 +134,17 @@ is summarized in the following diagram: | │ │ ├── :class:`~.signals.el_spectrum.ELSpectsrum` | │ │ └── :class:`~.signals.pl_spectrum.PLSpectrum` | │ └── :class:`~.signals.luminescence_transient.LumiTransient` -| └── :class:`hyperspy.signal.Signal2D` +| └── :class:`hyperspy.api.signals.Signal2D` | └── :class:`~.signals.luminescence_transientspec.LumiTransientSpectrum` | | +A special case is the :class:`~.signals.luminescence_transientspec.LumiTransientSpectrum` +for :ref:`streak camera data `, where the two signal axes have different +units. If the signal dimensionality of this ``signal_type`` is reduced, LumiSpy +casts the signal to either the :class:`~.signals.luminescence_spectrum.LumiSpectrum` +or :class:`~.signals.luminescence_transient.LumiTransient` depending on the axes +units of the one-dimensional signal. Where are we heading? ===================== diff --git a/doc/user_guide/signal_axis.rst b/doc/user_guide/signal_axis.rst index 0dcfc54d9..1506bc918 100644 --- a/doc/user_guide/signal_axis.rst +++ b/doc/user_guide/signal_axis.rst @@ -123,8 +123,8 @@ renormalization is automatically performed by LumiSpy if ``jacobian=True``. In particular, homoscedastic (constant) noise will consequently become heteroscedastic (changing as a function of the signal axis vector). Therefore, if the ``metadata.Signal.Noise_properties.variance`` attribute is a constant, -it is converted into a :external:class:`hyperspy.api.signals.BaseSignal` object -before the transformation. +it is converted into a :external:class:` BaseSignal ` +object before the transformation. See the section on :ref:`fitting_variance` for more general information on data variance in the context of model fitting and the HyperSpy documentation on ` @@ -136,6 +136,26 @@ in the context of model fitting and the HyperSpy documentation on ` ``metadata.Signal.Noise_properties.Variance_linear_model`` are reset to their default values (``gain_factor=1``, ``gain_offset=0`` and ``correlation_factor=1``). Should these values deviate from the defaults, make sure to run - :external:meth:`hyperspy.api.signals.BaseSignal.estimate_poissonian_noise_variance` + :external:meth:`estimate_poissonian_noise_variance() + ` prior to the transformation. + +.. _interpolate_to_uniform_axes: + +Interpolation to uniform axes +============================= + +As a number of HyperSpy tools are not supporting non-uniform axes, e.g. the +:meth:`rebin() ` function, the HyperSpy function +:meth:`interpolate_on_axis() ` +provides a possibility to convert a signal with a non-uniform axis to one with +a uniform axis. This function takes the argument ``"uniform"``, which will create +a signal with the same number of data points, but a uniform axes spacing and +interpolated data at these points (the second argument in the example below is the +``axis`` number on which to operate, ``-1`` referring to the signal axis being the +last one in the ``axes_manager``): + +.. code-block:: python + + >>> s.interpolate_on_axis("uniform", -1, inplace=False) diff --git a/doc/user_guide/streak_images.rst b/doc/user_guide/streak_images.rst new file mode 100644 index 000000000..76b072510 --- /dev/null +++ b/doc/user_guide/streak_images.rst @@ -0,0 +1,53 @@ +.. _streak_images: + +Working with streak images +************************** + +LumiSpy has implemented handling of streak camera images, which are a special +subclass of :class:`hyperspy.api.signals.Signal2D` as the two signal axes have +different units: Namely, wavelength (or energy) and time. The signal class is +:class:`~.signals.luminescence_transientspec.LumiTransientSpectrum`. An important +feature is that also for streak camera images (or linescans/maps of these), the +wavelength axis can be transformed to e.g. a :ref:`energy_axis`. + +.. Note:: + + For streak images, not all tools available for :class:`Signal2D + ` will work. However, in particular + :external+hyperspy:ref:`peak_finding-label` + can be helpful to identify local maxima in the images. + + +Transition to one-dimensional signals +===================================== + +When transitioning from a streak image to a one-dimensional signal, LumiSpy +uses the axes units of the new signal (whether it is time units or not) to +assign the correct 1D signal class: Either :class:`~.signals.luminescence_spectrum.LumiSpectrum` or +:class:`~.signals.luminescence_transient.LumiTransient`. Such a reduction of the signal dimensionality +can be done for example by slicing the signal with +:external+hyperspy:ref:`numpy-style indexing ` or by using +functions such as :external:meth:`sum() ` +and :external:meth:`integrate1D() ` + +In the following image, the spectrum summed over all times is obtained from the +streak image by: + +.. code-block:: python + + >>> s.sum(axis='Time') + >>> # Or alternatively: + >>> s.sum(axis=-1) + +Similarly, the transient summed over all wavelengths is obtained by: + +.. code-block:: python + + >>> s.sum(axis='Wavelength') + >>> # Or alternatively: + >>> s.sum(axis=-2) + +.. image:: images/streakmap.svg + :width: 700 + :alt: Plot of a streak camera image and its one-dimensional representations + obtained by summing over either the wavelength or time dimensions. diff --git a/upcoming_changes/205.new.rst b/upcoming_changes/205.new.rst index 536335c94..c629bc37d 100644 --- a/upcoming_changes/205.new.rst +++ b/upcoming_changes/205.new.rst @@ -1 +1 @@ -Implement correct casting of :class:`LumiTransientSpectrum` to either :class:`Luminescence` or :class:`Transient` when the signal dimension is reduced +Implement correct casting of :class:`~.signals.luminescence_transientspec.LumiTransientSpectrum` to either :class:`~.signals.luminescence_spectrum.LumiSpectrum` or :class:`~.signals.luminescence_transient.LumiTransient` when the signal dimension is reduced