NIPY logo

Site Navigation

NIPY Community

Table Of Contents

Previous topic

neurospin.statistical_mapping

This Page

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(con_id=None, onset=None, duration=None, amplitude=None)

Bases: nipy.neurospin.utils.design_matrix.Paradigm

Class to handle block paradigms

__init__(con_id=None, onset=None, duration=None, amplitude=None)
Parameters :

con_id: array of shape (n_events), type = string, optional :

id of the events (name of the 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, 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, 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, optional :

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

hfcut: float, optional :

cut frequency of the low-pass filter

drift_order: int, optional :

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

fir_delays: array of shape(nb_onsets) or list, optional, :

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

fir_duration: float, optional :

duration of the FIR block; in general it should be equal to the tr

add_regs: array of shape(nbframes, naddreg), optional :

additional user-supplied regressors

add_reg_names: list of (naddreg) regressor names, optional :

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

estimate()

Numerical estimation of self.

This creates the following attributes:
drift, conditions, formula, names, matrix, design_cond

and sets self.estimated to True

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 matrix and related information
show(rescale=True, ax=None)

Vizualization of a design matrix

Parameters :

rescale: bool, optional :

rescale columns magnitude for visualization or not

ax: figure handle, optional :

Returns :

ax, figure handle :

write_csv(path)

write self.matrix as a csv file witha propriate column names

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

EventRelatedParadigm

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

Bases: nipy.neurospin.utils.design_matrix.Paradigm

Class to handle event-related paradigms

__init__(con_id=None, onset=None, amplitude=None)
Parameters :

con_id: array of shape (n_events), type = string, optional :

id of the events (name of the 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(con_id=None, onset=None, amplitude=None)

Bases: object

Simple class to hanle the experimental paradigm in one session

__init__(con_id=None, onset=None, amplitude=None)
Parameters :

con_id: array of shape (n_events), type = string, optional :

identifier of the events

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: formula.Formula instance, :

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 resulting matrix

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

Creation of a formula that represents the convolution of the conditions onset with a 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

end_time: float, :

end time of the paradigm (needed only for block designs)

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: formula instance, :

contains the convolved regressors as functions of time

names: list of strings, :

the condition names, that depend on the 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’

nipy.neurospin.utils.design_matrix.dmtx_from_csv(path)

return a DesignMatrix instance from a csv file

Parameters :

path: string, :

path of the .csv file

Returns :

A DesignMatrix instance :

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, 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

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

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 :