---
title: "Data Dictionary"
vignette: >
  %\VignetteIndexEntry{data-dictionary}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
knitr:
  opts_chunk:
    collapse: true
    comment: '#>'
    warning: false
    message: false
---

<style>
table {
    font-size: 0.8em;
}
</style>

This vignette defines every column of every dataset shipped with `metrosp`. The [Metro Demand Data](https://viniciusoike.github.io/metrosp/articles/metro-demand-data.html) article covers the same datasets at length, with coverage windows by line, known source defects, and the conventions behind the numbers.

# Overview

The package ships four demand datasets. Two measure passengers at the line level, and two at the station level.

| Dataset | Description | Unit | Time span | Frequency |
|------------|------------|------------|------------|------------|
| `line_entries_monthly` | Passenger entries, measured at the station turnstiles, aggregated by day-type metrics. | Passengers | 2012--2026 | Monthly |
| `line_transported_monthly` | Passengers transported, measured at the turnstiles plus transfers between lines at interchange stations. | Passengers | 2012--2026 | Monthly |
| `station_transported_monthly` | Average business day passengers transported per station, aggregated by month. | Passengers | 2012--2026 | Monthly |
| `station_entries_daily` | Daily passenger entries at each station. | Passengers | 2012--2026 | Daily |
: Demand datasets

A **passenger entry** (*entrada de passageiros*) is a passenger who crossed the station's turnstile gates (*linha de bloqueios*). A **transported passenger** (*passageiro transportado*) is one who boarded a train on that line, whether through a turnstile or by transferring from another line at an interchange station, so transported counts are always equal to or greater than entry counts.

All four datasets count individual passengers. `line_transported_monthly` covers Line 4 from 2012 and Line 5 only through August 2018; `station_transported_monthly` covers Line 5 only through July 2018.

Four further datasets support analysis. `rail_lines` and `rail_stations` carry
route and station geometries; `calendar_spo` and `metro_colors` are lookup
tables.

## Data vintage

The bundled datasets are a fixed snapshot, current through July 2026. The snapshot moves when the column schema changes or when a release deliberately carries new data, never because new months were published upstream, so results computed from a given package version stay reproducible.

`read_metro_demand()` reads the most recently published data instead, from the rolling `data-latest` GitHub release the pipeline writes on every run.

```r
library(metrosp)

# Latest published data
entrance <- read_metro_demand("line_entries_monthly")

# The month's published batch
entrance_sep <- read_metro_demand("line_entries_monthly", vintage = "2026-09")
```

Columns are identical across sources, so everything below applies to both the bundled snapshot and the published data.

# Data producers

Three producers stand behind these datasets.

| Dataset | Granularity | Producer | Line coverage |
|---------------|---------------|---------------|---------------|
| `line_entries_monthly` | line $\times$ month $\times$ metric | METRO + Dataverse | All |
| `line_transported_monthly` | line $\times$ month $\times$ metric | METRO + Dataverse | Lines 1, 2, 3, 4, 5, and 15 |
| `station_transported_monthly` | station $\times$ month | METRO + Dataverse | Lines 1, 2, 3, 4, 5 (to Jul 2018), and 15 |
| `station_entries_daily` | station $\times$ day | METRO + Dataverse | All |
| `rail_lines` | line (spatial) | GeoSampa | All |
| `rail_stations` | station (spatial) | GeoSampa | All |
: Producer and granularity by dataset

**METRO SP transparency portal.** The Companhia do Metropolitano de São Paulo publishes monthly demand reports at its [transparency portal](https://transparencia.metrosp.com.br/dataset/demanda), covering Lines 1, 2, 3, 15, and Line 5 through July 2018. Values are reported in thousands.

**Insper Dataverse.** Line 4 (ViaQuatro) and Line 5 from August 2018 (ViaMobilidade) come from the [Insper Dataverse](https://doi.org/10.60873/FK2/UTGQ0I), starting January 2012 and August 2018 respectively. Counts are not rounded to the nearest thousand, so the pipeline multiplies METRO values by 1,000 before combining the two.

**GeoSampa.** Line and station geometries come from [GeoSampa](https://geosampa.prefeitura.sp.gov.br/), the City of São Paulo's open geospatial platform. Both currently operating and planned infrastructure are included.

**Station identity.** `station_id` identifies a physical station complex,
while `station_name` retains the official name used by each station member.
Complex membership is maintained in a committed crosswalk from official
network sources; it is not inferred from name similarity or distance. Thus
Consolação and Paulista retain different names but share one `station_id`.

The term *producer* is deliberate. Combining these sources takes substantial cleaning, and the pipeline that does it lives in the package's [GitHub repository](https://github.com/viniciusoike/metrosp/tree/main/data-raw).

# Demand datasets

## `line_entries_monthly`

Monthly passenger entries by metro line and day-type metric, in individual passengers.

| Column | Type | Description |
|------------------------|------------------------|------------------------|
| `date` | Date | First day of the month |
| `year` | integer | Calendar year |
| `line_number` | integer | Line identifier (1, 2, 3, 4, 5, or 15) |
| `line_name` | character | Line color in English |
| `line_name_pt` | character | Line color in Portuguese |
| `metric` | character | Metric code: `total`, `mdu`, `msa`, `mdo`, `max` |
| `metric_name` | character | Metric label in English |
| `metric_name_pt` | character | Metric label in Portuguese |
| `value` | numeric | Passenger count |
: `line_entries_monthly` columns

The `total`, `mdu`, `msa`, and `mdo` metrics cannot be summed into a clean network total across operators: METRO line entries include transfers arriving from Lines 4 and 5, while Lines 4 and 5 count turnstiles only. The `max` metric cannot be summed either: individual lines may peak on different days.

### Day-type metrics

METRO breaks each month into five metrics, shared by `line_entries_monthly` and `line_transported_monthly`.

| Code    | English                       | Portuguese           |
|---------|-------------------------------|----------------------|
| `total` | Total passengers in the month | Total                |
| `mdu`   | Average on business days      | Média dos Dias Úteis |
| `msa`   | Average on Saturdays          | Média dos Sábados    |
| `mdo`   | Average on Sundays            | Média dos Domingos   |
| `max`   | Daily peak                    | Máxima Diária        |
: Metric definitions

## `line_transported_monthly`

Monthly passengers transported by metro line and day-type metric.

| Column | Type | Description |
|------------------------|------------------------|------------------------|
| `date` | Date | First day of the month |
| `year` | integer | Calendar year |
| `line_number` | integer | Line identifier (1, 2, 3, 4, 5, or 15) |
| `line_name` | character | Line color in English |
| `line_name_pt` | character | Line color in Portuguese |
| `metric` | character | Metric code: `total`, `mdu`, `msa`, `mdo`, `max` |
| `metric_name` | character | Metric label in English |
| `metric_name_pt` | character | Metric label in Portuguese |
| `value` | numeric | Passengers transported |
: `line_transported_monthly` columns

Transported counts cannot be summed into a unique network count: a journey using multiple lines is counted once on each line.

## `station_transported_monthly`

Monthly average weekday passengers transported per station. Only the weekday average is available at the station level; `line_transported_monthly` carries all five metrics at the line level. Grouping by `station_id` gives boardings across a complex's platforms, not people entering it. Line 5 covers January 2016–July 2018 only.

| Column          | Type      | Description                            |
|-----------------|-----------|----------------------------------------|
| `date`          | Date      | First day of the month                 |
| `year`          | integer   | Calendar year                          |
| `line_number`   | integer   | Line identifier                        |
| `station_id` | character | Stable, opaque physical-station identifier |
| `station_name`  | character | Full station name                      |
| `line_name`     | character | Line color in English                  |
| `line_name_pt`  | character | Line color in Portuguese               |
| `metric` | character | Metric code, always `mdu` |
| `metric_name` | character | Metric label in English |
| `metric_name_pt` | character | Metric label in Portuguese |
| `value` | numeric | Average weekday (business day) transported passengers |
: `station_transported_monthly` columns

## `station_entries_daily`

Daily passenger entries at each station: turnstile entries plus transfers arriving from other operators, excluding transfers between METRO lines. Monthly station sums usually match the line's `total` in `line_entries_monthly`; when they differ, the gap is a fraction of a percent.

| Column | Type | Description |
|------------------------|------------------------|------------------------|
| `date` | Date | Date of observation |
| `year` | integer | Calendar year |
| `line_number` | integer | Line identifier |
| `station_id` | character | Stable, opaque physical-station identifier |
| `station_name` | character | Full station name |
| `station_code` | character | Three-letter METRO abbreviation (`NA` for Lines 4--5) |
| `line_name` | character | Line color in English |
| `line_name_pt` | character | Line color in Portuguese |
| `value` | numeric | Daily passenger entries |
: `station_entries_daily` columns

# Spatial datasets

`rail_lines` and `rail_stations` are `sf` objects in WGS 84 (EPSG:4326). Both cover METRO SP and CPTM commuter rail, operating and planned.

## `rail_lines`

| Column | Type | Description |
|------------------------|------------------------|------------------------|
| `line_number` | integer | Official line number |
| `line_name` | character | Line color in English |
| `line_name_pt` | character | Line color in Portuguese |
| `company_name` | character | Operator (Metrô, ViaQuatro, ViaMobilidade, CPTM) |
| `type` | character | `"metro"` (underground) or `"train"` (CPTM commuter rail) |
| `status` | character | `"current"` (operating) or `"future"` (planned) |
| `geom` | LINESTRING | Route geometry |
: `rail_lines` columns

## `rail_stations`

| Column         | Type      | Description               |
|----------------|-----------|---------------------------|
| `station_id` | character | Stable, opaque physical-station identifier |
| `station_name` | character | Station name (title case) |
| `station_code` | character | Three-letter METRO abbreviation when available |
| `line_number`  | integer   | Line number               |
| `line_name`    | character | Line color in English     |
| `line_name_pt` | character | Line color in Portuguese  |
| `company_name` | character | Operator                  |
| `type`         | character | `"metro"` or `"train"`    |
| `status`       | character | `"current"` or `"future"` |
| `geom`         | POINT     | Station location          |
: `rail_stations` columns

Transfer stations such as Sé, Paraíso, and Ana Rosa appear once per line they serve.

# Reference datasets

## `calendar_spo`

Daily calendar for the city of São Paulo, 2012--2030, flagging national, state, and municipal holidays. Join on `date` to build business-day aggregates from `station_entries_daily`.

| Column | Type | Description |
|------------------------|------------------------|------------------------|
| `date` | Date | Calendar date |
| `year` | integer | Calendar year |
| `weekday` | integer | Day of week, 1 = Sunday through 7 = Saturday |
| `is_weekend` | logical | `TRUE` for Saturdays and Sundays |
| `is_holiday` | logical | `TRUE` when the date is a gazetted holiday |
| `is_business_day` | logical | `TRUE` when the date is neither a weekend nor a holiday |
| `holiday_name` | character | Holiday name in Portuguese, `NA` otherwise |
| `holiday_scope` | character | `"national"`, `"state"`, or `"municipal"` |
| `is_optional_holiday` | logical | `TRUE` for optional holidays, such as Carnaval Monday |
| `is_long_weekend` | logical | `TRUE` when a holiday falls on a Monday, Tuesday, Thursday, or Friday |
: `calendar_spo` columns

## `metro_colors`

Named character vector of the official hex colors for the six lines with ridership data. Names are the English line colors, so `metro_colors["Blue"]` returns `"#171796"`. It pairs directly with `ggplot2::scale_color_manual()`.

| Name | Hex |
|----------|-----------|
| `Blue` | `#171796` |
| `Green` | `#007A5E` |
| `Red` | `#ED2E38` |
| `Yellow` | `#FFD525` |
| `Lilac` | `#874ABF` |
| `Silver` | `#8F8F8C` |
: `metro_colors` values

# Citation

These datasets are heavily processed and curated, so cite the package alongside the original producers. Run `citation("metrosp")` for the entry.