TimeseriesExtractor

class neurocaps.extraction.TimeseriesExtractor(space='MNI152NLin2009cAsym', parcel_approach=None, standardize=True, detrend=False, low_pass=None, high_pass=None, fwhm=None, use_confounds=True, confound_names='basic', fd_threshold=None, n_acompcor_separate=None, dummy_scans=None, dtype=None)

Timeseries Extractor Class.

Performs timeseries denoising, extraction, serialization (pickling), and visualization.

Important

It is highly recommended for all imaging data (the preprocessed BOLD images and parcellation map) to be in a standard MNI space. This is due to the CAP.caps2surf assuming that the parcellation map is in MNI standard space when transforming data between volumetric and surface spaces.

Parameters:

• space (str, default=”MNI152NLin2009cAsym”) – The standard template space that the preprocessed BOLD data is registered to. This parameter is used for querying the preprocessed BOLD data with BIDSLayout.

• parcel_approach (ParcelConfig, ParcelApproach, str, or None, default=None) –

  Specifies the parcellation approach to use. Options are “Schaefer”, “AAL”, or “Custom”. Can be initialized with parameters, as a nested dictionary, or loaded from a serialized file (i.e. pickle, joblib, json). For detailed documentation on the expected structure, see the type definitions for ParcelConfig and ParcelApproach in the “See Also” section. Defaults to {"Schaefer": {"n_rois": 400, "yeo_networks": 7, "resolution_mm": 1}} if None.

  Important

  The default “regions” names for “AAL” was changed in versions >=0.31.0, which will group nodes differently.

• standardize (bool or or None, default=True) –

  Standardizes the timeseries (zero mean and unit variance using sample standard deviation). Always the final step in the pipeline.

  Note

  Standard deviations below np.finfo(std.dtype).eps are replaced with 1 for numerical stability.

• detrend (bool, default=False) – Detrends the timeseries.

• low_pass (float, int, or None, default=None) – Filters out signals above the specified cutoff frequency.

• high_pass (float, int, or None, default=None) –

  Filters out signals below the specified cutoff frequency. .. versionchanged:: 0.37.4

  When cosine regressors (e.g., “cosine*”) are detected in user-specified confound_names, high_pass is automatically set to None to avoid multicollinearity between nilearn’s DCT basis functions and fMRIPrep’s cosine regressors.

• fwhm (float, int, or None, default=None) – Applies spatial smoothing to data (in millimeters).

• use_confounds (bool, default=True) –

  If True, performs nuisance regression during timeseries extraction using the default or user-specified confounds in confound_names.

  Important

  Requires the confound tsv files to be in same directory as preprocessed BOLD images.

• confound_names ({“basic”}, list[str], or None, default=”basic”) –

  Names of confounds extracted from the confound tsv files if use_confounds=True.

  If “basic”, the following confounds are used by default:

  • All discrete cosine-basis regressors (removes low-frequency signal drift, operates as a high-pass filter).

  • Six head-motion parameters and their first-order derivatives.

  • First six principal aCompCor components (accounts for physiological and motion-related artifacts).

  Important

  • Confound names follow fMRIPrep’s naming scheme (versions >= 1.2.0).

  • Wildcards are supported to match prefixes (e.g., “cosine*” matches all confounds starting with “cosine”.)

• fd_threshold (float, dict[str, float | int], or None, default=None) –

  Threshold for volume scrubbing (censoring) based on framewise displacement (FD).

  • If float, removes volumes where FD > threshold.

  • If dict, the following subkeys are available (all non-required subkeys are None by default):

    • ”threshold”: A float (required). Removes volumes where FD > threshold.

    • ”outlier_percentage”: A float in interval [0,1]. Removes entire runs where proportion of volumes exceeds the specified threshold. Proportion calculated after dummy scan removal to not deflate the percentage of steady-state volumes removed.

      Note

      • A warning is issued when a run is flagged.

      • If condition specified for task-based data in self.get_bold(), only considers volumes associated with the condition.

    • ”n_before”: An integer. Indicates the number of volumes to remove before each flagged volume.

    • ”n_after”: An integer. Indicates the number of volumes to remove after each flagged volume.

    • ”use_sample_mask”: A boolean. Controls when scrubbing is applied in the processing pipeline.

      Important

      • When True: - Passes a sample mask of high-motion volumes to Nilearn’s NiftiLabelsMasker. - Scrubbing is applied before nuisance regression. - Nilearn replaces high motion volumes with interpolated values using Scipy’s CubicSpline function prior to detrending and band-pass filtering. These interpolated values are then removed prior to nuisance regression. Additionally, extrapolation is set to False (clean__extrapolate=False) to prevent interpolation of end volumes. - If condition is specified for task-based data in self.get_bold(), the timeseries is temporarily padded to extract the correct frames.

        • When False or None (default behavior): - Full timeseries data is used during nuisance regression. - Scrubbing is applied after nuisance regression.

    • ”interpolate”: A boolean. If True, uses Scipy’s CubicSpline function to perform cubic spline interpolation only on scrubbed frames. Only performs interpolation if explicitly set to True.

    Note

    Interpolation is only performed on frames that are bounded by non-scrubbed frames on both ends. For example, given a censor_mask=[0, 0, 1, 0, 1, 0, 0, 0, 1, 0, 1, 0, 0] where “0” indicates scrubbed high motion volumes and “1” indicates non-scrubbed, low motion volumes, only the volumes at index 3, 5, 6, 7, and 9 would be interpolated.

  Important

  • A column named “framewise_displacement” must be available in the confounds file.

  • use_confounds must be set to True.

  • Do not specify “framewise_displacement” in confound_names.

  • See Nilearn’s documentation for details on scrubbed volume handling when “use_sample_mask” is True:

    • Signal Clean

    • NiftiLabelsMasker

  • If “interpolate” is True, then interpolation is only applied after the nuisance regression and parcellation steps have been completed.

  • See Scipy’s CubicSpline documentation.

• n_acompcor_separate (int or None, default=None) –

  Number of aCompCor components to extract separately from the white-matter (WM) and CSF masks. Uses first “n” components from each mask separately. For instance, if n_acompcor_separate=5, then the the first 5 WM components and the first 5 CSF components (totaling 10 components) are regressed out.

  Important

  • use_confounds must be set to True.

  • If specified, this parameter overrides any aCompCor components listed in confound_names.

• dummy_scans (int, dict[str, bool | int], “auto”, or None, default=None) –

  Number of initial volumes to remove before timeseries extraction.

  • If int, removes first “n” volumes.

  • If auto, removes first “n” volumes based on “non_steady_state_outlier_XX” columns.

  • If dict, the following keys are supported (all non-required subkeys are None by default):

    • ”auto”: A boolean (required). Removes first “n” volumes based on “non_steady_state_outlier_XX” columns.

    • ”min”: An integer. Minimum volumes to remove when auto is set to True. If “auto” finds 2 outliers but {"min": 3}, removes 3 volumes.

    • ”max”: An integer. Maximum volumes to remove when auto is set to True. If “auto” finds 6 outliers but {"max": 5}, removes 5 volumes.

  Important

  • ”auto” and dictionary option requires use_confounds to be True and “non_steady_state_outlier_XX” to be present in the confounds tsv file.

  • ”min” and “max” keys only apply when “auto” is True.

• dtype (str or “auto”, default=None) – The NumPy dtype to convert NIfTI images to.

Properties

spacestr

The standard template space that the preprocessed BOLD data is registered to. This property is also settable.

parcel_approachParcelApproach

Parcellation information with “maps” (path to parcellation file), “nodes” (labels), and “regions” (anatomical regions or networks). Returns a deep copy.

signal_clean_infodict[str, bool | int | float | str] or None

Dictionary containing signal cleaning parameters. Returns a deep copy.

task_infodict[str, str | int] or None

Dictionary containing all task-related information such. Defined after running self.get_bold().

subject_idslist[str] or None

A list containing all subject IDs retrieved from BIDSLayout for timeseries extraction. Defined after running self.get_bold().

n_coresint or None

Number of cores used for multiprocessing with Joblib. Defined after running self.get_bold().

subject_timeseriesSubjectTimeseries or None

A dictionary mapping subject IDs to their run IDs and their associated timeseries (TRs x ROIs) as a NumPy array. Can be deleted using del self.subject_timeseries. Defined after running self.get_bold(). This property is also settable (accepts a dictionary or pickle file). Returns a reference.

qcdict[str, dict[str, dict[str, float | int]]] or None

A dictionary reporting quality control, which maps subject IDs to their run IDs and information related to framewise displacement and dummy scans. Returns a reference.

{"subjectID": {"run-ID": {"mean_fd": float, "std_fd": float, ...}}}

See also

neurocaps.typing.ParcelConfig

Type definition representing the configuration options and structure for the Schaefer and AAL parcellations. (See ParcelConfig Documentation)

neurocaps.typing.ParcelApproach

Type definition representing the structure of the Schaefer, AAL, and Custom parcellation approaches. (See ParcelApproach Documentation)

neurocaps.typing.SubjectTimeseries

Type definition representing the structure of the subject timeseries. (See: SubjectTimeseries Documentation)

Note

Passed Parameters: detrend, low_pass, high_pass, fwhm, and nuisance regressors (confound_names) uses nilearn.maskers.NiftiLabelsMasker. The dtype parameter is used by nilearn.image.load_img.

Custom Parcellations: Refer to the NeuroCAPs’ Parcellation Documentation for detailed explanations and example structures for Custom parcellations.

Methods

__str__	Print Current Object State.
get_bold	Retrieve Preprocessed BOLD Data from BIDS Datasets.
report_qc	Report Quality Control Information.
timeseries_to_pickle	Save the Extracted Subject Timeseries.
visualize_bold	Plot the Extracted Subject Timeseries.