# modalities.fmri.experimental_paradigm

## Module: `modalities.fmri.experimental_paradigm`

Inheritance diagram for `nipy.modalities.fmri.experimental_paradigm`:

This module implements an object to deal with experimental paradigms. In fMRI data analysis, there are two main types of experimental paradigms: block and event-related paradigms. They correspond to 2 classes EventRelatedParadigm and BlockParadigm. Both are implemented here, together with functions to write paradigms to csv files.

### Notes

Although the Paradigm object have no notion of session or acquisitions (they are assumed to correspond to a sequential acquisition, called ‘session’ in SPM jargon), the .csv file used to represent paradigm may be multi-session, so it is assumed that the first column of a file yielding a paradigm is in fact a session index

Author: Bertrand Thirion, 2009-2011

## Classes

### `BlockParadigm`

class nipy.modalities.fmri.experimental_paradigm.BlockParadigm(con_id=None, onset=None, duration=None, amplitude=None)

  Bases: `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 experimental 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)

  write_to_csv(csv_file, session='0')

    Write the paradigm to a csv file

    Parameters:
      csv_file: string, path of the csv file
      session: string, optional, session identifier

### `EventRelatedParadigm`

class nipy.modalities.fmri.experimental_paradigm.EventRelatedParadigm(con_id=None, onset=None, amplitude=None)

  Bases: `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 experimental 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)

  write_to_csv(csv_file, session='0')

    Write the paradigm to a csv file

    Parameters:
      csv_file: string, path of the csv file
      session: string, optional, session identifier

### `Paradigm`

class nipy.modalities.fmri.experimental_paradigm.Paradigm(con_id=None, onset=None, amplitude=None)

  Bases: `object`

  Simple class to handle 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)

  write_to_csv(csv_file, session='0')

    Write the paradigm to a csv file

    Parameters:
      csv_file: string, path of the csv file
      session: string, optional, session identifier

## Function

nipy.modalities.fmri.experimental_paradigm.load_paradigm_from_csv_file(path, session=None)

  Read a (.csv) paradigm file consisting of values yielding (occurrence 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: string, optional, session identifier

      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

  Notes

  It is assumed that the csv file contains the following columns: (session id, condition id, onset), plus possibly (duration) and/or (amplitude). If all the durations are 0, the paradigm will be handled as event-related.

  FIXME: would be much clearer if amplitude was put before duration in the .csv