Metadata-Version: 2.4
Name: atarihns
Version: 1.0.1
Summary: A helper to calculate human normalized score for different atari environments efficiently and easily.
Author-email: Taha Shieenavaz <tahashieenavaz@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Taha Shieenavaz
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/tahashieenavaz/atarihns
Project-URL: Repository, https://github.com/tahashieenavaz/atarihns
Project-URL: Documentation, https://github.com/tahashieenavaz/atarihns#readme
Keywords: reinforcement learning,atari,human normalized score,hns score
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Atari HNS

[![PyPI](https://img.shields.io/pypi/v/atarihns?style=flat-square&label=PyPI)](https://pypi.org/project/atarihns/)
[![Python](https://img.shields.io/pypi/pyversions/atarihns?style=flat-square&label=Python)](https://pypi.org/project/atarihns/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)
[![Zero dependencies](https://img.shields.io/badge/dependencies-zero-2ea44f?style=flat-square)](pyproject.toml)
[![Atari HNS](https://img.shields.io/badge/Atari-HNS-ff6f00?style=flat-square)](#human-normalized-score-hns)

Small, dependency-free Python helper for computing Atari human-normalized score
(HNS) from published random-agent and human baselines.

`atarihns` keeps the benchmark math out of your experiment code: pass an Atari
environment name and an agent score, get the normalized score used across DQN
and Atari reinforcement-learning papers.

## Installation

```bash
pip install atarihns
```

## Quick Start

```python
from atarihns import calculate_hns, get_human_score, get_random_score

environment = "Pong-v5"
agent_score = 15.0

random_score = get_random_score(environment)
human_score = get_human_score(environment)
hns = calculate_hns(environment, agent_score)

print(f"Random: {random_score}")
print(f"Human: {human_score}")
print(f"HNS: {hns:.3f}")
```

Output:

```text
Random: -20.7
Human: 14.6
HNS: 1.011
```

## API Usage

Import from the package root:

```python
from atarihns import calculate_hns
from atarihns import get_hns
from atarihns import get_human_score
from atarihns import get_random_score, hns
```

| Function | Returns | Example |
| --- | --- | --- |
| `get_random_score(environment_name: str) -> float` | Published random-agent baseline. | `get_random_score("Breakout-v5")` |
| `get_human_score(environment_name: str) -> float` | Published human baseline. | `get_human_score("Breakout-v5")` |
| `calculate_hns(environment_name: str, agent_score: float) -> float` | Human-normalized score as a ratio. | `calculate_hns("Breakout-v5", 42.0)` |
| `get_hns(environment_name: str, agent_score: float) -> float` | Alias for `calculate_hns`. | `get_hns("pong", 15.0)` |
| `hns(environment_name: str, agent_score: float) -> float` | Alias for `calculate_hns`. | `hns("ALE/Pong-v5", 15.0)` |

Environment names may be passed as ALE-style Gymnasium IDs such as
`"Pong-v5"`, with an `ALE/` prefix such as `"ALE/Pong-v5"`, or with supported
lowercase aliases such as `"pong"`.

Unknown environment names raise `RuntimeError`.

## Human-Normalized Score (HNS)

HNS measures where an agent score lands between a random policy and a human
baseline for the same Atari environment:

```math
HNS = \frac{S_{agent} - S_{random}}{S_{human} - S_{random}}
```

Where:

<div align="center">

| Symbol | Meaning |
| --- | --- |
| `S_agent` | Score achieved by your agent. |
| `S_random` | Published random-agent baseline for the environment. |
| `S_human` | Published human baseline for the environment. |

</div>

Interpretation:

<div align="center">

| HNS value | Meaning |
| --- | --- |
| `0.0` | Random-agent level. |
| `1.0` | Human-level score. |
| `> 1.0` | Above the human baseline. |
| `< 0.0` | Below the random-agent baseline. |

</div>

This package returns HNS as a ratio. Multiply by `100` if you need the
percentage form commonly shown in benchmark tables.

## Examples

Use the direct API:

```python
from atarihns import calculate_hns

score = calculate_hns("Breakout-v5", 42.0)
print(f"{score:.2%}")  # percentage display
```

Use an alias in evaluation code:

```python
from atarihns import get_hns

results = {
    "pong": get_hns("pong", 15.0),
    "breakout": get_hns("Breakout-v5", 42.0),
    "seaquest": get_hns("ALE/Seaquest-v5", 1800.0),
}
```

## Available Games

The package includes baselines for the following Atari games. Environment IDs
may also be passed with an `ALE/` prefix, such as `ALE/Pong-v5`.

<div align="center">

| Game | Environment ID | Alias |
| :---: | :---: | :---: |
| Alien | `Alien-v5` | `alien` |
| Amidar | `Amidar-v5` | `amidar` |
| Assault | `Assault-v5` | `assault` |
| Asterix | `Asterix-v5` | `asterix` |
| Asteroids | `Asteroids-v5` | `asteroids` |
| Atlantis | `Atlantis-v5` | `atlantis` |
| BankHeist | `BankHeist-v5` | `bankheist` |
| BattleZone | `BattleZone-v5` | `battlezone` |
| BeamRider | `BeamRider-v5` | `beamrider` |
| Berzerk | `Berzerk-v5` | `berzerk` |
| Bowling | `Bowling-v5` | `bowling` |
| Boxing | `Boxing-v5` | `boxing` |
| Breakout | `Breakout-v5` | `breakout` |
| Centipede | `Centipede-v5` | `centipede` |
| ChopperCommand | `ChopperCommand-v5` | `choppercommand` |
| CrazyClimber | `CrazyClimber-v5` | `crazyclimber` |
| Defender | `Defender-v5` | `defender` |
| DemonAttack | `DemonAttack-v5` | `demonattack` |
| DoubleDunk | `DoubleDunk-v5` | `doubledunk` |
| Enduro | `Enduro-v5` | `enduro` |
| FishingDerby | `FishingDerby-v5` | `fishingderby` |
| Freeway | `Freeway-v5` | `freeway` |
| Frostbite | `Frostbite-v5` | `frostbite` |
| Gopher | `Gopher-v5` | `gopher` |
| Gravitar | `Gravitar-v5` | `gravitar` |
| Hero | `Hero-v5` | `hero` |
| IceHockey | `IceHockey-v5` | `icehockey` |
| Jamesbond | `Jamesbond-v5` | `jamesbond` |
| Kangaroo | `Kangaroo-v5` | `kangaroo` |
| Krull | `Krull-v5` | `krull` |
| KungFuMaster | `KungFuMaster-v5` | `kungfumaster` |
| MontezumaRevenge | `MontezumaRevenge-v5` | `montezumarevenge` |
| MsPacman | `MsPacman-v5` | `mspacman` |
| NameThisGame | `NameThisGame-v5` | `namethisgame` |
| Phoenix | `Phoenix-v5` | `phoenix` |
| Pitfall | `Pitfall-v5` | `pitfall` |
| Pong | `Pong-v5` | `pong` |
| PrivateEye | `PrivateEye-v5` | `privateeye` |
| Qbert | `Qbert-v5` | `qbert` |
| Riverraid | `Riverraid-v5` | `riverraid` |
| RoadRunner | `RoadRunner-v5` | `roadrunner` |
| Robotank | `Robotank-v5` | `robotank` |
| Seaquest | `Seaquest-v5` | `seaquest` |
| Skiing | `Skiing-v5` | `skiing` |
| Solaris | `Solaris-v5` | `solaris` |
| SpaceInvaders | `SpaceInvaders-v5` | `spaceinvaders` |
| StarGunner | `StarGunner-v5` | `stargunner` |
| Surround | `Surround-v5` | `surround` |
| Tennis | `Tennis-v5` | `tennis` |
| TimePilot | `TimePilot-v5` | `timepilot` |
| Tutankham | `Tutankham-v5` | `tutankham` |
| UpNDown | `UpNDown-v5` | `upndown` |
| Venture | `Venture-v5` | `venture` |
| VideoPinball | `VideoPinball-v5` | `videopinball` |
| WizardOfWor | `WizardOfWor-v5` | `wizardofwor` |
| YarsRevenge | `YarsRevenge-v5` | `yarsrevenge` |
| Zaxxon | `Zaxxon-v5` | `zaxxon` |

</div>

## Baseline Data

Baseline scores are stored in `atarihns.constants.ATARI_SCORES` as
`(random_score, human_score)` pairs. The table follows the standard Atari
benchmark convention used by DQN-style evaluation.

## Citation

If this package helps your work, cite the repository:

```bibtex
@software{shieenavaz2025atarihns,
  author = {Shieenavaz, Taha},
  title = {atarihns: Human-normalized scores for Atari environments},
  year = {2025},
  url = {https://github.com/tahashieenavaz/atarihns},
  version = {0.0.18},
  license = {MIT}
}
```

For the original DQN Atari benchmark paper:

```bibtex
@article{mnih2013playing,
  title = {Playing Atari with Deep Reinforcement Learning},
  author = {Mnih, Volodymyr and Kavukcuoglu, Koray and Silver, David and Graves, Alex and Antonoglou, Ioannis and Wierstra, Daan and Riedmiller, Martin},
  journal = {arXiv preprint arXiv:1312.5602},
  year = {2013},
  url = {https://arxiv.org/abs/1312.5602}
}
```

The canonical Nature DQN article is also commonly cited for Atari
human-normalized evaluation:

```bibtex
@article{mnih2015human,
  title = {Human-level control through deep reinforcement learning},
  author = {Mnih, Volodymyr and Kavukcuoglu, Koray and Silver, David and Rusu, Andrei A. and Veness, Joel and Bellemare, Marc G. and Graves, Alex and Riedmiller, Martin and Fidjeland, Andreas K. and Ostrovski, Georg and Petersen, Stig and Beattie, Charles and Sadik, Amir and Antonoglou, Ioannis and King, Helen and Kumaran, Dharshan and Wierstra, Daan and Legg, Shane and Hassabis, Demis},
  journal = {Nature},
  volume = {518},
  number = {7540},
  pages = {529--533},
  year = {2015},
  doi = {10.1038/nature14236}
}
```

## License

MIT. See [LICENSE](LICENSE).
