README.Rmd

---
output: github_document 
---

```{r, include = FALSE, message = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "figures/README-",
  out.width = "100%"
)
source("_targets.R")
```

# CNEFE padronizado

Este repositório contém o código utilizado na padronização dos endereços
listados no CNEFE 2022. Essa padronização visa principalmente subsidiar o pacote
[`{geocodebr}`](https://github.com/ipeaGIT/geocodebr/), que faz a geolocalização
de endereços a partir das informações do CNEFE.

A divulgação e publicização desse repositório tem como objetivo garantir a
transparência do trabalho realizado. O código necessário para realizar a
padronização está disposto como explicado na seção *[Estrutura dos arquivos]* e
pode ser utilizado para reproduzir os resultados finais conforme as instruções
apresentadas na seção *[Rodando o código]*. No entanto, nós **não** garantimos a
total reprodutibilidade do trabalho, uma vez que usamos o pacote interno
`{ipeadatalake}` (apenas disponível na rede interna do IPEA) para fazer a
leitura dos dados do CNEFE. Além disso, o comportamento das funções utilizadas
no código está condicionado a diversos fatores, como a versão instalada do R e o
sistema operacional em que o código é rodado. Ao final deste documento nós
listamos informações relevantes do *[Ambiente de trabalho]* usado no
desenvolvimento do estudo.

## Instalação

A primeira etapa para rodar esse projeto é clonar o repositório. Para isso, use
o comando:

```
git clone https://github.com/ipeaGIT/padronizacao_cnefe.git
```

## Estrutura dos arquivos

Os arquivos que compõem este repositório foram organizados de forma que cada
pasta armazene arquivos com uma determinada finalidade:

- `R/` - código utilizado no projeto;
- `figures/` - figuras geradas ao rodar o código do projeto;
- `_targets/` - pasta utilizada pelo pacote `{targets}` para manter controle do
fluxo de trabalho do projeto;
- `renv/` - pasta utilizada pelo pacote `{renv}` para manter controle das
dependências do projeto.

## Rodando o código

Este projeto utiliza o pacote
[`{renv}`](https://rstudio.github.io/renv/index.html) para fazer a gestão de
dependências do código, garantindo que os mesmos pacotes usados em seu
desenvolvimento sejam usados na cópia a ser reproduzida em seu computador. Para
instalar as dependências, abra o projeto e rode o seguinte comando:

```r
renv::restore()
```

Nesse momento, uma série de pacotes serão listados e o `{renv}` pedirá para
confirmar se você deseja instalá-los. Após essa confirmação, os pacotes serão
instalados.

O pacote [`{targets}`](https://github.com/ropensci/targets), por sua vez, faz a
gestão do fluxo de trabalho do projeto. O arquivo `_targets.R` configura as
dependências entre as diferentes funções internas usadas no código, de forma a
garantir que o resultado de uma determinada função esteja sempre sincronizado
com o resultado de suas dependências (por exemplo, se configuramos que o
resultado da função `b()` depende do valor da função `a()`, precisamos atualizar
`b()` no caso de uma atualização de `a()`).

Rode o arquivo `_targets.R` com a função `source()` para carregar as bibliotecas
necessárias e configurar as dependências entre as funções e os objetos usados no
projeto. Para visualizar as dependências do código na forma de um grafo
dirigido, use o seguinte comando:

```{r, eval = FALSE}
source("_targets.R")

tar_visnetwork(targets_only = TRUE)
```

```{r, graph-outdated, echo = FALSE}
widget <- tar_visnetwork(targets_only = TRUE, store = "missing")

tmp_widget <- tempfile(fileext = ".html")
visNetwork::visSave(widget, tmp_widget)

tmp_image <- tempfile(fileext = ".png")
webshot::webshot(tmp_widget, file = tmp_image)
```

Note que todos os vértices do grafo estão marcados como desatualizados. Para que
eles sejam marcados como atualizados, é necessário rodar o *pipeline* do projeto
respeitando suas dependências (nos termos do exemplo anterior, rodando primeiro
a função `a()` e depois a `b()`, que depende dos resultados da `a()`). Para
isso, use o seguinte comando:

```{r, eval = FALSE}
tar_make()
```

Caso a execução deste comando ocorra como esperado, sem erros, o fluxo de
trabalho do projeto será marcado como atualizado. O mesmo comando de
visualização do grafo de dependências usado anteriormente pode ser usado para
checar se os vértices estão atualizados:

```{r, eval = FALSE}
tar_visnetwork(targets_only = TRUE)
```

```{r, graph-updated, echo = FALSE}
widget <- tar_visnetwork(targets_only = TRUE)

tmp_widget <- tempfile(fileext = ".html")
visNetwork::visSave(widget, tmp_widget)

tmp_image <- tempfile(fileext = ".png")
webshot::webshot(tmp_widget, file = tmp_image)
```

## Ambiente de trabalho

<details>
<summary>Clique aqui para ver as informações do ambiente de trabalho utilizado
no desenvolvimento do projeto.</summary>
```{r}
info <- sessioninfo::session_info()
info$packages$library <- NULL

info
```
</details>