Added support for complex data

doc/user_guide/dielectric_function.rst

@@ -3,6 +3,23 @@ Dielectric function tools
 
 .. versionadded:: 0.7
 
+The :py:class:`~.signals.dielectric_function.DielectricFunction` class inherits from
+:py:class:`~.signals.complex_signal.ComplexSignal` and can thus access complex properties.
+To convert a :py:class:`~.signals.complex_signal.ComplexSignal` to a
+:py:class:`~.signals.dielectric_function.DielectricFunction`, make sure that the signal dimension
+and signyl type are properly set:
+
+    .. code-block:: python
+
+        >>> self.metadata.Signal.record_by = 'spectrum'
+        >>> s.set_signal_type('DielectricFunction')
+
+Note that a :py:class:`~._signals.dielectric_function.DielectricFunction` does not inherit from
+:py:class:`~._signals.signal1d.Signal1D`, because most functionality can not operate on complex
+data.
+
+
+
 Number of effective electrons
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

doc/user_guide/eds.rst

@@ -29,7 +29,7 @@ downloaded using:
     >>> urlretrieve(url + 'Ni_superalloy_010.raw', 'Ni_superalloy_010.raw')
 
 Loading data
-^^^^^^^^
+^^^^^^^^^^^^
 
 All data are loaded with the :py:func:`~.io.load` function, as described in detail in
 :ref:`Loading files<loading_files>`. HyperSpy is able to import different formats,

doc/user_guide/electron_holography.rst

@@ -0,0 +1,42 @@
+Electron Holography
+*******************
+
+HyperSpy provides the user with a class which can be used to process electron holography data and
+electron wave data in general:
+
+* :py:class:`~._signals.electron_wave_image.ElectronWaveImage`
+
+The usage of the class is explained in the following sections.
+
+
+
+The ElectronWaveImage class
+===========================
+
+The :py:class:`~._signals.electron_wave_image.ElectronWaveImage` class can hold information about
+the complex electron wave. It inherits from :py:class:`~._signals.complex_signal.ComplexSignal`
+and as such relevant properties like the `amplitude`, `phase` and the `real` and `imag` part of
+the complex data can be directly accessed and return appropriate
+:py:class:`~._signals.signal2d.Signal2D` signals.
+
+To transform a complex signal into a :py:class:`~._signals.electron_wave_image.ElectronWaveImage`
+use:
+
+.. code-block:: python
+
+    >>> s.metadata.Signal.record_by = 'image'
+    >>> s.set_signal_type('electron wave')
+
+Note that a :py:class:`~._signals.electron_wave_image.ElectronWaveImage` does not inherit from
+:py:class:`~._signals.signal2d.Signal2D`, because most functionality can not operate on complex
+data.
+
+
+Add a linear phase ramp
+-----------------------
+
+A linear phase ramp can be added to the signal via the :py:func:`~._signals.signal2d.Signal2D.add_phase_ramp`
+method. The parameters `ramp_x` and `ramp_y` dictate the slope of the ramp in `x`- and `y` direction,
+while the offset is determined by the `offset` parameter. The fulcrum of the linear ramp is at the origin
+and the slopes are given in units of the axis with the according scale taken into account.
+Both are available via the :py:class:`~.axes.AxesManager` of the signal.

doc/user_guide/index.rst

@@ -23,6 +23,7 @@ HyperSpy User Guide (DRAFT)
     eels.rst
     eds.rst
     dielectric_function.rst
+    electron_holography.rst
     io.rst
     events.rst
     metadata_structure.rst

doc/user_guide/mva.rst

@@ -143,7 +143,7 @@ the decomposition model. You can easily calculate and display the residuals:
     the model constructed using the chosen components.
 
 Non-negative matrix factorization
-----------------------------
+---------------------------------
 
 Another popular decomposition method is non-negative matrix factorization (NMF), which
 can be accessed in HyperSpy with:

doc/user_guide/signal2d.rst

@@ -22,3 +22,13 @@ the following method is available to crop spectra the familiar top, bottom,
 left, right syntax.
 
 * :py:meth:`~._signals.signal2d.Signal2DTools.crop_image`
+
+
+Add a linear ramp
+-----------------
+
+A linear ramp can be added to the signal via the :py:func:`~._signals.signal2d.Signal2D.add_ramp`
+method. The parameters `ramp_x` and `ramp_y` dictate the slope of the ramp in `x`- and `y` direction,
+while the offset is determined by the `offset` parameter. The fulcrum of the linear ramp is at the origin
+and the slopes are given in units of the axis with the according scale taken into account.
+Both are available via the :py:class:`~.axes.AxesManager` of the signal.

doc/user_guide/tools.rst

@@ -27,11 +27,13 @@ spectroscopy data analysis.
 
 Currently the following signal subclasses are available:
 
+* :py:class:`~._signals.complex_signal.ComplexSignal`
 * :py:class:`~._signals.signal1d.Signal1D`
 * :py:class:`~._signals.signal2d.Signal2D`
 * :py:class:`~._signals.eels.EELSSpectrum`
 * :py:class:`~._signals.eds_tem.EDSTEMSpectrum`
 * :py:class:`~._signals.eds_sem.EDSSEMSpectrum`
+* :py:class:`~._signals.electron_wave_image.ElectronWaveImage`
 * :py:class:`~._signals.spectrum_simulation.SpectrumSimulation`
 * :py:class:`~._signals.image_simulation.ImageSimulation`
 
@@ -62,12 +64,12 @@ information (including calibration) can be accessed (and modified) in the
 Transforming between signal subclasses
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The different subclasses are characterized by three
+The different subclasses are characterized by four
 :py:attr:`~.signal.BaseSignal.metadata` attributes (see the table below):
 
 `record_by`
     Can be "spectrum", "image" or "", the latter meaning undefined and describes
-    the way the data is arranged in memory. It is possible to transform any
+    the way the data is arranged in memory. It is possible to transform any non-complex
     :py:class:`~.signal.BaseSignal` subclass to a :py:class:`~._signals.signal1d.Signal1D`
     or :py:class:`~._signals.signal2d.Signal2D` subclass using the following
     :py:class:`~.signal.BaseSignal` methods: :py:meth:`~.signal.BaseSignal.as_signal2D`
@@ -95,27 +97,36 @@ The different subclasses are characterized by three
     :py:meth:`~.signal.BaseSignal.set_signal_origin` changes the signal_origin in place,
     which may result in a :py:class:`~.signal.BaseSignal` subclass transformation.
 
+`dtype`
+    Describes the underlying data type of the signal data and is determined automatically.
+    Can be "real" or "complex". It is important to note that `data` passed to the constructor of a
+    :py:class:`~._signals.complex_signal.ComplexSignal`, which is not already complex, will be
+    converted to the numpy standard of `np.complex`/`np.complex128`. `data` which is already
+    complex will be passed as is.
+
 .. table:: BaseSignal subclass :py:attr:`~.signal.BaseSignal.metadata` attributes.
 
-    +---------------------------------------------------------------+-----------+-------------+---------------+
-    |                      BaseSignal subclass                      | record_by | signal_type | signal_origin |
-    +===============================================================+===========+=============+===============+
-    |                 :py:class:`~.signal.BaseSignal`               |     -     |      -      |       -       |
-    +---------------------------------------------------------------+-----------+-------------+---------------+
-    |           :py:class:`~._signals.signal1d.Signal1D`            | spectrum  |      -      |       -       |
-    +---------------------------------------------------------------+-----------+-------------+---------------+
-    | :py:class:`~._signals.spectrum_simulation.SpectrumSimulation` | spectrum  |      -      |  simulation   |
-    +---------------------------------------------------------------+-----------+-------------+---------------+
-    |           :py:class:`~._signals.eels.EELSSpectrum`            | spectrum  |    EELS     |       -       |
-    +---------------------------------------------------------------+-----------+-------------+---------------+
-    |           :py:class:`~._signals.eds_sem.EDSSEMSpectrum`       | spectrum  |   EDS_SEM   |       -       |
-    +---------------------------------------------------------------+-----------+-------------+---------------+
-    |           :py:class:`~._signals.eds_tem.EDSTEMSpectrum`       | spectrum  |   EDS_TEM   |       -       |
-    +---------------------------------------------------------------+-----------+-------------+---------------+
-    |              :py:class:`~._signals.signal2d.Signal2D`         |   image   |      -      |       -       |
-    +---------------------------------------------------------------+-----------+-------------+---------------+
-    |    :py:class:`~._signals.image_simulation.ImageSimulation`    |   image   |      -      |  simulation   |
-    +---------------------------------------------------------------+-----------+-------------+---------------+
+    +---------------------------------------------------------------+-----------+---------------+---------------+---------+
+    |                      BaseSignal subclass                      | record_by |  signal_type  | signal_origin |  dtype  |
+    +===============================================================+===========+===============+===============+=========+
+    |                 :py:class:`~.signal.BaseSignal`               |     -     |       -       |       -       |  real   |
+    +---------------------------------------------------------------+-----------+---------------+---------------+---------+
+    |      :py:class:`~._signals.complex_signal.ComplexSignal`      |     -     |       -       |       -       | complex |
+    +---------------------------------------------------------------+-----------+---------------+---------------+---------+
+    |           :py:class:`~._signals.signal1d.Signal1D`            | spectrum  |       -       |       -       |  real   |
+    +---------------------------------------------------------------+-----------+---------------+---------------+---------+
+    | :py:class:`~._signals.spectrum_simulation.SpectrumSimulation` | spectrum  |       -       |  simulation   |  real   |
+    +---------------------------------------------------------------+-----------+---------------+---------------+---------+
+    |           :py:class:`~._signals.eels.EELSSpectrum`            | spectrum  |     EELS      |       -       |  real   |
+    +---------------------------------------------------------------+-----------+---------------+---------------+---------+
+    |           :py:class:`~._signals.eds_sem.EDSSEMSpectrum`       | spectrum  |    EDS_SEM    |       -       |  real   |
+    +---------------------------------------------------------------+-----------+---------------+---------------+---------+
+    |              :py:class:`~._signals.signal2d.Signal2D`         |   image   |       -       |       -       |  real   |
+    +---------------------------------------------------------------+-----------+---------------+---------------+---------+
+    | :py:class:`~._signals.electron_wave_image.ElectronWaveImage`  |   image   | electron_wave |       -       | complex |
+    +---------------------------------------------------------------+-----------+---------------+---------------+---------+
+    |    :py:class:`~._signals.image_simulation.ImageSimulation`    |   image   |       -       |  simulation   |  real   |
+    +---------------------------------------------------------------+-----------+---------------+---------------+---------+
 
 
 The following example shows how to transform between different subclasses.
@@ -198,6 +209,8 @@ following table:
     +===============================================================+========+
     |                 :py:class:`~.signal.BaseSignal`               | False  |
     +---------------------------------------------------------------+--------+
+    |      :py:class:`~._signals.complex_signal.ComplexSignal`      | False  |
+    +---------------------------------------------------------------+--------+
     |           :py:class:`~._signals.signal1d.Signal1D`            | False  |
     +---------------------------------------------------------------+--------+
     | :py:class:`~._signals.spectrum_simulation.SpectrumSimulation` | False  |
@@ -210,6 +223,8 @@ following table:
     +---------------------------------------------------------------+--------+
     |              :py:class:`~._signals.signal2d.Signal2D`         | False  |
     +---------------------------------------------------------------+--------+
+    | :py:class:`~._signals.electron_wave_image.ElectronWaveImage`  | False  |
+    +---------------------------------------------------------------+--------+
     |    :py:class:`~._signals.image_simulation.ImageSimulation`    | False  |
     +---------------------------------------------------------------+--------+
 
@@ -993,3 +1008,43 @@ for example:
       ├── record_by = spectrum
       ├── signal_origin = simulation
       └── signal_type =
+
+
+
+Handling complex data
+^^^^^^^^^^^^^^^^^^^^^
+
+The HyperSpy :py:class:`~.hyperspy.signals.ComplexSignal` signal class allows the user to access
+complex properties like the `real` and `imag` parts of the data or the `amplitude` (also known
+as the modulus) and `phase` (also known as angle or argument).
+directly. Getting and setting those properties can be done as follows:
+
+..code-block:: python
+
+  >>> real = s.real      # real is a new HyperSpy signal accessing the same data
+  >>> s.real = new_real  # new_real can be an array or signal
+  >>> imag = s.imag      # imag  is a new HyperSpy signal accessing the same data
+  >>> s.imag = new_imag  # new_imag can be an array or signal
+
+
+Calculate the angle / phase / argument
+--------------------------------------
+
+The :py:func:`~hyperspy.signals.ComplexSignal.angle` function can be used to calculate the
+angle, which is equivalent to using the `phase` property if no argument is used. If the data is
+real, the angle will be 0 for positive values and 2$\pi$ for negative values. If the `deg`
+parameter is set to `True`, the result will be given in degrees, otherwise in rad (default).
+The underlying function is the :py:func:`~numpy.angle` function.
+:py:func:`~hyperspy.signals.ComplexSignal.angle` will return an appropriate HyperSpy signal.
+
+
+Phase unwrapping
+----------------
+
+With the :py:func:`~hyperspy.signals.ComplexSignal.unwrapped_phase` method the complex phase
+of a signal can be unwrapped and returned as a new signal. The underlying method is
+:py:func:`~skimage.restoration.unwrap`, which uses the algorithm described in:
+Miguel Arevallilo Herraez, David R. Burton, Michael J. Lalor, and Munther A. Gdeisat,
+“Fast two-dimensional phase-unwrapping algorithm based on sorting by reliability following
+a noncontinuous path”, Journal Applied Optics, Vol. 41, No. 35, pp. 7437, 2002.
+(doi: 10.1364/AO.41.007437).