# jslawless/run3-mj-analyzer architecture

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

- Interactive diagram: https://gitdiagram.com/jslawless/run3-mj-analyzer
- Repository: https://github.com/jslawless/run3-mj-analyzer

## Overview

This repository is a Run-3 multijet physics-analysis toolkit: users point command-line analyses at ROOT files or dataset JSONs and produce weighted spectra, QA comparisons, and plots. Its workflows cover slimmed-QCD comparisons, evaluator candidate spectra and truth-matched JEC studies, plus mixer hemisphere and assembled-event analyses. The shared runtime layer loads dataset filesets and supplies kinematic observables and truth matching. The README is empty; relationships below are limited to source-index references and excerpted calls, so some script-to-helper links are omitted.

Main entry points: [`src/run3_mj_analyzer/fileset.py`](https://github.com/jslawless/run3-mj-analyzer/blob/main/src/run3_mj_analyzer/fileset.py) (Fileset loader), [`scripts/fill_qcd_slimming.py`](https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/fill_qcd_slimming.py) (QCD spectra), [`scripts/make_histograms_both_candidates.py`](https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/make_histograms_both_candidates.py) (Two-candidate spectra), [`scripts/make_stitched_histograms.py`](https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/make_stitched_histograms.py) (Stitched-event spectra)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Input preparation"]
  node_dataset_json["Dataset JSON"]
  node_make_json["Dataset manifest builder"]
  node_merge_root["ROOT dataset merger<br/>[hadd_datasets.py]"]
end

subgraph group_analysis["Spectrum analysis"]
  node_qcd_fill["QCD spectra"]
  node_candidate_hists["Candidate spectra<br/>[make_histograms.py]"]
  node_both_hists["Two-candidate spectra"]
  node_hemi_hists["Hemisphere spectra"]
  node_stitched_hists["Stitched-event spectra"]
end

subgraph group_validation["Validation and comparison"]
  node_qcd_compare["QCD slimming comparison"]
  node_exclusivity["Exclusivity checks"]
  node_jec_compare["Truth-matched JEC comparison"]
  node_slimming_compare["Slimming comparison"]
  node_mass_plot["Mass-spectrum plots"]
  node_slim_plot["Slimmed-spectrum plots"]
end

subgraph group_runtime["Analysis primitives"]
  node_fileset["Fileset loader<br/>[fileset.py]"]
  node_observables["Mass asymmetry<br/>[observables.py]"]
  node_truth["Truth matching<br/>[truth_matching.py]"]
end

node_qcd_data["Slimmed QCD"]
node_eval_data["Evaluator ROOT<br/>[evaluated_qcd.json]"]
node_root_outputs[("ROOT histograms")]
node_plots["Analysis plots"]

node_make_json -->|"writes manifest"| node_dataset_json
node_qcd_data -.->|"provides input"| node_qcd_fill
node_dataset_json -->|"lists datasets"| node_qcd_fill
node_qcd_fill -->|"loads fileset"| node_fileset
node_qcd_fill -->|"writes spectra"| node_root_outputs
node_qcd_compare -->|"loads fileset"| node_fileset
node_qcd_compare -->|"writes overlays"| node_plots
node_candidate_hists -.->|"loads fileset"| node_fileset
node_candidate_hists -->|"writes histograms"| node_root_outputs
node_both_hists -.->|"loads fileset"| node_fileset
node_both_hists -->|"uses observable"| node_observables
node_both_hists -->|"writes histograms"| node_root_outputs
node_hemi_hists -.->|"loads fileset"| node_fileset
node_hemi_hists -->|"writes histograms"| node_root_outputs
node_stitched_hists -->|"loads fileset"| node_fileset
node_stitched_hists -->|"reuses binning"| node_qcd_fill
node_stitched_hists -->|"writes histograms"| node_root_outputs
node_exclusivity -.->|"uses fileset"| node_fileset
node_jec_compare -->|"loads fileset"| node_fileset
node_jec_compare -->|"matches truth"| node_truth
node_jec_compare -->|"writes spectra"| node_root_outputs
node_mass_plot -.->|"produces plots"| node_plots
node_slim_plot -.->|"produces plots"| node_plots
node_merge_root -.->|"merges files"| node_root_outputs

click node_dataset_json "https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/make_dataset_json.py"
click node_qcd_data "https://github.com/jslawless/run3-mj-analyzer/blob/main/json_files/slimmed_qcd_lt6_j.json"
click node_eval_data "https://github.com/jslawless/run3-mj-analyzer/blob/main/json_files/evaluated_qcd.json"
click node_make_json "https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/make_dataset_json.py"
click node_merge_root "https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/hadd_datasets.py"
click node_fileset "https://github.com/jslawless/run3-mj-analyzer/blob/main/src/run3_mj_analyzer/fileset.py"
click node_observables "https://github.com/jslawless/run3-mj-analyzer/blob/main/src/run3_mj_analyzer/observables.py"
click node_truth "https://github.com/jslawless/run3-mj-analyzer/blob/main/src/run3_mj_analyzer/truth_matching.py"
click node_qcd_fill "https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/fill_qcd_slimming.py"
click node_qcd_compare "https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/compare_qcd_slimming.py"
click node_candidate_hists "https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/make_histograms.py"
click node_both_hists "https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/make_histograms_both_candidates.py"
click node_hemi_hists "https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/make_hemisphere_histograms.py"
click node_stitched_hists "https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/make_stitched_histograms.py"
click node_exclusivity "https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/check_exclusivity.py"
click node_jec_compare "https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/compare_ttbar_mass_jec.py"
click node_slimming_compare "https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/compare_qcd_slimming.py"
click node_mass_plot "https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/plot_mass_spectra.py"
click node_slim_plot "https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/plot_slimmed_spectra.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_dataset_json,node_make_json,node_merge_root toneBlue
class node_qcd_fill,node_candidate_hists,node_both_hists,node_hemi_hists,node_stitched_hists,node_root_outputs toneAmber
class node_qcd_compare,node_exclusivity,node_jec_compare,node_slimming_compare,node_mass_plot,node_slim_plot toneMint
class node_fileset,node_observables,node_truth toneRose
class node_qcd_data,node_eval_data toneTeal
class node_plots toneIndigo
```

## Components

### Input preparation

- [Dataset JSON](https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/make_dataset_json.py): `scripts/make_dataset_json.py`
- [Dataset manifest builder](https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/make_dataset_json.py): `scripts/make_dataset_json.py`
- [ROOT dataset merger](https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/hadd_datasets.py): `scripts/hadd_datasets.py`

### Spectrum analysis

- [QCD spectra](https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/fill_qcd_slimming.py): `scripts/fill_qcd_slimming.py`
- [Candidate spectra](https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/make_histograms.py): `scripts/make_histograms.py`
- [Two-candidate spectra](https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/make_histograms_both_candidates.py): `scripts/make_histograms_both_candidates.py`
- [Hemisphere spectra](https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/make_hemisphere_histograms.py): `scripts/make_hemisphere_histograms.py`
- [Stitched-event spectra](https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/make_stitched_histograms.py): `scripts/make_stitched_histograms.py`

### Validation and comparison

- [QCD slimming comparison](https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/compare_qcd_slimming.py): `scripts/compare_qcd_slimming.py`
- [Exclusivity checks](https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/check_exclusivity.py): `scripts/check_exclusivity.py`
- [Truth-matched JEC comparison](https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/compare_ttbar_mass_jec.py): `scripts/compare_ttbar_mass_jec.py`
- [Slimming comparison](https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/compare_qcd_slimming.py): `scripts/compare_qcd_slimming.py`
- [Mass-spectrum plots](https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/plot_mass_spectra.py): `scripts/plot_mass_spectra.py`
- [Slimmed-spectrum plots](https://github.com/jslawless/run3-mj-analyzer/blob/main/scripts/plot_slimmed_spectra.py): `scripts/plot_slimmed_spectra.py`

### Analysis primitives

- [Fileset loader](https://github.com/jslawless/run3-mj-analyzer/blob/main/src/run3_mj_analyzer/fileset.py): `src/run3_mj_analyzer/fileset.py`
- [Mass asymmetry](https://github.com/jslawless/run3-mj-analyzer/blob/main/src/run3_mj_analyzer/observables.py): `src/run3_mj_analyzer/observables.py`
- [Truth matching](https://github.com/jslawless/run3-mj-analyzer/blob/main/src/run3_mj_analyzer/truth_matching.py): `src/run3_mj_analyzer/truth_matching.py`

### Other components

- [Slimmed QCD](https://github.com/jslawless/run3-mj-analyzer/blob/main/json_files/slimmed_qcd_lt6_j.json): `json_files/slimmed_qcd_lt6_j.json`
- [Evaluator ROOT](https://github.com/jslawless/run3-mj-analyzer/blob/main/json_files/evaluated_qcd.json): `json_files/evaluated_qcd.json`
- **ROOT histograms**
- **Analysis plots**

## Connections

- Dataset manifest builder → Dataset JSON: writes manifest (evidence: `scripts/make_dataset_json.py`)
- Slimmed QCD → QCD spectra: provides input
- Dataset JSON → QCD spectra: lists datasets (evidence: `scripts/fill_qcd_slimming.py`)
- QCD spectra → Fileset loader: loads fileset (evidence: `scripts/fill_qcd_slimming.py`)
- QCD spectra → ROOT histograms: writes spectra (evidence: `scripts/fill_qcd_slimming.py`)
- QCD slimming comparison → Fileset loader: loads fileset (evidence: `scripts/compare_qcd_slimming.py`)
- QCD slimming comparison → Analysis plots: writes overlays (evidence: `scripts/compare_qcd_slimming.py`)
- Candidate spectra → Fileset loader: loads fileset (evidence: `scripts/make_histograms.py`)
- Candidate spectra → ROOT histograms: writes histograms (evidence: `scripts/make_histograms.py`)
- Two-candidate spectra → Fileset loader: loads fileset (evidence: `scripts/make_histograms_both_candidates.py`)
- Two-candidate spectra → Mass asymmetry: uses observable (evidence: `scripts/make_histograms_both_candidates.py`)
- Two-candidate spectra → ROOT histograms: writes histograms (evidence: `scripts/make_histograms_both_candidates.py`)
- Hemisphere spectra → Fileset loader: loads fileset (evidence: `scripts/make_hemisphere_histograms.py`)
- Hemisphere spectra → ROOT histograms: writes histograms (evidence: `scripts/make_hemisphere_histograms.py`)
- Stitched-event spectra → Fileset loader: loads fileset (evidence: `scripts/make_stitched_histograms.py`)
- Stitched-event spectra → QCD spectra: reuses binning (evidence: `scripts/make_stitched_histograms.py`)
- Stitched-event spectra → ROOT histograms: writes histograms (evidence: `scripts/make_stitched_histograms.py`)
- Exclusivity checks → Fileset loader: uses fileset (evidence: `scripts/check_exclusivity.py`)
- Truth-matched JEC comparison → Fileset loader: loads fileset (evidence: `scripts/compare_ttbar_mass_jec.py`)
- Truth-matched JEC comparison → Truth matching: matches truth (evidence: `scripts/compare_ttbar_mass_jec.py`)
- Truth-matched JEC comparison → ROOT histograms: writes spectra (evidence: `scripts/compare_ttbar_mass_jec.py`)
- Mass-spectrum plots → Analysis plots: produces plots
- Slimmed-spectrum plots → Analysis plots: produces plots
- ROOT dataset merger → ROOT histograms: merges files
