-
Notifications
You must be signed in to change notification settings - Fork 0
jibannez/Fitts
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
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.
About
No description, website, or topics provided.
Resources
Stars
Watchers
Forks
Releases
No releases published
Packages 0
No packages published