3. Reference documentation: all nistats functions

This is the class and function reference of nistats. Please refer to the full user guide for further details, as the class and function raw specifications may not be enough to give full guidelines on their uses.

List of modules

3.1. nistats.datasets: Datasets

Utilities to download NeuroImaging datasets Author: Gael Varoquaux

Functions:

fetch_language_localizer_demo_dataset([…])

Download language localizer demo dataset.

fetch_openneuro_dataset_index([data_dir, …])

Download a file with OpenNeuro BIDS dataset index.

select_from_index(urls[, inclusion_filters, …])

Select subset of urls with given filters.

fetch_openneuro_dataset([urls, data_dir, …])

Download OpenNeuro BIDS dataset.

fetch_localizer_first_level([data_dir, verbose])

Download a first-level localizer fMRI dataset

fetch_spm_auditory([data_dir, data_name, …])

Function to fetch SPM auditory single-subject data.

fetch_spm_multimodal_fmri([data_dir, …])

Fetcher for Multi-modal Face Dataset.

fetch_fiac_first_level([data_dir, verbose])

Download a first-level fiac fMRI dataset (2 sessions)

3.2. nistats.hemodynamic_models: Hemodynamic Models

This module is for hemodynamic reponse function (hrf) specification. Here we provide for SPM, Glover hrfs and finite timpulse response (FIR) models. This module closely follows SPM implementation

Author: Bertrand Thirion, 2011–2018

Functions:

spm_hrf(tr[, oversampling, time_length, onset])

Implementation of the SPM hrf model

glover_hrf(tr[, oversampling, time_length, …])

Implementation of the Glover hrf model

spm_time_derivative(tr[, oversampling, …])

Implementation of the SPM time derivative hrf (dhrf) model

glover_time_derivative(tr[, oversampling, …])

Implementation of the Glover time derivative hrf (dhrf) model

spm_dispersion_derivative(tr[, …])

Implementation of the SPM dispersion derivative hrf model

glover_dispersion_derivative(tr[, …])

Implementation of the Glover dispersion derivative hrf model

compute_regressor(exp_condition, hrf_model, …)

This is the main function to convolve regressors with hrf model

3.3. nistats.design_matrix: Design Matrix Creation

This module implements fMRI Design Matrix creation.

Design matrices are represented by Pandas DataFrames Computations of the different parts of the design matrix are confined to the make_first_level_design_matrix function, that create a DataFrame All the others are ancillary functions.

Design matrices contain three different types of regressors:

  1. Task-related regressors, that result from the convolution of the experimental paradigm regressors with hemodynamic models A hemodynamic model is one of:

    • ‘spm’ : linear filter used in the SPM software

    • ‘glover’ : linear filter estimated by G.Glover

    • ‘spm + derivative’, ‘glover + derivative’: the same linear models,

      plus their time derivative (2 regressors per condition)

    • ‘spm + derivative + dispersion’, ‘glover + derivative + dispersion’:

      idem plus the derivative wrt the dispersion parameter of the hrf (3 regressors per condition)

    • ‘fir’ : finite impulse response model, generic linear filter

  2. User-specified regressors, that represent information available on the data, e.g. motion parameters, physiological data resampled at the acquisition rate, or sinusoidal regressors that model the signal at a frequency of interest.

  3. Drift regressors, that represent low_frequency phenomena of no interest in the data; they need to be included to reduce variance estimates.

Author: Bertrand Thirion, 2009-2015

Functions:

make_first_level_design_matrix(frame_times)

Generate a design matrix from the input parameters

check_design_matrix(design_matrix)

Check that the provided DataFrame is indeed a valid design matrix descriptor, and returns a triplet of fields

make_second_level_design_matrix(subjects_label)

Sets up a second level design.

3.4. nistats.experimental_paradigm: Experimental Paradigm

An experimental protocol is handled as a pandas DataFrame that includes an ‘onset’ field.

This yields the onset time of the events in the experimental paradigm. It can also contain:

  • a ‘trial_type’ field that yields the condition identifier.

  • a ‘duration’ field that yields event duration (for so-called block

    paradigms).

  • a ‘modulation’ field that associated a scalar value to each event.

Author: Bertrand Thirion, 2015

Functions:

check_events(events)

Test that the events data describes a valid experimental paradigm

3.5. nistats.model: Statistical models

This module implement classes to handle statistical tests on likelihood models

Author: Bertrand Thirion, 2011–2015

Classes:

LikelihoodModelResults(theta, Y, model[, …])

Class to contain results from likelihood models

TContrastResults(t, sd, effect[, df_den])

Results from a t contrast of coefficients in a parametric model.

FContrastResults(effect, covariance, F, df_num)

Results from an F contrast of coefficients in a parametric model.

3.6. nistats.regression: Regression Models

This module implements some standard regression models: OLS and WLS models, as well as an AR(p) regression model.

Models are specified with a design matrix and are fit using their ‘fit’ method.

Subclasses that have more complicated covariance matrices should write over the ‘whiten’ method as the fit method prewhitens the response by calling ‘whiten’.

General reference for regression models:

‘Introduction to Linear Regression Analysis’, Douglas C. Montgomery,

Elizabeth A. Peck, G. Geoffrey Vining. Wiley, 2006.

Classes:

OLSModel(design)

A simple ordinary least squares model.

ARModel(design, rho)

A regression model with an AR(p) covariance structure.

RegressionResults(theta, Y, model, …[, …])

This class summarizes the fit of a linear regression model.

SimpleRegressionResults(results)

This class contains only information of the model fit necessary for contast computation.

3.7. nistats.first_level_model: First Level Model

This module presents an interface to use the glm implemented in nistats.regression.

It contains the GLM and contrast classes that are meant to be the main objects of fMRI data analyses.

Author: Bertrand Thirion, Martin Perez-Guevara, 2016

Classes:

FirstLevelModel([t_r, slice_time_ref, …])

Implementation of the General Linear Model for single session fMRI data.

Functions:

mean_scaling(Y[, axis])

Scaling of the data to have percent of baseline change along the specified axis

run_glm(Y, X[, noise_model, bins, n_jobs, …])

GLM fit for an fMRI data matrix

first_level_models_from_bids(dataset_path, …)

Create FirstLevelModel objects and fit arguments from a BIDS dataset.

3.8. nistats.second_level_model: Second Level Model

This module presents an interface to use the glm implemented in nistats.regression.

It provides facilities to realize a second level analysis on lists of first level contrasts or directly on fitted first level models

Author: Martin Perez-Guevara, 2016

Classes:

SecondLevelModel([mask_img, smoothing_fwhm, …])

Implementation of the General Linear Model for multiple subject fMRI data

3.9. nistats.contrasts: Contrasts

This module is for contrast computation and operation on contrast to obtain fixed effect results.

Author: Bertrand Thirion, Martin Perez-Guevara, 2016

Classes:

Contrast(effect, variance[, dim, dof, …])

The contrast class handles the estimation of statistical contrasts on a given model: student (t) or Fisher (F).

Functions:

compute_contrast(labels, regression_result, …)

Compute the specified contrast given an estimated glm

3.10. nistats.thresholding: Thresholding Maps

Utilities for probabilistic error control at voxel- and cluster-level in brain imaging: cluster-level thresholding, false discovery rate control, false discovery proportion in clusters.

Author: Bertrand Thirion, 2015 – 2019

Functions:

fdr_threshold(z_vals, alpha)

return the Benjamini-Hochberg FDR threshold for the input z_vals

map_threshold([stat_img, mask_img, alpha, …])

Compute the required threshold level and return the thresholded map

3.11. nistats.reporting: Report plotting functions

This module implements plotting functions useful to report analysis results.

Author: Martin Perez-Guevara, Elvis Dohmatob, 2017

Functions:

compare_niimgs(ref_imgs, src_imgs, masker[, …])

Creates plots to compare two lists of images and measure correlation.

plot_design_matrix(design_matrix[, rescale, …])

Plot a design matrix provided as a DataFrame

plot_contrast_matrix(contrast_def, design_matrix)

Creates plot for contrast definition.

get_clusters_table(stat_img, stat_threshold)

Creates pandas dataframe with img cluster statistics.

make_glm_report(model, contrasts[, title, …])

Returns HTMLDocument object for a report which shows all important aspects of a fitted GLM.

3.12. nistats.utils: Utility functions

Misc utilities for the library

Authors: Bertrand Thirion, Matthew Brett, 2015

Functions:

z_score(pvalue)

Return the z-score corresponding to a given p-value.

multiple_fast_inverse(a)

Compute the inverse of a set of arrays.

multiple_mahalanobis(effect, covariance)

Returns the squared Mahalanobis distance for a given set of samples

full_rank(X[, cmax])

Computes the condition number of X and if it is larger than cmax, returns a matrix with a condition number smaller than cmax.

positive_reciprocal(X)

Return element-wise reciprocal of array, setting X>=0 to 0

get_bids_files(main_path[, file_tag, …])

Search for files in a BIDS dataset following given constraints.

parse_bids_filename(img_path)

Returns dictionary with parsed information from file path