# ksl111/new_analysis_code architecture

> Architecture diagram of the GitHub repository ksl111/new_analysis_code, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ksl111/new_analysis_code
- Repository: https://github.com/ksl111/new_analysis_code

## Overview

This repository is a Run-3 CMS NanoAOD analysis pipeline: users select datasets and regions, the Python runner reads events, applies object selection, corrections, triggers and region cuts, then produces histograms and cutflows for plotting and datacard generation. Supporting branches manage dataset bookkeeping, derive/apply pT(ll) weights, and validate corrections. The README describes a C++ ROOT event-loop core, but the only C++ files present are in attic and the entry point is explicitly a stub; active runtime wiring is therefore represented by the Python runners. Arrows cite shown imports or README statements; unsampled relationships are omitted.

Main entry points: [`run_analysis.py`](https://github.com/ksl111/new_analysis_code/blob/main/run_analysis.py) (Analysis runner), [`run_analysis_all.py`](https://github.com/ksl111/new_analysis_code/blob/main/run_analysis_all.py) (Multi-region runner), [`python/bookkeeping/dataset_list.py`](https://github.com/ksl111/new_analysis_code/blob/main/python/bookkeeping/dataset_list.py) (Dataset catalog), [`python/common/io.py`](https://github.com/ksl111/new_analysis_code/blob/main/python/common/io.py) (NanoAOD I/O)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Event analysis"]
  node_runner["Analysis runner<br/>[run_analysis.py]"]
  node_multi_runner["Multi-region runner"]
end

subgraph group_analysis["Selection and observables"]
  node_objects["Object building<br/>[objects.py]"]
  node_leptons["Lepton utilities<br/>[leptons.py]"]
  node_triggers["Trigger selection<br/>[triggers.py]"]
  node_regions["Region cuts<br/>[regions.py]"]
  node_weights["Event weights<br/>[weights.py]"]
  node_histograms["Histograms<br/>[histograms.py]"]
end

subgraph group_support["Data and corrections"]
  node_io["NanoAOD I/O<br/>[io.py]"]
  node_datasets["Dataset catalog<br/>[dataset_list.py]"]
  node_muonscare["Muon correction<br/>[muonscare.py]"]
  node_metxy["MET XY correction<br/>[metxy_apply.py]"]
  node_ptll["pT&#40;ll&#41; reweighting<br/>[ptll_weight.py]"]
  node_ptll_derive["pT&#40;ll&#41; derivation<br/>[ptll_derive.py]"]
  node_chunking["Chunk planning<br/>[make_chunks.py]"]
  node_sumw["Sum-weight bookkeeping<br/>[compute_sumw.py]"]
end

subgraph group_products["Results and validation"]
  node_merge["Chunk merging<br/>[merge_chunks.py]"]
  node_plots["Data/MC plots"]
  node_datacard["Combine datacard<br/>[make_datacard.py]"]
  node_validation["Correction validation<br/>[validate_metxy.py]"]
  node_muon_validation["Muon validation"]
  node_outputs[("Histogram outputs")]
end

node_analyst(("Analyst"))
node_nano[("NanoAOD files")]

node_analyst -->|"starts analysis"| node_runner
node_analyst -->|"starts analysis"| node_multi_runner
node_nano -->|"provides events"| node_io
node_runner -->|"reads inputs"| node_io
node_runner -->|"selects datasets"| node_datasets
node_runner -->|"builds objects"| node_objects
node_runner -->|"uses lepton helpers"| node_leptons
node_runner -->|"applies triggers"| node_triggers
node_runner -->|"applies region cuts"| node_regions
node_runner -->|"computes weights"| node_weights
node_runner -->|"fills histograms"| node_histograms
node_runner -->|"applies correction"| node_muonscare
node_runner -->|"applies correction"| node_metxy
node_runner -->|"applies reweighting"| node_ptll
node_multi_runner -->|"builds objects"| node_objects
node_multi_runner -->|"applies region cuts"| node_regions
node_multi_runner -->|"fills histograms"| node_histograms
node_multi_runner -->|"applies correction"| node_metxy
node_multi_runner -->|"applies reweighting"| node_ptll
node_runner -.->|"writes results"| node_outputs
node_multi_runner -.->|"writes results"| node_outputs
node_datasets -->|"plans chunks"| node_chunking
node_io -->|"reads Runs tree"| node_sumw
node_outputs -->|"merges chunks"| node_merge
node_datasets -->|"selects datasets"| node_merge
node_outputs -->|"plots histograms"| node_plots
node_datasets -->|"labels samples"| node_plots
node_histograms -->|"defines histogram format"| node_plots
node_outputs -->|"reads yields"| node_datacard
node_datasets -->|"labels samples"| node_datacard
node_histograms -->|"uses histogram definitions"| node_datacard
node_outputs -.->|"supplies distributions"| node_ptll_derive
node_datasets -->|"selects samples"| node_ptll_derive
node_ptll_derive -.->|"derives reweighting"| node_ptll
node_analyst -->|"runs validation"| node_validation
node_io -->|"reads input files"| node_validation
node_analyst -->|"runs validation"| node_muon_validation
node_io -->|"reads input files"| node_muon_validation

click node_runner "https://github.com/ksl111/new_analysis_code/blob/main/run_analysis.py"
click node_multi_runner "https://github.com/ksl111/new_analysis_code/blob/main/run_analysis_all.py"
click node_io "https://github.com/ksl111/new_analysis_code/blob/main/python/common/io.py"
click node_datasets "https://github.com/ksl111/new_analysis_code/blob/main/python/bookkeeping/dataset_list.py"
click node_objects "https://github.com/ksl111/new_analysis_code/blob/main/python/analysis/objects.py"
click node_leptons "https://github.com/ksl111/new_analysis_code/blob/main/python/analysis/leptons.py"
click node_triggers "https://github.com/ksl111/new_analysis_code/blob/main/python/analysis/triggers.py"
click node_regions "https://github.com/ksl111/new_analysis_code/blob/main/python/analysis/regions.py"
click node_weights "https://github.com/ksl111/new_analysis_code/blob/main/python/analysis/weights.py"
click node_histograms "https://github.com/ksl111/new_analysis_code/blob/main/python/analysis/histograms.py"
click node_muonscare "https://github.com/ksl111/new_analysis_code/blob/main/python/corrections/muonscare.py"
click node_metxy "https://github.com/ksl111/new_analysis_code/blob/main/python/corrections/metxy_apply.py"
click node_ptll "https://github.com/ksl111/new_analysis_code/blob/main/python/corrections/ptll_weight.py"
click node_ptll_derive "https://github.com/ksl111/new_analysis_code/blob/main/python/corrections/ptll_derive.py"
click node_chunking "https://github.com/ksl111/new_analysis_code/blob/main/python/bookkeeping/make_chunks.py"
click node_sumw "https://github.com/ksl111/new_analysis_code/blob/main/python/bookkeeping/compute_sumw.py"
click node_merge "https://github.com/ksl111/new_analysis_code/blob/main/python/postproc/merge_chunks.py"
click node_plots "https://github.com/ksl111/new_analysis_code/blob/main/python/postproc/plot_data_mc_all.py"
click node_datacard "https://github.com/ksl111/new_analysis_code/blob/main/python/postproc/make_datacard.py"
click node_validation "https://github.com/ksl111/new_analysis_code/blob/main/python/validation/validate_metxy.py"
click node_muon_validation "https://github.com/ksl111/new_analysis_code/blob/main/python/validation/validate_muonscare.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runner,node_multi_runner toneBlue
class node_objects,node_leptons,node_triggers,node_regions,node_weights,node_histograms,node_nano toneAmber
class node_io,node_datasets,node_muonscare,node_metxy,node_ptll,node_ptll_derive,node_chunking,node_sumw toneMint
class node_merge,node_plots,node_datacard,node_validation,node_muon_validation,node_outputs toneRose
class node_analyst toneIndigo
```

## Components

### Event analysis

- [Analysis runner](https://github.com/ksl111/new_analysis_code/blob/main/run_analysis.py): `run_analysis.py`
- [Multi-region runner](https://github.com/ksl111/new_analysis_code/blob/main/run_analysis_all.py): `run_analysis_all.py`

### Selection and observables

- [Object building](https://github.com/ksl111/new_analysis_code/blob/main/python/analysis/objects.py): `python/analysis/objects.py`
- [Lepton utilities](https://github.com/ksl111/new_analysis_code/blob/main/python/analysis/leptons.py): `python/analysis/leptons.py`
- [Trigger selection](https://github.com/ksl111/new_analysis_code/blob/main/python/analysis/triggers.py): `python/analysis/triggers.py`
- [Region cuts](https://github.com/ksl111/new_analysis_code/blob/main/python/analysis/regions.py): `python/analysis/regions.py`
- [Event weights](https://github.com/ksl111/new_analysis_code/blob/main/python/analysis/weights.py): `python/analysis/weights.py`
- [Histograms](https://github.com/ksl111/new_analysis_code/blob/main/python/analysis/histograms.py): `python/analysis/histograms.py`

### Data and corrections

- [NanoAOD I/O](https://github.com/ksl111/new_analysis_code/blob/main/python/common/io.py): `python/common/io.py`
- [Dataset catalog](https://github.com/ksl111/new_analysis_code/blob/main/python/bookkeeping/dataset_list.py): `python/bookkeeping/dataset_list.py`
- [Muon correction](https://github.com/ksl111/new_analysis_code/blob/main/python/corrections/muonscare.py): `python/corrections/muonscare.py`
- [MET XY correction](https://github.com/ksl111/new_analysis_code/blob/main/python/corrections/metxy_apply.py): `python/corrections/metxy_apply.py`
- [pT(ll) reweighting](https://github.com/ksl111/new_analysis_code/blob/main/python/corrections/ptll_weight.py): `python/corrections/ptll_weight.py`
- [pT(ll) derivation](https://github.com/ksl111/new_analysis_code/blob/main/python/corrections/ptll_derive.py): `python/corrections/ptll_derive.py`
- [Chunk planning](https://github.com/ksl111/new_analysis_code/blob/main/python/bookkeeping/make_chunks.py): `python/bookkeeping/make_chunks.py`
- [Sum-weight bookkeeping](https://github.com/ksl111/new_analysis_code/blob/main/python/bookkeeping/compute_sumw.py): `python/bookkeeping/compute_sumw.py`

### Results and validation

- [Chunk merging](https://github.com/ksl111/new_analysis_code/blob/main/python/postproc/merge_chunks.py): `python/postproc/merge_chunks.py`
- [Data/MC plots](https://github.com/ksl111/new_analysis_code/blob/main/python/postproc/plot_data_mc_all.py): `python/postproc/plot_data_mc_all.py`
- [Combine datacard](https://github.com/ksl111/new_analysis_code/blob/main/python/postproc/make_datacard.py): `python/postproc/make_datacard.py`
- [Correction validation](https://github.com/ksl111/new_analysis_code/blob/main/python/validation/validate_metxy.py): `python/validation/validate_metxy.py`
- [Muon validation](https://github.com/ksl111/new_analysis_code/blob/main/python/validation/validate_muonscare.py): `python/validation/validate_muonscare.py`
- **Histogram outputs**

### Other components

- **Analyst**
- **NanoAOD files**

## Connections

- Analyst → Analysis runner: starts analysis (evidence: `run_analysis.py`)
- Analyst → Multi-region runner: starts analysis (evidence: `run_analysis_all.py`)
- NanoAOD files → NanoAOD I/O: provides events (evidence: `python/common/io.py`)
- Analysis runner → NanoAOD I/O: reads inputs (evidence: `run_analysis.py`)
- Analysis runner → Dataset catalog: selects datasets (evidence: `run_analysis.py`)
- Analysis runner → Object building: builds objects (evidence: `run_analysis.py`)
- Analysis runner → Lepton utilities: uses lepton helpers (evidence: `run_analysis.py`)
- Analysis runner → Trigger selection: applies triggers (evidence: `run_analysis.py`)
- Analysis runner → Region cuts: applies region cuts (evidence: `run_analysis.py`)
- Analysis runner → Event weights: computes weights (evidence: `run_analysis.py`)
- Analysis runner → Histograms: fills histograms (evidence: `run_analysis.py`)
- Analysis runner → Muon correction: applies correction (evidence: `run_analysis.py`)
- Analysis runner → MET XY correction: applies correction (evidence: `run_analysis.py`)
- Analysis runner → pT(ll) reweighting: applies reweighting (evidence: `run_analysis.py`)
- Multi-region runner → Object building: builds objects (evidence: `run_analysis_all.py`)
- Multi-region runner → Region cuts: applies region cuts (evidence: `run_analysis_all.py`)
- Multi-region runner → Histograms: fills histograms (evidence: `run_analysis_all.py`)
- Multi-region runner → MET XY correction: applies correction (evidence: `run_analysis_all.py`)
- Multi-region runner → pT(ll) reweighting: applies reweighting (evidence: `run_analysis_all.py`)
- Analysis runner → Histogram outputs: writes results
- Multi-region runner → Histogram outputs: writes results
- Dataset catalog → Chunk planning: plans chunks (evidence: `python/bookkeeping/make_chunks.py`)
- NanoAOD I/O → Sum-weight bookkeeping: reads Runs tree (evidence: `python/bookkeeping/compute_sumw.py`)
- Histogram outputs → Chunk merging: merges chunks (evidence: `python/postproc/merge_chunks.py`)
- Dataset catalog → Chunk merging: selects datasets (evidence: `python/postproc/merge_chunks.py`)
- Histogram outputs → Data/MC plots: plots histograms (evidence: `python/postproc/plot_data_mc_all.py`)
- Dataset catalog → Data/MC plots: labels samples (evidence: `python/postproc/plot_data_mc_all.py`)
- Histograms → Data/MC plots: defines histogram format (evidence: `python/postproc/plot_data_mc_all.py`)
- Histogram outputs → Combine datacard: reads yields (evidence: `python/postproc/make_datacard.py`)
- Dataset catalog → Combine datacard: labels samples (evidence: `python/postproc/make_datacard.py`)
- Histograms → Combine datacard: uses histogram definitions (evidence: `python/postproc/make_datacard.py`)
- Histogram outputs → pT(ll) derivation: supplies distributions
- Dataset catalog → pT(ll) derivation: selects samples (evidence: `python/corrections/ptll_derive.py`)
- pT(ll) derivation → pT(ll) reweighting: derives reweighting
- Analyst → Correction validation: runs validation (evidence: `python/validation/validate_metxy.py`)
- NanoAOD I/O → Correction validation: reads input files (evidence: `python/validation/validate_metxy.py`)
- Analyst → Muon validation: runs validation (evidence: `python/validation/validate_muonscare.py`)
- NanoAOD I/O → Muon validation: reads input files (evidence: `python/validation/validate_muonscare.py`)
