Multivariate Pattern Analysis in Python

# mvpa2.datasets.sources.openfmri.OpenFMRIDataset

class `mvpa2.datasets.sources.openfmri.``OpenFMRIDataset`(basedir)

  Handler for datasets following the openfmri.org layout specifications

  At present, this handler provides functions to query and access a number of dataset properties, BOLD images of individual acquisition runs, build datasets from individual BOLD images, and load stimulation design specifications for individual runs.

  Methods

  `get_anatomy_image`(subj[, path, fname]) | Return a NiBabel image instance for a structural image of a subject.
  `get_bold_run_dataset`(subj, task, run[, …]) | Return a dataset instance for the BOLD data of a particular subject/task/run combination.
  `get_bold_run_ids`(subj, task) | Return (sorted) list of run IDs for a given subject and task
  `get_bold_run_image`(subj, task, run[, flavor]) | Return a NiBabel image instance for the BOLD data of a particular subject/task/run combination.
  `get_bold_run_model`(model, subj, run) | Return the stimulation design for a particular subject/task/run.
  `get_bold_run_motion_estimates`(subj, task, run) | Return the volume-wise motion estimates for a particular BOLD run
  `get_model_bold_dataset`(model_id, subj_id[, …]) | Build a PyMVPA dataset for a model defined in the OpenFMRI dataset
  `get_model_conditions`(model) | Return a description of all conditions for a given model
  `get_model_contrasts`(model) | Return a defined contrasts for a model
  `get_model_descriptions`() | Return a dictionary with the models described in the dataset
  `get_model_ids`() | Return a sorted list of integer IDs for all available models
  `get_scan_properties`() | Return a dictionary with the scan properties listed in scan_key.txt
  `get_subj_ids`() | Return a (sorted) list of IDs for all subjects in the dataset
  `get_task_bold_attributes`(task, fname, loadfx) | Return data attributes for all BOLD data from a specific task.
  `get_task_bold_run_ids`(task) | Return a dictionary with run IDs by subjects for a given task
  `get_task_descriptions`() | Return a dictionary with the tasks defined in the dataset

  Parameters:

  basedir : path

  > Path to the dataset (i.e. the directory with the ‘sub*’ subdirectories).

  Methods

  `get_anatomy_image`(subj[, path, fname]) | Return a NiBabel image instance for a structural image of a subject.
  `get_bold_run_dataset`(subj, task, run[, …]) | Return a dataset instance for the BOLD data of a particular subject/task/run combination.
  `get_bold_run_ids`(subj, task) | Return (sorted) list of run IDs for a given subject and task
  `get_bold_run_image`(subj, task, run[, flavor]) | Return a NiBabel image instance for the BOLD data of a particular subject/task/run combination.
  `get_bold_run_model`(model, subj, run) | Return the stimulation design for a particular subject/task/run.
  `get_bold_run_motion_estimates`(subj, task, run) | Return the volume-wise motion estimates for a particular BOLD run
  `get_model_bold_dataset`(model_id, subj_id[, …]) | Build a PyMVPA dataset for a model defined in the OpenFMRI dataset
  `get_model_conditions`(model) | Return a description of all conditions for a given model
  `get_model_contrasts`(model) | Return a defined contrasts for a model
  `get_model_descriptions`() | Return a dictionary with the models described in the dataset
  `get_model_ids`() | Return a sorted list of integer IDs for all available models
  `get_scan_properties`() | Return a dictionary with the scan properties listed in scan_key.txt
  `get_subj_ids`() | Return a (sorted) list of IDs for all subjects in the dataset
  `get_task_bold_attributes`(task, fname, loadfx) | Return data attributes for all BOLD data from a specific task.
  `get_task_bold_run_ids`(task) | Return a dictionary with run IDs by subjects for a given task
  `get_task_descriptions`() | Return a dictionary with the tasks defined in the dataset

  `get_anatomy_image`(subj, path=None, fname='highres001.nii.gz')

    Return a NiBabel image instance for a structural image of a subject.

    Parameters:

    subj : int

    > Subject identifier.

    path : list or None

    > Path to the structural file within the anatomy/ tree.

    fname : str

    > Access a particular anatomy data flavor via its filename (see dataset description). Defaults to the first T1-weighted image.

    Returns: | NiBabel Nifti1Image

  `get_bold_run_dataset`(subj, task, run, flavor=None, preproc_img=None, add_sa=None, **kwargs)

    Return a dataset instance for the BOLD data of a particular subject/task/run combination.

    This method support the same functionality as fmri_dataset(), while wrapping get_bold_run_image() to access the input fMRI data. Additional attributes, such as subject ID, task ID, and run ID are automatically stored as dataset sample attributes.

    Parameters:

    subj : int

    > Subject identifier.

    task : int

    > Task ID (see task_key.txt)

    run : int

    > Run ID.

    flavor : None or str

    > BOLD data flavor to access (see dataset description). If `flavor` corresponds to an existing file in the respective task/run directory, it is assumed to be a stored dataset in HDF5 format and loaded via `h5load()` – otherwise datasets are constructed from NIfTI images.

    preproc_img : callable or None

    > If not None, this callable will be called with the loaded source BOLD image instance as an argument before fmri_dataset() is executed. The callable must return an image instance.

    add_sa: str or tuple(str)

    > Single or sequence of names of files in the respective BOLD directory containing additional samples attributes. At this time all formats supported by NumPy’s loadtxt() are supported. The number of lines in such a file needs to match the number of BOLD volumes. Each column is converted into a separate dataset sample attribute. The file name with a column index suffix is used to determine the attribute name.

    **kwargs:

    > All additional arguments are passed on to fmri_dataset()

    Returns: | Dataset

  `get_bold_run_ids`(subj, task)

    Return (sorted) list of run IDs for a given subject and task

    Typically, run IDs are integer values, but string IDs are supported as well.

    Parameters:

    subj : int or str

    > Subject ID

    task : int or str

    > Run ID

  `get_bold_run_image`(subj, task, run, flavor=None)

    Return a NiBabel image instance for the BOLD data of a particular subject/task/run combination.

    Parameters:

    subj : int

    > Subject identifier.

    task : int

    > Task ID (see task_key.txt)

    run : int

    > Run ID.

    flavor : None or str

    > BOLD data flavor to access (see dataset description)

  `get_bold_run_model`(model, subj, run)

    Return the stimulation design for a particular subject/task/run.

    Parameters:

    model : int

    > Model identifier.

    subj : int

    > Subject identifier.

    run : int

    > Run ID.

    Returns:

    list

    > One item per event in the run. All items are dictionaries with the following keys: ‘condition’, ‘onset’, ‘duration’, ‘intensity’, ‘run’, ‘task’, ‘trial_idx’, ‘ctrial_idx’, where the first is a literal label, the last four are integer IDs, and the rest are typically floating point values. ‘onset_idx’ is the index of the event specification sorted by time across the entire run (typically corresponding to a trial index), ‘conset_idx’ is analog but contains the onset index per condition, i.e. the nth trial of the respective condition in a run.

  `get_bold_run_motion_estimates`(subj, task, run, fname='bold_moest.txt')

    Return the volume-wise motion estimates for a particular BOLD run

    Parameters:

    subj : int

    > Subject identifier.

    task : int

    > Task ID (see task_key.txt)

    run : int

    > Run ID.

    fname : str

    > Filename.

    Returns:

    array

    > Array of floats – one row per fMRI volume, 6 columns (typically, the first three are translation X, Y, Z in mm and the last three rotation in deg)

  `get_model_bold_dataset`(model_id, subj_id, run_ids=None, preproc_img=None, preproc_ds=None, modelfx=None, stack=True, flavor=None, mask=None, add_fa=None, add_sa=None, **kwargs)

    Build a PyMVPA dataset for a model defined in the OpenFMRI dataset

    Parameters:

    model_id : int

    > Model ID.

    subj_id : int or str or list

    > Integer, or string ID of the subject whose data shall be considered. Alternatively, a list of IDs can be given and data from all matching subjects will be loaded at once.

    run_ids : list, optional

    > Run ids to be loaded. If None, all runs get loaded

    preproc_img : callable or None

    > See get_bold_run_dataset() documentation

    preproc_ds : callable or None

    > If not None, this callable will be called with each run bold dataset as an argument before `modelfx` is executed. The callable must return a dataset.

    modelfx : callable or None

    > This callable will be called with each run dataset and the respective event list for each run as arguments, In addition all additional **kwargs of this method will be passed on to this callable. The callable must return a dataset. If None, `assign_conditionlabels` will be used as a default callable.

    stack : boolean

    > Flag whether to stack all run datasets into a single dataset, or whether to return a list of datasets.

    flavor

    > See get_bold_run_dataset() documentation

    mask

    > See fmri_dataset() documentation.

    add_fa

    > See fmri_dataset() documentation.

    add_sa

    > See get_bold_run_dataset() documentation.

    Returns:

    Dataset or list

    > Depending on the `stack` argument either a single dataset or a list of datasets for all subject/task/run combinations relevant to the model will be returned. In the stacked case the dataset attributes of the returned dataset are taken from the first run dataset, and are assumed to be identical for all of them.

  `get_model_conditions`(model)

    Return a description of all conditions for a given model

    Parameters:

    model : int

    > Model identifier.

    Returns:

    list(dict)

    > A list of a model conditions is returned, where each item is a dictionary with keys `id` (numerical condition ID), `task` (numerical task ID for the task containing this condition), and `name` (the literal condition name). This information is returned in a list (instead of a dictionary), because the openfmri specification of model conditions contains no unique condition identifier. Conditions are only uniquely described by the combination of task and condition ID.

  `get_model_contrasts`(model)

    Return a defined contrasts for a model

    Parameters:

    model : int

    > Model identifier.

    Returns:

    dict(dict)

    > A dictionary is returned, where each key is a (numerical) task ID and each value is a dictionary with contrast labels (str) as keys and contrast vectors as values.

  `get_model_descriptions`()

    Return a dictionary with the models described in the dataset

    Dictionary keys are integer model IDs, values are description strings.

    Note that the return dictionary is not necessarily comprehensive. It only reflects the models described in `model_key.txt`. If a dataset is inconsistently described, `get_model_ids()` actually may discover more or less models in comparison to the avauilable model descriptions.

  `get_model_ids`()

    Return a sorted list of integer IDs for all available models

  `get_scan_properties`()

    Return a dictionary with the scan properties listed in scan_key.txt

  `get_subj_ids`()

    Return a (sorted) list of IDs for all subjects in the dataset

    Standard numerical subject IDs a returned as integer values. All other types of IDs are returned as strings with the ‘sub’ prefix stripped.

  `get_task_bold_attributes`(task, fname, loadfx, exclude_subjs=None)

    Return data attributes for all BOLD data from a specific task.

    This function can load arbitrary data from the directories where the relevant BOLD image files are stored. Data sources are described by specifying the file name containing the data in the BOLD directory, and by providing a function that returns the file content in array form. Optionally, data from specific subjects can be skipped.

    For example, this function can be used to access motion estimates.

    Parameters:

    task : int

    > Task ID (see task_key.txt)

    fname : str

    > Filename.

    loadfx : functor

    > Function that can open the relevant files and return their content as an array. This function is called with the name of the data file as its only argument.

    exclude_subjs : list or None

    > Optional list of subject IDs whose data shall be skipped.

    Returns:

    list(dict(array))

    > A list (one item per run) of dictionaries (one item per subject, key is subject ID) of arrays. Each array carries the information loaded from the respective files.

  `get_task_bold_run_ids`(task)

    Return a dictionary with run IDs by subjects for a given task

    Dictionary keys are subject IDs, values are lists of run IDs.

  `get_task_descriptions`()

    Return a dictionary with the tasks defined in the dataset

    Dictionary keys are integer task IDs, values are task description strings.