add user_guide chapter

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

doc/user_guide/introduction.rst

@@ -125,20 +125,26 @@ 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` 
 |           │       │       │       └── :class:`~.signals.cl_spectrum.CLSTEMSpectrum` 
 |           │       │       ├── :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 <streak_images>`, 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?
 =====================

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 <hyperspy.api.signals.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()
+    <hyperspy.api.signals.BaseSignal.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() <hyperspy.api.signals.BaseSignal.rebin>` function, the HyperSpy function
+:meth:`interpolate_on_axis() <hyperspy.api.signals.BaseSignal.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)

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
+    <hyperspy.api.signals.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 <signal.indexing>` or by using
+functions such as :external:meth:`sum() <hyperspy.api.signals.BaseSignal.sum>`
+and :external:meth:`integrate1D() <hyperspy.api.signals.BaseSignal.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.

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