| Name | atlasopenmagic JSON |
| Version |
1.1.0
JSON |
| download |
| home_page | None |
| Summary | A utility package for retrieving ATLAS open data URLs and metadata. |
| upload_time | 2025-07-24 21:51:33 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.6 |
| license | None |
| keywords |
atlas
open data
utilities
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Atlas Open Magic 🪄📊
[](https://github.com/atlas-outreach-data-tools/atlasopenmagic/actions/workflows/test.yml)
**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`.
```bash
pip install atlasopenmagic
```
Alternatively, clone the repository and install locally:
```bash
git clone https://github.com/atlas-outreach-data-tools/atlasopenmagic.git
cd atlasopenmagic
pip install .
```
## Quick start
First, import the package:
```python
import atlasopenmagic as atom
```
See the available releases and set to one of the options given by `available_releases()`
```python
atom.available_releases()
set_release('2024r-pp')
```
Check in the [Monte Carlo Metadata](https://opendata.atlas.cern/docs/data/for_research/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*:
```python
all_metadata = atom.get_metadata('301204')
```
If we only want a specific variable:
```python
xsec = atom.get_metadata('301204', 'cross_section')
```
To get the URLs to stream the files for that MC dataset:
```python
all_mc = atom.get_urls('301204')
```
To get some data instead, check the available options:
```python
atom.available_data()
```
And get the URLs for the one that's to be used:
```python
all_mc = atom.get_urls('2016')
```
## Open Data functions description and usage
### `available_releases()`
Shows the available open data releases keys and descriptions.
**Usage:**
```python
import atlasopenmagic as atom
atom.available_releases()
```
### `get_current_release()`
Retrieves the release that the package is currently set at.
**Usage:**
```python
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()`.
Args:
- `release`: name of the release to use.
**Usage:**
```python
atom.set_release('2024r-pp')
```
### `get_metadata(key, var)`
Get metadata information for MC data.
Args:
- `key`: Dataset ID.
- `var`: Variable to retrieve.
**Usage:**
You can get a dictionary with all the metadata
```python
metadata = atom.get_metadata('301209')
```
Or a single variable
```python
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](https://opendata.atlas.cern/docs/data/for_research/metadata)
### `get_urls(key, skim, protocol)`
Retrieves the list of URLs corresponding to a given key.
Args:
- `key`: Dataset ID.
- `skim`: Skim for the dataset. This parameter is only taken into account when using the `2025e-13tev-beta` release.
- `protocol`: protocol for the URLs. Options: 'root' and 'https'.
**Usage:**
```python
urls = atom.get_urls('12345', protocol='root')
```
### `available_data()`
Retrieves the list of keys for the data available for a scope/release.
**Usage:**
```python
atom.available_data()
```
### ❗**DEPRECATED** `get_urls_data(data_key, protocol)`
*Please use `get_urls(key, skim='noskim', protocol=protocol)` instead.*
Retrieves the list of URLs corresponding to one of the keys listed by `available_data()`.
Args:
- `data_key` : For non-beta releases (e.g. '2015', '2016', etc.), the data key to look up.
- `skim` : Only for the 2025e-13tev-beta release: the skim name to look up.
**Usage:**
```python
data = get_urls_data(data_key='2016', protocol='https')
```
## 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](https://github.com/atlas-outreach-data-tools/notebooks-collection-opendata/blob/master/binder/environment.yml).
**Usage:**
```python
import atlasopenmagic as atom
atom.install_from_environment("coffea", "pandas", environment_file="./myfile.yml")
```
### `build_dataset(samples_defs, skim='noskim', protocol='https')`
Build a dict of data and / or MC samples URLs.
Args:
- `samples_defs`: Dictionary with DIDs and optional color: `{ sample_name: {'list': [...urls...], 'color': ...}, … }`
- `skim` : The MC skim tag (only meaningful in the 2025e-13tev-beta release)
- `protocol` : Protocol to use for URLs.
**Usage:**
```python
import atlasopenmagic as atom
atom.set_release('2025e-13tev-beta')
samples_defs = {
r'Data': {'dids': ["data"], 'color': 'red'},
r'Background $t\bar t$': {'dids': [410470], 'color': 'yellow'},
r'Background $V+$jets': {'dids': [700335,700336,700337], 'color': 'orange'},
r'Background Diboson': {'dids': [700488,700489,700490,700491],'color': 'green'},
r'Background $ZZ^{*}$': {'dids': [700600,700601], 'color': '#ff0000'},
r'Signal ($m_H$=125 GeV)': {'dids': [345060,346228], 'color': '#00cdff'},
}
mc_samples = atom.build_dataset(samples_defs, skim='2bjets', protocol='https')
```
## 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).
## License
This project is licensed under the [Apache 2.0 License](https://github.com/atlas-outreach-data-tools/atlasopenmagic/blob/main/LICENSE)
Raw data
{
"_id": null,
"home_page": null,
"name": "atlasopenmagic",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "ATLAS, Open Data, Utilities",
"author": null,
"author_email": "ATLAS Collaboration <atlas-outreach-opendata-support@cern.ch>",
"download_url": "https://files.pythonhosted.org/packages/24/ad/3d60dc1a3a8e3acd5f1eee753fa5a00eae8d0f0b9eb2e3b3e37b01d619ef/atlasopenmagic-1.1.0.tar.gz",
"platform": null,
"description": "# Atlas Open Magic \ud83e\ude84\ud83d\udcca\n[](https://github.com/atlas-outreach-data-tools/atlasopenmagic/actions/workflows/test.yml)\n\n\n\n**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.\n\n## **Installation**\nYou can install this package using `pip`.\n\n```bash\npip install atlasopenmagic\n```\nAlternatively, clone the repository and install locally:\n```bash\ngit clone https://github.com/atlas-outreach-data-tools/atlasopenmagic.git\ncd atlasopenmagic\npip install .\n```\n## Quick start\nFirst, import the package:\n```python\nimport atlasopenmagic as atom\n```\nSee the available releases and set to one of the options given by `available_releases()`\n```python\natom.available_releases()\nset_release('2024r-pp')\n```\nCheck in the [Monte Carlo Metadata](https://opendata.atlas.cern/docs/data/for_research/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*:\n```python\nall_metadata = atom.get_metadata('301204')\n```\nIf we only want a specific variable:\n```python\nxsec = atom.get_metadata('301204', 'cross_section')\n```\nTo get the URLs to stream the files for that MC dataset:\n```python\nall_mc = atom.get_urls('301204')\n```\nTo get some data instead, check the available options:\n```python\natom.available_data()\n```\nAnd get the URLs for the one that's to be used:\n```python\nall_mc = atom.get_urls('2016')\n```\n\n## Open Data functions description and usage \n### `available_releases()`\nShows the available open data releases keys and descriptions.\n\n**Usage:**\n```python\nimport atlasopenmagic as atom\natom.available_releases()\n```\n### `get_current_release()`\nRetrieves the release that the package is currently set at.\n\n**Usage:**\n```python\nrelease = atom.get_current_release()\nprint(release)\n```\n### `set_release(release)`\nSet 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()`.\n\nArgs:\n- `release`: name of the release to use.\n\n**Usage:**\n```python\natom.set_release('2024r-pp')\n```\n### `get_metadata(key, var)`\nGet metadata information for MC data.\n\nArgs:\n- `key`: Dataset ID.\n- `var`: Variable to retrieve.\n\n**Usage:**\nYou can get a dictionary with all the metadata\n```python\nmetadata = atom.get_metadata('301209')\n```\nOr a single variable\n```python\nxsec = atom.get_metadata('301209', 'cross_section')\n```\nThe 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`.\n\nThe keys to be used for research data are the Dataset IDs found in the [Monte Carlo Metadata](https://opendata.atlas.cern/docs/data/for_research/metadata)\n\n### `get_urls(key, skim, protocol)`\nRetrieves the list of URLs corresponding to a given key.\n\nArgs:\n- `key`: Dataset ID.\n- `skim`: Skim for the dataset. This parameter is only taken into account when using the `2025e-13tev-beta` release.\n- `protocol`: protocol for the URLs. Options: 'root' and 'https'.\n\n**Usage:**\n```python\nurls = atom.get_urls('12345', protocol='root')\n```\n### `available_data()`\nRetrieves the list of keys for the data available for a scope/release.\n\n**Usage:**\n```python\natom.available_data()\n```\n### \u2757**DEPRECATED** `get_urls_data(data_key, protocol)`\n \n*Please use `get_urls(key, skim='noskim', protocol=protocol)` instead.*\n\nRetrieves the list of URLs corresponding to one of the keys listed by `available_data()`.\n\nArgs:\n- `data_key` : For non-beta releases (e.g. '2015', '2016', etc.), the data key to look up.\n- `skim` : Only for the 2025e-13tev-beta release: the skim name to look up.\n\n**Usage:**\n```python\ndata = get_urls_data(data_key='2016', protocol='https')\n```\n## Notebooks utilities description and usage \n### `install_from_environment(*packages, environment_file)`\nInstall specific packages listed in an `environment.yml` file via pip.\n\nArgs:\n- `*packages`: Package names to install (e.g., 'coffea', 'dask').\n- `environment_file`: Path to the environment.yml file. If None, defaults to [the environment file for the educational resources](https://github.com/atlas-outreach-data-tools/notebooks-collection-opendata/blob/master/binder/environment.yml).\n\n**Usage:**\n```python\nimport atlasopenmagic as atom\natom.install_from_environment(\"coffea\", \"pandas\", environment_file=\"./myfile.yml\")\n```\n\n### `build_dataset(samples_defs, skim='noskim', protocol='https')`\nBuild a dict of data and / or MC samples URLs.\n \nArgs:\n- `samples_defs`: Dictionary with DIDs and optional color: `{ sample_name: {'list': [...urls...], 'color': ...}, \u2026 }`\n- `skim` : The MC skim tag (only meaningful in the 2025e-13tev-beta release)\n- `protocol` : Protocol to use for URLs.\n\n**Usage:**\n```python\nimport atlasopenmagic as atom\natom.set_release('2025e-13tev-beta')\nsamples_defs = {\n r'Data': {'dids': [\"data\"], 'color': 'red'},\n r'Background $t\\bar t$': {'dids': [410470], 'color': 'yellow'},\n r'Background $V+$jets': {'dids': [700335,700336,700337], 'color': 'orange'},\n r'Background Diboson': {'dids': [700488,700489,700490,700491],'color': 'green'},\n r'Background $ZZ^{*}$': {'dids': [700600,700601], 'color': '#ff0000'},\n r'Signal ($m_H$=125\u2009GeV)': {'dids': [345060,346228], 'color': '#00cdff'},\n}\n\nmc_samples = atom.build_dataset(samples_defs, skim='2bjets', protocol='https')\n```\n\n## Contributing\nContributions are welcome! To contribute:\n\n1. Fork the repository.\n2. Create a new branch (`git checkout -b feature-name`).\n3. Commit your changes (`git commit -am 'Add some feature'`).\n4. Push to the branch (`git push origin feature-name`).\n5. Create a Pull Request.\n\nPlease ensure all tests pass before submitting a pull request (just run `pytest` from the main directory of the package).\n\n## License\nThis project is licensed under the [Apache 2.0 License](https://github.com/atlas-outreach-data-tools/atlasopenmagic/blob/main/LICENSE)\n",
"bugtrack_url": null,
"license": null,
"summary": "A utility package for retrieving ATLAS open data URLs and metadata.",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://opendata.atlas.cern/",
"Repository": "https://github.com/atlas-outreach-data-tools/atlasopenmagic"
},
"split_keywords": [
"atlas",
" open data",
" utilities"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "30b62d0ffa8737a03e99d482f19b49c00defa6aa2dbe4efce3f650210293a3b4",
"md5": "f985108357dbc2c49efbf0eb016fd430",
"sha256": "a42d41d86f75e3033e43b4b4d6eea3ca260cdcb9e8418188942044cba05bdbe4"
},
"downloads": -1,
"filename": "atlasopenmagic-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f985108357dbc2c49efbf0eb016fd430",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 15941,
"upload_time": "2025-07-24T21:51:31",
"upload_time_iso_8601": "2025-07-24T21:51:31.942895Z",
"url": "https://files.pythonhosted.org/packages/30/b6/2d0ffa8737a03e99d482f19b49c00defa6aa2dbe4efce3f650210293a3b4/atlasopenmagic-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "24ad3d60dc1a3a8e3acd5f1eee753fa5a00eae8d0f0b9eb2e3b3e37b01d619ef",
"md5": "f87b0c78e88bfefa26dfe6b2091ef600",
"sha256": "9cb8c98c170f472e46330d74471bd20d6ef662df8e91b509ae9b6871144041db"
},
"downloads": -1,
"filename": "atlasopenmagic-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "f87b0c78e88bfefa26dfe6b2091ef600",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 15412,
"upload_time": "2025-07-24T21:51:33",
"upload_time_iso_8601": "2025-07-24T21:51:33.551573Z",
"url": "https://files.pythonhosted.org/packages/24/ad/3d60dc1a3a8e3acd5f1eee753fa5a00eae8d0f0b9eb2e3b3e37b01d619ef/atlasopenmagic-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-24 21:51:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "atlas-outreach-data-tools",
"github_project": "atlasopenmagic",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "atlasopenmagic"
}
