mu2e-cosmic

This repository provides a comphrehensive framework for Monte Carlo-based cosmic-ray-induced background analyses, and performance evaluation studies, for the Cosmic Ray Veto (CRV) system at the Fermilab Mu2e experiment. It deploy Mu2e/pyutils to explore cut strategies for signal-like track selection and cosmic ray background sensitivy studies through reproducible workflows.

Structure

Please click the dropdown for detailed information.

Repository structure

```bash mu2e-cosmic/ ├── config/ # Configuration files │ ├── ana/ # YAML configs for analyses │ └── common/ # YAML cut flow definitions │ └── cuts.yaml # Shared cut definitions ├── src/ # Core analysis code │ ├── core/ # Main processing pipeline │ │ ├── analyse.py # Core analysis workflow (Analyse, Utils classes) │ │ └── process.py # Data processing │ │ ├── postprocess.py # Result combination and aggregation │ └── utils/ # Helper utilities │ ├── cut_manager.py # Cut management and statistics │ ├── io_manager.py # Input/output handling │ ├── draw.py # Plotting utilities │ ├── efficiency.py # CRV efficiency calculations │ ├── run_logger.py # Logging configuration │ └── mu2e.mplstyle # Matplotlib style for plots ├── run/ # Scripts to execute analyses │ ├── run.py # Main analysis runner │ ├── run.sh # Shell script wrapper │ └── run_test.py # Test runner ├── notebooks/ # Jupyter notebooks │ ├── ana/ # Analysis result exploration │ │ ├── generate_notebook.py # Notebook generator script │ │ ├── ana_template.ipynb # Template for analysis notebooks │ │ └── ana_test.ipynb # Test analysis notebook │ ├── comp/ # Dataset comparisons │ └── models/ # Statistical modeling ├── examples/ # Example inputs and outputs │ ├── example_io.ipynb # I/O demonstration │ ├── example_parquet.py # Parquet file handling │ ├── input/ # Sample input data │ └── output/ # Sample output data ├── scripts/ # Utility scripts ├── docs/ # Additional documentation ├── latex/ # LaTeX documentation generation └── setup.sh # Environment setup script ```

Quick start

Firstly, setup your Python environment on Mu2e VMs or Fermilab Elastic Analysis Facility (EAF):

mu2einit # source /cvmfs/mu2e.opensciencegrid.org/setupmu2e-art.sh
pyenv ana

Clone the repository:

git clone https://github.com/sam-grant/mu2e-cosmic.git
cd mu2e-cosmic

Now, if running with remote files (using xrootd), source the setup script

source setup.sh

and run the analysis

cd mu2e-cosmic/run 
python run.py -c example.yaml

this will produce some relatively versose output, which can be controlled via YAML (see below), ending in

[run] ✅ Analysis complete, wrote results to ../output/results/example

Note: Analyses are configured by YAML files in config/ana and config/common. Here we are using an example conifiguration that runs an example cut flow with a single local file.

Then, explore the results interactively by generating a notebook:

cd ../notebooks/ana
python generate_notebook.py example

which will output

(current) [sgrant@jupyter-sgrant ana]$ python generate_notebook.py example
[generate_notebook] ⭐️ Created/using directory: example
[generate_notebook] ✅ Successfully generated notebook: example/example.ipynb

Analysis configuration template

Analyses are configured via YAML, which pass arguments directly to the process.py and postprocess.py modules. Many of the arguments are optional, but a template containing the full suite of options is below.

# ==================================
# ANALYSIS CONFIGURATION TEMPLATE
# ==================================
# This YAML file configures a cosmic-ray-induced background analysis
# It is used to steer run/run.py via 
# 
# python run.py -c my_config.yaml
#
# Naming: <cutset_name>_<generator>_<spill-reco>_<ds_type>.yaml
# 
# Example: "alpha_CRY_onspill-LH_au.yaml"
#


# Configure src/core/process.py
process:    
     defname (str, opt): Dataset definition name. Defaults to None.
     file_list_path (str, opt): Path to file list. Defaults to None.
     file_name (str, opt): Single file to process. Defaults to None.
     cutset_name (str, opt): Which cutset to use. Defaults to "alpha".
     branches (dict or list, opt): EventNtuple branches to extract.
     on_spill (bool, opt): Apply on-spill timing cuts. Defaults to True.
     cuts_to_toggle (dict, opt): Cuts to enable/disable. Defaults to None.
     groups_to_toggle (dict, opt): Cut groups to enable/disable. Defaults to None.
     use_remote (bool, opt): Use remote file access. Defaults to True.
     location (str, opt): File location ("disk", etc.). Defaults to "disk".
     max_workers (int, opt): Number of parallel workers. Defaults to 50.
     use_processes (bool, opt): Use processes rather than threads. Defaults to True.
     verbosity (int, opt): Logging verbosity level. Defaults to 2 (max).
     worker_verbosity (int, opt): Verbosity for worker processes (debug only!). Defaults to 0.

# Configure src/core/postprocess.py
postprocess:
    on_spill (bool): Whether we are using on spill cuts. Propagated from Process by run.py
    write_events (bool, opt): write filtered events. Defaults to False.
    write_event_info (bool, opt): write filtered event info. Defaults to False.
    generated_events (int, opt): Number of generated events. Defaults to 4.11e10.
    livetime (float, opt): The total livetime in seconds for this dataset. Defaults to 1e7.
    on_spill_frac (dict, opt): Fraction of walltime in single and two batch onspill. Defaults to 32.2% and 24.6%.
    veto (bool, opt): Whether running with CRV veto. Defaults to True.
    verbosity (int, opt): Printout level. Defaults to 1.

output:
    out_path: "../output/results/<name>" 

Cut flows

Cut flows are also configured by YAML, in config/common/cuts.yaml. The structure follows a base cutset which is inherited by the others, where the use can modify thresholds and toggle cuts and cut groups on/off.