JetClass Particle Visualizer
This Python pipeline turns jets from the JetClass dataset into plots of their particle clouds. It reads the per-particle branches from the official ROOT files with uproot, or it generates synthetic jets that have the right number of prongs for each class. From either source it produces single-jet η–φ clouds, interactive 3D momentum clouds, heatmaps averaged over each class, energy, pT and mass spectra, radial energy profiles, multiplicity plots and stylised event displays for all 10 classes.
- Python
- uproot
- awkward
- NumPy
- Matplotlib
- Plotly
- JetClass
Status: early exploration tool (single commit, July 2026). No plot outputs are committed. The model work moved to GDS-ParT.
plots/trajectory.py renders: straight rays along each particle's momentum, coloured by charge, with width and opacity scaled by energy. This is not output from the code.01What it does
cloud_2d.py
Shows one jet's constituents in (Δη, Δφ). Marker size scales with pT and colour with log(1+E).
cloud_3d.py
Shows one jet as an interactive Plotly scatter in (px, py, pz), with energy and charge in the hover text.
heatmaps.py
Stacks many jets into a 60×60 histogram of Δη and Δφ weighted by pT, giving one "fingerprint" per class. A 5×2 grid shows all classes together.
spectra.py
Plots step histograms, normalised to unit area, of particle energy (log–log), jet pT and jet mass for each class.
radial_profile.py
Plots the mean pT density against ΔR from the jet axis. Each bin is normalised by the ring area 2πr·dr and by the number of jets.
multiplicity.py
Plots the number of constituents against jet pT for each class.
trajectory.py
Draws a stylised 3D event display. Each particle is a straight ray to a fixed radius, with no magnetic-field bending.
02How it works
- Fetch
data/download.pydownloads the JetClass tar files from Zenodo (record 6619768) and unpacks them. - Load
data/loader.pyreads 8part_*branches for each class and builds one dict of NumPy arrays per jet. - DeriveFrom the summed four-momenta it computes jet pT, energy and mass, and each particle's pT.
- Plot
main.pyruns all seven plot modules and writes PNG and HTML files to--out.
Without data, data/synth.py builds jets with a fixed number of prongs per class. QCD has 1, Hbb, Hcc, Hgg, Zqq, Wqq and Tbl have 2, Hqql and Tbqq have 3, and H4q has 4. Particles are spread around each prong as Gaussians, and energies follow a Pareto distribution. The module docstring says: "Not real physics — just enough structure … to make the plots look like the real thing."
| Label | Process | File prefix |
|---|---|---|
| QCD | light-quark / gluon jets | ZJetsToNuNu |
| Hbb | H → bb̄ | HToBB |
| Hcc | H → cc̄ | HToCC |
| Hgg | H → gg | HToGG |
| H4q | H → WW*/ZZ* → 4q | HToWW4Q |
| Hqql | H → WW*/ZZ* → qqℓν | HToWW2Q1L |
| Zqq | Z → qq̄ | ZToQQ |
| Wqq | W → qq̄′ | WToQQ |
| Tbqq | t → bW(→qq̄′) | TTBar |
| Tbl | t → bW(→ℓν) | TTBarLep |
03Results and status
- The repository has the code only. No generated plots or data are committed, so this page shows no output figures.
- The repo has one commit (July 2026) and no tests.
- The visualizer does no classification. Jet tagging on JetClass is done in GDS-ParT, the gated dual-stream particle transformer, which has the trained models and results.
04Run it locally
These commands are taken from the README:
# setup python -m venv venv && source venv/bin/activate pip install -r requirements.txt # real data (~9 GB validation split) python data/download.py --split val_5M --out ./raw_data python main.py --data-dir ./raw_data --n-jets 2000 --out ./outputs # synthetic data (no download required) python main.py --synthetic --n-jets 2000 --out ./outputs
05Limitations
- Synthetic jets only look like jets. Their shapes are not physics results and should not be used to compare classes.
- The loader reads only the first ROOT file it finds for each class, and only the first
--n-jetsentries of that file. - The event display is stylised: every ray is straight and has the same length.
- The 3D modules write one HTML file per jet, and these files grow large as
--n-examplesincreases. - The README's file list does not quite match the code.
main.pywrites one combinedcloud2d_grid_all_classes.pngrather than separatecloud2d_<class>files.
If you need trained jet taggers or performance numbers, see GDS-ParT.