---
title: "Package data"
output: 
  rmarkdown::html_vignette:
       toc: true
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{Package data}
  %\usepackage[UTF-8]{inputenc}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```
This vignette covers package data. Central to all vignettes are data inputs in the form of, country classifications, estimated correlations, estimated national and subnational model parameters for one-country runs, and national and subnational family planning source data.

1. [Family planning source data](#cu) `national_FPsource_data` and `subnat_FPsource_data`
2. [Country and area classification](#cu) `Country_and_area_classification_inclFP2020`
3. [Country names](#cu) `country_names`
4. [Estimated national correlations](#cu) `national_estimated_correlations_logitnormal`
5. [Estimated subnational correlations](#cu)  `subnational_estimated_correlations`
6. [Estimated model parameters for national one-country runs](#cu) `national_theta_rms_hat_logitnormal`, `national_tau_alpha_cms_hat_logitnormal` , and `national_sigma_delta_hat_logitnormal`, 
7. [Estimated model parameters for subnational one-country runs](#cu) `subnational_alpha_cms_hat`, `subnational_tau_alpha_pms_hat`, and `subnational_inv.sigma_delta_hat`.

## Load your library
```{r, include=TRUE, message=FALSE}
library(mcmsupply)
```

## <a name="div"></a>
## Family planning source data 
These are are two family planning commodity source datasets provided in this package - one for the national level observations, `national_FPsource_data` and one for the subnational level data `subnat_FPsource_data`. For the national level data, there is a vignette `calculate_FPsource_national_data_from_DHSmicrodata` in the `inst/data-raw` folder that explains how the national level data was calculated using the DHS micro-data. A similar approach was used for the subnational data using IPUMS data.

```{r}
head(national_FPsource_data)
```


```{r}
head(subnat_FPsource_data)
```


## <a name="cu"></a>
## Country and area classification
Country and area classification data is used as the a link between low-level divisions (country) and higher-level divisions (sub-regions, regions). After loading the package, enter `Country and area classification` into the console to access this data.
```{r}
Country_and_area_classification
??Country_and_area_classification
```


## <a name="cu"></a>
## Country names
Country names is to inform users of what countries are available at the national and subnational administrative division in the preloaded data of the mcmsupply package. After loading the package, enter `country_names` into the console to access this data.
```{r}
country_names
??country_names
```


## <a name="cu"></a>
## Estimated national correlations
This is the estimated correlations for the rates of change between methods in the global national model. The approach for estimating correlations at the national level is very similar to that at the subnational level. For an example of how to calculate the subnational correlations, please review the `inst/data-raw/estimated_global_subnational_correlations.R` script.
```{r}
mcmsupply::national_estimated_correlations_bivarlogitnormal
```


## <a name="cu"></a>
## Estimated subnational correlations
This is the estimated correlations for the rates of change between methods in the global national model. There is a vignette to describe how we calculated these correlations at the subnational level, please review the `inst/data-raw/estimated_global_subnational_correlations.R` script. 

```{r}
subnational_estimated_correlations
```


## <a name="cu"></a>
## Estimated model parameters for national one-country runs
These are the estimated parameters used in a one-country national model run. `national_theta_rms_hat_logitnormal` are the regional intercepts used to inform the country-specific intercept of the model, the `national_tau_alpha_cms_hat_logitnormal` are the associated variance with these country-specific intercepts. `national_sigma_delta_hat_logitnormal` is the variance-covariance matrix used to inform the multivariate normal prior describing the first-order differences of the spline coefficients ($\delta_{k}$).

```{r}
national_theta_rms_hat_bivarlogitnorm
```

```{r}
national_tau_alpha_cms_hat_bivarlogitnorm
```

```{r}
national_inv_sigma_delta_hat_bivarlogitnorm
```

## <a name="cu"></a>
## Estimated model parameters for subnational one-country runs
These are the estimated parameters used in a one-country subnational model run. `subnational_alpha_cms_hat` are the country-specific intercepts used to inform the subnational province-specific intercepts of the model, the `subnational_tau_alpha_pms_hat` are the associated variance with these province-specific intercepts. `subnational_inv.sigma_delta_hat` is a precision of the variance-covariance matrix used to inform the multi-variate normal prior on first-order differences of the spline coefficients for the one-country subnational model. 

```{r}
subnational_alpha_cms_hat
```

```{r}
subnational_tau_alpha_pms_hat
```

```{r}
subnational_inv.sigma_delta_hat
```