# hitesh-na/hera-radiation-profiles architecture

> Architecture diagram of the GitHub repository hitesh-na/hera-radiation-profiles, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hitesh-na/hera-radiation-profiles
- Repository: https://github.com/hitesh-na/hera-radiation-profiles

## Overview

This repository is a research workflow for preparing balloon-flight measurements, evaluating XGBoost count-rate models, and assessing whether altitude profiles support a Pfotzer-peak estimate. The main path is verified raw data → preprocessing → grouped model evaluation → profile and peak analysis; prediction and final refitting are additional documented capabilities. The exploratory HERA run is a separate path for explicitly unverified observations. Sampled source excerpts establish several internal calls; other workflow links below are documented by the README, while unsampled implementation details are not inferred.

Main entry points: [`pfotzer_xgb/experiments.py`](https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/experiments.py) (Grouped model evaluation), [`pfotzer_xgb/preprocessing.py`](https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/preprocessing.py) (Raw preprocessing), [`pfotzer_xgb/__main__.py`](https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/__main__.py) (Workflow commands), [`pfotzer_xgb/profiles.py`](https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/profiles.py) (Altitude profiles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Data preparation"]
  node_raw["Flight measurements"]
  node_preprocess["Raw preprocessing<br/>[preprocessing.py]"]
  node_alignment["Time alignment<br/>[time_alignment.py]"]
  node_io["Integrity and I/O<br/>[io.py]"]
  node_combined["Combined flight data"]
end

subgraph group_model["Modeling"]
  node_cli["Workflow commands<br/>[__main__.py]"]
  node_quality["Quality screening<br/>[quality.py]"]
  node_features["Feature engineering<br/>[features.py]"]
  node_experiments["Grouped model evaluation<br/>[experiments.py]"]
  node_model_results["Evaluation artifacts"]
end

subgraph group_science["Profile analysis"]
  node_profiles["Altitude profiles<br/>[profiles.py]"]
  node_peaks["Peak screening<br/>[peaks.py]"]
  node_plotting["Scientific plots<br/>[plotting.py]"]
end

subgraph group_hera["HERA workflows"]
  node_exploratory["Exploratory HERA training"]
  node_final_refit["Final model refit<br/>[refit.py]"]
  node_predict["Final prediction<br/>[predict.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs workflow"| node_cli
node_raw -->|"supplies recordings"| node_preprocess
node_preprocess -->|"unwraps timer"| node_alignment
node_preprocess -->|"writes provenance"| node_io
node_preprocess -->|"writes combined data"| node_combined
node_cli -->|"dispatches preparation"| node_preprocess
node_cli -->|"dispatches evaluation"| node_experiments
node_combined -->|"provides training data"| node_experiments
node_experiments -->|"audits rows"| node_quality
node_experiments -->|"engineers inputs"| node_features
node_experiments -->|"builds profiles"| node_profiles
node_experiments -->|"screens peaks"| node_peaks
node_experiments -->|"creates figures"| node_plotting
node_experiments -->|"saves evaluation artifacts"| node_model_results
node_peaks -->|"smooths supported bins"| node_profiles
node_plotting -->|"uses profile smoothing"| node_profiles
node_researcher -->|"runs exploratory study"| node_exploratory
node_researcher -->|"requests refit"| node_final_refit
node_final_refit -.->|"enables model prediction"| node_predict
node_researcher -->|"requests predictions"| node_predict

click node_raw "https://github.com/hitesh-na/hera-radiation-profiles/tree/main/data/raw"
click node_preprocess "https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/preprocessing.py"
click node_alignment "https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/time_alignment.py"
click node_io "https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/io.py"
click node_combined "https://github.com/hitesh-na/hera-radiation-profiles/tree/main/data/processed"
click node_cli "https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/__main__.py"
click node_quality "https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/quality.py"
click node_features "https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/features.py"
click node_experiments "https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/experiments.py"
click node_model_results "https://github.com/hitesh-na/hera-radiation-profiles/tree/main/results"
click node_profiles "https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/profiles.py"
click node_peaks "https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/peaks.py"
click node_plotting "https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/plotting.py"
click node_exploratory "https://github.com/hitesh-na/hera-radiation-profiles/blob/main/HERA_Exploratory_Training_2026-11-06/train_exploratory.py"
click node_final_refit "https://github.com/hitesh-na/hera-radiation-profiles/blob/main/HERA_Final_XGBoost_2026-11-19/refit.py"
click node_predict "https://github.com/hitesh-na/hera-radiation-profiles/blob/main/HERA_Final_XGBoost_2026-11-19/predict.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_raw,node_preprocess,node_alignment,node_io,node_combined toneBlue
class node_cli,node_quality,node_features,node_experiments,node_model_results toneAmber
class node_profiles,node_peaks,node_plotting toneMint
class node_exploratory,node_final_refit,node_predict toneRose
class node_researcher toneIndigo
```

## Components

### Data preparation

- [Flight measurements](https://github.com/hitesh-na/hera-radiation-profiles/tree/main/data/raw): `data/raw`
- [Raw preprocessing](https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/preprocessing.py): `pfotzer_xgb/preprocessing.py`
- [Time alignment](https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/time_alignment.py): `pfotzer_xgb/time_alignment.py`
- [Integrity and I/O](https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/io.py): `pfotzer_xgb/io.py`
- [Combined flight data](https://github.com/hitesh-na/hera-radiation-profiles/tree/main/data/processed): `data/processed`

### Modeling

- [Workflow commands](https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/__main__.py): `pfotzer_xgb/__main__.py`
- [Quality screening](https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/quality.py): `pfotzer_xgb/quality.py`
- [Feature engineering](https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/features.py): `pfotzer_xgb/features.py`
- [Grouped model evaluation](https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/experiments.py): `pfotzer_xgb/experiments.py`
- [Evaluation artifacts](https://github.com/hitesh-na/hera-radiation-profiles/tree/main/results): `results`

### Profile analysis

- [Altitude profiles](https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/profiles.py): `pfotzer_xgb/profiles.py`
- [Peak screening](https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/peaks.py): `pfotzer_xgb/peaks.py`
- [Scientific plots](https://github.com/hitesh-na/hera-radiation-profiles/blob/main/pfotzer_xgb/plotting.py): `pfotzer_xgb/plotting.py`

### HERA workflows

- [Exploratory HERA training](https://github.com/hitesh-na/hera-radiation-profiles/blob/main/HERA_Exploratory_Training_2026-11-06/train_exploratory.py): `HERA_Exploratory_Training_2026-11-06/train_exploratory.py`
- [Final model refit](https://github.com/hitesh-na/hera-radiation-profiles/blob/main/HERA_Final_XGBoost_2026-11-19/refit.py): `HERA_Final_XGBoost_2026-11-19/refit.py`
- [Final prediction](https://github.com/hitesh-na/hera-radiation-profiles/blob/main/HERA_Final_XGBoost_2026-11-19/predict.py): `HERA_Final_XGBoost_2026-11-19/predict.py`

### Other components

- **Researcher**

## Connections

- Researcher → Workflow commands: runs workflow (evidence: `README.md`)
- Flight measurements → Raw preprocessing: supplies recordings (evidence: `pfotzer_xgb/preprocessing.py`)
- Raw preprocessing → Time alignment: unwraps timer (evidence: `pfotzer_xgb/preprocessing.py`)
- Raw preprocessing → Integrity and I/O: writes provenance (evidence: `pfotzer_xgb/preprocessing.py`)
- Raw preprocessing → Combined flight data: writes combined data (evidence: `pfotzer_xgb/preprocessing.py`)
- Workflow commands → Raw preprocessing: dispatches preparation (evidence: `pfotzer_xgb/__main__.py`)
- Workflow commands → Grouped model evaluation: dispatches evaluation (evidence: `pfotzer_xgb/__main__.py`)
- Combined flight data → Grouped model evaluation: provides training data (evidence: `README.md`)
- Grouped model evaluation → Quality screening: audits rows (evidence: `pfotzer_xgb/experiments.py`)
- Grouped model evaluation → Feature engineering: engineers inputs (evidence: `pfotzer_xgb/experiments.py`)
- Grouped model evaluation → Altitude profiles: builds profiles (evidence: `pfotzer_xgb/experiments.py`)
- Grouped model evaluation → Peak screening: screens peaks (evidence: `pfotzer_xgb/experiments.py`)
- Grouped model evaluation → Scientific plots: creates figures (evidence: `pfotzer_xgb/experiments.py`)
- Grouped model evaluation → Evaluation artifacts: saves evaluation artifacts (evidence: `README.md`)
- Peak screening → Altitude profiles: smooths supported bins (evidence: `pfotzer_xgb/peaks.py`)
- Scientific plots → Altitude profiles: uses profile smoothing (evidence: `pfotzer_xgb/plotting.py`)
- Researcher → Exploratory HERA training: runs exploratory study (evidence: `HERA_Exploratory_Training_2026-11-06/train_exploratory.py`)
- Researcher → Final model refit: requests refit (evidence: `README.md`)
- Final model refit → Final prediction: enables model prediction
- Researcher → Final prediction: requests predictions (evidence: `README.md`)
