script

Extractor for FreeSurfer aseg/aparc stats and quality control metrics.

Module Contents

script.build_parser()

Create the parser for the CLI.

Return type:

argparse.ArgumentParser

script.run(input_dir_path, output_dir_path, mode=DEFAULT_MODE, with_qc=False, container_command_and_args=None, aseg_measures=DEFAULT_ASEG_MEASURES, aparc_parcellations=DEFAULT_APARC_PARCELLATIONS, aparc_measures=DEFAULT_APARC_MEASURES, aparc_optional_args=None, aseg_optional_args=None, euler_surf_paths=DEFAULT_EULER_SURF_PATHS, cnr_vol_paths=DEFAULT_CNR_VOL_PATHS, cnr_cols=DEFAULT_CNR_COLS, sub_colname=DEFAULT_SUB_COLNAME, ses_colname=DEFAULT_SES_COLNAME, sub_prefix=DEFAULT_SUB_PREFIX, ses_prefix=DEFAULT_SES_PREFIX, verbose=False)

Extract FreeSurfer aseg/aparc statistics into a single file.

Optionally extract QC metrics into a separate file.

This extractor uses FreeSurfer commands (asegstats2table, aparcstats2table, mris_euler_number, and mri_cnr), and so requires FreeSurfer installation or a container with FreeSurfer available.

Parameters:

  • input_dir_path (Union[str, os.PathLike]) – Path to input directory, which should be a FreeSurfer subjects directory if mode is “single” or a directory containing multiple FreeSurfer subjects directories if mode is “multi”.

  • output_dir_path (Union[str, os.PathLike]) – Path to the directory where output files will be created. Any existing file may be overwritten.

  • aseg_measures (list[str]) – List of measures to use for aparcstats2table.

  • aparc_parcellations (list[str]) – List of parcellations to use for asegstats2table.

  • aparc_measures (list[str]) – List of measures to use for asegstats2table.

  • with_qc (bool, optional) – Whether or not to compute QC metrics.

  • mode (str) – See input_dir_path.

  • container_command_and_args (Optional[list[str]], optional) – Container command and arguments (including image file), by default None. This needs to contain everything needed to be able to run the FreeSurfer commands, for example [“apptainer”, “exec”, “–bind”, “<INPUT_DIR_PATH>”, “<IMAGE_FILE_PATH>”]. Does not need to be specified if running on a system with FreeSurfer installed. IMPORTANT: only the Singularity/Apptainer container engine is explicitly supported because it allows for forwarding environment variables; this function might work with Docker containers but likely only with –mode “single”.

  • aparc_optional_args (Optional[list[str]], optional) – Optional arguments to pass to aparcstats2table, by default None. Should not include –subjects, –tablefile (or -t), –hemo, –measure or –parc arguments.

  • aseg_optional_args (Optional[list[str]], optional) – Optional arguments to pass to asegstats2table, by default None. Should not include –subjects, –tablefile or –meas argument.

  • euler_surf_paths (list[Union[str, os.PathLike]], optional) – Paths to surface files for which to calculate number of holes with mris_euler_number.

  • cnr_vol_paths (list[Union[str, os.PathLike]], optional) – Paths to volume files for which to calculate contrast-to-noise ratios with mri_cnr.

  • cnr_cols (list[str], optional) – Metrics to extract from mri_cnr outputs.

  • sub_colname (str, optional) – Column name to use for the subject ID in the final output files.

  • ses_colname (str, optional) – Column name to use for the session ID in the final output files.

  • sub_prefix (str, optional) – Prefix to strip from the subject IDs in the final output files. Set as empty string to keep the original values.

  • ses_prefix (str, optional) – Prefix to strip from the session IDs in the final output files. Set as empty string to keep the original values.

  • verbose (bool)

script.run_multi(sessions_dir_path, container_command_and_args=None, aseg_measures=DEFAULT_ASEG_MEASURES, aparc_parcellations=DEFAULT_APARC_PARCELLATIONS, aparc_measures=DEFAULT_APARC_MEASURES, aparc_optional_args=None, aseg_optional_args=None, with_qc=False, euler_surf_paths=DEFAULT_EULER_SURF_PATHS, cnr_vol_paths=DEFAULT_CNR_VOL_PATHS, cnr_cols=DEFAULT_CNR_COLS, sub_colname=DEFAULT_SUB_COLNAME, ses_colname=DEFAULT_SES_COLNAME, sub_prefix=DEFAULT_SUB_PREFIX, ses_prefix=DEFAULT_SES_PREFIX, verbose=False)

Extract FreeSurfer aseg/aparc statistics and QC metrics for multiple sessions.

This function calls run_single for each session and concatenates the results with a session level in the index.

Parameters:

  • sessions_dir_path (Union[str, os.PathLike]) – Path containing multiple FreeSurfer subjects directories, one for each session.

  • aseg_measures (list[str]) – List of measures to use for aparcstats2table.

  • aparc_parcellations (list[str]) – List of parcellations to use for asegstats2table.

  • aparc_measures (list[str]) – List of measures to use for asegstats2table.

  • container_command_and_args (Optional[list[str]], optional) – Passed to run_single.

  • aparc_optional_args (Optional[list[str]], optional) – Passed to run_single.

  • aseg_optional_args (Optional[list[str]], optional) – Passed to run_single.

  • with_qc (bool, optional) – Whether or not to include QC metrics.

  • euler_surf_paths (list[Union[str, os.PathLike]], optional) – Passed to run_single.

  • cnr_vol_paths (list[Union[str, os.PathLike]], optional) – Passed to run_single.

  • cnr_cols (list[str], optional) – Passed to run_single.

  • sub_colname (str, optional) – Passed to run_single.

  • ses_colname (str, optional) – Passed to run_single.

  • sub_prefix (str, optional) – Prefix to strip from the subject IDs in the final output file. Set as empty string to keep the original values.

  • ses_prefix (str, optional) – Prefix to strip from the session IDs in the final output file. Set as empty string to keep the original values.

  • verbose (bool)

Returns:

Dataframes with multi-level index (subject, session) and FreeSurfer stats columns. First dataframe is for aseg and second is for aparc. Third “dataframe” is None if with_qc is False.

Return type:

tuple[pd.DataFrame, pd.DataFrame, Optional[pd.DataFrame]]

script.run_single(subjects_dir_path, container_command_and_args=None, aseg_measures=DEFAULT_ASEG_MEASURES, aparc_parcellations=DEFAULT_APARC_PARCELLATIONS, aparc_measures=DEFAULT_APARC_MEASURES, aseg_optional_args=None, aparc_optional_args=None, with_qc=False, euler_surf_paths=DEFAULT_EULER_SURF_PATHS, cnr_vol_paths=DEFAULT_CNR_VOL_PATHS, cnr_cols=DEFAULT_CNR_COLS, sub_colname=DEFAULT_SUB_COLNAME, sub_prefix=DEFAULT_SUB_PREFIX, verbose=False)

Extract FreeSurfer aseg/aparc statistics and QC metrics for a single session.

Parameters:

  • subjects_dir_path (Union[str, os.PathLike]) – Path to the FreeSurfer subjects directory.

  • container_command_and_args (Optional[list[str]], optional) – Passed to run_single_stats and run_single_qc.

  • aseg_measures (list[str]) – List of measures to use for aparcstats2table.

  • aparc_parcellations (list[str]) – List of parcellations to use for asegstats2table.

  • aparc_measures (list[str]) – List of measures to use for asegstats2table.

  • aseg_optional_args (Optional[list[str]], optional) – Passed to run_single_stats.

  • aparc_optional_args (Optional[list[str]], optional) – Passed to run_single_stats.

  • with_qc (bool, optional) – Whether or not to include QC metrics.

  • euler_surf_paths (list[Union[str, os.PathLike]], optional) – Passed to run_single_qc.

  • cnr_vol_paths (list[Union[str, os.PathLike]], optional) – Passed to run_single_qc.

  • cnr_cols (list[str], optional) – Passed to run_single_qc.

  • sub_colname (str, optional) – Passed to run_single_stats and run_single_qc.

  • sub_prefix (str, optional) – Passed to run_single_stats and run_single_qc.

  • verbose (bool, optional) – Passed to run_single_stats and run_single_qc.

Returns:

DataFrames with multi-level index (subject, session) and FreeSurfer stats columns. Second “dataframe” is None if with_qc is False.

Return type:

tuple[pd.DataFrame, Optional[pd.DataFrame]]

script.run_single_aparc(subjects_dir_path, container_command_and_args=None, parcellations=DEFAULT_APARC_PARCELLATIONS, measures=DEFAULT_APARC_MEASURES, optional_args=None, sub_colname=DEFAULT_SUB_COLNAME, sub_prefix=DEFAULT_SUB_PREFIX, verbose=False)

Extract FreeSurfer aseg and aparc statistics for a single subjects directory.

This function calls _run_aparcstats2table (twice, once for each hemisphere) and concatenates the results into a single DataFrame.

Parameters:

  • subjects_dir_path (Union[str, os.PathLike]) – Path to the FreeSurfer subjects directory.

  • container_command_and_args (Optional[list[str]], optional) – Passed _run_aparcstats2table.

  • parcellations (list[str], optional) – List of parcellations to use for _run_aparcstats2table.

  • measures (list[str], optional) – List of measures to use for _run_aparcstats2table.

  • optional_args (Optional[list[str]], optional) – Passed to _run_aparcstats2table.

  • sub_colname (str, optional) – Passed to _run_aparcstats2table.

  • sub_prefix (str, optional) – Passed to _run_aparcstats2table.

  • verbose (bool, optional) – Passed to _run_subprocess.

Returns:

Keys are tuples of parcellation and measure names. Values are dataframes for aparc stats, with subject index.

Return type:

dict[Tuple[str, str], pd.DataFrame]

script.run_single_aseg(subjects_dir_path, container_command_and_args=None, measures=DEFAULT_ASEG_MEASURES, optional_args=None, sub_colname=DEFAULT_SUB_COLNAME, sub_prefix=DEFAULT_SUB_PREFIX, verbose=False)

Extract FreeSurfer aseg and aparc statistics for a single subjects directory.

This function calls _run_asegstats2table and _run_aparcstats2table (twice, once for each hemisphere) and concatenates the results into a single DataFrame.

Parameters:

  • subjects_dir_path (Union[str, os.PathLike]) – Path to the FreeSurfer subjects directory.

  • container_command_and_args (Optional[list[str]], optional) – Passed to _run_asegstats2table.

  • measures (list[str], optional) – List of measures to use for asegstats2table.

  • optional_args (Optional[list[str]], optional) – Passed to _run_asegstats2table.

  • sub_colname (str, optional) – Passed to run_asegstats2table.

  • sub_prefix (str, optional) – Passed to run_asegstats2table.

  • verbose (bool, optional) – Passed to _run_subprocess.

Returns:

Keys are measure names. Values are dataframes for aseg stats, with subject index.

Return type:

dict[str, pd.DataFrame]

script.run_single_qc(subjects_dir_path, euler_surf_paths=DEFAULT_EULER_SURF_PATHS, cnr_vol_paths=DEFAULT_CNR_VOL_PATHS, cnr_cols=DEFAULT_CNR_COLS, container_command_and_args=None, sub_colname=DEFAULT_SUB_COLNAME, sub_prefix=DEFAULT_SUB_PREFIX, verbose=False)

Extract FreeSurfer QC metrics for a single subjects directory.

This function calls _run_mris_euler_number and _run_mri_cnr for each subject and concatenates the results into a single DataFrame.

Parameters:

  • subjects_dir_path (Union[str, os.PathLike]) – Path to the FreeSurfer subjects directory.

  • euler_surf_paths (list[Union[str, os.PathLike]], optional) – Paths to the surface files to calculate the Euler number from, relative to subjects_dir_path.

  • cnr_vol_paths (list[Union[str, os.PathLike]], optional) – Paths to the volume files to calculate the contrast-to-noise ratio from, relative to subjects_dir_path.

  • cnr_cols (list[str], optional) – Names of the CNR measures to include in the QC metrics file for each volume.

  • container_command_and_args (Optional[list[str]], optional) – Passed to _run_mris_euler_number and _run_mri_cnr.

  • sub_colname (str, optional) – Column name to use for the subject ID in the final output file.

  • sub_prefix (str, optional) – Prefix to strip from the subject IDs in the final output file. Set as empty string to keep the original values.

  • verbose (bool, optional) – Passed to _run_subprocess.

Return type:

pd.DataFrame

script.ALL_CNR_COLS = ['gray_white_cnr', 'gray_csf_cnr', 'white_mean', 'gray_mean', 'csf_mean', 'sqrt_white_var',...
script.DEFAULT_APARC_MEASURES = ['thickness', 'area', 'meancurv']
script.DEFAULT_APARC_PARCELLATIONS = ['aparc', 'aparc.a2009s', 'aparc.DKTatlas']
script.DEFAULT_ASEG_MEASURES = ['volume']
script.DEFAULT_CNR_COLS = ['gray_white_cnr', 'gray_csf_cnr']
script.DEFAULT_CNR_VOL_PATHS = ['mri/norm.mgz']
script.DEFAULT_EULER_SURF_PATHS = ['surf/lh.white', 'surf/rh.white', 'surf/lh.pial', 'surf/rh.pial']
script.DEFAULT_MODE = 'single'
script.DEFAULT_SES_COLNAME = 'session_id'
script.DEFAULT_SES_PREFIX = 'ses-'
script.DEFAULT_SUB_COLNAME = 'participant_id'
script.DEFAULT_SUB_PREFIX = 'sub-'
script.FNAME_FS_VERSION = 'build-stamp.txt'
script.MODE_MULTI = 'multi'
script.MODE_SINGLE = 'single'
script.RE_FS_VERSION
script.parser