# tomasate/bsm3g_coffea architecture

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

- Interactive diagram: https://gitdiagram.com/tomasate/bsm3g_coffea
- Repository: https://github.com/tomasate/bsm3g_coffea

## Overview

BSM3G Coffea processes CMS NanoAOD data and simulation through configurable physics selections, corrections, event weights, and histogram production, then combines, normalizes, reports, and plots results. The README documents filesets and workflow configuration as inputs and describes local and Condor execution. Sampled processor and postprocessing code supports the central processing and results flow; some runner, submission, and configuration wiring is documented but not sampled, so those links are limited accordingly.

Main entry points: [`analysis/processors/base.py`](https://github.com/tomasate/bsm3g_coffea/blob/main/analysis/processors/base.py) (Base processor), [`analysis/postprocess/coffea_postprocessor.py`](https://github.com/tomasate/bsm3g_coffea/blob/main/analysis/postprocess/coffea_postprocessor.py) (Histogram postprocessing), [`runner.py`](https://github.com/tomasate/bsm3g_coffea/blob/main/runner.py) (Workflow runner), [`analysis/selections`](https://github.com/tomasate/bsm3g_coffea/tree/main/analysis/selections) (Object and event selections)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Analysis inputs"]
  node_datasets["Dataset filesets"]
  node_workflow["Workflow definitions"]
end

subgraph group_processing["Event processing"]
  node_processor["Base processor<br/>[base.py]"]
  node_config["Workflow config"]
  node_selections["Object and event selections"]
  node_workingpoints["Physics working points<br/>[working_points.py]"]
  node_corrections["Corrections and weights"]
  node_histograms["Histogram filling<br/>[hist_filler.py]"]
end

subgraph group_results["Results and plots"]
  node_coffeaoutputs["Coffea outputs"]
  node_postprocess["Histogram postprocessing"]
  node_reports["Cutflow and reports<br/>[run_postprocess.py]"]
  node_plotter["Plots<br/>[coffea_plotter.py]"]
  node_rootoutput["ROOT output<br/>[root_writer.py]"]
end

subgraph group_execution["Job execution"]
  node_runner["Workflow runner<br/>[runner.py]"]
  node_condor["Condor submission<br/>[submit_condor.py]"]
end

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

node_analyst -->|"selects workflow"| node_runner
node_analyst -->|"submits jobs"| node_condor
node_datasets -->|"selects samples"| node_runner
node_workflow -->|"configures run"| node_runner
node_nanoaod -->|"supplies events"| node_processor
node_runner -->|"runs workflow"| node_processor
node_processor -->|"builds config"| node_config
node_processor -->|"selects objects"| node_selections
node_selections -->|"uses criteria"| node_workingpoints
node_processor -->|"applies corrections"| node_corrections
node_processor -->|"fills histograms"| node_histograms
node_processor -->|"writes results"| node_coffeaoutputs
node_coffeaoutputs -->|"loads and combines"| node_postprocess
node_postprocess -->|"provides summaries"| node_reports
node_postprocess -->|"provides histograms"| node_plotter
node_postprocess -.->|"exports ROOT"| node_rootoutput

click node_datasets "https://github.com/tomasate/bsm3g_coffea/tree/main/analysis/filesets"
click node_workflow "https://github.com/tomasate/bsm3g_coffea/tree/main/analysis/workflows"
click node_runner "https://github.com/tomasate/bsm3g_coffea/blob/main/runner.py"
click node_condor "https://github.com/tomasate/bsm3g_coffea/blob/main/submit_condor.py"
click node_processor "https://github.com/tomasate/bsm3g_coffea/blob/main/analysis/processors/base.py"
click node_config "https://github.com/tomasate/bsm3g_coffea/blob/main/analysis/workflows/config/workflow_config_builder.py"
click node_selections "https://github.com/tomasate/bsm3g_coffea/tree/main/analysis/selections"
click node_workingpoints "https://github.com/tomasate/bsm3g_coffea/blob/main/analysis/working_points/working_points.py"
click node_corrections "https://github.com/tomasate/bsm3g_coffea/blob/main/analysis/corrections/corrections_manager.py"
click node_histograms "https://github.com/tomasate/bsm3g_coffea/blob/main/analysis/histograms/hist_filler.py"
click node_postprocess "https://github.com/tomasate/bsm3g_coffea/blob/main/analysis/postprocess/coffea_postprocessor.py"
click node_reports "https://github.com/tomasate/bsm3g_coffea/blob/main/run_postprocess.py"
click node_plotter "https://github.com/tomasate/bsm3g_coffea/blob/main/analysis/postprocess/coffea_plotter.py"
click node_rootoutput "https://github.com/tomasate/bsm3g_coffea/blob/main/analysis/utils/root_writer.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_datasets,node_workflow toneBlue
class node_processor,node_config,node_selections,node_workingpoints,node_corrections,node_histograms toneAmber
class node_coffeaoutputs,node_postprocess,node_reports,node_plotter,node_rootoutput toneMint
class node_runner,node_condor toneRose
class node_analyst,node_nanoaod toneIndigo
```

## Components

### Analysis inputs

- [Dataset filesets](https://github.com/tomasate/bsm3g_coffea/tree/main/analysis/filesets): `analysis/filesets`
- [Workflow definitions](https://github.com/tomasate/bsm3g_coffea/tree/main/analysis/workflows): `analysis/workflows`

### Event processing

- [Base processor](https://github.com/tomasate/bsm3g_coffea/blob/main/analysis/processors/base.py): `analysis/processors/base.py`
- [Workflow config](https://github.com/tomasate/bsm3g_coffea/blob/main/analysis/workflows/config/workflow_config_builder.py): `analysis/workflows/config/workflow_config_builder.py`
- [Object and event selections](https://github.com/tomasate/bsm3g_coffea/tree/main/analysis/selections): `analysis/selections`
- [Physics working points](https://github.com/tomasate/bsm3g_coffea/blob/main/analysis/working_points/working_points.py): `analysis/working_points/working_points.py`
- [Corrections and weights](https://github.com/tomasate/bsm3g_coffea/blob/main/analysis/corrections/corrections_manager.py): `analysis/corrections/corrections_manager.py`
- [Histogram filling](https://github.com/tomasate/bsm3g_coffea/blob/main/analysis/histograms/hist_filler.py): `analysis/histograms/hist_filler.py`

### Results and plots

- **Coffea outputs**
- [Histogram postprocessing](https://github.com/tomasate/bsm3g_coffea/blob/main/analysis/postprocess/coffea_postprocessor.py): `analysis/postprocess/coffea_postprocessor.py`
- [Cutflow and reports](https://github.com/tomasate/bsm3g_coffea/blob/main/run_postprocess.py): `run_postprocess.py`
- [Plots](https://github.com/tomasate/bsm3g_coffea/blob/main/analysis/postprocess/coffea_plotter.py): `analysis/postprocess/coffea_plotter.py`
- [ROOT output](https://github.com/tomasate/bsm3g_coffea/blob/main/analysis/utils/root_writer.py): `analysis/utils/root_writer.py`

### Job execution

- [Workflow runner](https://github.com/tomasate/bsm3g_coffea/blob/main/runner.py): `runner.py`
- [Condor submission](https://github.com/tomasate/bsm3g_coffea/blob/main/submit_condor.py): `submit_condor.py`

### Other components

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

## Connections

- Analyst → Workflow runner: selects workflow
- Analyst → Condor submission: submits jobs
- Dataset filesets → Workflow runner: selects samples
- Workflow definitions → Workflow runner: configures run
- NanoAOD files → Base processor: supplies events
- Workflow runner → Base processor: runs workflow
- Base processor → Workflow config: builds config
- Base processor → Object and event selections: selects objects
- Object and event selections → Physics working points: uses criteria
- Base processor → Corrections and weights: applies corrections
- Base processor → Histogram filling: fills histograms
- Base processor → Coffea outputs: writes results
- Coffea outputs → Histogram postprocessing: loads and combines
- Histogram postprocessing → Cutflow and reports: provides summaries
- Histogram postprocessing → Plots: provides histograms
- Histogram postprocessing → ROOT output: exports ROOT