ATLAS Open Magic 🪄📊

atlasopenmagic is a Python package made to simplify working with ATLAS Open Data by providing utilities to manage metadata and URLs for streaming the data.

Key Features:

• Simple functions to set the active data release (e.g., 2024r-pp).
• Efficient local caching of metadata to minimize API calls.
• Helper functions to retrieve specific dataset information, including file URLs for different "skims" (filtered versions of datasets).
• Support for multiple URL protocols (root, https, eos).
• Configuration via environment variables for easy integration into different workflows.

Installation

You can install this package using pip.

pip install atlasopenmagic

Alternatively, clone the repository and install locally:

git clone https://github.com/atlas-outreach-data-tools/atlasopenmagic.git
cd atlasopenmagic
pip install .

Documentation

You can find the full documentation for ATLAS Open Magic in the ATLAS Open Data website.

Quick start

First, import the package:

import atlasopenmagic as atom

See the available releases and set to one of the options given by available_releases()

atom.available_releases()
set_release('2024r-pp')

Check in the Monte Carlo Metadata which datasets do you want to retrieve and use the 'Dataset ID'. For example, to get the metadata from Pythia8EvtGen_A14MSTW2008LO_Zprime_NoInt_ee_SSM3000:

all_metadata = atom.get_metadata('301204')

If we only want a specific variable:

xsec = atom.get_metadata('301204', 'cross_section_pb')

To get the URLs to stream the files for that MC dataset:

all_mc = atom.get_urls('301204')

To get some data instead, check the available options:

atom.available_data()

And get the URLs for the one that's to be used:

all_mc = atom.get_urls('data')

Contributing

Contributions are welcome! To contribute:

1. Fork the repository.
2. Create a new branch (git checkout -b feature-name).
3. Commit your changes (git commit -am 'Add some feature').
4. Push to the branch (git push origin feature-name).
5. Create a Pull Request.

Please ensure all tests pass before submitting a pull request (just run pytest from the main directory of the package).

Developers can also pip install including additional tools required for testing:

pip install atlasopenmagic[dev]

or with a local copy of the repository:

pip install '.[dev]'

Pre-commit Hooks

We use pre-commit hooks, find below how to use them.

Installation

1. Install the [dev] dependencies if you haven't already, as shown above.

2. Install the git hook scripts:

pre-commit install

3. (Optional) Run against all files:

pre-commit run --all-files

What the hooks do

• black: Formats Python code consistently
• isort: Sorts imports alphabetically and separates them into sections
• ruff: Fast Python linter that catches common errors and style issues
• codespell: Checks for common misspellings in code and comments
• trailing-whitespace: Removes trailing whitespace
• end-of-file-fixer: Ensures files end with a newline
• pydocstyle: Checks docstring style (Google convention)

The hooks will run automatically on git commit. If any hook fails, the commit will be blocked until the issues are fixed.

License

This project is licensed under the Apache 2.0 License