decon - Wrapper for AFNI’s 3dDeconvolve program

class neural.decon.Decon

wrapper for AFNI 3dDeconvolve command

Properties:

input_dset:list of input datasets decon_stims:list of DeconStim objects that define the different stimuli. Allows for flexible coding of complex stimuli. Alternatively, for simpler stimuli, you can simply use one of the traditional options below (e.g., stim_files or stim_times) stim_files:dict where keys are used as stimulus labels and the values are taken as 1D files stim_times:same as stim_files, but used as a stim_times file models:dict of model names to use for each of the listed stimuli (optional) model_default:default model to use for each stim_times stimulus if nothing is listed in models stim_base:list of names of stimuli (defined either in stim_files or stim_times) that should be considered in the baseline instead of full model stim_am1:list of names of stimuli defined in stim_times that should use the -stim_times_AM1 model stim_am2:list of names of stimuli defined in stim_times that should use the -stim_times_AM2 model glts:dict where keys are GLT labels, and the value is a symbolic statement mask:either a mask file, or “auto”, which will use “-automask” errts:name of file to save residual time series to

Options that are obvious:

nfirst (default: 3), censor_file, polort (default: ‘A’), tout, vout, rout, prefix

Other options:

opts:list of extra things to put directly in the command (in case none of the above options cover you) partial:dict with keys of datasets (given in input_dsets) and values of a tuple of (start,end) for each given dataset. Will automatically adjust all stimfiles and such to match. Column-style stimuli only work if there’s only one dataset

Example::

decon = neural.decon.Decon()
decon.input_dsets = ['dset_run1.nii.gz', 'dset_run2.nii.gz']
decon.censor_file = 'subject_censor.1D'
decon.stim_files = {
    'motion_1': 'motion_file.1D[0]',
    'motion_2': 'motion_file.1D[1]',
    'motion_3': 'motion_file.1D[2]',
    'motion_4': 'motion_file.1D[3]',
    'motion_5': 'motion_file.1D[4]',
    'motion_6': 'motion_file.1D[5]'
}
decon.stim_base = ['motion_%d' % i for i in range(1,7)]
decon.stim_times = {
    'stim_a': 'stim_a.stimtimes',
    'stim_b': 'stim_b.stimtimes',
    'stim_c': 'stim_c.stimtimes',
}
decon.glts ={
    'a-b': '1*stim_a + -1*stim_b',
    'ab-c': '0.5*stim_a + 0.5*stim_b + -1*stim_c'
}
decon.prefix = 'subject_decon.nii.gz'
decon.run()

command_list()

returns the 3dDeconvolve command as a list

The list returned can be run by passing it into a subprocess-like command (e.g., neural.run())

command_string()

returns the 3dDeconvolve command as as string

This command can then be run in something like a shell script

run()

runs 3dDeconvolve through the neural.utils.run shortcut

class neural.decon.DeconStim(name, column_file=None, times_file=None, model='GAM', base=False, AM1=False, AM2=False)

encapsulates the definition of any arbitrary stimulus, along with all of its 3dDeconvolve options

Attributes:

name:Label used for the stimulus

You only need to define one of the following to define the stimulus: :column: A list of numbers (usually the length of the runs) that is placed directly in the 3dDeconvolve

matrix. This can be a series of 1’s and 0’s, a 1D-file that has already been convolved with an HRF, or a covariate like motion parameters

column_file:The filename of a file that contains a matrix column times:Definition of stimuli using stim_times approach. Either a list or a list of list``s (one for each run) containing either ``float``s or strings of the stimulus times. For details on how to define the stimulus time, see the documentation of ``3dDeconvolve. times_file:A file containing a stim_times stimulus times_model:If using stim_times, which HRF model to use base:Is this stimulus part of the baseline? (True/False) AM1:Does this stimulus use an “AM1” model? (True/False) AM2:Does this stimulus use an “AM2” model? (True/False) reps:Number of reps in associated fMRI run (helpful when manipulating the stims) TR:TR of the associated fMRI run

blank_stim(type=None, fill=0)

Makes a blank version of stim. If a type is not given, returned as same type as current stim. If a column stim, will fill in blanks with fill

concat_stim(decon_stim)

concatenate this to another DeconStim of the same “type”

partial(start=0, end=None, run=0)

chops the stimulus by only including time points start through end (in reps, inclusive; None``=until the end) if using stim_times-style simulus, will change the ``run’th run. If a column, will just chop the column

read_file()

if this is stored in a file, read it into self.column

type()

returns kind of stim (“column” or “times”), based on what parameters are set

neural.decon.smooth_decon_to_fwhm(decon, fwhm, cache=True)

takes an input Decon object and uses 3dBlurToFWHM to make the output as close as possible to fwhm returns the final measured fwhm. If cache is True, will save the blurred input file (and use it again in the future)

neural.decon.stack_decon_stims(stim_list)

take a list (in order of runs) of dict``s of stim_name:DeconStim and stack them together. returns a single ``dict of stim_name:decon_stim

As in, takes: [

# Run 1 { “stim1”: decon_stim1a, “stim2”: decon_stim2a }, # Run 2 { “stim1”: decon_stim1b, “stim2”: decon_stim2b, “stim3”: decon_stim3 }

]

And makes:

{ “stim1”: decon_stim1, “stim2”: decon_stim2, “stim3”: decon_stim3 }

If a stimulus is not present in a run, it will fill that run with an empty stimulus