.. highlightlang:: us

.. index:: Import of MATLAB Data Files
.. index:: MATLAB Files
.. index:: MATLAB

.. _import-of-matlab-data-files:

Import of MATLAB Data Files
===========================

Introduction
------------

The command converts MATLAB files (.mat) into UniPlot-netCDF files or
netCDF files into MATLAB files. A MATLAB installation is not necessary.

MATLAB is a trademark of The MathWorks, Inc. (http://www.mathworks.de).

MATLAB files in the ControlDesk format can be loaded.
ControlDesk is a trademark of dSpace GmbH. (http://www.dspace.de).

Options
-------

In the dialog box :ref:`tools-more-options` the option 
"Always use structure names as a prefix for channel names" can be enabled or
disabled.

If enabled the channel name will be created from the structure names and element
names separated by a period. Example: St1.speed.

Until UniPlot 2015.4 only the element name was used as a channel name. Only if
this would lead to duplicate names the structure name was added.

Usage
-----

* Start UniPlot.

* Choose :ref:`fileimport-data`.

* Choose Type "MATLAB File (\*.mat)".

* Select one or more MATLAB files. 

Elements
--------

The following MATLAB file elements are loaded: 

Vector
^^^^^^

A MATLAB vector is saved as a channel in the NC file. The element name
is used as the channel name. The vector must contain at least 2 values.

Matrix
^^^^^^

Each column of a MATLAB matrix is saved as a channel. 
The matrix can be imported, if the following conditions are met:

* The matrix must have at least 2 columns and 2 rows.

* A string matrix with the identical number of columns must exist beside
  the matrix in the same structure.

* The first row of the string matrix must contain valid names.

The names of the first row are used as channel names. If the string matrix
contains more than one row, the second row is used as units. All other rows
are ignored.

Example of a valid structure for a matrix with 3 columns and 2 rows:

::

   * o = [. Data = rand(2,3), Header = ["C1", "C2", "C3"]] 
   * o
   [.
       Data = matrix 2 x 3 [0.566211, 0.82072, 0.325495, 0.34008, 0.895177, ...]
       Header = string-matrix 1 x 3 ["C1", ...]
   ]
   object (obj at 0x386C4BC)
   * 

Other Elements
^^^^^^^^^^^^^^

The following elements are used for the import if available:

**channel_info**: Is an array of structures. The structure name should match a 
channel name. Each structure element is saved as a channel attribute. Predefined 
elements: ``C_format``, ``add_offset``, ``datatype``, ``long_name``,
``scale_factor``, ``title``, ``units``.

**globals**: Contains scalar elements which are saved as global attributes
in the NC file.

**order**: Is a string array with channel names which sets the order in the 
NC file.

If the Matlab file contains multiple time groups, the time channels can be 
marked with the attribute ``Type``. The value is then the text
``Time Channel``. In this case, the global attribute
``nc_has_indep_channel`` with the value 1 should be defined.
If the file is prepared in this way, you can load the curves in the browser as
2D: y/t "MDF/INCA/CAN...". In this case, UniPlot will automatically select
the correct time channel.

Example:

::

   * matlab_load(GetRootDirectory() + "samples/map-data.mat")
   [.
       BEEWG = matrix 1 x 78 [1002.5, 461.7, 350.3, 322, 302.6, ...]
       CO = matrix 1 x 78 [0.6, 0.08, 0, 0.05, 0.05, ...]
       order = string-matrix 2 x 1 ["BEEWG", "CO", ...]
       channel_info = [.
           BEEWG = [.
               C_format = "%.2lf"
               add_offset = 0
               datatype = "real4"
               long_name = "BEEWG/g/kWh"
               scale_factor = 1
               title = "BEEWG"
               units = "g/kWh"
           ]
           CO = [.
               C_format = "%.2lf"
               add_offset = 0
               datatype = "real4"
               long_name = "CO/%"
               scale_factor = 1
               title = "CO"
               units = "%"
           ]
       ]
       globals = [.
           Creator = "UniPlot Excel Converter v2"
           Origin = "D:\uniplot_du\samples\map-data.xls [map]"
           Source = "FEV Software and Testing Solutions GmbH (www.uniplot.de)"
           missing_value = 1e+10
       ]
   ]

.. _export-of-netcdf-files-to-matlab:

Export of netCDF files to MATLAB
--------------------------------

A netCDF file can be saved as a MATLAB file. See :ref:`fileexport-data`.

History
-------

* R2018.7, 19.04.2019: The structure ``channel_info`` was not correctly processed for matlab 7.3 (HDF5).

* R2015.9, Apr 08, 2016: Load HDF5 based MATLAB files.

* R2015.6, Sep. 20, 2015: New Option: "Always use structure names as a prefix for
  channel names" .

* UniPlot 5.14.5, March 26, 2010: Renamed ``_channel_info`` to ``channel_info``,
  ``_globals`` to ``globals`` and ``_`` to ``order``.

* UniPlot 5.11.1, September 01, 2009: ControlDesk format added.

* UniPlot 5.10.2, June 03, 2009: Import of MAT-4-Files.

* UniPlot 5.10.1, May 17, 2009: Save matrix columns as channels added.

* UniPlot 5.10.0, April 30, 2009: MATLAB Import-Filter added.

:sub:`id-1736791`