mkanalysis-sess - make FsFast analysis


mkanalysis-sess -analysis [analysis] -TR [TR] -paradigm [paradigm.par] -designtype [design] [<options>]


Positional Arguments


Required Flagged Arguments

-analysis [analysisname]

name of session-level functional analysis

This is the name given to the analysis. A folder called analysisname will be created in the Study Directory. Two files ( and analysis.cfg) will be created in this directory. The analysis parameters will be stored in these files. Contrast matrices (created by mkcontrast-sess) will also be stored in this directory. When the session data are analyzed with selxavg-sess or sfa-sess data, a folder called analysisname will be created in the functional subdirectory (FSD), and the results of the analysis will be placed there.

-TR [TR]

TR value in seconds

This is the TR in seconds. It will be checked against the TR in each session when selxavg-sess is run. See also -TER.

-paradigm [parname]

name of paradigm file

This is the name of the paradigm file as found in each functional run directory. For blocked and event-related designs, the paradigm file defines which event type was presented when. For periodic designs (retinotopy and AB blocked), it defines the phase and period of stimulation for each run. The name of the paradigm file must be the same across runs and sessions, though its contents can change. If event types are redefined (eg, post-hoc event sorting), then a new paradigm file (with a different name) should be created followed by creating a new analysis. For event and blocked designs, time=0 is relative to the time of acquisition of the first stored image.

-designtype [type]

type of design. Legal values are: event-related, blocked, abblocked, retinotopy

This specifies the type of design for which the analysis is being created. Legal values are event-related, blocked, abblocked, and retinotopy. Event-related and blocked must be analyzed with selxavg-sess. abblocked and retinotopy must be analyzed with sfa-sess. abblocked is a block design in which only two conditions (or one condition and one null condition) are presented in a periodic fashion. Ie, each condition is presented for for the same duration in an alternating fashion.

Optional Flagged Arguments


-fsd [FSD]

functional subdirectory

Functional subdirectory (FSD). This is the folder under the sessions directory in which the runs of raw functional data will be found (default is bold).

-funcstem [stem]

stem of functional data (default = f or fmc)

This is the bshort/bfloat stem of the functional volume to process. This volume must exist in each functional run. By default, the stem is f. If the -motioncor flag is included, then the stem fmc is used (this is the default output of mc-sess).


use motion corrected data (see mc-sess)

If the -motioncor flag is included, then the stem fmc is used (this is the default output of mc-sess).

-runlistfile [filename]

file with list of runs to include in analysis

This is a file that should exist in each FSD that lists the runs to be processed in that session. The name must be the same across sessions but the contents of each file can vary. If an RLF is not specified, all runs found in the FSD will be processed.


intensity normalize data (see inorm-sess)

Perform ?IntensityNormalization. This requires that inorm-sess be run on the volume specified by -funcstem (or whatever it defaults to). ?IntensityNormalization will force the grand within-tissue mean of the functional data to be 1000 for each run.

-fwhm [FWHM]

Full-Width/Half-Max for in-plane smoothing (mm)

This functionality is somewhat obsolete. Consider using spatialsmooth-sess for 3D smoothing. -fwhm specifies that within-plane (ie, 2D) spatial smoothing using a Hanning kernel should be performed. The Full-Width-Half-Max (FWHM) indicates the extent of the smoothing and is specified in mm.

-nskip [N]

skip the first N time points in each run

Skip the first N time points in each functional run. It may be necessary to eliminate the first 4 or 5 time points in a functional run because the sample has not reached magnetic equilibrium. This is usually not necessary if the sample was scanned with discarded acquisitions (DISTACQS or DDAs). Note: the nskip does not affect the definition of time=0 in the paradigm file (see -paradigm). This functionality can also be implemented using a time-point exclude file (see -tpef).

-tpef [filename]

time-point exclude file name

This is the name of a time point exclude file (TPEF). The TPEF stores a list of times (in seconds) of time points to exclude from the analysis. The TPEF must be found in the run directory with the functional data to which it applies. Like paradigm files, the TPEFs must have the same name across subjects and runs though their contents can differ. Unlike paradigm files, it is not necessary to have a TPEF in each run; if no TPEF is found, no time points are excluded.

-polyfit [N]

fit trend with polynomial of order N

Drift removal. Fit and remove polynomial of order N. Default is 1 (i.e., 0=mean, 1=linear, and 2=quadratic).

-extreg [extregstem]

external regressor

Use external regressors when doing estimation. The external regressors should be stored in the bfloat "volume" with stem extregstem. There should actually be only one file there (extregstem_000.bfloat). It should have one row, and the number of columns should be equal to the number of external regressors. The number of frames must be equal to the number time points. There should be an external regressor file in each run directory. By default, all the regressors will be used, but this can be changed with -nextreg. See also -mcextreg.


use motion parameters as external regressors

Use motion parameters as external regressors. This is the same as setting "-extreg mcextreg -nextreg 3". mcextreg is created when running mc-sess by orthognalizing the motion parameters. Only the top three components are used (unless changed with -nextreg). Note: this feature was incorporated into mc-sess on 7/1/02. If motion correction was run before this date, it will need to be re-run in order to create the mcextreg file.

-umask [umask]

set unix file permission mask to [umask]


print version and exit


my analysis has fallen, and it can't get up!

Event-Related and Blocked Design

-nconditions [Nc]

number of conditions (excluding fixation)

-timewindow [TW]

event time window (sec)

-prestim [PS]

event prestimulus window (sec)

(For blocked and event-related designs). Start averaging ?PreStimTimeWindow seconds before the onset of the stimulus. This only applies to analyses in which the no shape to the hemodynamic response is to be assumed (ie, -gammafit is not used).


temporal estimation resolution (sec)

(For event-related designs). The TER is the Temporal Estimation Resolution. This is the resolution to which the hemodynamic response will be estimated (in seconds). It must be an integer divisor of the TR. The stimulus schedule (ie, paradigm file) must have been created with with the given TER in mind.

-gammafit [gfDelta gfTau]

assume IRF is a gamma function

(For blocked and event-related designs). Assume that the hemodynamic response takes the shape of a gamma function. gfDelta is the hemodynamic delay (ie, the time until the onset of the response), and gfTau is the dispersion, which controls the rise and fall times. Both are specified in seconds. gfAlpha is the exponent for the gamma function (see -gammaexp); for BOLD, alpha=2. The gamma function takes the form: f(t) = ((t-delta)/tau)^alpha * exp(-(t-delta)/tau)

-gammaexp [gfAlpha]

gamma exponent (default is 2)

Exponent for the gamma function. Default is 2, which tends to fit the BOLD hemodynamic response better.

-taumax [tauMax]

maximum lag for noise autocor and whitening (sec)

(For blocked and event-related designs). This instructs selxavg-sess to estimate and correct for global autocorrelation in the noise. It will assume that the autocorrelation function is zero beyond a delay of tauMax seconds.

-mask [maskid]

use masks/maskid to compute autocor and whitening

This only applies when using -taumax. This is a mask (as found in bold/masks) that is used to limit the voxels used in the computation of the whitening fillter. Usually, one would run mkbrainmask-sess to create masks/brain, and then specify brain as maskid.

-timeoffset [toffset]

time offset (sec) to add to each paradigm file

(For blocked and event-related designs). The time to add to the times listed in each paradigm file. This is only useful if, for some reason, each paradigm file if off by the same amount. This may happen if there was a systematic delay between the beginning of the stimulus stream and the beginning of scanning.

Retinotopy and AB Blocked Design (Required)

-ncycles [N]

number of cycles in each run

(For retinotopy and AB blocked designs). For designs in which the stimuli are presented periodically, this is the number of cycles of stimulation presented in each run.







mkanalysis-sess creates an 'analysis'. An analysis is a concept within the FsFast processing stream framework. The analysis is meant to be a placeholder for all the within-session processing options (eg, motion correction, spatial smoothing, event-type definition, etc). As such, the parameters apply to ALL sessions (ie, it does not need to be run separately for each session), and does not depend upon the data in any one session. This program should be run from your FsFast Study Directory. This program only configures the analysis; it does not analyze the data (see selxavg-sess or sfa-sess).


Example 1

mkanalysis-sess foo -i f -o out


Example 2

mkanalysis-sess foo -i f -o out -f fvalue




See Also

othercommand1, othercommand2



Methods Description




Reporting Bugs

Report bugs to <>



mkanalysis-sess (last edited 2020-01-02 12:49:54 by DougGreve)