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_stats_file_path, output_qc_file_path=None, mode=DEFAULT_MODE, container_command_and_args=None, 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_stats_file_path (Union[str, os.PathLike]) – Path to the output TSV file for the stats file. The parent directory of this path must exist.

  • output_qc_file_path (Optional[Union[str, os.PathLike]], optional) – Path to the output TSV file for QC metrics. If this is not provided, only the stats file will be created.

  • 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

  • aseg_optional_args (Optional[list[str]], optional) – Optional arguments to pass to asegstats2table, by default None

  • 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 file.

  • ses_colname (str, optional) – Column name to use for the session 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.

  • 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)

script.run_multi(sessions_dir_path, container_command_and_args=None, 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.

  • 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. Second “dataframe” is None if with_qc is False.

Return type:

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

script.run_single(subjects_dir_path, container_command_and_args=None, 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_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_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.run_single_stats(subjects_dir_path, container_command_and_args=None, aseg_optional_args=None, aparc_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 and _run_aparcstats2table.

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

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

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

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

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

Returns:

DataFrame with subject index and FreeSurfer stats columns.

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_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.MODE_MULTI = 'multi'
script.MODE_SINGLE = 'single'
script.parser