---
title: "Analyzing demographic data with epiCo"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Analyzing demographic data with epiCo}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

**epiCo**'s demographic module is a tool for demographic descriptive analysis and risk assessment of epidemiological events in Colombia. Based on linelist data provided by the Colombian National Surveillance System [(SIVIGILA)](https://www.ins.gov.co/Direcciones/Vigilancia/Paginas/SIVIGILA.aspx) and demographic data from the Colombian National Administrative Department of Statistics [(DANE)](https://microdatos.dane.gov.co/index.php/catalog/central/about).

The module allows you to:

-   Consult and visualize the population pyramid of a municipality, department, or country for a year of interest.
-   Consult the definitions of demographic variables such as ethnicities, special population groups, and occupational labels.
-   Estimate the distribution of occupations reported in the line list according to the [ISCO 88 Standard](https://unstats.un.org/unsd/classifications/Family/Detail/1067/).
-   Estimate the incidence rate of a municipality, department, or country.
-   Calculate and visualize a relative age risk by normalizing the distribution of cases by the specific age structure of the location of interest.

In the following vignette, you will learn how to:

1.  Navigate the Codification of the Political Administrative Division of Colombia (DIVIPOLA).
2.  Consult, visualize, and interpret Colombian population pyramids at different administrative levels.
3.  Interpret the demographic variables reported by the SIVIGILA (as ethnicities, special population groups, and occupational labels).
4.  Understand the typical SIVIGILA epidemiological data.
5.  Estimate weekly and monthly incidence rates for a municipality, department, or country.
6.  Integrate the age distributions of cases with population pyramids to obtain an age-risk assessment for a disease.

## 1. Navigating the Codification of the Political Administrative Division of Colombia (DIVIPOLA)

DIVIPOLA is a standardized nomenclature designed by the DANE for the identification of territorial entities (departments, districts, and municipalities), non-municipalized areas, and populated centers by assigning a unique numerical code to each of these territorial units.

Colombia has:

-   32 Departments (Administrative Division Level 1)
-   1102 Municipalities (Administrative Division Level 2)
-   1 Island
-   18 Non-municipalized areas
-   6678 Populated centers

Two digits are used for the codification of departments, and five digits are used for the codification of municipalities (the first two being the department where they are located).

**epiCo** provides the complete list of departments and municipalities codes through a built-in dataset.

```{r}
library(epiCo)
library(incidence)

data("divipola_table")
```

## 2. Population pyramids

**epiCo** provides a built-in dataset with the population projections of Colombia at the national, departmental, and municipality levels (provided by the DANE). These datasets contains the population projections from 2012 to 2024 for ages from 0 to 100 years. However, for the municipal projections it has the ages from 0 to over 85 years old.

Users can perform queries on this data by using the `population_pyramid` function, providing the DIVIPOLA code of the territory of interest and the year to consult.

```{r}
ibague_code <- "73001" # DIVIPOLA code for the city of Ibagu<U+00E9>
year <- 2016 # Year to consult
ibague_pyramid_2016 <- population_pyramid(ibague_code, year) # Population
# pyramid (dataframe) for the city of Ibagu<U+00E9> in the year 2019
# dissagregated by sex
knitr::kable(ibague_pyramid_2016[1:5, ])
```

Definitions of age ranges and plotting are also provided for both: total number of individuals, or proportion of individuals

```{r, fig.cap='Population pyramid for the city of Ibagué in 2019'}
ibague_code <- "73001" # DIVIPOLA code for the city of Ibagué
year <- 2019 # Year to consult
age_range <- 5 # Age range or window
ibague_pyramid_2019 <- population_pyramid(ibague_code, year,
  range = age_range,
  sex = TRUE, total = TRUE,
  plot = TRUE
)
```

## 3. Demographic variables

Events of epidemiological relevance are reported to the SIVIGILA using an official notification form (see [link](https://www.ins.gov.co/buscador-eventos/Paginas/Fichas-y-Protocolos.aspx)).

**epiCo** provides a function to consult the dictionaries for the ethnicity categories, special population groups, and occupation codifications used by the SIVIGILA. As shown in the following example:

```{r, fig.cap='Treemap plot of the distribution of occupations reported in the line list'}
demog_data <- data.frame(
  id = c(0001, 002, 003, 004, 005, 006, 007, 008),
  ethnicity_label = c(3, 4, 2, 3, 3, 3, 2, 3),
  occupation_label = c(6111, 3221, 5113, 5133, 6111, 23, 25, 99),
  sex = c("F", "M", "F", "F", "M", "M", "F", "M"),
  stringsAsFactors = FALSE
)


ethnicities <- describe_ethnicity(demog_data$ethnicity_label)
knitr::kable(ethnicities)

occupations <- describe_occupation(
  isco_codes = demog_data$occupation_label,
  sex = demog_data$sex,
  plot = "treemap"
)
knitr::kable(occupations$data)
```

## 4. Epidemiological data

**epiCo** is a tool that produces analyses based on epidemiological data extracted from SIVIGILA or provided by the user. `epi_data` is a built-in file that shows an example of the structure used by the package, which is the same as the one reported by SIVIGILA. This file contains the cases of all the municipalities in Tolima for the years 2015-2021.

The following analyses use the dengue cases reported in Tolima in 2019.

```{r}
data("epi_data")

data_tolima <- epi_data[lubridate::year(epi_data$fec_not) == 2019, ]
knitr::kable(data_tolima[1:5, 4:12])
```

## 5. Estimation of incidence rates

The incidence rate feature of **epiCo** requires the [incidence](https://www.repidemicsconsortium.org/incidence/) package to produce a modified incidence object. Instead of a count vector (or matrix), it transforms the object to provide a rate element accounting for the number of cases in the time period divided by the total number of inhabitants in the specific region and year.

**epiCo** uses the DANE population projections as denominators; therefore, it is necessary to provide the administration level at which incidences are calculated.

```{r}
incidence_object <- incidence(
  dates = data_tolima$fec_not,
  groups = data_tolima$cod_mun_o,
  interval = "1 epiweek"
)
incidence_rate_object <- incidence_rate(incidence_object, level = 2)
knitr::kable(incidence_rate_object$counts[1:5, 1:12])
```

If groups in the incidence object are not within the DIVIPOLA coding for municipalities (level 2) or departments (level 1), or a national estimation is intended (level 0), the function will not be able to estimate an incidence rate.

## 6. Estimation of risk by age group

Normalization of data is a key aspect of epidemiology. **epiCo** allows for the age distribution of cases and normalizes the epidemiological data with the age structure of a population. This normalization allows us to estimate the age risk of a disease according to the age structure of the general population in a municipality, department, or country in a certain year.

```{r, fig.cap='Age risk plot for the city of Ibagué in 2019'}
data_ibague <- data_tolima[data_tolima$cod_mun_o == 73001, ]

age_risk_data <- age_risk(
  age = data_ibague$edad,
  population_pyramid = ibague_pyramid_2019$data,
  sex = data_ibague$sexo, plot = TRUE
)
```