Freely Moving Animal (FMA) Toolbox
INTRODUCTION
The purpose of the Freely Moving Animal (FMA) Toolbox is to help analyze
electrophysiological and behavioral data recorded from freely moving animals.
These data typically include broadband brain signals (e.g. local field potentials),
spike data (timestamps as well as full waveforms), moment-to-moment position of
the animal, and behavioral events (stimulus presentation, photodetector crossing,
brain stimulation, etc.)
<a href="http://fmatoolbox.sourceforge.net/">FMAToolbox</a> is part of a larger data analysis framework, including <a href="http://neurosuite.sourceforge.net/">Klusters</a> (a powerful
and easy-to-use cluster cutting application), <a href="http://neurosuite.sourceforge.net/">NeuroScope</a> (an advanced viewer for
electrophysiological and behavioral data), and <a href="http://neurosuite.sourceforge.net/">NDManager</a> (a simple application to
manage recording parameters and data preprocessing).
INSTALLATION
The easiest way to install FMAToolbox is using the <a href="matlab:run pathtool">pathtool</a>. Click 'Add with subfolders...'
and select the 'FMAToolbox' directory.
For efficiency reasons, the toolbox includes a few functions in C/C++. These can be
easily compiled for your platform. In the command window, type:
>> compilefma;
or simply click <a href="matlab:run compilefma">here</a>.
Some functions in the toolbox depend on other Matlab toolboxes:
* <a href="http://www.artefact.tk/software/matlab/xml/">xmltree</a> to read XML parameter files
* <a href="http://www.chronux.org">chronux</a> to perform time-frequency analyses
* <a href="http://sourceforge.net/projects/mym/">mYm</a> to provide database functionality
* <a href="http://sites.google.com/site/oliverwoodford/software/export_fig">export_fig</a> (optional) to export figures as PNG, EPS, PDF, etc.
LICENSE
This toolbox was developed by <a href="http://zugarolab.net">Michaël Zugaro</a> (CRNS-Collège de France, Paris,
France). It is free software distributed under the <a href="http://www.gnu.org/licenses/gpl.html">General Public License (GPL)</a>.
CONTENTS
The toolbox is organized in distinct functional categories:
Data - Experimental data handling
General - General-purpose data processing and statistical tests.
Analyses - Specialized analyses (PSTH, place maps, tuning curves...)
Plot - Enhanced and specialized plotting functions.
Database - Database access and storage
IO - Input/output helper functions, including batch handling
OVERVIEW
Functions provided in the <a href="matlab:help Data">Data</a> category can be used to read experimental data files.
The file format is the same as in other programs such as <a href="http://neurosuite.sourceforge.net">Klusters</a>, <a href="http://neurosuite.sourceforge.net">NeuroScope</a> and
<a href="http://neurosuite.sourceforge.net">NDManager</a> (see e.g. <a href="matlab:help http://neuroscope.sourceforge.net/UserManual/data-files.html">http://neuroscope.sourceforge.net/UserManual/data-files.html</a>).
However, the rest of the toolbox is independent from these file formats, so you
are free to use any format you like (of course, you would then have to add your own
code to read your files).
Upon loading, the data are stored in simple matrices where the first column contains
timestamps and the remaining columns contain the corresponding values. For instance,
moment-to-moment positions of the animal are stored as
0 100.625 74.375
0.0256 99.375 75
0.0512 99.375 75
0.0768 100.625 75
0.1024 100.625 75
... ... ...
where the first column is time (in seconds), the second is the X coordinate of the
animal, and the third is its Y coordinate. Positions stored in such a matrix are
referred to as position <a href="matlab:help samples">'samples'</a>.
Many functions in FMAToolbox provide basic processing of samples, such as time
selection, interpolation or smoothing. These are grouped in the <a href="matlab:help General">General</a> category,
together with statistical measures and tests, interval handling, binning, etc.
More specialized analysis functions are grouped in the <a href="matlab:help Analyses">Analyses</a> category, including
peri-event time histograms (PETH), place maps, tuning curves, spectrograms, current
source density, ripple detection, etc.
Results can be plotted using enhanced or specialized functions provided in the <a href="matlab:help Plot">Plot</a>
category, and stored in a local or network database using functions in the <a href="matlab:help Database">Database</a>
category.
Last, the <a href="matlab:help IO">IO</a> category contains low-level disk access functions (which should normally
not be used directly), as well as batch-processing handling functions.
GETTING STARTED
A typical data analysis session would start by loading the experimental data:
>> SetCurrentSession
A dialog pops up, where you can navigate your disk to choose the recording session to
analyze. Files are then loaded and kept in memory. You can now access the data very
easily. For instance, if you need the position samples, do:
>> p = GetPositions;
To plot the firing map of the place cell corresponding to cluster 5 on tetrode 3:
>> s = GetSpikes([3 5]);
>> map = FiringMap(p,s);
>> figure;
>> PlotColorMap(map.rate,map.time); % time is used to dimm the colors
To plot theta phase precession information (phase as a function of position, phase
distribution as a function of position, and phase as a function of firing rate) for
the same neuron:
>> lfp = GetLFP(20); % theta is measured on channel 20
>> theta = FilterLFP(lfp,'passband','theta');
>> phi = Phase(theta);
>> precession = PhasePrecession(p,s,phi);
>> figure;
>> PlotPhasePrecession(precession);
Now let us plot a spike raster synchronized on stimulation events:
>> stims = GetEvents('stimulation');
>> [sync,i] = Sync(s,stims);
>> figure;
>> PlotSync(sync,i);
and the corresponding PSTH and time-varying spike distribution:
>> [h,t] = SyncHist(sync,i);
>> figure;
>> bar(t,h); % PSTH
>> [h,t,n] = SyncHist(sync,i,'mode','dist');
>> figure;
>> PlotColorMap(h,1,'x',t,'y',n); % distribution
For more information, read the help topics listed above (CONTENTS).
NOTE
You may wish to add the following line to your <a href="matlab:edit startup.m">startup</a> file:
Browse('on');
This will automatically activate <a href="matlab:help Browse">browsing features</a> in every figure.0001 % Freely Moving Animal (FMA) Toolbox 0002 % 0003 % INTRODUCTION 0004 % 0005 % The purpose of the Freely Moving Animal (FMA) Toolbox is to help analyze 0006 % electrophysiological and behavioral data recorded from freely moving animals. 0007 % 0008 % These data typically include broadband brain signals (e.g. local field potentials), 0009 % spike data (timestamps as well as full waveforms), moment-to-moment position of 0010 % the animal, and behavioral events (stimulus presentation, photodetector crossing, 0011 % brain stimulation, etc.) 0012 % 0013 % <a href="http://fmatoolbox.sourceforge.net/">FMAToolbox</a> is part of a larger data analysis framework, including <a href="http://neurosuite.sourceforge.net/">Klusters</a> (a powerful 0014 % and easy-to-use cluster cutting application), <a href="http://neurosuite.sourceforge.net/">NeuroScope</a> (an advanced viewer for 0015 % electrophysiological and behavioral data), and <a href="http://neurosuite.sourceforge.net/">NDManager</a> (a simple application to 0016 % manage recording parameters and data preprocessing). 0017 % 0018 % INSTALLATION 0019 % 0020 % The easiest way to install FMAToolbox is using the <a href="matlab:run pathtool">pathtool</a>. Click 'Add with subfolders...' 0021 % and select the 'FMAToolbox' directory. 0022 % 0023 % For efficiency reasons, the toolbox includes a few functions in C/C++. These can be 0024 % easily compiled for your platform. In the command window, type: 0025 % 0026 % >> compilefma; 0027 % 0028 % or simply click <a href="matlab:run compilefma">here</a>. 0029 % 0030 % Some functions in the toolbox depend on other Matlab toolboxes: 0031 % 0032 % * <a href="http://www.artefact.tk/software/matlab/xml/">xmltree</a> to read XML parameter files 0033 % * <a href="http://www.chronux.org">chronux</a> to perform time-frequency analyses 0034 % * <a href="http://sourceforge.net/projects/mym/">mYm</a> to provide database functionality 0035 % * <a href="http://sites.google.com/site/oliverwoodford/software/export_fig">export_fig</a> (optional) to export figures as PNG, EPS, PDF, etc. 0036 % 0037 % LICENSE 0038 % 0039 % This toolbox was developed by <a href="http://zugarolab.net">Michaël Zugaro</a> (CRNS-Collège de France, Paris, 0040 % France). It is free software distributed under the <a href="http://www.gnu.org/licenses/gpl.html">General Public License (GPL)</a>. 0041 % 0042 % CONTENTS 0043 % 0044 % The toolbox is organized in distinct functional categories: 0045 % 0046 % Data - Experimental data handling 0047 % General - General-purpose data processing and statistical tests. 0048 % Analyses - Specialized analyses (PSTH, place maps, tuning curves...) 0049 % Plot - Enhanced and specialized plotting functions. 0050 % Database - Database access and storage 0051 % IO - Input/output helper functions, including batch handling 0052 % 0053 % OVERVIEW 0054 % 0055 % Functions provided in the <a href="matlab:help Data">Data</a> category can be used to read experimental data files. 0056 % The file format is the same as in other programs such as <a href="http://neurosuite.sourceforge.net">Klusters</a>, <a href="http://neurosuite.sourceforge.net">NeuroScope</a> and 0057 % <a href="http://neurosuite.sourceforge.net">NDManager</a> (see e.g. <a href="matlab:help http://neuroscope.sourceforge.net/UserManual/data-files.html">http://neuroscope.sourceforge.net/UserManual/data-files.html</a>). 0058 % However, the rest of the toolbox is independent from these file formats, so you 0059 % are free to use any format you like (of course, you would then have to add your own 0060 % code to read your files). 0061 % 0062 % Upon loading, the data are stored in simple matrices where the first column contains 0063 % timestamps and the remaining columns contain the corresponding values. For instance, 0064 % moment-to-moment positions of the animal are stored as 0065 % 0066 % 0 100.625 74.375 0067 % 0.0256 99.375 75 0068 % 0.0512 99.375 75 0069 % 0.0768 100.625 75 0070 % 0.1024 100.625 75 0071 % ... ... ... 0072 % 0073 % where the first column is time (in seconds), the second is the X coordinate of the 0074 % animal, and the third is its Y coordinate. Positions stored in such a matrix are 0075 % referred to as position <a href="matlab:help samples">'samples'</a>. 0076 % 0077 % Many functions in FMAToolbox provide basic processing of samples, such as time 0078 % selection, interpolation or smoothing. These are grouped in the <a href="matlab:help General">General</a> category, 0079 % together with statistical measures and tests, interval handling, binning, etc. 0080 % 0081 % More specialized analysis functions are grouped in the <a href="matlab:help Analyses">Analyses</a> category, including 0082 % peri-event time histograms (PETH), place maps, tuning curves, spectrograms, current 0083 % source density, ripple detection, etc. 0084 % 0085 % Results can be plotted using enhanced or specialized functions provided in the <a href="matlab:help Plot">Plot</a> 0086 % category, and stored in a local or network database using functions in the <a href="matlab:help Database">Database</a> 0087 % category. 0088 % 0089 % Last, the <a href="matlab:help IO">IO</a> category contains low-level disk access functions (which should normally 0090 % not be used directly), as well as batch-processing handling functions. 0091 % 0092 % GETTING STARTED 0093 % 0094 % A typical data analysis session would start by loading the experimental data: 0095 % 0096 % >> SetCurrentSession 0097 % 0098 % A dialog pops up, where you can navigate your disk to choose the recording session to 0099 % analyze. Files are then loaded and kept in memory. You can now access the data very 0100 % easily. For instance, if you need the position samples, do: 0101 % 0102 % >> p = GetPositions; 0103 % 0104 % To plot the firing map of the place cell corresponding to cluster 5 on tetrode 3: 0105 % 0106 % >> s = GetSpikes([3 5]); 0107 % >> map = FiringMap(p,s); 0108 % >> figure; 0109 % >> PlotColorMap(map.rate,map.time); % time is used to dimm the colors 0110 % 0111 % To plot theta phase precession information (phase as a function of position, phase 0112 % distribution as a function of position, and phase as a function of firing rate) for 0113 % the same neuron: 0114 % 0115 % >> lfp = GetLFP(20); % theta is measured on channel 20 0116 % >> theta = FilterLFP(lfp,'passband','theta'); 0117 % >> phi = Phase(theta); 0118 % >> precession = PhasePrecession(p,s,phi); 0119 % >> figure; 0120 % >> PlotPhasePrecession(precession); 0121 % 0122 % Now let us plot a spike raster synchronized on stimulation events: 0123 % 0124 % >> stims = GetEvents('stimulation'); 0125 % >> [sync,i] = Sync(s,stims); 0126 % >> figure; 0127 % >> PlotSync(sync,i); 0128 % 0129 % and the corresponding PSTH and time-varying spike distribution: 0130 % 0131 % >> [h,t] = SyncHist(sync,i); 0132 % >> figure; 0133 % >> bar(t,h); % PSTH 0134 % >> [h,t,n] = SyncHist(sync,i,'mode','dist'); 0135 % >> figure; 0136 % >> PlotColorMap(h,1,'x',t,'y',n); % distribution 0137 % 0138 % For more information, read the help topics listed above (CONTENTS). 0139 % 0140 % NOTE 0141 % 0142 % You may wish to add the following line to your <a href="matlab:edit startup.m">startup</a> file: 0143 % 0144 % Browse('on'); 0145 % 0146 % This will automatically activate <a href="matlab:help Browse">browsing features</a> in every figure. 0147 0148 help FMAToolbox;