# MDF Import Function Help

This document describes how to import MDF files with `mdfimport` called as function. To learn how to call `mdfimport` as an interactive tool, see separate MDF import tool help.

## Contents

- Function parameters
- File name
- Import location
- Signal selection
- Time vector type
- Rate designation
- Additional text
- Example: Import all signals from an MDF file to the workspace using defaults
- Example: Import all signals to a MAT-file with automatic name
- Example: Import all signals to a MAT-file with a specified name
- Example: Import just two signals
- Example: Import signals with names stored in signal selection text file
- Example: Use rate string rather than rate number to designate variable rates
- Example: Append variable names with additional text
- Example: Import multiple MDF files using a for loop
- Example: Import a whole directory of MDF files as store as MAT-Files

## Function parameters

The `mdfimport` tool, when called as a function takes up to six parameters provided in this order:

`mdfimport(fileName,importlocation,signalselection,timevectortype,ratedesignation, additionaltext);`

All parameters are optional except for the first, the file name, which must be provided if `mdfimport` is to be called as a function. The list below shows the possible values of each parameter. Curly braces { } enclose default values. Use `[]` to skip parameters.

## File name

`fileName: 'MDFfilename.dat'`

String specifying name of the MDF file to be imported. Must be provided if `mdfimport` is to be called as a function.

## Import location

`importlocation: {'workspace'} | 'Auto MAT-File' | 'MATfilename.mat'`

String specifying location signals are to be imported to, which can be the base workspace (`'workspace'`), a MAT file with the same name as the MDF file ('Auto MAT-File') or a MAT file of specified name. Note that 'workspace' specifies the base workspace. As a result, `mdfimport` is not easily called from a function. A workaround is to save to a MAT-File then load back in.

## Signal selection

`signalselection: {'all'} | 'signalselectionfilename.txt' | cellarrayofnames`

String or cell array specifying which signals to be selected, which can be all signals (`'all'`), those with names listed in a given signal selection file or in a cell array of strings.

## Time vector type

`timevectortype: {'actual'} | 'ideal'`

String specifying what time instants to put in time vector, which can either be the actual times from the associated time signal in the MDF file (`'actual'`) or ideal uniform sampled times (`'ideal'`).

## Rate designation

`ratedesignation: {'ratenumber'} | 'ratestring'`

String specifying how the rate of the variables is designated. Options are either an integer (`'ratenumber'`), e.g. rpm_1 , or a string representing the sample rate (`'ratestring'`), e.g. rmp_10ms

## Additional text

|additionaltext: 'text'

String specifying optional additional text to append to names of all variables generated. This can be useful if you want to differentiate data from multiple sessions, simulation runs or experiments. The default is to have no additional text.

The follow section gives examples of using `mdfimport` called as a function.

## Example: Import all signals from an MDF file to the workspace using defaults

    clear;
    mdfimport('BitSignals.dat');

    Created 3 signal variable(s) appended with '_1' for 'TimeC' rate
    ... and 1 actual time vector 'time_1'

    whos

      Name             Size                    Bytes  Class

      B_GREEN_1       50x1                       400  double array
      B_RED_1         50x1                       400  double array
      B_YELLOW_1      50x1                       400  double array
      time_1          50x1                       400  double array

    Grand total is 200 elements using 1600 bytes

## Example: Import all signals to a MAT-file with automatic name

    clear
    mdfimport('BitSignals.dat','Auto MAT-File');

    Created 3 signal variable(s) appended with '_1' for 'TimeC' rate
    ... and 1 actual time vector 'time_1'

    dir *.mat

    BitSignals.mat  measure239.mat  my01.mat

    whos('-file', 'BitSignals.mat')

      Name             Size                    Bytes  Class

      B_GREEN_1       50x1                       400  double array
      B_RED_1         50x1                       400  double array
      B_YELLOW_1      50x1                       400  double array
      time_1          50x1                       400  double array

    Grand total is 200 elements using 1600 bytes

    delete BitSignals.mat % clean up

## Example: Import all signals to a MAT-file with a specified name

    clear
    mdfimport('BitSignals.dat','mymatfile.mat');

    Created 3 signal variable(s) appended with '_1' for 'TimeC' rate
    ... and 1 actual time vector 'time_1'

    dir *.mat

    measure239.mat  my01.mat        mymatfile.mat

    delete mymatfile.mat % clean up

## Example: Import just two signals

    clear
    mdfimport('BitSignals.dat',[],{'B_GREEN' 'B_RED'});

    Created 2 signal variable(s) appended with '_1' for 'TimeC' rate
    ... and 1 actual time vector 'time_1'

    whos

      Name            Size                    Bytes  Class

      B_GREEN_1      50x1                       400  double array
      B_RED_1        50x1                       400  double array
      time_1         50x1                       400  double array

    Grand total is 150 elements using 1200 bytes

## Example: Import signals with names stored in signal selection text file

Show contents of signal selection file :

    clear;
    type signalselection.txt

    58X3160
    ACREQAI
    ACREQ

    mdfimport('DICP_V6_vehicle_data.dat',[],'signalselection.txt');

    Created 2 signal variable(s) appended with '_3' for '7.82ms' rate
    ... and 1 actual time vector 'time_3'
    Created 1 signal variable(s) appended with '_4' for 'Cyl Event' rate
    ... and 1 actual time vector 'time_4'

    whos

      Name             Size                    Bytes  Class

      ACREQAI_3    78533x1                    628264  double array
      ACREQ_3      78533x1                    628264  double array
      time_3       78533x1                    628264  double array
      time_4       46362x1                    370896  double array
      x58X3160_4   46362x1                    370896  double array

    Grand total is 328323 elements using 2626584 bytes

## Example: Use rate string rather than rate number to designate variable rates

    clear;
    mdfimport('DICP_V6_vehicle_data.dat',[],'signalselection.txt',[],'ratestring');

    Created 2 signal variable(s) appended with '_7p82ms' for '7.82ms' rate
    ... and 1 actual time vector 'time_7p82ms'
    Created 1 signal variable(s) appended with '_Cyl_Event' for 'Cyl Event' rate
    ... and 1 actual time vector 'time_Cyl_Event'

    whos

      Name                     Size                    Bytes  Class

      ACREQAI_7p82ms       78533x1                    628264  double array
      ACREQ_7p82ms         78533x1                    628264  double array
      time_7p82ms          78533x1                    628264  double array
      time_Cyl_Event       46362x1                    370896  double array
      x58X3160_Cyl_Event   46362x1                    370896  double array

    Grand total is 328323 elements using 2626584 bytes

## Example: Append variable names with additional text

    clear;
    mdfimport('BitSignals.dat',[],[],[],[],'_run1');
    mdfimport('BitSignals.dat',[],[],[],[],'_run2');

    Created 3 signal variable(s) appended with '_1_run1' for 'TimeC' rate
    ... and 1 actual time vector 'time_1_run1'
    Created 3 signal variable(s) appended with '_1_run2' for 'TimeC' rate
    ... and 1 actual time vector 'time_1_run2'

    whos

      Name                  Size                    Bytes  Class

      B_GREEN_1_run1       50x1                       400  double array
      B_GREEN_1_run2       50x1                       400  double array
      B_RED_1_run1         50x1                       400  double array
      B_RED_1_run2         50x1                       400  double array
      B_YELLOW_1_run1      50x1                       400  double array
      B_YELLOW_1_run2      50x1                       400  double array
      time_1_run1          50x1                       400  double array
      time_1_run2          50x1                       400  double array

    Grand total is 400 elements using 3200 bytes

## Example: Import multiple MDF files using a for loop

    clear;

    % Specify list of file names as cell array of strings
    MDFFileNames={'BitSignals.dat' 'my01.dat' 'measure239.dat'};

    for k=1:length(MDFFileNames)
        % Remember to use {} to access string in cell array
        mdfimport(MDFFileNames{k},'Auto MAT-File');  % Call mdfimport
    end

    Created 3 signal variable(s) appended with '_1' for 'TimeC' rate
    ... and 1 actual time vector 'time_1'
    Created 1 signal variable(s) appended with '_1' for '1.0ms' rate
    ... and 1 actual time vector 'time_1'
    Created 1 signal variable(s) appended with '_1' for '2ms' rate
    ... and 1 actual time vector 'time_1'

Note: From R14SP3 on, this can be done in one line with:

`cellfun(@(x) mdfimport(x, 'Auto MAT-File'), MDFFileNames);`

Show generated MAT files:

    dir *.mat

    BitSignals.mat  measure239.mat  my01.mat

## Example: Import a whole directory of MDF files as store as MAT-Files

    clear

View names of MDF files in a directory

    dir *.dat

    BitSignals.dat  measure239.dat  my01.dat

Import files

    % Get info on MDF files
    MDFFilesInfo = dir('*.dat');

    % Load all and convert to .mat
    for k=1:length(MDFFilesInfo)
        mdfimport(MDFFilesInfo(k).name,'Auto MAT-File');  % Call mdfimport
    end

    Created 3 signal variable(s) appended with '_1' for 'TimeC' rate
    ... and 1 actual time vector 'time_1'
    Created 1 signal variable(s) appended with '_1' for '2ms' rate
    ... and 1 actual time vector 'time_1'
    Created 1 signal variable(s) appended with '_1' for '1.0ms' rate
    ... and 1 actual time vector 'time_1'

Note: From R14SP3 on, this can be done in one line with:

`arrayfun(@(x) mdfimport(x.name, 'Auto MAT-File'), MDFFilesInfo);`