API Reference

create_input_txt

Create an input list of BIDS images to preprocess.

This script scans one or more BIDS dataset roots and writes a text file containing one quoted absolute path per line (e.g., T1w images). It supports:

• Longitudinal (sub-*/ses-*/anat) and cross-sectional (sub-*/anat) layouts

• Excluding subjects/sessions/runs via exclude.yaml

• Optional filtering by a list of subjects

• Optional filtering by age range (in months), using participants.tsv or a custom TSV

By default, the exclusion file is expected at:

<bids_root>/code/qc/raw/exclude.yaml

The output text file can be passed directly to your preprocessing script (e.g., brainprep.py --inputs <output.txt>).

Notes for Sphinx

• All logic is import-safe (no work performed at import).

• Use main() as the CLI entrypoint.

Examples

Single longitudinal dataset:

python create_input_txt.py /path/to/hc-calgary-preschool       -l long       --modality T1w       -o to_preprocess_hc-calgary-preschool.txt

Multiple datasets at once:

python create_input_txt.py /path/to/hc-bcp /path/to/hc-calgary-preschool       -l long long       --modality T1w       -o to_preprocess_all.txt

With an age filter (1–7 years = 12–84 months):

python create_input_txt.py /path/to/hc-calgary-preschool       -l long       --modality T1w       --min-age-months 12 --max-age-months 84       --age-tsv /path/to/hc-calgary-preschool/participants.tsv       --age-col age --age-units years       -o to_preprocess_12to84mo.txt

create_input_txt.load_age_lookup(bids_root, layout, tsv_path=None, pid_col='participant_id', ses_col='session', age_col='age', age_units='years')

Load ages from a TSV/CSV into a lookup dictionary.

For layout="long" this returns:

{(sub_id, ses_id): age_months, ...}

For layout="cross" this returns:

{sub_id: age_months, ...}

Parameters:

• bids_root (str) -- BIDS dataset root.

• layout (str) -- "long" or "cross".

• tsv_path (Optional[str]) -- Optional TSV/CSV path. If None, defaults to <bids_root>/participants.tsv.

• pid_col (str) -- Column names in the TSV.

• ses_col (str) -- Column names in the TSV.

• age_col (str) -- Column names in the TSV.

• age_units (str) -- Either "years" or "months". Years are converted to months.

Returns:

Age lookup in months.

Return type:

dict

create_input_txt.load_excludes(yaml_path)

Load exclude identifiers from YAML.

Supports either: - a YAML list - a dict containing a list under keys: exclude, exclude_paths, exclude_images

Return type:

List[str]

Parameters:

yaml_path (str)

create_input_txt.expand_excludes(excludes)

Expand BIDS-style identifiers into glob-like relative patterns.

Return type:

List[str]

Parameters:

excludes (Sequence[str])

Examples

• sub-10001 -> sub-10001/**

• sub-10001_ses-001 -> sub-10001/ses-001/**

• path-like patterns are kept as-is.

create_input_txt.is_excluded(path, patterns, root)

Check whether an absolute path is excluded by any relative pattern.

Return type:

bool

Parameters:

• path (str)

• patterns (Sequence[str])

• root (str)

class create_input_txt.ScanArgs(exclude_file, modality, min_age_months, max_age_months, pattern)

Arguments used during scanning (subset of CLI args).

Parameters:

• exclude_file (str)

• modality (str | None)

• min_age_months (int | None)

• max_age_months (int | None)

• pattern (str | None)

create_input_txt.process_dir(root, glob_suffix, layout, scan_args, allowed_subs, age_lut)

Scan one BIDS dataset root and return a set of matching absolute file paths.

Applies: - exclusion patterns from exclude.yaml - optional subject filter - optional age filter (months), with fallback to parsing ses-XXmo if present

Parameters:

• root (str) -- Absolute dataset root.

• glob_suffix (str) -- Glob pattern to use for non-anat modalities (or fallback scanning).

• layout (str) -- "long" or "cross".

• scan_args (ScanArgs) -- Scanning parameters (exclude file, modality, age range, pattern).

• allowed_subs (Set[str]) -- Set of allowed subject IDs (e.g. {"sub-10001", ...}). Empty means no restriction.

• age_lut (Dict[Union[str, Tuple[str, str]], float]) -- Age lookup in months.

Returns:

Matching image paths (absolute).

Return type:

set[str]

create_input_txt.norm_sub_id(s)

Normalize subject IDs provided by the user into sub-... format.

Return type:

str

Parameters:

s (str)

create_input_txt.load_subjects(subjects_list, subjects_file)

Load allowed subjects from CLI arguments.

Parameters:

• subjects_list (Optional[Sequence[str]]) -- Subject IDs provided directly on the command line.

• subjects_file (Optional[str]) -- Optional file containing one subject ID per line.

Returns:

Allowed subject IDs.

Return type:

set[str]

create_input_txt.build_argparser()

Build CLI argument parser.

Return type:

ArgumentParser

create_input_txt.main(argv=None)

CLI entrypoint.

Returns:

Exit code (0 on success).

Return type:

int

Parameters:

argv (Sequence[str] | None)