photon_mosaic_pipeline.cli#

Command line interface for photon-mosaic-pipeline.

Functions

build_snakemake_command(args, config_path)

Build the base snakemake command with common arguments.

configure_slurm_execution(cmd, config)

Configure SLURM execution options if enabled.

create_argument_parser()

Create and configure the argument parser for the CLI.

ensure_default_config([reset_config])

Ensure the default config file exists, create if missing or reset requested.

execute_pipeline_with_retry(cmd, log_path)

Execute the snakemake pipeline with automatic unlock and retry on lock errors.

load_and_process_config(args)

Load configuration file and apply CLI overrides.

main()

Run the photon-mosaic-pipeline Snakemake pipeline for automated and reproducible analysis of multiphoton calcium imaging datasets.

save_timestamped_config(config, configs_dir)

Save configuration with timestamp for reproducibility.

setup_output_directories(project_path)

Create necessary output directories for the pipeline.

update_default_config(config_path, project_path)

Update the default config file with new project path while preserving comments.
photon_mosaic_pipeline.cli.create_argument_parser()[source]#

Create and configure the argument parser for the CLI.

Returns:

Configured argument parser with all CLI options

Return type:

argparse.ArgumentParser

photon_mosaic_pipeline.cli.ensure_default_config(reset_config=False)[source]#

Ensure the default config file exists, create if missing or reset requested.

Parameters:

reset_config (bool) – Whether to reset the config file to defaults

Returns:

Path to the default config file

Return type:

Path

photon_mosaic_pipeline.cli.load_and_process_config(args)[source]#

Load configuration file and apply CLI overrides.

Parameters:

args (argparse.Namespace) – Parsed command line arguments

Returns:

Configuration dictionary and path to config file used

Return type:

tuple[dict, Path]

photon_mosaic_pipeline.cli.update_default_config(config_path, project_path)[source]#

Update the default config file with new project path while preserving comments.

Parameters:

  • config_path (Path) – Path to the config file to update

  • project_path (Path) – Project path

photon_mosaic_pipeline.cli.setup_output_directories(project_path)[source]#

Create necessary output directories for the pipeline.

Parameters:

project_path (Path) – Project path

Returns:

Paths to output directory, logs directory, and configs directory

Return type:

tuple[Path, Path, Path]

photon_mosaic_pipeline.cli.save_timestamped_config(config, configs_dir)[source]#

Save configuration with timestamp for reproducibility.

Parameters:

  • config (dict) – Configuration dictionary to save

  • configs_dir (Path) – Directory to save config files

Returns:

Timestamp string and path to saved config file

Return type:

tuple[str, Path]

photon_mosaic_pipeline.cli.build_snakemake_command(args, config_path)[source]#

Build the base snakemake command with common arguments.

Parameters:

  • args (argparse.Namespace) – Parsed command line arguments

  • config_path (Path) – Path to the config file to use

Returns:

Snakemake command as list of strings

Return type:

list[str]

photon_mosaic_pipeline.cli.configure_slurm_execution(cmd, config)[source]#

Configure SLURM execution options if enabled.

Parameters:

  • cmd (list[str]) – Base snakemake command to extend

  • config (dict) – Configuration dictionary

Returns:

Updated command with SLURM configuration

Return type:

list[str]

photon_mosaic_pipeline.cli.execute_pipeline_with_retry(cmd, log_path)[source]#

Execute the snakemake pipeline with automatic unlock and retry on lock errors.

Parameters:

  • cmd (list[str]) – Snakemake command to execute

  • log_path (Path) – Path to save execution logs

Returns:

Return code from the snakemake execution

Return type:

int

photon_mosaic_pipeline.cli.main()[source]#

Run the photon-mosaic-pipeline Snakemake pipeline for automated and reproducible analysis of multiphoton calcium imaging datasets.

This pipeline integrates Suite2p for image registration and signal extraction, with a standardized output folder structure following the NeuroBlueprint specification. It is designed for labs that store their data on servers connected to HPC clusters and want to batch-process multiple imaging sessions in parallel.

Notes

The pipeline is invoked via the photon-mosaic-pipeline CLI. The supported command-line arguments are:

–configstr, optional

Path to your config.yaml file. If not provided, uses ~/.photon_mosaic_pipeline/config.yaml.

–project_pathstr, optional

Override project_path in config file (root of NeuroBlueprint project).

–jobsstr, default=”1”

Number of parallel jobs to run.

–dry-runbool, optional

Perform a dry run to preview the workflow without executing.

–forcerunstr, optional

Force re-run of a specific rule (e.g., ‘suite2p’).

–rerun-incompletebool, optional

Rerun any incomplete jobs.

–latency-waitint, default=10

Time to wait before checking if output files are ready.

–log-levelstr, default=”INFO”

Log level.

–verbose, -vflag, optional

Enable verbose output (default is quiet mode).

–reset-configflag, optional

Reset the config file to the default values.

extralist

Additional arguments to pass to snakemake.

On each invocation, the pipeline will:

  1. Create a timestamped config file in derivatives/photon-mosaic-pipeline/configs/

  2. Save execution logs in derivatives/photon-mosaic-pipeline/logs/

  3. Process all TIFF files found under rawdata/sub-*/ses-*/funcimg/

  4. Generate standardized outputs following NeuroBlueprint specification