neurospin.utils.design_matrix

Module: neurospin.utils.design_matrix

Inheritance diagram for nipy.neurospin.utils.design_matrix:

fMRI Design Matrix creation functions.

Classes

BlockParadigm

class nipy.neurospin.utils.design_matrix.BlockParadigm(index=None, onset=None, duration=None, amplitude=None)

Bases: nipy.neurospin.utils.design_matrix.Paradigm

Class to handle block paradigms

__init__(index=None, onset=None, duration=None, amplitude=None)

Parameters:

index: array of shape (n_events), type = int, optional :

index of the events (the index of their exprimental condition)

onset: array of shape (n_events), type = float, optional :

onset time (in s.) of the events

amplitude: array of shape (n_events), type = float, optional, :

amplitude of the events (if applicable)

DesignMatrix

class nipy.neurospin.utils.design_matrix.DesignMatrix(frametimes=None, paradigm=None, hrf_model='Canonical', drift_model='Cosine', hfcut=128, drift_order=1, fir_delays=[, 0], fir_duration=1.0, cond_ids=None, add_regs=None, add_reg_names=None)

Bases: object

Class to handle design matrices

Methods

estimate
read_from_csv
show
write_csv

__init__(frametimes=None, paradigm=None, hrf_model='Canonical', drift_model='Cosine', hfcut=128, drift_order=1, fir_delays=[, 0], fir_duration=1.0, cond_ids=None, add_regs=None, add_reg_names=None)

Parameters:

frametimes: array of shape(nbframes), optional :

the timing of the scans

paradigm: Paradigm instance, optional :

descritpion of the experimental paradigm

hrf_model, string, optional, :

that specifies the hemodynamic reponse function it can be ‘Canonical’, ‘Canonical With Derivative’ or ‘FIR’

drift_model, string :

specifies the desired drift model, to be chosen among ‘Polynomial’, ‘Cosine’, ‘Blank’

hfcut=128: float , :

cut frequency of the low-pass filter

drift_order=1, int, :

order of the dirft model (in case it is polynomial)

fir_delays=[0], optional, :

array of shape(nb_onsets) or list in case of FIR design, yields the array of delays used in the FIR model

fir_duration=1., float, duration of the FIR block; :

in general it should be equal to the tr

cond_ids=None, list of strin of length (ncond), :

ids of the experimental conditions. If None this will be called ‘c0’,..,’cn’

add_regs=None, array of shape(naddreg, nbframes) :

additional user-supplied regressors

add_reg_names=None: list of (naddreg) regressor names :

if None, while naddreg>0, these will be termed ‘reg_%i’,i=0..naddreg-1

estimate()

Numerical estimation of self

read_from_csv(path)

load self.matrix and self.names from a csv file Parameter ——— path: string,

path of the .csv file that includes the matriox and related information

show(rescale=True, ax=None)

Vizualization of a design matrix

Parameters:

rescale: bool, optional :

rescale columns for visualization or not

ax: figure handle, optional :

Returns:

ax, figure handle :

write_csv(path)

write oneselfs as a csv

Parameters:path: string, path of the resulting csv file :

EventRelatedParadigm

class nipy.neurospin.utils.design_matrix.EventRelatedParadigm(index=None, onset=None, amplitude=None)

Bases: nipy.neurospin.utils.design_matrix.Paradigm

Class to handle event-related paradigms

__init__(index=None, onset=None, amplitude=None)

Parameters:

index: array of shape (n_events), type = int, optional :

index of the events (the index of their exprimental condition)

onset: array of shape (n_events), type = float, optional :

onset time (in s.) of the events

amplitude: array of shape (n_events), type = float, optional, :

amplitude of the events (if applicable)

Paradigm

class nipy.neurospin.utils.design_matrix.Paradigm(index=None, onset=None, amplitude=None)

Bases: object

Simple class to hanle the experimental paradigm in one session

__init__(index=None, onset=None, amplitude=None)

Parameters:

index: array of shape (n_events), type = int, optional :

index of the events (the index of their exprimental condition)

onset: array of shape (n_events), type = float, optional, :

onset time (in s.) of the events

amplitude: array of shape (n_events), type = float, optional, :

amplitude of the events (if applicable)

Functions

nipy.neurospin.utils.design_matrix.build_dmtx(form, frametimes)

This is a work arount to control the order of the regressor in the design matrix construction

Parameters:

form, the formula that describes the design matrix :

frametimes, array of shape (nb_time_samples), the time sampling grid :

Returns:

X array of shape (nrows,nb_time_samples) the sdesign matrix :

nipy.neurospin.utils.design_matrix.convolve_regressors(paradigm, hrf_model, names=None, fir_delays=[, 0], fir_duration=1.0)

Creation of a formula that represents the convolution of the conditions onset witha certain hrf model

Parameters:

paradigm: paradigm instance :

hrf_model, string that can be ‘Canonical’, :

‘Canonical With Derivative’ or ‘FIR’ that specifies the hemodynamic reponse function

names=None, list of strings corresponding to the condition names :

if names==None, these are create as ‘c1’,..,’cn’ meaning ‘condition 1’.. ‘condition n’

fir_delays=[0], optional, array of shape(nb_onsets) or list :

in case of FIR design, yields the array of delays used in the FIR model

fir_duration=1., float, duration of the FIR block; :

in general it should eb equal to the tr

Returns:

f a formula object that contains the convolved regressors :

as functions of time

names list of strings corresponding to the condition names :

the output names depend on teh hrf model used if ‘Canonical’ then this is identical to the input names if ‘Canonical With Derivative’, then two names are produced for

input name ‘name’: ‘name’ and ‘name_derivative’

fixme: :

normalization of the columns of the design matrix ? :

nipy.neurospin.utils.design_matrix.dmtx_light(frametimes, paradigm=None, hrf_model='Canonical', drift_model='Cosine', hfcut=128, drift_order=1, fir_delays=[, 0], fir_duration=1.0, cond_ids=None, add_regs=None, add_reg_names=None, path=None)

Make a design matrix while avoiding framework

Parameters:

frametimes: array of shape(nbframes), :

the timing of the scans

paradigm: Paradigm instance, optional :

descritpion of the experimental paradigm if paradigm==None, then no condition is included

hrf_model, string, optional, :

that specifies the hemodynamic reponse function it can be ‘Canonical’, ‘Canonical With Derivative’ or ‘FIR’

drift_model, string that specifies the desired drift model, :

to be chosen among ‘Polynomial’, ‘Cosine’, ‘Blank’

hfcut=128 float , cut frequency of the low-pass filter :

drift_order=1, int, order of the dirft model (in case it is polynomial) :

fir_delays=[0], optional, array of shape(nb_onsets) or list :

in case of FIR design, yields the array of delays used in the FIR model

fir_duration=1., float, duration of the FIR block; :

in general it should be equal to the tr

cond_ids=None, list of strin of length (ncond), :

ids of the experimental conditions.

If None this will be called ‘c0’,..,’cn’

add_regs=None, array of shape(naddreg, nbframes) :

additional user-supplied regressors

add_reg_names=None, list of (naddreg) regressor names :

if None, while naddreg>0, these will be termed ‘reg_%i’,i=0..naddreg-1

path: string, optional :

if not None, the matrix is written as a .csv file at the given path

Returns:

dmtx array of shape(nreg, nbframes): :

the sampled design matrix

names list of strings of len (nreg) :

the names of the columns of the design matrix

nipy.neurospin.utils.design_matrix.full_rank(X, cmax=1000000000000000.0)

This function possibly adds a scalar matrix to X to guarantee that the condition number is smaller than a given threshold.

Parameters:

X array of shape(nrows,ncols) :

cmax=1.e-15, float tolerance for condition number :

Returns:

X array of shape(nrows,ncols) after regularization :

cmax=1.e-15, float tolerance for condition number :

nipy.neurospin.utils.design_matrix.load_protocol_from_csv_file(path, session=None)

Read a (.csv) paradigm file consisting of values yielding (occurence time, (duration), event ID, modulation) and returns a paradigm instance or a dictionary of paradigm instances

Parameters:

path: string, :

path to a .csv file that describes the paradigm

session: int, optional :

session number. by default the output is a dictionary of session-level dictionaries indexed by session

Returns:

paradigm, paradigm instance (if session is provided), or :

dictionary of paradigm instances otherwise, the resulting session-by-session paradigm

nipy.neurospin.utils.design_matrix.set_drift(DriftModel, frametimes, order=1, hfcut=128.0)

Create the drift formula

Parameters:

DriftModel: string, :

to be chosen among ‘Polynomial’, ‘Cosine’, ‘Blank’ that specifies the desired drift model

frametimes: array of shape(ntimes), :

list of values representing the desired TRs

order: int, optional, :

order of the dirft model (in case it is polynomial)

hfcut: float, optional, :

frequency cut in case of a cosine model

Returns:

df, the resulting drift formula :