---
title: "Projections for a single region"
output: 
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 2
vignette: >
  %\VignetteIndexEntry{Projections for a single region}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r setup, warning=FALSE, message = FALSE}
library(propop)

# load package data
data("fso_parameters")
data("fso_population")
```

# Overview

This vignette explains how to use `propop::propop()` to perform population 
projections for a **single region** such as a **canton** (for projections of 
subregions, see [this vignette](project_multiple_regions.html)). 

The function was tailored to the context of 
Switzerland. It uses the cohort component method for cantonal scenarios, which 
was developed by the Federal Statistical Office (FSO, [2020](https://github.com/statistik-aargau/propop-additional-resources/blob/358ffa280f3777af34d3ac4b2782c1171ed93beb/FSO_2020_Meth_scenarios%20cant.pdf); only available in French). 
To run the function, you need the following input:

-   a data frame with the **starting population**, that is, the most up-to-date
number of people for each demographic group before the first projection year; to
illustrate, the example population data in `propop` are from 31. December 2018 
and the first projection year is 2019.

-   a data frame containing model **parameters**, that is, information about how
key demographic variables such as mortality are expected to develop in the future;

-   some global arguments which do not change over time or across demographic 
groups (e.g., proportion of female to male newborns).

Importantly, the two data frames' structure (number, names, type of columns) must
correspond exactly to the **specifications** shown in [this vignette](prepare_data.html). 
Among other things, it is **mandatory** to provide two levels for sex. Nationality
can have either one or two levels. The function requires 1-year age groups 
ranging from 0 to 100 (incl. those who are older).   

# Projections for a single region

The package `propop` includes the population data from the canton of Aargau from 
2018 and the FSO parameters from the [population development scenarios 2020](https://www.bfs.admin.ch/bfs/en/home/statistics/catalogues-databases.assetdetail.14963221.html). 
Using these resources, we can project the population for the canton as a whole 
for 1-year age groups for the period 2019-2030. 

The start and end of women's fertile period, the proportion of babies born as 
female, and the share of babies born by mothers who are not Swiss are stable 
parameters that are defined in `propop::project_raw()` and passed to 
`propop::propop()`.
\

``` {r project-canton}
projection_canton_2030 <- propop(
  parameters = fso_parameters,
  year_first = 2019,
  year_last = 2030,
  population = fso_population,
  subregional = FALSE,
  binational = TRUE
)

projection_canton_2030 |>
  # round to 2 digits
  dplyr::mutate(across(n_jan:n_dec, \(x) sprintf(fmt = "%.0f", x))) |>
  DT::datatable(filter = "top") |> 
  DT::formatStyle(
  'n_jan',
  backgroundColor = '#ffcc8f'
) |> 
  DT::formatStyle(
  c("births", "mor", "emi_int", "emi_nat", "imm_int", "imm_nat", "acq"),
  backgroundColor = '#96D4FF'
) |> 
  DT::formatStyle(
  'n_dec',
  backgroundColor = '#007AB8'
)  
```

\
The **output** file includes the 
<span style="color:#ffcc8f;">number of people in January </span> (`n_jan`) 
and the
<span style="color:#007AB8;">number of people in December </span> (`n_dec`) 
per demographic group and year. The 
<span style="color:#96D4FF;">components</span> 
that are used to project the population growth from the start to the end of the 
year are also included in the output. Thus, all elements of the cohort component 
equation are directly available from the output. Note that the number of people 
who acquire the Swiss citizenship (`acq`) are added if the demographic 
group is Swiss and subtracted if the demographic group has a different 
nationality.
\

# No distinction between nationalities

As of version 0.2.0 it is possible to run projections without distinguishing 
between Swiss and non-Swiss nationals. The simplest way to achieve this is to 
provide population data and parameters without the nationality-specific columns 
(remove `nat`, `acq`, `births_int_ch`).

Let's adapt the input files accordingly. To keep things simple, we run the 
projection for only one of the two nationalities. It goes without saying that 
using `propop::propop()` like this in real settings requires more preparation 
(e.g., determining a single value for the joint population when parameters differ between Swiss and 
non-Swiss people).

``` {r prepare-single-nationality}
fso_parameters_int <- fso_parameters |>
  # drop Swiss people
    dplyr::filter(nat == "int") |>
  #   remove `nat`, `acq` and `births_int_ch` from `parameters`
    dplyr::select(-c(nat, acq, int_mothers))

fso_population_int <- fso_population |> 
# drop Swiss people
    dplyr::filter(nat == "int") |>
    # remove `nat` from `population`
     dplyr::select(-nat)
```

When calling `propop::propop()`, you need to set `binational = FALSE`.

``` {r project-int}
projection_int <- propop(
  parameters = fso_parameters_int,
  year_first = 2019,
  year_last = 2030,
  population = fso_population_int,
  subregional = FALSE,
  binational = FALSE
)

projection_int |>
  # round to two digits
  dplyr::mutate(across(n_jan:n_dec, \(x) sprintf(fmt = "%.0f", x))) |>
  DT::datatable(filter = "top")
```
\