# ammelsayed/hepdataset architecture

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

- Interactive diagram: https://gitdiagram.com/ammelsayed/hepdataset
- Repository: https://github.com/ammelsayed/hepdataset

## Overview

HEPDataset turns Delphes ROOT inputs and a samples card into selected, analysis-ready ROOT trees, with summaries and optional merging or parallel event processing. The main path is CLI dispatch → dataset orchestration → sample parsing and loop selection → event/object selection and configured feature building → ROOT output. Other documented capabilities include standalone loop modes, sample-card inspection/conversion, and output merging. Edges are limited to relationships shown in excerpts, indexed references, or README; several loop internals and integrations are unsampled.

Main entry points: [`src/make_dataset.py`](https://github.com/ammelsayed/hepdataset/blob/main/src/make_dataset.py) (Dataset orchestration), [`src/loops/adaptive_delphes.py`](https://github.com/ammelsayed/hepdataset/blob/main/src/loops/adaptive_delphes.py) (Adaptive loop), [`src/core/object_selection.py`](https://github.com/ammelsayed/hepdataset/blob/main/src/core/object_selection.py) (Object selection), [`src/cli.py`](https://github.com/ammelsayed/hepdataset/blob/main/src/cli.py) (CLI dispatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and orchestration"]
  node_cli["CLI dispatcher<br/>[cli.py]"]
  node_dataset["Dataset orchestration<br/>[make_dataset.py]"]
end

subgraph group_inputs["Inputs and configuration"]
  node_samples["Samples reader<br/>[samples_reader.py]"]
  node_branch_config["Branch-card reader<br/>[branches_reader.py]"]
  node_defaults["Packaged defaults"]
end

subgraph group_analysis["Event analysis"]
  node_delphes["Delphes access<br/>[delphes_utilis.py]"]
  node_object_select["Object selection"]
  node_event_select["Channel selection<br/>[event_selection.py]"]
  node_kinematics["Kinematics features<br/>[kinematics.py]"]
end

subgraph group_execution["Loop execution"]
  node_adaptive["Adaptive loop"]
  node_basic_loops["Basic loops"]
  node_loop_util["Loop arguments<br/>[loop_utilis.py]"]
  node_parallel["Parallel processing<br/>[parallel_loop.py]"]
end

subgraph group_outputs["Output management"]
  node_root_trees[("Selected ROOT trees")]
  node_summaries["Selection summaries"]
  node_merge["Sample merger<br/>[merge_samples.py]"]
end

node_user(("Analyst"))
node_root_files[("ROOT inputs")]
node_sample_user(("Sample-card user"))

node_user -->|"invokes"| node_cli
node_cli -.->|"dispatches to"| node_dataset
node_dataset -->|"reads card"| node_samples
node_dataset -->|"loads selected loop"| node_adaptive
node_dataset -.->|"configures features"| node_branch_config
node_dataset -->|"uses defaults"| node_defaults
node_dataset -->|"runs chunks"| node_parallel
node_dataset -->|"creates selector"| node_object_select
node_dataset -->|"creates selector"| node_event_select
node_adaptive -->|"builds tree chain"| node_delphes
node_adaptive -.->|"reads config"| node_branch_config
node_adaptive -->|"selects objects"| node_object_select
node_adaptive -.->|"classifies events"| node_event_select
node_adaptive -.->|"computes features"| node_kinematics
node_adaptive -->|"writes trees"| node_root_trees
node_adaptive -->|"writes summaries"| node_summaries
node_object_select -->|"uses observables"| node_kinematics
node_basic_loops -->|"uses selector"| node_object_select
node_basic_loops -->|"uses selector"| node_event_select
node_parallel -->|"merges chunks"| node_root_trees
node_root_files -.->|"lists file paths"| node_samples
node_root_files -.->|"provides events"| node_delphes
node_sample_user -->|"inspects or converts"| node_samples
node_sample_user -->|"requests merge"| node_merge
node_merge -.->|"merges outputs"| node_root_trees
node_cli -->|"dispatches loop"| node_basic_loops
node_loop_util -->|"configures execution"| node_parallel

click node_cli "https://github.com/ammelsayed/hepdataset/blob/main/src/cli.py"
click node_dataset "https://github.com/ammelsayed/hepdataset/blob/main/src/make_dataset.py"
click node_samples "https://github.com/ammelsayed/hepdataset/blob/main/src/samples_reader.py"
click node_branch_config "https://github.com/ammelsayed/hepdataset/blob/main/src/core/branches_reader.py"
click node_defaults "https://github.com/ammelsayed/hepdataset/tree/main/src/defaults"
click node_delphes "https://github.com/ammelsayed/hepdataset/blob/main/src/core/delphes_utilis.py"
click node_adaptive "https://github.com/ammelsayed/hepdataset/blob/main/src/loops/adaptive_delphes.py"
click node_basic_loops "https://github.com/ammelsayed/hepdataset/tree/main/src/loops"
click node_object_select "https://github.com/ammelsayed/hepdataset/blob/main/src/core/object_selection.py"
click node_event_select "https://github.com/ammelsayed/hepdataset/blob/main/src/core/event_selection.py"
click node_kinematics "https://github.com/ammelsayed/hepdataset/blob/main/src/core/kinematics.py"
click node_loop_util "https://github.com/ammelsayed/hepdataset/blob/main/src/loops/loop_utilis.py"
click node_parallel "https://github.com/ammelsayed/hepdataset/blob/main/src/loops/parallel_loop.py"
click node_merge "https://github.com/ammelsayed/hepdataset/blob/main/src/merge_samples.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_cli,node_dataset,node_sample_user toneBlue
class node_samples,node_branch_config,node_defaults,node_root_files toneAmber
class node_delphes,node_object_select,node_event_select,node_kinematics toneMint
class node_adaptive,node_basic_loops,node_loop_util,node_parallel toneRose
class node_root_trees,node_summaries,node_merge,node_user toneIndigo
```

## Components

### Entry and orchestration

- [CLI dispatcher](https://github.com/ammelsayed/hepdataset/blob/main/src/cli.py): `src/cli.py`
- [Dataset orchestration](https://github.com/ammelsayed/hepdataset/blob/main/src/make_dataset.py): `src/make_dataset.py`

### Inputs and configuration

- [Samples reader](https://github.com/ammelsayed/hepdataset/blob/main/src/samples_reader.py): `src/samples_reader.py`
- [Branch-card reader](https://github.com/ammelsayed/hepdataset/blob/main/src/core/branches_reader.py): `src/core/branches_reader.py`
- [Packaged defaults](https://github.com/ammelsayed/hepdataset/tree/main/src/defaults): `src/defaults`

### Event analysis

- [Delphes access](https://github.com/ammelsayed/hepdataset/blob/main/src/core/delphes_utilis.py): `src/core/delphes_utilis.py`
- [Object selection](https://github.com/ammelsayed/hepdataset/blob/main/src/core/object_selection.py): `src/core/object_selection.py`
- [Channel selection](https://github.com/ammelsayed/hepdataset/blob/main/src/core/event_selection.py): `src/core/event_selection.py`
- [Kinematics features](https://github.com/ammelsayed/hepdataset/blob/main/src/core/kinematics.py): `src/core/kinematics.py`

### Loop execution

- [Adaptive loop](https://github.com/ammelsayed/hepdataset/blob/main/src/loops/adaptive_delphes.py): `src/loops/adaptive_delphes.py`
- [Basic loops](https://github.com/ammelsayed/hepdataset/tree/main/src/loops): `src/loops`
- [Loop arguments](https://github.com/ammelsayed/hepdataset/blob/main/src/loops/loop_utilis.py): `src/loops/loop_utilis.py`
- [Parallel processing](https://github.com/ammelsayed/hepdataset/blob/main/src/loops/parallel_loop.py): `src/loops/parallel_loop.py`

### Output management

- **Selected ROOT trees**
- **Selection summaries**
- [Sample merger](https://github.com/ammelsayed/hepdataset/blob/main/src/merge_samples.py): `src/merge_samples.py`

### Other components

- **Analyst**
- **ROOT inputs**
- **Sample-card user**

## Connections

- Analyst → CLI dispatcher: invokes (evidence: `README.md`)
- CLI dispatcher → Dataset orchestration: dispatches to
- Dataset orchestration → Samples reader: reads card (evidence: `src/make_dataset.py`)
- Dataset orchestration → Adaptive loop: loads selected loop (evidence: `src/make_dataset.py`)
- Dataset orchestration → Branch-card reader: configures features
- Dataset orchestration → Packaged defaults: uses defaults (evidence: `README.md`)
- Dataset orchestration → Parallel processing: runs chunks (evidence: `src/make_dataset.py`)
- Dataset orchestration → Object selection: creates selector (evidence: `src/make_dataset.py`)
- Dataset orchestration → Channel selection: creates selector (evidence: `src/make_dataset.py`)
- Adaptive loop → Delphes access: builds tree chain (evidence: `src/loops/adaptive_delphes.py`)
- Adaptive loop → Branch-card reader: reads config (evidence: `src/loops/adaptive_delphes.py`)
- Adaptive loop → Object selection: selects objects (evidence: `src/loops/adaptive_delphes.py`)
- Adaptive loop → Channel selection: classifies events (evidence: `src/loops/adaptive_delphes.py`)
- Adaptive loop → Kinematics features: computes features (evidence: `src/loops/adaptive_delphes.py`)
- Adaptive loop → Selected ROOT trees: writes trees (evidence: `src/loops/adaptive_delphes.py`)
- Adaptive loop → Selection summaries: writes summaries (evidence: `src/loops/adaptive_delphes.py`)
- Object selection → Kinematics features: uses observables (evidence: `src/core/object_selection.py`)
- Basic loops → Object selection: uses selector (evidence: `src/loops/basic2_delphes.py`)
- Basic loops → Channel selection: uses selector (evidence: `src/loops/basic2_delphes.py`)
- Parallel processing → Selected ROOT trees: merges chunks (evidence: `src/loops/parallel_loop.py`)
- ROOT inputs → Samples reader: lists file paths
- ROOT inputs → Delphes access: provides events
- Sample-card user → Samples reader: inspects or converts (evidence: `README.md`)
- Sample-card user → Sample merger: requests merge (evidence: `README.md`)
- Sample merger → Selected ROOT trees: merges outputs
- CLI dispatcher → Basic loops: dispatches loop (evidence: `README.md`)
- Loop arguments → Parallel processing: configures execution (evidence: `src/loops/loop_utilis.py`)
