---
title: "Getting started with inspercidados"
description: >
  Find a dataset, download it into R, and cite it.
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with inspercidados}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)
```

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

`inspercidados` gives you direct access to datasets from Insper Cidades, hosted
on [Insper Dataverse](https://dataverse.datascience.insper.edu.br). Insper
Cidades is a multidisciplinary research center at Insper, and the datasets come
from publications by its authors. The [Cidados](https://cidados.insper.edu.br)
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.

```r
install.packages("inspercidados")
```

Install the development version from
[R-universe](https://inspercidades.r-universe.dev/inspercidados).

```r
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.

```{r list}
list_datasets()
```

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

```{r search}
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.

```{r resources}
list_resources("qualidade_ar_mare")
```

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

```{r 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.

```{r query}
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.

```{r cite}
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.

```{r project}
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.