Atlas Open Magic 🪄📊

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

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 .

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')

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('2016')

Open Data functions description and usage

available_releases()

Shows the available open data releases keys and descriptions.

Usage:

import atlasopenmagic as atom
atom.available_releases()

get_current_release()

Retrieves the release that the package is currently set at.

Usage:

release = atom.get_current_release()
print(release)

set_release(release)

Set the release (scope) in which to look for information (research open data, education 8 TeV, et). The release passed to the function has to be one of the keys listed by available_releases().

Usage:

atom.set_release('2024r-pp')

get_metadata(key, *var)

Get metadata information for MC data.

Usage: You can get a dictionary with all the metadata

metadata = atom.get_metadata('301209')

Or a single variable

xsec = atom.get_metadata('301209', 'cross_section')

The available variables are: dataset_id, short_name, e-tag, cross_section, filter_efficiency, k_factor, number_events, sum_weights, sum_weights_squared, process, generators, keywords, description, job_link.

The keys to be used for research data are the Dataset IDs found in the Monte Carlo Metadata

get_urls(key)

Retrieves the list of URLs corresponding to a given key. This is used for MC data.

Usage:

urls = atom.get_urls('12345')

available_data()

Retrieves the list of keys for the data available for a scope.

Usage:

atom.available_data()

get_urls_data(data_key)

Retrieves the list of URLs corresponding to one of the keys listed by available_data().

Usage:

data = get_urls_data('2016')

Notebooks utilities description and usage

install_from_environment(*packages, environment_file)

Install specific packages listed in an environment.yml file via pip.

Args:

• *packages: Package names to install (e.g., 'coffea', 'dask').
• environment_file: Path to the environment.yml file. If None, defaults to the environment file for the educational resources.

Usage:

import atlasopenmagic as atom
atom.install_from_environment("coffea", "pandas", environment_file="./myfile.yml")

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.

License

This project is licensed under the Apache 2.0 License