Package {metrosp}

Type: Package
Title: São Paulo Metro Passenger Demand Data
Version: 2.0.0
Description: Provides passenger demand data for the São Paulo metro system, covering 2012 to 2026. Datasets include monthly passenger entries and transported counts by line, average weekday passengers transported by station, daily station entries, and spatial geometries for metro and commuter train lines and stations. The bundled datasets are a fixed snapshot, so analyses stay reproducible and examples run offline. More recent data is published to 'GitHub' releases as the upstream sources are updated, and read_metro_demand() downloads, caches, and reads it, optionally pinned to a dated monthly batch.
License: MIT + file LICENSE
Encoding: UTF-8
Language: en-US
LazyData: true
Depends: R (≥ 4.0.0)
Imports: cli, jsonlite, tools, utils
Suggests: bizdays, spelling, dataverse, digest, dplyr (≥ 1.2.0), ggplot2, knitr, quarto, rmarkdown, sf, tarchetypes, targets, testthat (≥ 3.0.0), waldo, withr
Config/testthat/edition: 3
RoxygenNote: 7.3.3
URL: https://github.com/viniciusoike/metrosp, https://viniciusoike.github.io/metrosp/
BugReports: https://github.com/viniciusoike/metrosp/issues
VignetteBuilder: quarto
NeedsCompilation: no
Packaged: 2026-10-06 11:38:27 UTC; viniciusreginatto
Author: Vinicius Oike ORCID iD [aut, cre, cph]
Maintainer: Vinicius Oike <viniciusoike@gmail.com>
Repository: CRAN
Date/Publication: 2026-10-06 12:00:02 UTC

São Paulo Holiday and Business-Day Calendar

Description

A daily calendar for São Paulo (city) covering 2012–2030, classifying each date as a holiday or business day. Includes national, state, and municipal holidays in São Paulo, with flags for optional work days (is_optional_holiday) and extended holiday weekends (is_long_weekend).

Usage

calendar_spo

Format

A data frame with one row per day and the following columns:

date

Calendar date (Date).

year

Calendar year (integer).

weekday

Day of week from lubridate::wday(): 1 = Sunday, 2 = Monday, ..., 7 = Saturday (integer).

is_weekend

TRUE for Saturdays and Sundays (logical).

is_holiday

TRUE when the date is a gazetted holiday at any scope (logical).

is_business_day

TRUE when the date is neither a weekend nor a holiday (logical).

holiday_name

Name of the holiday in Portuguese (character). NA on non-holiday dates.

holiday_scope

Scope of the holiday (character). One of "national", "state", or "municipal"; NA on non-holiday dates.

is_optional_holiday

TRUE for holidays that are technically optional at the federal level (Carnaval, Corpus Christi) but observed as holidays in São Paulo (logical).

is_long_weekend

TRUE when a holiday falls on Monday, Tuesday, Thursday, or Friday, creating a potential extended weekend with the adjacent Saturday/Sunday (logical).

Details

The calendar covers the full date range of the station_entries_daily dataset (Lines 4/5 from January 2012) and extends through 2030 for forecasting use.

See Also

station_entries_daily for daily passenger data that can be joined on date.

Passengers Entering Metro SP Stations by Line

Description

Monthly count of passengers entering São Paulo metro stations, aggregated by metro line. Data covers January 2016 through 2026 for Lines 1, 2, 3, and 15; Line 4 from January 2012; Line 5 from January 2016. July 2017 is the one missing month, absent for every line the METRO portal covers. Sourced from the METRO SP transparency portal and the Insper Dataverse.

Usage

line_entries_monthly

Format

A data frame with the following columns:

date

First day of the month (Date).

year

Calendar year (integer).

line_number

Metro line number: 1, 2, 3, 4, 5, or 15 (integer).

line_name

English name of the metro line (character).

line_name_pt

Portuguese name of the metro line (character).

metric

Metric code (character). One of: "total", "mdu", "msa", "mdo", "max".

metric_name

Measurement type in English (character). One of: "Total", "Average on Business Days", "Average on Saturdays", "Average on Sundays", "Daily Peak".

metric_name_pt

Measurement type in Portuguese (character). One of: "Total", "Média dos Dias Úteis", "Média dos Sábados", "Média dos Domingos", "Máxima Diária".

value

Passenger count, in individual passengers (numeric).

Details

Data by source and line:

METRO published January–September 2017 only as PDFs, with no machine-readable equivalent. Those months were transcribed from the reports and reconciled against the published totals. July 2017 has no entrance table at all, because the file METRO published under that name repeats the transported figures. Lines 1, 2, 3, 5, and 15 therefore carry no value for that month; Line 4 comes from the Dataverse and is unaffected.

Summing across lines does not give a clean network total. METRO line entries include transfers arriving from Lines 4 and 5, while Lines 4 and 5 count turnstiles only, so a Line 4 → Line 1 journey counts twice. Do not sum max: individual lines may peak on different days. See the Metro Demand Data article for details: https://viniciusoike.github.io/metrosp/articles/metro-demand-data.html.

Metrics:

Months beyond the last published data point for each line are trimmed during assembly; interior NAs (e.g. operational outages) are preserved.

Data vintage

This dataset is a fixed snapshot, current through July 2026. It ships with the package so examples, vignettes, and offline analysis always have data to hand. The snapshot moves only when the column schema changes or a release deliberately carries new data, not when new months are published upstream.

METRO SP publishes on an irregular schedule and revises already-published years, so the numbers here will drift from the source over time. Freshly rebuilt data is published on every pipeline run at https://github.com/viniciusoike/metrosp/releases.

Source

Companhia do Metropolitano de São Paulo (METRO SP). https://transparencia.metrosp.com.br/dataset/demanda

See Also

line_transported_monthly for transported counts, station_transported_monthly for station-level weekday averages.

Passengers Transported by Metro SP Line

Description

Monthly count of passengers transported by São Paulo metro, aggregated by metro line. Data covers January 2016 through 2026 for Lines 1, 2, 3, and 15; January 2016 through August 2018 for Line 5; and January 2012 through 2026 for Line 4. Sourced from the METRO SP transparency portal and the Insper Dataverse.

Usage

line_transported_monthly

Format

A data frame with the following columns:

date

First day of the month (Date).

year

Calendar year (integer).

line_number

Metro line number: 1, 2, 3, 4, 5, or 15 (integer).

line_name

English name of the metro line (character).

line_name_pt

Portuguese name of the metro line (character).

metric

Metric code (character). One of: "total", "mdu", "msa", "mdo", "max".

metric_name

Measurement type in English (character). One of: "Total", "Average on Business Days", "Average on Saturdays", "Average on Sundays", "Daily Peak".

metric_name_pt

Measurement type in Portuguese (character). One of: "Total", "Média dos Dias Úteis", "Média dos Sábados", "Média dos Domingos", "Máxima Diária".

value

Passengers transported (numeric).

Details

A transported passenger is one who boarded a train on that line, whether through a turnstile or by transferring from another line at an interchange station. METRO's term is passageiros transportados: turnstile entries plus transfers between lines. Transported counts therefore run above entry counts for the same line and month. Do not sum this dataset to estimate unique network passengers: a journey using multiple lines is counted once on each line. See the Metro Demand Data article for details: https://viniciusoike.github.io/metrosp/articles/metro-demand-data.html.

Line 4 (Amarela/ViaQuatro) comes from the Insper Dataverse, January 2012–2026, all five metrics, summing both Bloqueio (turnstile) and Integracao (transfer) boarding types. Line 5 (Lilás) is available from the METRO portal only for January 2016–August 2018: the line was handed over to ViaMobilidade in August 2018 and the portal stopped reporting its transported counts afterwards. The Dataverse feed for Line 5 records turnstiles only, so no transported measure exists for it after the handover. August 2018 covers only the days before the handover: its total is a partial month, and msa and mdo are NA.

METRO SP publishes these counts in thousands of passengers. They are multiplied by 1000 here, so value counts individual passengers like every other demand dataset and carries METRO's rounding to the thousand. Line 4 comes from the Dataverse in individual passengers.

METRO published January–September 2017 only as PDFs, with no machine-readable equivalent. Those months were transcribed from the reports and reconciled against the published totals.

Metrics:

Months beyond the last published data point for each line are trimmed during assembly; interior NAs (e.g. operational outages) are preserved.

Data vintage

This dataset is a fixed snapshot, current through July 2026. It ships with the package so examples, vignettes, and offline analysis always have data to hand. The snapshot moves only when the column schema changes or a release deliberately carries new data, not when new months are published upstream.

METRO SP publishes on an irregular schedule and revises already-published years, so the numbers here will drift from the source over time. Freshly rebuilt data is published on every pipeline run at https://github.com/viniciusoike/metrosp/releases.

Source

Companhia do Metropolitano de São Paulo (METRO SP). https://transparencia.metrosp.com.br/dataset/demanda

See Also

line_entries_monthly for entry counts, station_transported_monthly for station-level weekday averages.

Metro SP Official Line Colors

Description

A named character vector of official hex color codes for the six metro lines operated by METRO SP (Lines 1–3 and 15) and ViaMobilidade (Lines 4 and 5).

Usage

metro_colors

Format

A named character vector of length 6. Names are English color names; values are hex color codes:

Blue

Line 1 — "#171796"

Green

Line 2 — "#007A5E"

Red

Line 3 — "#ED2E38"

Yellow

Line 4 — "#FFD525"

Lilac

Line 5 — "#874ABF"

Silver

Line 15 — "#8F8F8C"

Details

Colors follow official METRO SP and ViaMobilidade branding. Only the six currently operating metro lines are included; CPTM train lines and planned future lines (e.g., Line 6 Orange, Line 17 Gold) are not covered.

See Also

rail_lines for the full line reference (numbers, names, and route geometries).

Inspect cached Metro SP data

Description

Lists the files downloaded by read_metro_demand(). The cache directory is resolved from the metrosp.cache_dir option, then the METROSP_CACHE_DIR environment variable, and finally tools::R_user_dir(). Printing the result also shows the resolved directory.

Usage

metrosp_cache()

## S3 method for class 'metrosp_cache'
print(x, ...)

Arguments

x

A cache listing returned by metrosp_cache().

...

Additional arguments passed to the data-frame print method.

Details

Each read marks its vintage as used. A vintage left unused for 90 days is deleted the next time read_metro_demand() touches the cache.

Value

A data frame with one row per cached file, holding the vintage tag, file name, size in bytes, and modification time. Zero rows when the cache is empty.

x, invisibly.

See Also

metrosp_cache_clear() to remove cached files.

Examples

metrosp_cache()

Delete cached Metro SP data

Description

Delete cached Metro SP data

Usage

metrosp_cache_clear(vintage = NULL)

Arguments

vintage

Vintage to remove, such as "latest" or "2026-09". When NULL, removes every package-managed data-latest or data-YYYY-MM vintage directory. The cache root and unrelated files are preserved.

Value

The number of files removed, invisibly.

See Also

metrosp_cache() to inspect cached files.

Examples

# Point the cache at a temporary directory so the example leaves yours alone.
old <- options(metrosp.cache_dir = tempfile("metrosp-cache"))

metrosp_cache_clear("2026-09")
metrosp_cache_clear()

options(old)

Metro and Train Line Routes

Description

Spatial line geometries for São Paulo metro (METRO SP) and commuter train (CPTM) lines, including both currently operating lines and planned future expansions.

Usage

rail_lines

Format

An sf data frame with LINESTRING geometry (CRS: WGS84 / EPSG:4326) and the following columns:

line_number

Official line number (integer).

line_name

English color name of the line (character).

line_name_pt

Portuguese color name of the line (character).

company_name

Operating company name (character).

type

Either "metro" (METRO SP) or "train" (CPTM) (character).

status

Either "current" (operating) or "future" (planned expansion) (character).

geom

Line route geometry (sfc_LINESTRING).

Details

Requires the sf package to work with spatial features. The distinction between types follows GeoSampa's classification. Broadly, "metro" lines run underground as a subway and "train" lines run above ground as commuter rail, though exceptions exist.

Source

GeoSampa, Prefeitura de São Paulo. https://geosampa.prefeitura.sp.gov.br/

See Also

rail_stations for station point locations.

Metro and Train Station Locations

Description

Spatial point locations for São Paulo metro (METRO SP) and commuter train (CPTM) stations, including both currently operating stations and planned future stations.

Usage

rail_stations

Format

An sf data frame with POINT geometry (CRS: WGS84 / EPSG:4326) and the following columns:

station_id

Stable identifier for the physical station complex (character). Shared across lines and modes; treat as opaque.

station_name

Station name in title case (character).

station_code

Three-letter METRO abbreviation when available (character).

line_number

Line number the station belongs to (integer).

line_name

English color name of the line (character).

line_name_pt

Portuguese color name of the line (character).

company_name

Operating company name (character).

type

Either "metro" (METRO SP) or "train" (CPTM) (character).

status

Either "current" (operating) or "future" (planned expansion) (character).

geom

Station location (sfc_POINT).

Details

Requires the sf package to work with spatial features. The distinction between types follows GeoSampa's classification. Broadly, "metro" lines run underground as a subway and "train" lines run above ground as commuter rail, though exceptions exist.

Source

GeoSampa, Prefeitura de São Paulo. https://geosampa.prefeitura.sp.gov.br/

See Also

rail_lines for line route geometries, station_transported_monthly for passenger data by station.

Read Metro SP demand data

Description

Reads one of the four passenger demand datasets, preferring the most recently published version over the frozen snapshot bundled with the package. Published data lives in the repository's GitHub releases and is rebuilt from the upstream sources on every pipeline run.

Usage

read_metro_demand(
  dataset = c("line_entries_monthly", "line_transported_monthly",
    "station_transported_monthly", "station_entries_daily"),
  source = c("auto", "cache", "remote", "bundled"),
  vintage = "latest",
  cache = TRUE,
  quiet = FALSE
)

Arguments

dataset

Dataset to read. One of "line_entries_monthly", "line_transported_monthly", "station_transported_monthly", or "station_entries_daily".

source

Where to read from.

  • "auto" (default) uses the cache, downloads when it is stale or empty, and falls back to the bundled snapshot with a warning if the download fails. When a stale manifest cannot be refreshed, it reads the cached copy with a warning instead.

  • "cache" reads only what is already on disk and errors otherwise.

  • "remote" downloads and errors if that fails.

  • "bundled" reads the frozen snapshot and never touches the network.

vintage

Which published batch to read. "latest" tracks the rolling release; a year-month string such as "2026-09" reads the last batch published in that month. A month's batch can be republished until the month ends, so a monthly vintage is revisable rather than an exact pin.

cache

Whether to store downloads in the persistent cache. Set to FALSE to use session-temporary storage instead.

quiet

Whether to suppress progress messages.

Details

Only the demand datasets are published separately. The reference datasets (rail_lines, rail_stations, calendar_spo, and metro_colors) do not change with new months, so read them directly.

Each vintage's manifest.json is cached and checked again once it is older than getOption("metrosp.cache_ttl") seconds (six hours by default). This applies to dated vintages too, so a month republished after your first read is picked up; cached assets whose checksum is unchanged are not downloaded again.

Downloads verify the manifest's SHA-256 when the digest package is installed and skip verification otherwise.

Value

A data frame. See line_entries_monthly, line_transported_monthly, station_transported_monthly, and station_entries_daily for the column definitions, which are identical across sources.

See Also

metrosp_cache() and metrosp_cache_clear() for cache management.

Examples

# The bundled snapshot, read without touching the network.
head(read_metro_demand("line_entries_monthly", source = "bundled"))


# Keep this example's downloads out of your persistent cache.
old <- options(metrosp.cache_dir = tempfile("metrosp-cache"))

# The most recently published data, cached between calls.
entrance <- read_metro_demand("line_entries_monthly")

# A monthly vintage, so an analysis can name the batch it used.
entrance_sep <- read_metro_demand(
  "line_entries_monthly",
  vintage = "2026-09"
)

options(old)

Daily Passenger Entries by Metro SP Station

Description

Daily passenger entries at each station in the São Paulo metro system. Data covers January 2012 through 2026 for Line 4 and August 2018 through 2026 for Line 5 (Insper Dataverse), and 2020 through 2026 for Lines 1, 2, 3, and 15 (METRO SP transparency portal).

Usage

station_entries_daily

Format

A data frame with the following columns:

date

Date of observation (Date).

year

Calendar year (integer).

line_number

Metro line number: 1, 2, 3, 4, 5, or 15 (integer).

station_id

Stable identifier for the physical station complex (character). Treat as opaque. An interchange complex keeps one id across the lines that serve it while each line keeps its own official station_name, so group by station_id alone to total a complex.

station_name

Full station name (character).

station_code

Three-letter station abbreviation used internally by METRO SP (character). NA for Lines 4 and 5 (Dataverse source).

line_name

English name of the metro line (character).

line_name_pt

Portuguese name of the metro line (character).

value

Daily passenger entries (numeric).

Details

This is an entries measure — METRO's Entrada de Passageiros por Estação: turnstile entries plus transfers arriving from other operators (CPTM, Line 4, Line 5), 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.

Station coverage and date range by line:

Some stations appear on multiple lines (e.g., Ana Rosa on Lines 1 and 2, Paraíso on Lines 1 and 2, Sé on Lines 1 and 3). These are recorded separately for each line.

Days beyond the last published data point for each line are trimmed during assembly; interior NAs (e.g. operational outages) are preserved.

Data vintage

This dataset is a fixed snapshot, current through July 2026. It ships with the package so examples, vignettes, and offline analysis always have data to hand. The snapshot moves only when the column schema changes or a release deliberately carries new data, not when new months are published upstream.

METRO SP publishes on an irregular schedule and revises already-published years, so the numbers here will drift from the source over time. Freshly rebuilt data is published on every pipeline run at https://github.com/viniciusoike/metrosp/releases.

Source

Companhia do Metropolitano de São Paulo (METRO SP). https://transparencia.metrosp.com.br/dataset/demanda

See Also

station_transported_monthly for monthly weekday averages, line_entries_monthly for monthly line-level totals.

Average Weekday Passengers Transported by Station

Description

Monthly average of weekday (business day) passengers transported for each station in the São Paulo metro system. This is METRO's transported measure — Demanda de Passageiros por Estação: boardings on that line plus transfers from the other lines — not turnstile entries. Summed over a line's stations it usually comes within 2\ mdu in line_transported_monthly. Line 15 station values are rounded to the thousand, and a few source months differ by more, notably Line 1 from February to June 2016. Data covers January 2016 through 2026 for Lines 1, 2, 3, and 15; Line 4 from January 2012; Line 5 from January 2016 through July 2018. Sourced from the METRO SP transparency portal and the Insper Dataverse.

Usage

station_transported_monthly

Format

A data frame with the following columns:

date

First day of the month (Date).

year

Calendar year (integer).

line_number

Metro line number (integer).

station_id

Stable identifier for the physical station complex (character). Treat as opaque. An interchange complex keeps one id across the lines that serve it while each line keeps its own official station_name. Grouping by station_id on this table gives boardings across the complex's platforms, not people entering it.

station_name

Name of the metro station (character).

line_name

English name of the metro line (character).

line_name_pt

Portuguese name of the metro line (character).

metric

Metric code: "mdu" (character).

metric_name

Metric name in English (character).

metric_name_pt

Metric name in Portuguese (character).

value

Average weekday passengers transported (numeric).

Details

Only the weekday average (mdu) metric is available at the station level. For line-level data with all five metrics, see line_transported_monthly. Months beyond the last published data point for each line are trimmed during assembly; interior NAs (e.g. operational outages) are preserved.

Station coverage by line and source:

METRO published January–September 2017 only as PDFs, with no machine-readable equivalent. Those months were transcribed from the reports and reconciled against the published line totals.

February–June 2016 carries a defect in the Line 1 values. Across those five months the station sum runs about 14% below the transported mdu in line_transported_monthly, and the figures are misallocated across stations, with Santa Cruz and Sé too high and São Bento and Portuguesa-Tietê too low. The defect comes from METRO's retroactive publication of 2016 and is not corrected here, so exclude those five months from station-level baselines.

Data vintage

This dataset is a fixed snapshot, current through July 2026. It ships with the package so examples, vignettes, and offline analysis always have data to hand. The snapshot moves only when the column schema changes or a release deliberately carries new data, not when new months are published upstream.

METRO SP publishes on an irregular schedule and revises already-published years, so the numbers here will drift from the source over time. Freshly rebuilt data is published on every pipeline run at https://github.com/viniciusoike/metrosp/releases.

Source

Companhia do Metropolitano de São Paulo (METRO SP). https://transparencia.metrosp.com.br/dataset/demanda

See Also

station_entries_daily for daily station entries, line_transported_monthly for monthly line-level totals.