.. _tutorial_vels_matlab_format:

VEX (and MEX) ELS matlab data format
=====================================

VEX (and MEX) ELS matlab formatted database is generated regularly at
``spaghetti.irf.se`` by the user of ``aspera-data``.

The original database location is ``/venus/elsdata``
``irfpy`` start to supporting the database access (2011-06-29: now undergoing).
The implementation will be in :mod:`irfpy.vels.scidata`.

The format was defined by (probably) HerbertG.
I have not contributed for definition of the format.

Below a simple description of data format is described, but this is no guarantee.
The analysis routine can be found at :mod:`vels_matlab_analysis` script.

ELS data types
--------------

ELS data has two different types.  Here I refer them to **count** data and **level** data.

The count data is for science and the level data is for HV monitoring.

In 32 second, 7 continuous count data and 1 level data is sent.


Matlab keys
-----------
Matlab file is loaded as a dictionary in python.
There are several keys for matlab data dictionary.

Here is a list of keys and its typical shapes.

::

        __globals__     #       []
        __header__      #       MATLAB 5.0 MAT-file, Platform: GLNXA64, Created on: Sun Oct  5 10:41:05 2008
        __version__     #       1.0

        elstimes        #       (1, Nc)
        elssectors      #       (1, 16)
        elsmatrix       #       (128, 16, Nc)

        elsleveltimes   #       (1, Nl)
        elslevels       #       (128, Nl)
        elsdeltatimes   #       (128, Nl)

Here *Nl* refers to the number of level data and *Nc* refers to the number of count data.


elstimes
++++++++
ELS time in the ``Matlab`` format.  To convert it to python ``datatime.datetime`` instance,
you can use ``irfpy.util.utc.mat2dt()`` method. Note that according to ``scipy`` version,
it may be returned as a shape of ``(Nc, )``.  Thus, it is recommended to use ``.flatten()``
method to avoid unexpected error.

elssectors
++++++++++
This may be the sector looking up table for the dataset.
As this is only 1 elements, I am not sure what happens if the mode (anode compression) changed.

elsmatrix
+++++++++
ELS count rate data.  From high energy to low energy.  Thus, the order of the index differs
from the bible modules like :mod:`irfpy.vels.bible.energy`.
For :mod:`irfpy.vels.scidata` should absorb the difference.

.. todo::

        This should be carefully checked.

elsleveltimes
+++++++++++++
The start time of the ELS level data.  It starts the same time of the 7-consequtive count data.

::

        Time:           --+---+---+---+---+---+---+---+---+---+---+---+---+---+---+--
        elstimes:         ^   ^       ^   ^   ^   ^   ^   ^   ^       ^   ^   ^   ^
        elsleveltimes:                ^                               ^

elslevels
+++++++++
ELS HV TM monitor(?) value, I think.  There is (128, Nl) element that means that you can
calculate the energy step's real energy more precisely using :mod:`irfpy.vels.bible.energy` module.

elsdeltatimes
+++++++++++++
I am not sure but most probably the time difference from the elsleveltimes and the time of each component of elslevels.