Run the processing pipeline

This remains the standard execution path after setup_project(). It resolves the same stages, streams, subject/session scope, and force setting exposed by plan_project() before submission; calling plan_project() first is optional.

Usage

run_project(
  scfg,
  steps = NULL,
  subject_filter = NULL,
  postprocess_streams = NULL,
  extract_streams = NULL,
  debug = FALSE,
  force = FALSE,
  dry_run = FALSE,
  log_level = c("INFO", "DEBUG", "WARN", "ERROR", "TRACE", "FATAL")
)

Arguments

scfg

a project configuration object as produced by load_project or setup_project

steps

Character vector of pipeline stages to execute. Supported stages are "flywheel_sync", "bids_conversion", "mriqc", "fmriprep", "aroma", "postprocess", and "extract_rois". Use "all" to run all enabled stages. If NULL, the user will be prompted for which stages to run. BIDS validation is configured with the project but submitted separately through run_bids_validation(); it is not a run_project() stage.

subject_filter

Optional character vector or data.frame specifying which subjects (and optionally sessions) to process. When NULL and run interactively, the user will be prompted to enter space-separated subject IDs (press ENTER to process all subjects). When a data.frame is provided, it must contain a sub_id column and may include a ses_id column to filter on specific subject/session combinations.

postprocess_streams

Optional character vector specifying which postprocessing streams should run. When "postprocess" is included in steps, NULL selects every configured postprocessing stream.

extract_streams

Optional character vector specifying which ROI extraction streams should run. When "extract_rois" is included in steps, NULL selects every configured extraction stream.

debug

A logical value indicating whether to run in debug mode (verbose output for debugging, no true processing).

force

A logical value indicating whether to force the execution of all steps, regardless of their current status.

dry_run

A logical value indicating whether to perform a dry run. Dry runs validate settings and report subject/session scope plus resolved postprocessing and extraction stream settings without submitting any jobs.

log_level

Character string controlling log verbosity. One of TRACE, DEBUG, INFO, WARN, ERROR, or FATAL.

Value

For submitted work, an invisible bg_project_run object containing the run UUID, scheduler job IDs known at submission time, and the path to the complete run provenance record. Dry runs invisibly return TRUE after printing the resolved plan.

Details

Before submission, BrainGnomes reports when it is checking project folders, finding matching subjects, and saving the run record. The first use of a large container in a project may take longer because BrainGnomes reads the complete file once to identify the exact copy used. During large submissions, periodic messages report progress through the subject list.

See also

inspect_project() to monitor current progress; get_run_provenance() to read the recorded configuration, execution context, and artifact fingerprints; plan_project() for optional inspection or persistence of the resolved request; run_bids_validation() to submit the BIDS validation configured with the project; diagnose_project() and retry_project_run() for optional recovery after a submitted run fails.

Examples

  if (FALSE) { # \dontrun{
    # Assuming you have a valid project configuration list named `study_config`
    run_project(study_config, steps = "fmriprep", force = FALSE)
  } # }