Atari 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

pip install atarihns

Quick Start

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:

Random: -20.7
Human: 14.6
HNS: 1.011

API Usage

Import from the package root:

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

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:

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

Where:

Interpretation:

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:

from atarihns import calculate_hns

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

Use an alias in evaluation code:

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.

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:

@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:

@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:

@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.