HOW TO USE THESE SCRIPTS

0-INTRODUCTION
These scripts read, organize, store, analyze and plot the output files from KINARM system. It is customized for the results from the bimanual Fitts experiment that we developed  (cannot be used elsewhere in its present form), but it is designed to be easily extendible and reusable. 
Due to strong computational constraints, there are many hacks and optimizations spread throughout the code. The most obvious one is the use of MATLAB's object oriented programming framework, which makes necessary the use of a modern version of the software (2010 or above). The whole code is hierarchically organized in a small set of classes that naturally match the components of the experiment (like time series, vector field, trial, block, session, participant or experiment). For each class, a certain set of methods are defined (like load, plot, save, analyze, get...) to manipulate the data encapsulated in the class.  Although many things can be corrected to improve integration of the different components  and the user experience, it can perform all the expected behaviors. 

1-INPUT AND OUTPUT
-The scripts assume as root directory for all analysis  $USERDIR/KINARM
-It should work in linux or windows with no modification (for linux, $USERDIR is /home/username and for windows it is My Documents). 
-The input files of the scripts, KINARM recorded data files in c3d format, are stored in the folder $ROOT/data/participantXXX. 
-By default, processed objects are stored in $ROOT (root directory) when save method is issued.
-Saved figures generated when issuing a plot method are stored in $ROOTDIR/plots
-The scripts themselves can be stored anywhere in the filesystem. You should remember of adding that directory and all its subdirectories to Matlab path.
-To run the whole script, a machine with a minimum of 8GB RAM (12GB recommendable) and 64bit operative system is required, together with quite some hours. To run the script for a single participant, a more modest machine can be used (but not too modest!). The more cores, the better (there is support for paralelization, see below).

2-BASIC WORKFLOW
-Load all experimental data
          exp = Experiment(); %Serial version
          exp = Experiment(1); %Parallel version
          
-Load a single participant
          p = Participant(N)%Where N is the number of participant
          
-Save either a participant or a experiment
          save(exp);
          save(part);
          
-Load a previously saved participant or experiment
          exp = Experiment.load();
          part = Participant.load(N); %Where N is the number of participant
          
-Plot the whole experiment or just a participant
          plot(exp);
          plot(part);
          plot(exp.participants(3));

-Get a whole block from a certain participant:
          blk=exp.participants(3).session(1).bimanual;
          
The same behaviour can be expected for the rest of classes in the project, although some combinations are not consistent yet (specifically for Trial and below classes, where plot saving in $ROOTDIRECTORY and overwriting previously plotted figures, or not saving but interactively displaying for some classes but not others). This can, however, be easily improved with your feedback when facing some unexpected behavior. 


2-RATIONALE: DIRECTORY STRUCTURE
All directories beggining with @ contain MATLAB class definitions. The implementation
of a class can be found in a .m file named as the class itself. The directory 
"trial" contains all the classes required to load and analyze a single trial.
The behaviour of these classes is a bit different from the rest with respect 
to methods like plot and save. Many improvements in usability can be performed
here.

@Experiment
@Participant
@Session
@Block 
trial---> @Trial
          @TimeSeriesBimanual
          @TimeSeriesUnimanual
          @VectorField
          @LockingStrength
          @Oscillations
util

3-PLOT DIRECTORY LAYOUT
When issued at the highest level, that is, plot(exp), it will generate
the following directory layout for each participant:
-Learning: It includes cross-session comparisons of different magnitudes:
    -Oscillations: variables contained in Oscillation class
    -Relative: the same as oscillation, but bimanual data is scaled with
     respect to the performance in the unimanual experiment for the same 
     session.
    -LockingStrength: variables contained in LockingStrength
    -VectorField: vector fields and angle differences across sessions and
     with unimanual cases on the side to compare.
-Session[1|4|7]: For each session, contains plots of each block, and also 
 oscillation variables from bimanual block scaled with respect to the 
 unimanual performace (Relative dir).
-Each block, contain similar plots as the Learning directory, excepcion made
 for time series. 
 

3-CLASS HIERARCHY

Experiment->| some properties and methods
            | participants (10 element Participants array)
            |    |
            |    |
            |    V
            | Participant-->| some properties and methods
            |               | sessions (7 element Session array)
            |               |   |
            |               |   |
            |               |   V
            |               | Session-->| some properties and methods
            |               |           | bimanual (Block instance)
            |               |           | uniLeft (Block instance)
            |               |           | uniRight (Block instance)
            |               |           |    |
            |               |           |    |
            |               |           |    V
            |               |           | Block-->| some properties and methods 
            |               |           |         | data_set{IDL, IDR, rep+1}
            |               |           |         |          of Trial objects 
            |_______________|___________|_________|_____________________________


Trial  (uni) -----> | ts: TimeSeriesUnimanual
                    | vf: VectorField
                    |osc: Oscillation
                    |_________________


Trial  (bi) ----->  | ts: TimeSeriesBimanual
                    | vfR: VectorField
                    | vfL: VectorField
                    | oscR: Oscillation
                    | oscL: Oscillation
                    | ls: LockingStrength
                    |___________________

Timeseries[Bi|Uni]manual--> Stores raw data (x,v,a time series) and allow
                            access to different transformations of them
                            using dependent properties. It also contains
                            the code to extract and organize data from
                            KINARM's output files (.c3d).

Oscillation-------------->  Computes and stores per-oscillation variables
                            such as peak velocity, acceleration time,
                            index of performance...

LockingStrengh----------->  Computes and stores power-spectrum, maximum 
                            frequency, locking strength, phase difference.

VectorField-------------->  Computes conditional probabilities of state
                            transitions in (x,v) space using Daffersthoffer's
                            implementation of Kramers-Moyal expansion. 
                            It gives access to related vector fields and angle
                            differences.
                            

4-SUBTLE DETAILS
Due to the huge amount of data, there are only two types of variables with
a considerable size that are actually stored by the algorithm: [x,v,a] raw time series
and conditional probability matrices. The rest of derived magnitudes are computed
on the fly. Besides, the raw data is stored in memory as gzipped data, so 
decompression is performed on the fly for each access. 
Both factors contribute to making the plotting algorithms pretty slow, but
it's the only way I found to fit all data in a less than 8GB memory systems.
Another approach, which I've been using until recently, is to process data
separatedly for each participant. The main reason to try to store all data
in a single and relatively small data structure is that cross-participant
analysis will be painful, due to the overhead of reading from disk some GBs
for each computation, and because MATLAB memory management in linux is less
than poor (rendering it almost impossible).  

5-THINGS TO DO/KNOWN ISSUES
-Improve source comments. Now many file headers are out of date, coming from previous versions or from unrelated files.

-Improve integration and coherente usage.

-Try to get indexing to work. The initial intention was that container
 classes (like Experiment containing 10 Participants) could be directly
 indexed without reference to the underlying array storing them. Like:
    
    exp = Experiment(1);    %Get data from c3d files
    part = exp(2);          %Get the second participant
    blk = exp(1,4).bimanual %Get bimanual block of 4th session of 1st participant
    plot(exp(5,1).bimanual) %Plot the selected block
    new=copy(exp(2));       %Full copy of participant 2
    
 However, MATLAB made it difficult to me to get subsref method working.
 For now, you have to access in a bit long way like:
    blk = exp(1).participants(4).bimanual.data_set;
    
-Desing and code cross-participant analysis.

-Improve vector field extraction. It is very noisy yet.