Package {aopdata}

Title:	Data from the 'Access to Opportunities Project (AOP)'
Version:	1.2.0
Description:	Download data from the 'Access to Opportunities Project (AOP)'. The 'aopdata' package brings annual estimates of access to employment, health, education and social assistance services by transport mode, as well as data on the spatial distribution of population, jobs, health care, schools and social assistance facilities at a fine spatial resolution for all cities included in the project. More info on the 'AOP' website https://www.ipea.gov.br/acessooportunidades/en/.
URL:	https://ipea.github.io/aopdata/, https://github.com/ipea/aopdata
BugReports:	https://github.com/ipea/aopdata/issues
License:	MIT + file LICENSE
Encoding:	UTF-8
Depends:	R (≥ 4.1.0)
Imports:	cli (≥ 3.0.0), checkmate, curl (≥ 5.0.0), data.table, httr2 (≥ 1.2.0), methods, rlang (≥ 1.0.0), sf (≥ 0.9-3), utils
Suggests:	covr, dplyr (≥ 0.8-3), ggplot2 (≥ 3.3.1), knitr, rmarkdown (≥ 2.30), scales, testthat (≥ 3.1.7), units
VignetteBuilder:	knitr
Config/roxygen2/version:	8.1.0
NeedsCompilation:	no
Packaged:	2026-10-19 03:12:20 UTC; rafap
Author:	Rafael H. M. Pereira [aut, cre], Daniel Herszenhut [aut], Marcus Saraiva [aut], Carlos Kaue Vieira Braga [aut], Diego Bogado Tomasiello [ctb], Joao Bazzo [ctb], Ipea - Institute for Applied Economic Research [cph, fnd]
Maintainer:	Rafael H. M. Pereira <rafa.pereira.br@gmail.com>
Repository:	CRAN
Date/Publication:	2026-10-19 08:40:02 UTC

aopdata: Data from the 'Access to Opportunities Project (AOP)'

Description

Download data from the 'Access to Opportunities Project (AOP)'. The aopdata package brings annual estimates of access to employment, health, education and social assistance services by transport mode, as well as data on the spatial distribution of population, jobs, health care, schools and social assistance facilities at a fine spatial resolution for all cities included in the project. More info on the AOP website https://www.ipea.gov.br/acessooportunidades/en/.

Usage

Please check the vignettes on the website.

Author(s)

Maintainer: Rafael H. M. Pereira rafa.pereira.br@gmail.com (ORCID)

Authors:

• Rafael H. M. Pereira rafa.pereira.br@gmail.com (ORCID)

• Daniel Herszenhut dhersz@gmail.com (ORCID)

• Marcus Saraiva marcus.saraiva@gmail.com (ORCID)

• Carlos Kaue Vieira Braga kaue@kauebraga.dev (ORCID)

Other contributors:

• Diego Bogado Tomasiello diegobt86@gmail.com [contributor]

• Joao Bazzo joao.bazzo@gmail.com [contributor]

• Ipea - Institute for Applied Economic Research [copyright holder, funder]

See Also

Useful links:

• https://ipea.github.io/aopdata/

• https://github.com/ipea/aopdata

• Report bugs at https://github.com/ipea/aopdata/issues

Throw an aopdata error when a checkmate check fails

Description

Throw an aopdata error when a checkmate check fails

Usage

abort_if_invalid(check, arg, call = rlang::caller_env())

Arguments

Value

invisible(TRUE), or an error of class aopdata_error.

Download files in parallel

Description

The only function in the package that downloads data files.

Usage

aop_fetch(urls, paths, progress = FALSE, label = "Downloading files")

Arguments

Value

A character vector with one status per file (see classify_resp()).

Merge land use and access data

Description

Merges landuse and access data

Usage

aop_merge(aop_landuse, aop_access)

Arguments

Value

Returns a data.table with landuse and access data

Build a download request

Description

Build a download request

Usage

aop_request(url)

Arguments

Value

An httr2_request. curl's 10 s connect timeout is kept, a transfer slower than 1 kB/s for 30 s is aborted, and nothing is retried automatically (the mirror is the retry).

Spatial join of AOP data

Description

Merges land use or access data with H3 grid geometries

Usage

aop_spatial_join(aop_df, aop_sf)

Arguments

Value

Returns a ⁠data.frame sf⁠ with access/land use data and grid geometries

aopdata data dictionary

Description

Opens aopdata data dictionary on a web browser. This function requires internet connection.

Usage

aopdata_dictionary(lang = "en")

Arguments

Value

Opens aopdata data dictionary on a web browser

Examples

# Data dictionary in English
aopdata_dictionary(lang='en')

# Data dictionary in Portuguese
aopdata_dictionary(lang='pt')

Check internet connection with Ipea server

Description

Checks if there is an internet connection with Ipea server.

Usage

check_connection(
  url = "https://www.ipea.gov.br/geobr/aopdata/metadata/metadata.csv",
  silent = FALSE
)

Arguments

Value

Logical. TRUE if url is working, FALSE if not.

Classify the result of one download

Description

Classify the result of one download

Usage

classify_resp(x)

Arguments

Value

One of "ok", "http_error", "conn_error" or "aborted".

Download data to a temporary directory.

Description

Downloads the requested files to a temporary directory (the session cache) and reads them. Each file is downloaded from the Ipea server first and, if that fails, from the GitHub release mirror.

Usage

download_data(url, progress_bar)

Arguments

Value

An sf or a data.frame, or NULL (with a message) if any file could not be downloaded or read.

Support function to download metadata internally used in aopdata

Description

Downloads metadata.csv from the GitHub release or, if that fails, from the Ipea server, and caches it in tempdir() for the session. A file is cached only once it has been read successfully; a cached file that can't be read is downloaded again.

Usage

download_metadata()

Value

A data.table with the metadata, or NULL (with a message) if it could not be downloaded.

Examples

## Not run:  if (interactive()) {
df <- download_metadata()
}
## End(Not run)

Inform the user that a download failed

Description

Inform the user that a download failed

Usage

inform_failure(msg)

Arguments

Value

Signals a message of class aopdata_network.

Load data from tempdir to global environment

Description

Reads data from tempdir to global environment.

Usage

load_data(temps)

Arguments

Value

Returns either an sf or a data.frame, depending of the data set that was downloaded

Download accessibility estimates with population and land use data

Description

Download estimates of access to employment, health, education and social assistance services by transport mode and time of the day for the cities included in the AOP project. See the documentation 'Details' for the data dictionary. The data set reports information for each hexagon in a H3 spatial grid at resolution 9, with a side of 174 meters and an area of 0.10 km2. More information about H3 at https://h3geo.org/docs/core-library/restable/.

Usage

read_access(
  city = NULL,
  mode = "walk",
  peak = TRUE,
  year = 2019,
  geometry = FALSE,
  showProgress = TRUE
)

Arguments

Details

The output also includes the land use and population columns returned by read_landuse(); see its documentation or aopdata_dictionary().

Value

A data.table, or an sf object (which also inherits from data.table) when geometry = TRUE.

Data dictionary:

The name of the columns with accessibility estimates are the junction of three components: 1) Type of accessibility indicator 2) Type of opportunity / population 3) Time threshold

1) Type of accessibility indicator

2) Type of opportunity / population

3) Time threshold (only applicable to CMA and CMP estimates)

4) Cities available

Walking and cycling: all cities, 2017 to 2019. Car: all cities, 2019. Public transport: bho, cam, cur, for, poa, spo (2017 to 2019); rio (2018 and 2019); goi, rec (2019).

Examples

# Read accessibility estimates of a single city
df <- read_access(
  city = 'Fortaleza',
  mode = 'public_transport',
  year = 2019,
  showProgress = FALSE
)

# Read accessibility estimates for all cities
all <- read_access(
  city = 'all',
  mode = 'walk',
  year = 2019,
  showProgress = FALSE
)

Download spatial hexagonal grid H3

Description

Results of the AOP project are spatially aggregated on a H3 spatial grid at resolution 9, with a side of 174 meters and an area of 0.10 km2. More information about H3 at https://h3geo.org/docs/core-library/restable/. See the documentation 'Details' for the data dictionary.

Usage

read_grid(city = NULL, showProgress = FALSE)

Arguments

Value

An ⁠sf data.frame⁠ object

Data dictionary:

Cities available

Examples

# Read spatial grid of a single city
nat <- read_grid(city = 'Natal', showProgress = FALSE)

# Read spatial grid of all cities in the project
# all <- read_grid(city = 'all', showProgress = FALSE)

Download land use and population data

Description

Download data on the spatial distribution of population, jobs, schools, health care and social assistance facilities at a fine spatial resolution for the cities included in the AOP project. See the documentation 'Details' for the data dictionary. The data set reports information for each hexagon in a H3 spatial grid at resolution 9, with a side of 174 meters and an area of 0.10 km2. More information about H3 at https://h3geo.org/docs/core-library/restable/.

Usage

read_landuse(city = NULL, year = 2019, geometry = FALSE, showProgress = TRUE)

Arguments

Value

A data.table, or an sf object (which also inherits from data.table) when geometry = TRUE.

Data dictionary:

Cities available

Examples

# a single city: pass the city name
bho <- read_landuse(
  city = 'Belo Horizonte',
  year = 2019,
  showProgress = FALSE
  )

# ... or pass a three-letter abbreviation
bho <- read_landuse(
  city = 'bho',
  year = 2019,
  showProgress = FALSE
  )

# all cities
all <- read_landuse(city = 'all', year = 2019)

Read and validate a metadata file

Description

Read and validate a metadata file

Usage

read_metadata(path)

Arguments

Value

A data.table, or NULL if the file is missing, can't be read, is empty or lacks the columns used by the package.

Download population and socioeconomic data

Description

Download population and socioeconomic data from the Brazilian Census at a fine spatial resolution for the cities included in the AOP project. See the documentation 'Details' for the data dictionary. The data set reports information for each hexagon in a H3 spatial grid at resolution 9, with a side of 174 meters and an area of 0.10 km2. More information about H3 at https://h3geo.org/docs/core-library/restable/.

Usage

read_population(
  city = NULL,
  year = 2010,
  geometry = FALSE,
  showProgress = TRUE
)

Arguments

Value

A data.table, or an sf object (which also inherits from data.table) when geometry = TRUE.

Data dictionary:

Cities available

Examples

# a single city: pass the city name
bho <- read_population(
  city = 'Belo Horizonte',
  year = 2010,
  showProgress = FALSE
  )

# ... or pass a three-letter abbreviation
bho <- read_population(
  city = 'bho',
  year = 2010,
  showProgress = FALSE
  )

# all cities
all <- read_population(city = 'all', year = 2010)

Select city input

Description

Subsets the metadata table by 'city'.

Usage

select_city_input(temp_meta = temp_meta, city = NULL)

Arguments

Value

A data.frame object with metadata subsetted by 'city'

Select metadata

Description

Subsets the metadata table by data 'type', 'city', 'year' and 'mode'

Usage

select_metadata(t = NULL, c = NULL, y = NULL, m = NULL)

Arguments

Value

A data.frame object with metadata subsetted by data type, 'city', 'year' and 'mode'

Select mode input

Description

Subsets the metadata table by 'mode'.

Usage

select_mode_input(
  temp_meta = temp_meta,
  mode = NULL,
  all_cities = FALSE,
  year_meta = temp_meta
)

Arguments

Value

A data.frame object with metadata subsetted by 'mode'

Select year input

Description

Subsets the metadata table by 'year'.

Usage

select_year_input(temp_meta = temp_meta, year = NULL)

Arguments

Value

A data.frame object with metadata subsetted by 'year'