photon_mosaic.cli#

Command line interface for photon-mosaic.

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 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`(processed_data_base)	Create necessary output directories for the pipeline.
`update_default_config`(config_path, ...)	Update the default config file with new base paths while preserving comments.

photon_mosaic.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.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.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.cli.update_default_config(config_path, raw_data_base, processed_data_base)[source]#

Update the default config file with new base paths while preserving comments.

Parameters:

config_path (Path) – Path to the config file to update
raw_data_base (Path) – Raw data base path
processed_data_base (Path) – Processed data base path

photon_mosaic.cli.setup_output_directories(processed_data_base)[source]#

Create necessary output directories for the pipeline.

Parameters:: processed_data_base (Path) – Base path for processed data
Returns:: Paths to output directory, logs directory, and configs directory
Return type:: tuple[Path, Path, Path]

photon_mosaic.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.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.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.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.cli.main()[source]#

Run the photon-mosaic 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.

Command Line Arguments#

–configstr, optional: Path to your config.yaml file. If not provided, uses ~/.photon_mosaic/config.yaml.
–raw_data_basestr, optional: Override raw_data_base in config file (path to raw imaging data).
–processed_data_basestr, optional: Override processed_data_base in config file (path for processed outputs).
–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.

Notes

The pipeline will: 1. Create a timestamped config file in derivatives/photon-mosaic/configs/ 2. Save execution logs in derivatives/photon-mosaic/logs/ 3. Process all TIFF files found in the raw data directory 4. Generate standardized outputs following NeuroBlueprint specification