load_ft_raw#

syncopy.load_ft_raw(filename, list_only=False, select_structures=None, include_fields=None, mem_use=4000)[source]#

Imports raw time-series data from Field Trip into potentially multiple AnalogData objects, one for each structure found within the MAT-file.

The aim is to parse each FT data structure, which have the following fields (Syncopy analogon on the right):

FT

Syncopy

label

channel

trial

trial

time

time

trialinfo

trialinfo

fsample (optional)

samplerate

cfg

cfg

Limitations:

The FT cfg contains a lot of meta data which at the moment we don’t import into Syncopy. Syncopy however has it’s own cfg mirroring FT’s functionality (replay analyses)

FT’s sampleinfo is not generally compatible with Syncopy

Parameters:

  • filename (str) – Path to the MAT-file

  • list_only (bool, optional) – Set to True to return only a list containing the names of the structures found

  • select_structures (sequence or None, optional) – Sequence of strings, one for each structure, the default None will load all structures found

  • include_fields (sequence, optional) – Additional MAT-File fields within each structure to be imported. They can be accessed via the AnalogData.info attribute.

  • mem_use (int) – The amount of RAM requested for the import process in MB. Note that < v7.3 MAT-File formats can only be loaded at once. For MAT-File v7.3 this should be at least twice the size of a single trial.

Returns:

out_dict – Dictionary with the names of the structures as keys loaded from the MAT-File, and AnalogData datasets as values

Return type:

dict

Notes

For MAT-File < v7.3 the MAT-file gets loaded completely into RAM using scipy.io.loadmat(), but its size should be capped by Matlab at 2GB. The >v7.3 MAT-files are in hdf5 format and will be read in trial-by-trial, this should be the Matlab default for MAT-files exceeding 2GB.

See also

MAT-File formats Field Trip datastructures

Examples

Load two structures ‘Data_K’ and ‘Data_KB’ from a MAT-File example.mat:

>>> dct = load_ft_raw('example.mat', select_structures=('Data_K', 'Data_KB'))

Access the individual AnalogData datasets:

>>> data_kb = dct['Data_KB']
>>> data_k = dct['Data_K']

Load all structures from example.mat plus additional field ‘chV1’:

>>> dct = load_ft_raw('example.mat', include_fields=('chV1',))

Access the additionally loaded field:

>>> dct['Data_K'].info['chV1']

Just peek into the MAT-File and get a list of the contained structures:

>>> load_ft_raw('example.mat', list_only=True)
>>> ['Data_K', 'Data_KB']