Particle physics · data visualisation

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.

Schematic: a jet as straight particle rays leaving the interaction point, coloured by charge interaction point prong 1 prong 2 q = +1q = −1neutral
Hand-drawn schematic of what 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

  1. Fetchdata/download.py downloads the JetClass tar files from Zenodo (record 6619768) and unpacks them.
  2. Loaddata/loader.py reads 8 part_* branches for each class and builds one dict of NumPy arrays per jet.
  3. DeriveFrom the summed four-momenta it computes jet pT, energy and mass, and each particle's pT.
  4. Plotmain.py runs 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."

The 10 JetClass classes and the ROOT file prefixes in config.py
LabelProcessFile prefix
QCDlight-quark / gluon jetsZJetsToNuNu
HbbH → bb̄HToBB
HccH → cc̄HToCC
HggH → ggHToGG
H4qH → WW*/ZZ* → 4qHToWW4Q
HqqlH → WW*/ZZ* → qqℓνHToWW2Q1L
ZqqZ → qq̄ZToQQ
WqqW → qq̄′WToQQ
Tbqqt → bW(→qq̄′)TTBar
Tblt → bW(→ℓν)TTBarLep

03Results and status

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

If you need trained jet taggers or performance numbers, see GDS-ParT.

06Further reading