Skip to contents

Getting started with inspercidados

Source: vignettes/getting-started.Rmd
getting-started.Rmd

inspercidados gives you direct access to datasets from Insper Cidades, hosted on Insper Dataverse. Insper Cidades is a multidisciplinary research center at Insper, and the datasets come from publications by its authors. The Cidados website features these publications as data visualization narratives.

Open science

The package supports open and reproducible research in two ways.

  • Findable and accessible open data. The package ships a registry that gives each dataset a stable alias and a DOI, so anyone can find and download the same data with one call.
  • Transparency and replication. Most datasets come from research projects whose pipelines are published as repositories. open_project() takes you from a dataset to the code that produced it.

Installation

Install the stable version from CRAN.

install.packages("inspercidados")

Install the development version from R-universe.

install.packages(
  "inspercidados",
  repos = c(
    "https://inspercidades.r-universe.dev",
    "https://cloud.r-project.org"
  )
)

Using the package

list_datasets() reads the registry from GitHub once per session, so datasets added after a release appear without reinstalling. Offline, it uses the copy shipped with the package. Set options(inspercidados.registry = "bundled") to always use that copy.

To search by alias, title, description, theme, region, or keywords, use the search argument of list_datasets().

list_datasets(search = "Mobilidade")

Each registered dataset has a short alias. Some aliases contain several logical resources. qualidade_ar_mare, for example, holds its measurements and the coordinates of its measurement points as separate resources. Each resource may come in several file formats or be split by year. Use list_resources() to inspect the resources of an alias without querying Dataverse.

list_resources("qualidade_ar_mare")

Use get_dataset() to download a dataset by its alias. The year, resource, and format arguments narrow the download.

# By alias
embarques <- get_dataset("embarques_mensais")

# Filter by year in multi-year datasets
pemob_2023 <- get_dataset("pemob_anual", year = 2023)

# Select one logical resource and file format
pontos <- get_dataset(
  "qualidade_ar_mare",
  resource = "pontos",
  format = "gpkg"
)

Query large datasets

Some datasets are too large to load comfortably. query_dataset() opens a parquet dataset as a lazy table: DuckDB reads the file directly from Dataverse, and only the columns your query uses are downloaded. Build the query with dplyr verbs and call collect() to bring the result into R. It needs the duckdb, DBI, and dbplyr packages.

library(dplyr)

itbi <- query_dataset("itbi_sp")

itbi |>
  filter(data_de_transacao >= as.Date("2020-01-01")) |>
  count(bairro, sort = TRUE) |>
  collect()

Cite a dataset

cite_dataset() fetches metadata from Dataverse and returns a citation in plain text, BibTeX, or RIS.

cite_dataset("embarques_mensais")
cite_dataset("embarques_mensais", format = "bibtex")

Explore the study behind a dataset

open_project() prints the study, lists its datasets, and opens the repository. Private repositories are flagged before they open.

open_project("embarques_mensais")

Next steps

The full function reference is at https://inspercidades.github.io/inspercidados/. get_dataverse() downloads any Insper Dataverse deposit, registered or not, from a pasted DOI or URL. list_projects() lists the studies behind the datasets and their repositories.