Loading FUNPACK outputs into MATLAB
===================================


.. |readtable| replace:: ``readtable``
.. _readtable: https://uk.mathworks.com/help/matlab/ref/readtable.html

.. |table| replace:: ``table``
.. _table: https://uk.mathworks.com/help/matlab/ref/table.html


If you are using MATLAB, you have several options for loading the FUNPACK
output. The best option is |readtable|_, which will load column names, and
will handle both non-numeric data and missing values.  Use ``readtable`` like
so (assuming that you generated a tab-separated file)::

    data = readtable('out.tsv', 'FileType', 'text');


The ``readtable`` function returns a |table|_ object, which stores each column
as a separate vector (or cell-array for non-numeric columns). If you are only
interested in numeric columns, you can retrieve them as an array like this::

    data    = data(:, vartype('numeric'));
    rawdata = data.Variables;


The ``readtable`` function will potentially rename the column names to ensure
that they are are valid MATLAB identifiers. You can retrieve the original
names from the ``table`` object like so::

    colnames = data.Properties.VariableDescriptions';


If you have used the ``--write_description`` or ``--description_file``
options, you can load in the descriptions for each column as follows::

    descs = readtable('out_descriptions.tsv', ...
                      'FileType', 'text', ...
                      'Delimiter', '\t',  ...
                      'ReadVariableNames',false);
    descs = [descs; {'eid', 'ID'}];
    idxs  = cellfun(@(x) find(strcmp(descs.Var1, x)), colnames, ...
                    'UniformOutput', false);
    idxs  = cell2mat(idxs);
    descs = descs.Var2(idxs);