---
title: "Getting started with olympicAthletes"
output: rmarkdown::html_vignette
description: >
  A tour of the core datasets in olympicAthletes — what they contain,
  how they fit together, and a few starter analyses.
vignette: >
  %\VignetteIndexEntry{Getting started with olympicAthletes}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.align = "center",
  fig.width = 7,
  fig.height = 4.2
)
```

`olympicAthletes` covers every modern Olympic Games from **Athens 1896**
through **Milano-Cortina 2026**. Three core datasets carry all the
information; the rest of the package is convenience subsets of them
(single sports, single Games, pre-counted summaries) built for teaching
examples. This vignette walks through the three core datasets and shows
a few representative analyses.

```{r setup}
library(olympicAthletes)
```

## The three core datasets at a glance

| Dataset            | Rows    | One row per…                            |
|--------------------|--------:|------------------------------------------|
| `olympic_athletes` | 315,094 | (athlete, Games, event) participation    |
| `medal_table`      |   1,929 | (Games, NOC) verified medal totals       |
| `editions`         |      62 | Olympic edition (incl. cancelled Games)  |

`olympic_athletes` is the headline long-format table. `medal_table` and
`editions` are companion tables that make per-team-event medal counting
and edition-level lookups easy without re-aggregating 300k+ rows.
The convenience subsets (e.g. `athletics_athletes`,
`olympic_athletes_2024`, `usa_summer_medals`) are documented in
`help(package = "olympicAthletes")` and keep the same columns as their
parent dataset.

## `olympic_athletes`: athlete-event participations

```{r athletes-glimpse}
data(olympic_athletes)
str(olympic_athletes, give.attr = FALSE, vec.len = 2)
```

A quick sanity check — participations per Games, by season:

```{r athletes-by-year}
tab <- table(olympic_athletes$year, olympic_athletes$season)
tail(tab, 10)
```

### A note on team medals

Medals in `olympic_athletes` are **per-player**: every member of a
gold-winning ice hockey roster has their own `medal = "Gold"` row. It
is the right shape for athlete-level analysis, but it inflates team
counts when you sum naively.

```{r medal-per-player}
# Every roster member of the men's ice hockey gold medal team
# at Beijing 2022 gets a Gold row:
hockey_2022 <- subset(
  olympic_athletes,
  year == 2022 &
    event == "Ice Hockey Men's Ice Hockey" &
    medal == "Gold"
)
nrow(hockey_2022)
```

For headline medal-table totals, use `medal_table` instead.

## `medal_table`: verified per-edition totals

`medal_table` covers every Olympic edition from Athens 1896 through
Milano-Cortina 2026 and uses the IOC per-team-event convention.

```{r medal-table}
data(medal_table)
head(subset(medal_table, year == 2024), 5)
```

Top five NOCs at Paris 2024 by gold count:

```{r paris-top}
paris <- subset(medal_table, year == 2024)
paris <- paris[order(-paris$gold, -paris$total), ]
head(paris[, c("noc", "country", "gold", "silver", "bronze", "total")], 5)
```

## `editions`: metadata for every Games

`editions` includes one row per Olympic edition (62 in total), including
the handful of Games cancelled by the World Wars.

```{r editions}
data(editions)
head(editions[, c("games", "city_local_latin", "city_english", "country",
                  "opening_ceremony", "closing_ceremony",
                  "participants", "medal_events")], 10)
```

Use it to enrich `olympic_athletes` with edition-level facts (host
country, opening date, total medal events) without scraping anything
yourself.

## Provenance recap

- **1896-2016** rows come from
  [rgriff23/Olympic_history](https://github.com/rgriff23/Olympic_history),
  originally scraped from sports-reference.com.
- **2018-2026** rows were scraped from
  [olympedia.org](https://www.olympedia.org/) using the pipeline at
  [ismayc/olympic-moderndive-data](https://github.com/ismayc/olympic-moderndive-data).
- The build script in `data-raw/DATASET.R` reproduces every `.rda` in
  `data/` from the CSVs in `data-raw/`.

See `?olympic_athletes`, `?medal_table`, and `?editions` for full
column-level documentation.