---
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><i>X</i></td>
            <td>X</td>
            <td>X</td>
            <td>X</td>
            <td>X</td>
            <td>X</td>
            <td><i>soon</i></td>
        </tr>
        <tr>
            <td>Census tract aggregates</td>
            <td></td>
            <td></td>
            <td></td>
            <td></td>
            <td>X</td>
            <td>X</td>
            <td><i>soon</i></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 currently covers the data dictionaries for all Brazilian censuses since 1960 (`19960`, `1970`, `1980`, `1991`, `2000` and `2010`), and it includes dictionaries for the variables of both microdata (sample portion of the census) and for the variables available in census tract-level aggregate data.


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

# Census tract-level variables
data_dictionary(year = 2010,
                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}
# 2010
interview_manual(year = 2022)

# 1970
interview_manual(year = 1960)

```