Metadata-Version: 2.4
Name: cleanskate
Version: 0.1.0
Summary: Pandas-friendly access to figure skating scores
Project-URL: Homepage, https://github.com/erleholgersen/cleanskate
Project-URL: Repository, https://github.com/erleholgersen/cleanskate
Project-URL: Issues, https://github.com/erleholgersen/cleanskate/issues
Project-URL: Documentation, https://github.com/erleholgersen/cleanskate#readme
Author: Erle Holgersen
License: MIT License
        
        Copyright (c) 2026 Erle Holgersen
        
        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.
License-File: LICENSE
Keywords: data,figure skating,pandas,sports analytics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Requires-Dist: pandas>=2.2
Requires-Dist: platformdirs>=4.3
Requires-Dist: pyarrow>=16.0
Requires-Dist: requests>=2.32
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: hatchling>=1.26; extra == 'dev'
Requires-Dist: ipython>=9.0; extra == 'dev'
Requires-Dist: matplotlib>=3.10; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: seaborn>=0.13; extra == 'dev'
Requires-Dist: twine>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# ⛸️ cleanskate

`cleanskate` is a Python package for loading figure skating scores as pandas data
frames. The package covers overall results, judge information, program component
scores, and per-element scores for international events from the `2018-2019`
season onward.

The current dataset covers major international events, including:

- Olympics
- Worlds
- Junior Worlds
- Europeans
- Four Continents
- Grand Prix
- Grand Prix Final
- Junior Grand Prix
- much of the Challenger Series

The dataset may be expanded in the future. Feel free to open an issue if you
notice anything missing.

## Installation

```bash
pip install cleanskate
```

For local development:

```bash
pip install -e .
```

## Quick Start

```python
from cleanskate import Dataset

ds = Dataset(version="latest")

events = ds.load_events()
results = ds.load_results()
elements = ds.load_elements()
```

Tables are downloaded automatically on first use and cached locally. You do not
need to call a separate download command.

## Common Filters

All loader filters accept either a single value or a list of values. Lists use
"one of these values" semantics.

```python
from cleanskate import Dataset

ds = Dataset()

worlds_events = ds.load_events(event_series="Worlds")
season_results = ds.load_results(season="2025-2026")
women_segments = ds.load_segments(discipline="Women")
triple_axels = ds.load_elements(attempt_code="3A")

senior_jump_attempts = ds.load_elements(
    event_level="Senior",
    element_family="Jump",
)

non_clean_jumps = ds.load_elements(
    attempt_code=["3A", "4T", "4S"],
    clean_element=False,
)
```

Recommended public filters:

- `season`
- `event_series`
- `event_level`
- `event_label`
- `segment_label`
- `discipline`
- `element_family`
- `attempt_code`
- `clean_element`

Lower-level IDs like `event_id`, `segment_id`, and `result_id` are also
available for power users.

## Local Datasets

You can point `Dataset` at a local directory instead of the hosted snapshot:

```python
from cleanskate import Dataset

ds = Dataset(base_dir="/path/to/local/dataset")
segments = ds.load_segments()
```

`prefetch()` is available if you want to warm the cache explicitly:

```python
ds.prefetch()
```

## Example Notebooks

The repository currently includes:

- [Quick start notebook](https://github.com/erleholgersen/cleanskate/blob/main/examples/quick_start.ipynb)
- [Judge nationality patterns notebook](https://github.com/erleholgersen/cleanskate/blob/main/examples/judge_nationality_patterns.ipynb)

## Documentation

Additional docs:

- [Getting started](https://github.com/erleholgersen/cleanskate/blob/main/docs/getting-started.md)
- [API reference](https://github.com/erleholgersen/cleanskate/blob/main/docs/api-reference.md)
- [Data model](https://github.com/erleholgersen/cleanskate/blob/main/docs/data-model.md)
- [Dataset operations](https://github.com/erleholgersen/cleanskate/blob/main/docs/dataset-operations.md)
- [Dataset changelog](https://github.com/erleholgersen/cleanskate/blob/main/DATASET_CHANGELOG.md)
- [Provenance and citation](https://github.com/erleholgersen/cleanskate/blob/main/docs/provenance.md)
- [Analysis notes](https://github.com/erleholgersen/cleanskate/blob/main/docs/analysis-notes.md)
- [Release process](https://github.com/erleholgersen/cleanskate/blob/main/docs/release-process.md)
- [Release readiness](https://github.com/erleholgersen/cleanskate/blob/main/docs/release-readiness.md)


## Related Work

- [BuzzFeed data parsers](https://github.com/BuzzFeedNews/figure-skating-scores/tree/master)
- [BuzzFeed judge bias analysis](https://www.buzzfeednews.com/article/johntemplon/the-edge)
