function hdr=cosmo_map2meeg(ds, fn)
% maps a dataset to a FieldTrip or EEGlab structure or file
%
% hdr=cosmo_map2meeg(ds[, fn])
%
% Inputs:
% ds dataset struct with field .samples with MEEG data
% fn output filename or extension. If a filename,
% the following extentions are supported:
% .mat : FieldTrip time-locked or
% time-frequency data at either the
% sensor or source level.
% .txt : exported EEGLab with timelocked data.
% .daterp time-locked }
% .icaerp ICA time-locked } EEGLab
% .dattimef time-freq }
% .icatimef ICA time-freq }
% .datitc inter-trial coherence }
% .icaitc ICA inter-trial coherence }
% To avoid writing a file, but get output in the hdr
% field, use one of the extensions above but with the
% dot ('.') replaced by a hyphen ('-'), for example
% '-dattimef' for time-freq data.
%
% Returns:
% hdr FieldTrip or EEGLAB struct with the MEEG data
%
% Notes:
% - a typical use case is to use this function to map the dataset to a
% FieldTrip struct, then use FieldTrip to visualize the data
% - there is currently no support for writing EEGLAB 'ersp' data.
%
% Examples:
% % convert a dataset struct to a FieldTrip struct
% ft=cosmo_map2meeg(ds);
%
% % store a dataset in FieldTrip file
% cosmo_map2meeg(ds,'fieldtrip_data.mat');
%
% % store a timeseries dataset in an EEGlab text file
% cosmo_map2meeg(ds,'eeglab_data.txt');
%
% % convert a dataset structure to a FieldTrip structure
% ft=cosmo_map2meeg(ds,'-mat');
%
% % convert a time-lock dataset to an EEGLAB structure
% eeglab_daterp=cosmo_map2meg(ds,'-daterp');
%
% % write EEGLAB time-frequency data
% cosmo_map2meeg(ds,'timefreq.dattimef');
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
