| name | physlite-basics |
| description | Use when the user needs to OPEN an ATLAS DAOD_PHYSLITE file with `uproot` / `awkward`, list its branches, reconstruct calibrated objects (electrons, muons, photons, taus, small-R jets, large-R jets, MET, trigger decisions), or apply MC normalisation. Assumes a public HTTPS or XRootD URI such as `root://eospublic.cern.ch/...` from `atlas_get_urls` or `cod_list_files`. Does NOT cover the older flat 13 TeV reduced ntuples (use the matching tutorial via `atlas-notebooks`), CMS NanoAOD or MiniAOD, or sample discovery (use `atlas-opendata`). Disambiguator phrase: PHYSLITE branch reader. |
Scope
Use this skill when the user is handling DAOD_PHYSLITE files
(the default "physics-lite" derivation format of the 2024+ ATLAS Open
Data releases). For the older 13 TeV reduced ntuples used by the
uproot_python tutorials in
atlas-outreach-data-tools/notebooks-collection-opendata, this skill
is not the right one — those are flat ntuples with bespoke
branches; point users at the relevant notebook directly via
atlas-notebooks.
If the user needs a DSID or cross-section, use atlas-opendata.
If the user needs a portal file URI, use cern-opendata.
What PHYSLITE is
- ATLAS's official slimmed-down derivation designed for analysis
without the full xAOD framework.
- Ships calibrated analysis-level objects: electrons, muons, photons,
taus, small-R jets, large-R jets, MET, trigger decisions, event
info.
- Readable with uproot (or xAOD via Athena; Open Data users should
prefer uproot).
- Companion tutorial:
for-research/physlite_tutorial.ipynb in
atlas-outreach-data-tools/notebooks-collection-opendata.
Reading a file
Given a URI from atlas_get_urls(protocol='https') or from
cod_list_files:
import uproot
f = uproot.open("https://opendata.cern.ch/record/.../DAOD_PHYSLITE.root")
t = f["CollectionTree"]
The interesting physics objects live under AnalysisElectronsAuxDyn,
AnalysisMuonsAuxDyn, AnalysisJetsAuxDyn, AnalysisPhotonsAuxDyn,
AnalysisTauJetsAuxDyn, MET_Core_AnalysisMETAuxDyn, with kinematics
in pt, eta, phi, m (in MeV — watch the units).
Common branches
| Collection | Typical branches | Notes |
|---|
AnalysisElectronsAuxDyn | pt, eta, phi, m, charge | Calibration applied |
AnalysisMuonsAuxDyn | pt, eta, phi, charge, muonType, quality | muonType == 0 is Combined |
AnalysisJetsAuxDyn | pt, eta, phi, m, DFCommonJets_jetClean_LooseBad | AntiKt4EMPFlow |
AnalysisPhotonsAuxDyn | pt, eta, phi, m | Use with ID flags |
MET_Core_AnalysisMETAuxDyn | mpx, mpy, sumet | MET = sqrt(mpx^2 + mpy^2) |
EventInfoAuxDyn | mcEventWeights, runNumber, eventNumber | First element of mcEventWeights is the nominal mcWeight |
Units are MeV throughout PHYSLITE. Convert to GeV before
plotting.
MC normalisation
Use the formula (always — do not hide it in a helper):
weight = cross_section_pb * 1000 * kFactor * genFiltEff * mcWeight / sumOfWeights * luminosity_fb
Get the per-sample terms from the atlasopenmagic MCP:
atlas_get_metadata(dsid) → cross_section_pb, kFactor,
genFiltEff, sumOfWeights.mcWeight is per-event, from EventInfoAuxDyn.mcEventWeights[0].luminosity_fb comes from the release (e.g. 36.1 fb⁻¹ for the
old Hyy tutorial, 140 fb⁻¹ for Run 2 full).
Procedure
- Get the URI for the sample with
atlas_get_urls(dsid, protocol='https') (or protocol='root' for
XRootD).
- Open with
uproot.open.
- Read the branches you need with
t.arrays([...], library='ak').
- Convert MeV → GeV.
- Compute the per-event weight using the formula above.
- Fill histograms with
hist / boost_histogram, plot with
mplhep.style.ATLAS.
Pitfalls
- Units are MeV, not GeV. Most published plots divide by 1000.
mcEventWeights is a vector, nominal is index [0]. The rest
are systematic variations.sumOfWeights is a dataset-level quantity. Read it once from
atlas_get_metadata, not per-event.- Data files don't have
mcEventWeights; guard with an
is_data flag.
- For trigger decisions you need
TrigMatch info which is not
in PHYSLITE auxiliaries — fall back to the reduced 13 TeV ntuples
if the user wants detailed trigger studies.
Verification
A successful use of this skill ends with the user having:
- Opened a PHYSLITE file with
uproot.open.
- Extracted at least one kinematic array in GeV.
- Printed (or plotted) a weighted distribution using the
normalisation formula above.
