- m@cortex
- Tutorial
11. the @spix class
getting started
The purpose of the @spix class is to efficiently analyze data collected from any number of neurons in a given experiment. A @spix object is fundamentally a collection of spike matrices drawn from previously created @cortex objects. The simple analysis tools that apply to the @cortex class (i.e., the @cortex methods) have their @spix equivalents, thus making it easier to run either population analyses or the same analysis on many cells at once without having to write much code.
First of all, a @spix needs to know how to parse out trials and retrieve spike matrices from the @cortex object. This is accomplished by passing a set of keys (i.e., a @key object) as an argument to the class constructor:
>> k = key ('source.key');
>> n = 'myspix'; % this is going to be the object's label
>> sp = spix (k, n);
A newly created @spix is like an empty shell, ready to be fed with @cortex data:
>> c = cortex ('source.0', 1:2);
>> sp = addunits (sp, c, c.bank);
Here, the keys provided when the @spix was created are used to add spikes from selected trials to an ever-growing spike matrix (indeed, addunits internally calls spikematrix). By repeating these steps, you will eventually have all the spike data collected during an experiment gathered into a single entity.
Currently there are two important limitations in the design of the @spix class:
- Only one cue event can be used to time-lock spikes. Thus, if you want to run analyses locked on different events (e.g., stimulus onset vs. reaction time) you must create different @spix objects.
- Time windows must be of the same duration for all trials added to the @spix. Thus, it is usually a good idea to use @keys that specify as long an epoch as possible, without having to give up significant numbers of trials
Analyzing data
Once all data have been added to the @spix, you can, for example, compute average firing rates for all cells with only one line of code:
>> a = meanfiringrate (sp, [-100 299], 50);
This will retrieve spikes/second rates in 8 contiguous bins of 50 ms each, starting 100 ms before the cue event, for each of the currently selected units, and for each of the currently selected keys.
Restricting analysis to subsets of units
temporarily excluding and restoring units
In most cases you will want to restrict a certain analysis to a specific subset of units. For example you might find out that certain units are poorly responsive, and so you would prefer to exclude them more or less permanently from the sample. Units can be excluded by executing:
>> sp = excludeunits (sp, [3 7]);
This will exclude units #3 and #7 from subsequent analyses. The exclusion can be reverted by doing:
>> sp = restoreunits (sp, [3 7]);
Instead of using ordinal numbers, you can refer to individual units and subsets using labels (see furthers for more details):
>> sp = excludeunits (sp, '011210.1');
>> sp = restoreunits (sp, 'all');
Note that these commands actually change the content of the object (without going into much technical detail, this is why sp must appear on both sides of the expression).
explicitly specifying unit subsets
Units to be analyzed can be directly specified in the function call's argument list:
>> fr = meanfiringrate (sp, [-100 299], 50, 'units', [1:4]);
>> fr = meanfiringrate (sp, [50 249], 200, 'units', '011210.1');
Functions that perform computations on @spix data use a variable input argument list. While the first few arguments are mandatory (e.g., arguments 1, 2, and 3 in meanfiringrate), you can add RESTRICTIONS in the form of argument pairs (somewhat similar to those used by many Matlab graphics functions) that can be used to restrict the analysis in various ways. In the examples above, the string 'units', followed by the range [1:4], instructs the function to retrieve mean firing rates from units 1 through 4 only. Note that explicitly specifying units overrides unit exclusion status.
storing unit subsets in the object
Specifying unit subsets in the argument list does NOT change the object. If you are going to repeatedly run analyses on the same subset of units, it may be convenient to store the subset in the object itself:
>> sp = addsubset (sp, 'niceunits', [1:4 7 15]);
This will create a subset labeled 'niceunits' consisting of the 6 units specified in the range. From now on, you will be able to do:
>> fr = meanfiringrate (sp, [-100 299], 50, 'subset', 'niceunits');
Again, a unit that is part of a subset will be processed even if that unit is currently marked as 'excluded'. Note that it is illegal to specify both 'units' and 'subset' restrictions in the same function call.
Restricting analysis to groups of keys
Similarly to what you do with units, it is possible to specify which keys the analysis should be run on. Suppose, for example, that a @spix object contains 40 keys. If you do:
>> fr = meanfiringrate (sp, [-100 299], 50);
...the analysis will be run on all currently selected units, for each of the currently selected keys. Now, if you do:
>> sp = excludekeys (sp, [2:4]);
>> fr = meanfiringrate (sp, [-100 299], 50);
keys 2, 3, and 4 will be excluded from this (and any following) analysis. Any or all excluded keys can be restored at any time:
>> sp = restorekeys (sp, 3);
>> fr = meanfiringrate (sp, [-100 299], 50);
analysis is now performed using all keys except 2 and 4. It is also possible to directly specify groups of keys when calling analysis functions, and store predefined groups of keys in the object.
>> sp = addgroup (sp, 'att_away', 2:8);
>> fr = meanfiringrate (sp, [-100 299], 50, 'group', 'att_away');
>> fr = meanfiringrate (sp, [-100 299], 50, 'keys', 2:8);
The last two calls are equivalent.
Several keys can be combined in a single analysis. For example, if you have different keys corresponding to red stimulus targets of different orientations, and you are interested in analyzing the responses to all red stimuli irrespective of their orientation, you can create a key "combo":
>> sp = addcombo (sp, 'red', [2 18 31 40]);
>> fr = meanfiringrate (sp, [-100 299], 50, 'combo', 'red');
This analysis returns only one value (average firing rate to all red targets) per unit per bin.
Note that argument pairs can be listed in any order:
>> fr = meanfiringrate (sp, 75, 200, 'gro', 'red', 'uni', 1:20);
>> fr = meanfiringrate (sp, 75, 200, 'sub', 'niceunits', 'com', 'red');
Also note that only the first 3 (case insensitive) letters are needed to specify the RESTRICTION type.
