-----------------------------------------------------------------------------
-----------------------------------------------------------------------------

These data files are meant to be a template for our data format, 
and do not contain meaningful experimental results.

-----------------------------------------------------------------------------
-----------------------------------------------------------------------------



matlab data format
-----------------------------------------------------------------------------

General:
--------
* Use '_' to separate words, in both file names and variables, e.g.:
.../finger_move/both_hand/

* Time unit standardization:
"session" - an experimental session (usually 1 per day), e.g. AT051215
"run"     - a group of ~continuous-time trials, same as fMRI run
"trial"   - a period of 1 or more samples with
"block"   - optionally a group of similar trials (e.g. same condition)
             that aren't quite a run

* Dimension standardization:
     what    dim  matrix   meg/eeg            fmri
     ----    ---  ------   -------            ----
1. "sensor" = y  = row    = channel          = voxel ...
2. "sample" = x  = column = time/sample_freq = 1 (1 sample = 1 volume)
3. "trial"  = z  = page   = trial            = volume
Use these in variables in programs and some data files (see below).

+ Yes, fMRI data will be a.
sensor_num x 1 x trial_num (= num_voxels x 1 x num_volumes)
Why the dummy dimension?
To match "labels" with appropriate dimension.
To match potential simultaneous eeg-fmri data together.

Directories:
------------
* Rename 'share'->'data' to avoid confusion with other shared items 
(e.g. code).

* Separate subfolders of 'data' into primary decoding data type, e.g.:
~neo/data/meg/
~neo/data/fmri/
~neo/data/eeg/
...
This is because there is a primary decoding data format, and even though
we're trying to unify formats, there will still be many differences that
should be described in the README_MEG, README_FMRI, etc. of each of 
these
directories.

* General things (e.g. this document) will the in ~neo/data/README.

* MEG-, EEG-, etc-specific data items (variables) will be in:
~neo/data/meg/README_MEG
~neo/data/eeg/README_EEG
...

* Task-specific things (variables) will be in their task folder as
README_<TASK>, e.g.:
~neo/data/meg/HandMove/Readme.txt

In each subject-session folder:
-------------------------------
* Postfix each folder containing .mat files with 6 or 7 to indicate
Matlab version 6 or 7 data (may only contain 6), e.g.:
~neo/data/meg/HandMove/voluntary/AT051215/meg6/run1.mat
                                               run2.mat
                                               ...
                                      .../meg7/...

* Put raw data in a '_raw' folder:   .../meg_raw/...

* Put all VB filters in a folder:    .../VB_filters/...
(or "VB_MEG"?)

* For each data run, name each file with the .mat data, only as:
run1.mat, run2.mat, run3.mat, ...
Otherwise, it will be difficult to switch between data sets in programs;
the 'meg' part is redundant.

Variable names:
---------------
* Use data type prefixes (meg, eog, etc.) to group data types.
* Use these suffixes for qualifiers:
dat = data matrix, ix = index, num = number of, freq = frequency
Essential:
meg_dat			- meg data matrix
meg_sensor_ix 	- meg sensor(channel) index
meg_sensor_loc	- locations of meg sensor (<- 'pick')
meg_sample_freq	- meg sample frequency
eog_dat			- eog data matrix
eog_sensor_ix 	- eog sensor(channel) index
eog_sample_freq	- eog sample frequency
...
Optionally:
meg_sensor_num	- number of meg sensors
meg_trial_num		- number of meg trials

**Generally:
<datatype>_<dimension>_<what>

If something applies to multiple data types or just the primary,
data type can be left out, e.g.:
trial_labels		<dim>_<what>
sample_labels

If something has multiple dimensions, this can be left out:
meg_dat			<datatype>_<what>

* Note: time Он samples
If time is the unit, use it:
onsettime -> meg_time_onset
If sample is the unit, use it:
meg_sample_onset

Other variables:
----------------
Vcenter? -> more descriptive?
Vradius? -> "

MEGinfo -> MEG_info:
--------------------
nch 		-> sensor_num (_used or _total?)
nsamp 	-> sample_num_total (not all used)
nprsamp 	-> national public radio samples?
sampf 	-> sample_freq
nrept	-> trial_rep_num?


Additional important variables in each .mat:
--------------------------------------------
run_num	- number of runs, so my program knows how many
		  files to read!

dat_names = {'meg'; 'oeg';...];
- CELLS should list each data types (_dat's) exactly as variables

label_names = {'base'; 'rock'; ...];
- cells should map condition integer to label names

Questions:
What if meg, oeg, etc. don't quite match in sample and trial dimensions,
e.g. if they start later or their sample rate is different?
Then meg_sample_onset, meg_time_onset, meg_sample_freq, eog... may
be necessary.
If dimensions match assume sample sample rate and onset time?