Metadata-Version: 2.4
Name: EmpireStateRunUp
Version: 2026.1.1
Summary: Collection of scripts to analyze the results of the Empire State Run Up race
Author-email: Jose Vicente Nunez <kodegeek.com@protonmail.com>
Keywords: running,race,empire state,tower racing
Classifier: Environment :: Console
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3.11
Classifier: Intended Audience :: End Users/Desktop
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas==2.2.3
Requires-Dist: textual==7.5.0
Requires-Dist: textual-serve==1.1.3
Requires-Dist: rich==14.3.2
Requires-Dist: numpy==1.26.4
Requires-Dist: matplotlib==3.10.8
Requires-Dist: tomlkit==0.14.0
Requires-Dist: uv
Provides-Extra: lint
Requires-Dist: ruff==0.15.0; extra == "lint"
Requires-Dist: yamllint==1.38.0; extra == "lint"
Provides-Extra: dev
Requires-Dist: textual-dev==1.8.0; extra == "dev"
Requires-Dist: uv==0.11.32; extra == "dev"
Dynamic: license-file

# Empire State Run Up

[![Downloads](https://static.pepy.tech/badge/EmpireStateRunUp)](https://pepy.tech/project/EmpireStateRunUp)

![empire_state_runup.png](images/empire_state_runup.png)

![ESRU browser](images/esru_browser.png)

Hello. I wrote an application to analyse the results of the 'Empire State Run Up', 2013 edition, after I ran the race.

Here you will find my code.

## If you just want to install it

See the previous section called 'Packaging', and then install it on your virtual environment:

```shell
uv build
uv pip install dist/empirestaterunup-2025.1.2-py3-none-any.whl
```

There are 4 scripts that you can run:

* esru_numbers
* esru_outlier
* esru_browser
* esru_plot

If you have uvx, you can run any of them like this:

```shell
uvx --from EmpireStateRunUp esru_numbers
uvx --from EmpireStateRunUp esru_outlier
uvx --from EmpireStateRunUp esru_browser
uvx --from EmpireStateRunUp esru_plot
```

If you want to learn more about these programs, please grab a cup of coffe and read the [TUTORIAL](TUTORIAL.md)

## If you are a developer

### Running the code in developer mode

```shell
uv pip install --editable .
uv sync --dev
```

#### Modifying the layout without restarting the apps

For example, playing with the 'esru_outlier' application:

```shell
. ~/virtualenv/EmpireStateRunUp/bin/activate
pip install textual-dev
# On another terminal: . ~/virtualenv/EmpireStateRunUp/bin/activate && textual console
textual run --dev empirestaterunup.apps:run_outlier 
```

### Packaging

```shell
uv build
```

### Installation from PiPy

For your user:

```shell
uv pip install EmpireStateRunUp
```

#### Country codes

I used the files generated by the [ISO-3166-Countries-with-Regional-Codes
](https://github.com/lukes/ISO-3166-Countries-with-Regional-Codes/tree/master) for the flag lookup, using [Regional indicator symbol](https://en.wikipedia.org/wiki/Regional_indicator_symbol).

Notes: Data from the 2025 race is full of errors. Whoever entered the data decided than things like not populating the country of origin was correct:

```json
{"name": "Alessandro Manrique", "bib": "377", "age": 20, "country": "US", "locality": "Mexico", "gender": "M", "state": "Wisconsin", "racer_has_finished": true, "split_data": [{"name": "Full Course", "number": 1, "time_ms": 1077000, "distanc    e_m": 320, "time_with_penalties_ms": 1077000, "gun_time_ms": {"timeInMillis": 2769000, "timeUnit": "m"}, "interval_full": true}, {"name": "20th Floor", "number": 2, "time_ms": 209000, "distance_m": 61, "time_with_penalties_ms": 209000, "gun_    time_ms": {"timeInMillis": 1900000, "timeUnit": "m"}, "interval_full": false}, {"name": "65th Floor", "number": 3, "time_ms": 785000, "distance_m": 229, "time_with_penalties_ms": 785000, "gun_time_ms": {"timeInMillis": 2476000, "timeUnit": "    m"}, "interval_full": false}]}
```

I did not want to spend an long time fixing this, so first extracted all localities with some jq magic:

```shell
jq -r '[.locality | ascii_downcase]|.[]' empirestaterunup/results-2025.jsonl|sort -u
albany
albuquerque
alexandria
altamonte
ames
angier
armonk
astoria
athens
aventura
albany
albuquerque
alexandria
altamonte
ames
angier
armonk
astoria
athens
aventura
...
```

Next, using an AI LLM, I tried to use a reverse lookup of the country 2 letter ISO code with the locality, all in lowercase. Then wrote a small script to "fix" the country from the original dowloaded race results.
For ambiguous locations I assumed the country was US, as the majority of racers from 2023-2024 where from this country.

```toml
[berkeley]
alpha-2 = "US"

[berlin]
alpha-2 = "DE"

[bethel]
alpha-2 = "US"

[bilbao]
alpha-2 = "ES"
```

## Tutorial

Make sure you check the [tutorial](TUTORIAL.md). It explains how this project got started, as well showcases features of the applications.

## Running in server mode

The applications now support running in web server mode. To enable:

```shell
(EmpireStateRunUp) [josevnz@dmaf5 EmpireStateRunUp]$ esru_server --help
usage: esru_server [-h] --application {esru_numbers,esru_outlier,esru_browser} [--port PORT] [--debug] [results ...]

Browse user results

positional arguments:
  results               Race results.

options:
  -h, --help            show this help message and exit
  --application {esru_numbers,esru_outlier,esru_browser}
                        Applications that can run in server mode: ['esru_numbers', 'esru_outlier', 'esru_browser']
  --port PORT           Default port (8000)
  --debug               Enable debug mode

```

```shell
esru_server --application esru_numbers

# Or if you have an external results file:

sru_server --application esru_browser empirestaterunup/results-2023.jsonl
```

## Getting latest race results

I used [athlinks-races](https://pypi.org/project/athlinks-races/) to parse the race results. This is an example of a scrapping session:

```shell
uvx --from athlinks_races athlinks_races_cli --metadata_rpt /home/josevnz/EmpireStateBuildingRunUp/empirestaterunup/metadata-2025.json --athletes_rpt /home/josevnz/EmpireStateBuildingRunUp/empirestaterunup/results-2025.jsonl --format jsonlines --race_url https://www.athlinks.com/event/382111/results/Event/1124263/Results
uvx --from athlinks_races athlinks_races_cli --metadata_rpt /home/josevnz/EmpireStateBuildingRunUp/empirestaterunup/metadata-2024.json --athletes_rpt /home/josevnz/EmpireStateBuildingRunUp/empirestaterunup/results-2024.jsonl --format jsonlines --race_url https://www.athlinks.com/event/382111/results/Event/1093108/Results
uvx --from athlinks_races athlinks_races_cli --metadata_rpt /home/josevnz/EmpireStateBuildingRunUp/empirestaterunup/metadata-2023.json --athletes_rpt /home/josevnz/EmpireStateBuildingRunUp/empirestaterunup/results-2023.jsonl --format jsonlines --race_url https://www.athlinks.com/event/382111/results/Event/1062909/Results
```
