By name: atlas-notebooks
description: Use when the user names a specific ATLAS Open Data outreach notebook (e.g. HZZAnalysis.ipynb, Find_the_Z, HyyAnalysis.ipynb) or asks which runtime (Binder / Colab / SWAN / Docker image) to pick for one. Routes to the canonical path under atlas-outreach-data-tools/notebooks-collection-opendata and the matching docs section in 13TeV25Doc. Does NOT cover Standard Model walkthroughs by physics process (use sm-analyses), DSID or cross-section lookups (use atlas-opendata), or fuzzy infrastructure goals (use infra-advisor). Disambiguator phrase: outreach notebook routing.
data_scope: open
experiment: atlas
Scope
Use this skill for notebook discovery and runtime selection in the
public repo
https://github.com/atlas-outreach-data-tools/notebooks-collection-opendata.
If the user has already picked a Standard Model walkthrough, prefer
the sm-analyses skill for the physics-level procedure. If the user
needs to look up ATLAS MC metadata to feed a notebook, use
atlas-opendata.
This skill does not drive an MCP. It is a curated index of existing material. Cite the GitHub path whenever you name a notebook.
Repository layout (as of April 2026)
13-TeV-examples/uproot_python/— Python + uproot notebooks (no ROOT required). The main tutorial set.13-TeV-examples/rdataframe/— RDataFrame (PyROOT) variants of the Hyy analysis.13-TeV-examples/pyroot/— minimal PyROOT examples (histogram, Z mass, Hyy, kinematics).13-TeV-examples/cpp/— C++ ROOT variants.8-TeV-examples/— legacy 8 TeV tutorials.for-research/— advanced material (PHYSLITE tutorial, event-generation tutorial, Rivet, fake-rate estimation, phoenix viewer, public likelihoods).
Notebook map (13-TeV-examples/uproot_python/)
| File | Topic | Skill to pair with |
|---|---|---|
IntroToEducationAndOutreachOD.ipynb |
Orientation for new users | — |
Find_the_Z.ipynb |
Z → μμ peak reconstruction | sm-analyses |
HZZAnalysis.ipynb |
H → ZZ → 4ℓ rediscovery | sm-analyses |
CoffeaHZZAnalysis.ipynb |
Same, using coffea | sm-analyses |
HyyAnalysis.ipynb |
H → γγ, 36.1 fb⁻¹ | sm-analyses |
HbbAnalysis.ipynb |
H → bb (advanced) | sm-analyses |
Hmumu.ipynb |
H → μμ | sm-analyses |
ttbar_analysis.ipynb |
tt̄ pair production | sm-analyses |
WZ3l_Analysis.ipynb |
WZ → 3ℓ + ν | sm-analyses |
GravitonAnalysis.ipynb |
BSM graviton search | — |
Dark_Matter_Machine_Learning.ipynb |
ML for DM | — |
HZZ_BDT_demo.ipynb, HZZ_NeuralNet_demo.ipynb |
ML on H→ZZ | — |
MetadataTutorial.ipynb |
Cross-sections and weights | atlas-opendata |
systematics_notebook.ipynb |
Systematic uncertainties | — |
detector_acceptance_and_efficiency.ipynb |
Acceptance vs efficiency | — |
Fluctuations.ipynb |
Statistical fluctuations | — |
NCB.ipynb |
Non-collision backgrounds | — |
Notebook map (for-research/)
| File | Topic |
|---|---|
physlite_tutorial.ipynb |
DAOD_PHYSLITE format (pair with physlite-basics) |
OpenEvgenTutorial.ipynb |
Event generation tutorial |
rivet.ipynb |
Rivet for generator-level analysis |
FakeRateEstimation/ |
Fake-lepton estimation |
public-likelihoods/ |
pyhf likelihoods |
phoenix/ |
Phoenix event display |
limitations/ |
Documented limits of the dataset |
Procedure
- Identify the physics process or technique the user cares about.
- Pick the notebook from the tables above. Quote the path exactly
(
13-TeV-examples/<subdir>/<name>.ipynb). - Pick the runtime (see next section).
- List the Python dependencies (uproot, awkward, matplotlib,
mplhep, hist, coffea, pyhf as applicable). For
for-research/physlite_tutorial.ipynb, there is a dedicatedphyslite_tutorial_requirements.txt. - If the user hasn't cloned the repo, point them at
git clone https://github.com/atlas-outreach-data-tools/notebooks-collection-opendata.git.
Runtime selection
The README in the upstream repo advertises all five of these for the 13 TeV examples. Default order of recommendation:
| Runtime | When to recommend |
|---|---|
| Binder | Default for first-time users. Zero local install. Warn that the "not trusted" button must be clicked for interactive histograms. |
| Google Colab | User wants GPU (e.g. for the ML notebooks) or already lives in Colab. |
| SWAN (swan.cern.ch) | User has a CERN account. |
| GitHub Codespaces | Developer workflow, wants a persistent environment. |
| Docker | Local reproducibility. docker-compose.yml at the repo root. |
Pitfalls
- The outreach notebooks use a reduced 13 TeV ntuple format, not
raw PHYSLITE, except for
for-research/physlite_tutorial.ipynbwhich does use PHYSLITE. Don't confuse the two. - File paths are read-only URIs. Users don't need Rucio.
HZZ_BDT_demo.ipynbandHZZ_NeuralNet_demo.ipynbare not self-contained ML tutorials — they assumeHZZAnalysis.ipynbhas been run first.
Verification
A successful use of this skill ends with the user knowing:
- The exact notebook path in the outreach repo.
- One recommended runtime with a concrete click-through (Binder badge / Colab URL / SWAN share).
- The Python packages they'll need, if running locally.