---
title: "Census documentation"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
urlcolor: blue
vignette: >
  %\VignetteIndexEntry{Census documentation}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = identical(tolower(Sys.getenv("NOT_CRAN")), "true"),
  out.width = "100%"
)
```

The **{censobr}** package includes a few functions to help users navigate Brazilian census data, its variables and methodology. 


<table cellpadding="0" cellspacing="0" style="border-collapse:collapse" border="1">
    <thead>
        <tr>
            <th rowspan="2"><center>Function</center></th>
            <th rowspan="2"><center>Documentation</center></th>
            <th rowspan="2"><center>Type</center></th>
            <th colspan="7"><center>Years available</center></th>
        </tr>
        <tr>
            <th>1960</th>
            <th>70</th>
            <th>80</th>
            <th>91</th>
            <th>2000</th>
            <th>10</th>
            <th>22</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td rowspan="2" valign="middle">data_dictionary()</td>
            <td rowspan="2" valign="middle">Data dictionary (codebook)</td>
            <td>Microdata</td>
            <td>X</td>
            <td>X</td>
            <td>X</td>
            <td>X</td>
            <td>X</td>
            <td>X</td>
            <td>X</td>
        </tr>
        <tr>
            <td>Census tract aggregates</td>
            <td></td>
            <td>X</td>
            <td>X</td>
            <td>X</td>
            <td>X</td>
            <td>X</td>
            <td>X</td>
        </tr>
        <tr>
            <td>questionnaire()</td>
            <td>Questionnaires</td>
            <td>Long and short</td>
            <td>X</td>
            <td>X</td>
            <td>X</td>
            <td>X</td>
            <td>X</td>
            <td>X</td>
            <td>X</td>
        </tr>
        <tr>
            <td>interview_manual()</td>
            <td>Interviewer’s manual (Enumerator Instructions)</td>
            <td>-</td>
            <td>X</td>
            <td>X</td>
            <td>X</td>
            <td>X</td>
            <td>X</td>
            <td>X</td>
            <td>X</td>
        </tr>
    </tbody>
</table>



All of these functions download supporting documents in either `.html` or `.pdf` format, and open the documents on a web browser. Like all other datasets in **{censobr}**, these support documents are downloaded and cached locally the first time when users run the function. This way, when users need to take a peak at the documentation again, the functions simply load local files, making it super quick and convenient.


# Data Dictionary

The `data_dictionary()` indicate the definition of each variable, and the meaning of their categories in the case of categorical variables. The function covers two types of dictionary, passed in the `dataset` argument: `"microdata"`, which describes the variables of the microdata (sample portion of the census) and is available for every Brazilian census since 1960 (`1960`, `1970`, `1980`, `1991`, `2000`, `2010` and `2022`), and `"tracts"`, which describes the variables of the census tract-level aggregate data and is available since 1970.


```{r, eval = FALSE}
# Microdata variables
data_dictionary(
  year = 2022,
  dataset = 'microdata'
  )

# Census tract-level variables
data_dictionary(
  year = 2022,
  dataset = 'tracts'
  )
```


# Questionnaires

Oftentimes, it is really important to understand the structure of the questionnaire used in surveys. The `questionnaire()` function includes the questionnaires used in the data collection of all Brazilian censuses since 1970.

Here, users need to pass the `year` parameter indicating the edition of the census of interest and whether they want the `'short'` questionnaire that is used to interview all households, or the `'short'` one that is used in the sample component of the cesus.

```{r, eval = FALSE}
# short questionnaire
questionnaire(
  year = 2022, 
  type = 'short'
  )

# long questionnaire
questionnaire(
  year = 2022, 
  type = 'long'
  )
```


# Interview manual

Finally, the `interview_manual()` function downloads and opens on a browser the "Manual do Recenseador", i.e. the manual of instructions for IBGE's census takers (recenseadores) on how to collect the census data.

Manuals for all censuses since 1970 are available.

```{r, eval = FALSE}
# 2022
interview_manual(year = 2022)

# 1960
interview_manual(year = 1960)

```