# ATLAS Open Data Derivation Framework

Welcome to the **ATLAS Open Data Derivation Tool**! [`Physlitetoopendata`](https://gitlab.cern.ch/atlas-outreach-data-tools/physlitetoopendata) is a C++ framework devoted to skimming the [PHYSLITE](../documentation/data_format/physlite) files used for research to create flat ROOT NTuples used for educational purposes.

---

## 📌 **What is this framework for?**

`Physlitetoopendata` is designed to:

- Process datasets in the **PHYSLITE format**.
- Produce **ROOT NTuples** that retain essential information for analysis.
- Execute workflows either on the [Worldwide LHC Computing Grid](https://home.cern/science/computing/grid) or locally.

### **Useful Features**
- **Accessible:** You can install the framework locally or use our [Docker images](https://gitlab.cern.ch/atlas-outreach-data-tools/physlitetoopendata/container_registry/21562).
- **Versatile:** Useful for both educational and professional research purposes.

---

## 🔍 **What does the framework do?**

This framework automates the skimming of PHYSLITE datasets into ROOT NTuples, including the following objects in the output datasets:

- **Lepton data:** Some of the stored branches for leptons would be the number of leptons (`lep_n`), transverse momentums (`lep_pt`), pseudo-rapidities (`lep_eta`), azimuthal angles (`lep_phi`), charges (`lep_charge`) and their energies (`lep_e`). 
- **Tau data:** Some of the stored branches for tau-leptons would be the number of taus (`tau_n`), transverse momentums (`tau_pt`), pseudo-rapidities (`tau_eta`), azimuthal angles (`tau_phi`), charges (`tau_charge`) and their energies (`tau_e`).
- **Jets data:** Some of the stored branches for jets would be the number of jets (`jet_n`), transverse momentums (`jet_pt`), pseudo-rapidities (`jet_eta`), azimuthal angles (`jet_phi`) and their energies (`jet_e`).
- **Photons data:** Some of the stored branches for photons would be the number of photons (`photon_n`), transverse momentums (`photon_pt`), pseudo-rapidities (`photon_eta`), azimuthal angles (`photon_phi`) and their energies (`photon_e`).
- **Relevant Scale Factors:** Scale factors that account for the efficiencies of many objects, such as electrons (`ScaleFactor_ELE`), muons (`ScaleFactor_MUON`), taus (`ScaleFactor_TAU`), photons (`ScaleFactor_PHOTON`), or different operating efficiencies for b-tagging (`ScaleFactor_BTAG`), lepton triggers (`ScaleFactor_lepTRIGGER`), the pileup (`ScaleFactor_PILEUP`) and the jvt (`ScaleFactor_JVT`). 
- **Missing transverse energy (MET):** The missing transverse energy per event (`met`).
- **Truth information:** related to the particles produced in the collision, like truth electrons number (`truth_elec_n`), transverse momentums (`truth_elec_pt`), pseudo-rapities (`truth_elec_eta`), azimuthal angles (`truth_elec_phi`), truth muons number (`truth_muon_n`), transverse momentums (`truth_muon_pt`), pseudo-rapities (`truth_muon_eta`), azimuthal angles (`truth_muon_phi`), truth jets number (`truth_jet_n`), transverse momentums (`truth_jet_pt`), pseudo-rapities (`truth_jet_eta`), azimuthal angles (`truth_jet_phi`), etc.
- **Example systematic uncertainty variations** that can be used to better understand how systematic uncertainties are applied in real analyses, for instance `jet_pt_jer1` or `jet_pt_jer2` (transverse momentum of the jet after applying a specific systematic uncertainty from the jet energy resolution calibration).
- A carefully selected set of information sufficient to get started exploring the Run 2 proton-proton collisions collected by ATLAS ([detailed list of variables](../data/for_education/13TeV25_details)).

---

## ⚙️ **How does it work?**
Getting started with the framework is straightforward:

1. **Access the Repository:** Visit the [main GitLab repository](https://gitlab.cern.ch/atlas-outreach-data-tools/physlitetoopendata).
   - For the 2025 beta release of Outreach and Education Open Data, please check out [this tag](https://gitlab.cern.ch/atlas-outreach-data-tools/physlitetoopendata/-/tags/2025beta)
   - In general, the main branch should work and be up to date with the latest changes, but it is not guaranteed to be stable at all times
2. **Follow the Documentation:** The repository includes a comprehensive **README file** with step-by-step instructions to:
   - Install the framework (a docker image is available).
   - Run the framework locally.
   - Convert PHYSLITE samples to ROOT NTuples. 
3. Get the ROOT NTuples for your educational purposes.

---