====== Generation of continuous carry-over covariates ======

Continuous carry-over experiments ([[http://dx.doi.org/10.1016/j.neuroimage.2007.02.005|Aguirre 2007]]) provide the experimenter with the ability to simultaneously examine BOLD fMRI activity associated with recovery from adaptation to a stimulus dimension and that directly associated with particular stimulus, independent of first-order context. We have written functions which help the experimenter in the practical task of constructing covariates which will model these various components to be examined. 

To use this code (although not the carry-over approach in general), your stimuli should fall in a well-defined stimulus space, varying on one or two dimensions.  (The code expects two; if only one dimension is used, the other should simply be held constant.)  You should also already have generated an efficient [[selection_of_efficient_type_1_index_1_sequences|type 1, index 1 sequence]] which contains //n// elements, where //n// is the number of stimuli you plan to present, plus 1 for the blank screen. 

The functions [[public:dmd_covariatecode#writeccocov|writeccocov]] and [[public:dmd_covariatecode#genccocov|genccocov]] do the work.

===== writeccocov =====
<code>
% WRITECCOCOV(DEGREES, POINTSLIST, USETARGET, CUTOFFFIRST, RUNFILES, SEQUENCE, MINKEXPONENT)
</code>

This function calls ''genccocov'', and does the work of writing files for each experimental run. It takes several arguments.

^argument^default^description^
|degrees|0|Lets you specify a rotated stimulus space; see the //post-hoc tests// section of this page. For normal use, pass 0 or [].|
|pointslist|A 4 x 4 square grid, from -1.5 to +1.5|An //n// by 2 list of stimulus coordinates.|
|usetarget|false|Some experiments involve detection of an infrequent target. If yours is such, you should have //n// + 2 elements in your sequence, where //n// is the number of normal stimuli, not including the target.|
|cutofffirst|10|In the typical experiment one wishes to analyze all runs as if they were a single extended run. To do this, we duplicate the last //m// stimuli from run //k// at the beginning of run //k// + 1, and so on, so that at the end of these //m// stimuli the subject's brain is in approximately the correct contextual state. Then, in analysis, these timepoints are dropped. [[https://cfn.upenn.edu/aguirre/code/matlablib/expr/genouts.m|genouts.m]] will assist with this process. If the SEQUENCE you are using already has this padding, you can specify here how many elements in the sequence to ignore. If not, pass 0.|
|runfiles|5|If you are reading from sequence files (see code) rather than passing a SEQUENCE in as a variable, this specifies how many sequentially-numbered files to read from.|
|sequence| |This is the stimulus order; for example, [[https://cfn.upenn.edu/aguirre/public/exampledata/dioctpopcorn/REFs/sequence.ref|sequence.ref]]|
|minkexponent|2|The assumed distance metric of the stimulus space. 2 corresponds to a Euclidean metric; 1 to a city-block (additive) metric.|




===== genccocov =====

This actually does the work of generating the covariates. The covariates involved and the rationale for using them are described in [[http://dx.doi.org/10.1016/j.neuroimage.2007.02.005|Aguirre 2007]].

''genccocov'' returns a structure, ''covs'', containing the covariates. Those not ending in ''orig'' are [[public:dmd_covariatecode#mncnleavezeros|mean-centered excepting zeroes]].

The purpose of ''genccocov'' is to take a sequence vector ''v'' and return a set of covariates which describe that sequence in various ways.

^covariate^explanation^
|main|models the main effect of stimulus presence; it is 1 whenever a stimulus is present, and -1 for blank screens. (In practice, recall that this and most other covariates are mean-centered; rather than 1 and -1, there will be two real values, one positive and one negative.)|
|new|models the effect of a stimulus shown after a blank screen; it is 1 whenever a stimulus follows the blank, 0 for blanks, and -1 for stimuli which do not follow blanks.|
|rept|models the effect of a stimulus shown after the identical stimulus; it is 1 for repeats, 0 for blanks, and -1 for all other stimuli.|
|direct[PQ]|models the direct effect of each stimulus axis. It is the simply value of the stimulus on the axis.|
|adapt|models the recovery from adaptation to the previous stimulus, based on the passed similarity space, for each stimulus. It is the difference of the current and previous stimulus coordinates.|
|adapt[PQ]|is similar, but selective to only one dimension.|
|pairings|models each individual pair of stimuli (of the 120 possible)|
|target|models the presence of the target, if one is in use.|
|aftertarget|models the stimulus immediately following the target.|

===== GenTestMat =====


[[public:dmd_covariatecode#gentestmat|GenTestMat]] creates vectors and matrices representing stimulus spaces.


Given a set of points, e.g., the dioct space, it generates similarity and other matrices and vectors, e.g. cityblock distances:
|<code>
    0.2929         0
    0.7071         0
    1.0000    0.2929
    1.0000    0.7071
    0.7071    1.0000
    0.2929    1.0000
    0.0000    0.7071
    0.0000    0.2929
    0.2929    0.2929
    0.5000    0.2071
    0.7071    0.2929
    0.7929    0.5000
    0.7071    0.7071
    0.5000    0.7929
    0.2929    0.7071
    0.2071    0.5000
</code>|{{public:seqs:dioctspace_labels.png|}}|{{:public:seqs:dioctsim_labels.png|}}|

===== example data =====

We have made available an [[data_JNeurophysiology_2009_Drucker|example data and covariate set]] to demonstrate the process.