"RESTRICTION" arguments with @spix methods

Introduction

@spix methods (functions that analyze @spix data and return results) use variable argument lists. Mandatory arguments are followed by optional RESTRICTIONS in the form of argument pairs whose purpose is to limit analysis to unit subsets and/or key groups. For example:

meanfiringrate (sp, start, bin, 'units', [2 4 6 10])

computes average firing rates from the sp @spix object, over an epoch of bin ms beginning start ms from the cue event, but only for units #2, 4, 6, and 10. The first 3 (mandatory) arguments are followed by an argument pair, composed of the argument type (a string) and the argument value, which restricts analysis to a subset of units. In general, the following restrictions can be applied:

restriction value note
units a range of explicitly invoked units mutually exclusive
subset a range of previously stored units
keys a range of explicitly invoked keys; separate analyses are run on each of the keys mutually exclusive
combo a range of previously stored keys; the keys in a combo are combined in a single analysis
group a range of previously stored keys; separate analyses are run on each of the keys in a group
factor see @spix/anovan
level see @spix/anovan only allowed after a factor

Values can be specified in different ways:

value type processes
scalar the item identified by its ordinal number (i.e., the order in which it was added to the spix)
numeric vector the items identified by their ordinal numbers (i.e., the order in which they were added to the spix)
string the item identified by its label;
one of the following reserved strings: 'first' 'last' 'all' 'none'
cell array of strings the items identified by their labels

The following table shows the valid value types for each restriction:

restriction scalar numvector string cell array
units yes yes yes yes
subset yes   yes  
keys yes yes yes yes
combo yes yes yes yes
group yes   yes  
factor yes   yes  

Important reminders

Note that if restrictions for units/keys are not invoked, then all currently selected units/keys are used. To change the current selections use the following methods:

selectunits excludeunits restoreunits
selectkeys excludekeys restorekeys

Also note that the first 3 (case insensitive) letters are actually sufficient to specify a restriction. For example, the following calls are all equivalent:

>> meanfiringrate (sp, start, bin, 'units', [2 4 6 10]);
>> meanfiringrate (sp, start, bin, 'uNI', [2 4 6 10]);
>> meanfiringrate (sp, start, bin, 'Unità', [2 4 6 10]);

Examples

The following examples assume that sp is a @spix object containing 30 units and 40 keys. No units or keys are currently excluded.

>> meanfiringrate (sp, start, bin, 'units', [2 4 6 10])

(analysis run on 4 units using all 40 keys)

>> meanfiringrate (sp, start, bin, 'keys', 1:8)

(analysis run on all 30 units, using only the first 8 keys)

>> meanfiringrate (sp, start, bin, 'key', 'red_vertical', 'units', [2 4 6 10])

(analysis run on 4 units using only the key labeled 'red_vertical')

>> sp = addgroup (sp, 'reds', {'red_vert' 'red_horiz' 'red_left' 'red_right'});
>> sp = addsubset (sp, 'nice', {'990101.1' '990312.1' '990502.1'});
>> meanfiringrate (sp, start, bin, 'sub', 'nice', 'gro', 'reds')

(analysis run on the 3 units contained in the 'nice' subset, using the 4 keys contained in the group 'red')

>> sp = addcombo (sp, 'redcom', {'red_vert' 'red_horiz' 'red_left' 'red_right'});
>> sp = excludeunits (sp, {'990101.1' '990312.1' '990502.1'});
>> meanfiringrate (sp, start, bin, 'com', 'redcom')

(analysis run on all but 3 units, using the 'redcom' key combo. The 4 keys contained in 'redcom' are combined, and therefore treated as if they were the same condition.)