Command-Line Interface#

The thesis CLI is built with Click and provides commands for running workflows, listing available configurations, inspecting the framework, and exporting batch statistics.

See also CLI Reference for the full user-facing reference.

Global Flags#

These flags are placed before the subcommand:

  • --log-level [DEBUG|INFO|WARNING|ERROR] — Loguru log level (default INFO).

  • --log-dir <path> — Directory for log files (default logs).

  • -v / --verbose — Verbose events + DEBUG logging. Mutually exclusive with -q.

  • -q / --quiet — Errors and the final result line only.

  • --summary [off|compact|full] — End-of-run summary detail (default compact).

  • --no-progress — Disable spinners/progress bars. Auto-disabled for non-TTY.

  • --version — Print version and exit.

Subcommands#

thesis run#

Execute a registered workflow for one or more patients.

  • Use repeated -p/--patient-id flags for an explicit patient list.

  • Use --all to discover patients from the configured raw data directory.

  • --pattern <glob> is valid only together with --all.

  • -j/--max-workers implies parallel execution even if --parallel is not passed.

  • --retries N retries each failed patient after a 60-second wait (parallel mode re-runs the meta-workflow with Nipype caching).

  • --hemisphere [left|right|both|both-separately] overrides tractography.hemisphere.

  • --graph writes the workflow graph as PNG.

  • --dry-run builds and verifies but does not execute.

  • Cohort-level workflows (atlas, learned_atlas, tract_similarity_cohort, tract_similarity_hcp_loo, tract_similarity_sweep) ignore patient-selection flags.

Examples:

thesis run -w hcp -p 114823 -c default
thesis run -w hcp -p 114823 -p 115320 -c default --retries 1
thesis run -w hcp --all -c default -j 4
thesis run -w hcp --all --pattern 'P*' -c default
thesis run -w mrtrix3 -p 114823 -c mrtrix3 --hemisphere both-separately
thesis run -w full_pipeline -p 114823 -c full_pipeline
thesis run -w atlas -c default                    # cohort-level
thesis run -w hcp -p 114823 -c default -v --summary full
thesis run -w hcp --all -c default -q --no-progress

thesis list-workflows#

List every registered workflow with description and default protocol.

thesis list-configs#

List available YAML configuration files. --subdir patients or --subdir protocols restricts the listing.

thesis show-config <name>#

Print the merged configuration as YAML.

thesis info#

Display version, Python/platform info, dependency presence, and external-tool availability (FSL, ANTs).

thesis stats collect#

Re-run the post-batch tractography stats collector against an existing output directory and write the result as JSON. Reuses the same collectors as the post-run summary (collect_batch_stats + detect_batch_outliers).

Flags:

  • -o / --output-dir <path> (required) — root directory containing per-subject outputs.

  • -p / --patient <id> — limit to specific patient IDs (repeatable).

  • --out <file> — destination JSON (default <output-dir>/batch_stats/stats_<timestamp>.json).

  • --sd-threshold <float> — outlier threshold in standard deviations (default 2.0).

  • --tractography-relpath <path> — relative path under each patient directory where the tractography run lives. Default tractography/probtrackx2; use tractography/mrtrix3 for the MRtrix3 backend.

Examples:

thesis stats collect -o data/processed/
thesis stats collect -o data/processed/ --tractography-relpath tractography/mrtrix3
thesis stats collect -o data/processed/ -p 114823 -p 115320 --out reports/stats.json

QC Workflow Note#

The qc workflow generates ROI overlays, track-density figures, and statistics for a patient whose tractography workflow has already completed:

thesis run -w qc -p 114823 -c default

ROI overlays are also generated automatically after each HCP workflow run when qc.generate_overlays: true is set in the config.

Module Reference#

Command-line interface for the thesis framework.

Provides CLI commands for running custom Nipype workflows.

class thesis.cli.ClickNodeProgress[source]#

Bases: object

Simple wrapper for node progress using Click’s progressbar.

This class provides the same interface as WorkflowProgress (node_started, node_finished, start, stop) so it can be used with Nipype’s status callback mechanism without changing executor.py.

Parameters:
__init__(total, label, enabled=True)[source]#
Parameters:
start()[source]#
Return type:

None

stop()[source]#
Return type:

None

node_started(node_name)[source]#
Parameters:

node_name (str)

Return type:

None

node_finished(node_name, status='')[source]#
Parameters:

  • node_name (str)

  • status (str)

Return type:

None