pcarpet.Dataset

class pcarpet.Dataset(fmri_file, mask_file, output_dir)

Class for generating carpet plot from fMRI data and fitting PCA to it

correlate_with_carpet(ncomp=5, flip_sign=True)

Correlates the first ncomp principal components (PCs) with all carpet voxel time-series. Saves the correlation matrix.

Parameters

ncompint

Number of PCA components to retain. These first PCs (fPCs) are correlated with all carpet voxels. Default: 5

flip_signboolean

If True, an fPC (and its correlation values) will be sign-flipped when the median of its original correlation with carpet voxels is negative. This enforces the sign of the fPC to match the sign of the BOLD signal activity for most voxels. The sign-flipped fPCs are only used for downstream analysis and visualization (the saved PCA components and scores retain the original sign). Default: True

correlate_with_fmri()

Correlates the retained (and possibly sign-flipped) first ncomp PCs (fPCs) with the original 4d fMRI dataset and saves the resulting correlation maps as a 4d NIFTI file (3d space + ncomp).

fit_pca2carpet(save_pca_scores=False)

Fits PCA to carpet matrix and saves the principal componens (PCs), the explained variance ratios, and optionally the PCA scores (PCA-tranformed carpet)

Parameters

save_pca_scoresboolean

Whether to save the PCA scores (transformed carpet) in the output directory. The file might be large (possibly > 100MB depending on fMRI data and mask size). Default: False

get_carpet(tSNR_thresh=15.0, reorder_carpet=True, save_carpet=False)

Makes a carpet matrix from fMRI data. A carpet is a 2d matrix shaped voxels x time which contains the normalized (z-score) BOLD-fMRI signal from within a mask

Parameters

tSNR_threshfloat or None

Voxels with tSNR values below this threshold will be excluded. To deactivate set to None. Default: 15.0

reorder_carpetboolean

Whether to reorder carpet voxels according to their (decreasing) correlation with the global (mean across voxels) signal Default: True

save_carpetboolean

Whether to save the carpet matrix in the output directory. The file might be large (possibly > 100MB depending on fMRI data and mask size). Default: False

import_data()

Loads fMRI and mask data using nibabel.

plot_report(TR='auto')

Plots a report of the results, including the carpet plot, the first ncomp PCs (fPCs), their correlation with the carpet, and their explained variance ratios. The plot image is saved in ‘.png’ (raster) and ‘.svg’ (vector) formats.

Parameters

TR‘auto’ or float

fMRI repetition time in seconds. If ‘auto’, the program attempts to read TR from the fMRI header. This can be bypassed by explicitly passing TR as a float. Default: ‘auto’

run_pcarpet(**kwargs)

Runs the entire pcarpet pipeline using the default options for each function. The defaults can be overriden by passing the following optional keywords arguments:

Parameters

tSNR_threshfloat or None

Voxels with tSNR values below this threshold will be excluded from the carpet. To deactivate set to None. Default: 15.0

reorder_carpetboolean

Whether to reorder carpet voxels according to their (decreasing) correlation with the global (mean across voxels) signal Default: True

save_carpetboolean

Whether to save the carpet matrix in the output directory. The file might be large (possibly > 100MB depending on fMRI data and mask size). Default: False

save_pca_scoresboolean

Whether to save the PCA scores (transformed carpet) in the output directory. The file might be large (possibly > 100MB depending on fMRI data and mask size). Default: False

ncompint

Number of PCA components to retain. These first PCs (fPCs) are correlated with all carpet voxels and subsequently also with the entire fMRI dataset. Default: 5

flip_signboolean

If True, an fPC (and its correlation values) will be sign-flipped when the median of its original correlation with carpet voxels is negative. This enforces the sign of the fPC to match the sign of the BOLD signal activity for most voxels. The sign-flipped fPCs are only used for downstream analysis and visualization (the saved PCA components and scores retain the original sign). Default: True

TR‘auto’ or float

fMRI repetition time in seconds. If ‘auto’, the program attempts to read the TR from the fMRI header. This can be bypassed by explicitly passing TR as a float. Default: ‘auto’