---
title: "Introduction to the DHS.rates package"
author: "Mahmoud Elkasabi, Ph.D."
date: "`r Sys.Date()`"
output:
  rmarkdown::html_vignette:
  toc: true
vignette: >
  %\VignetteIndexEntry{Introduction to the DHS.rates package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

# Overview

The package was developed to calculate key indicators based on the Demographic and Health Survey data. In addition to calculating the indicators on the national level, the DHS.rates allows for domain level indicators.

In addition to the indicators, the 'DHS.rates' package estimates precision indicators such as Standard Error (SE), Design Effect (DEFT), Relative Standard Error (RSE) and Confidence Interval (CI).

The package is developed according to the DHS methodology of calculating the DHS indicators outlined in the "DHS Guide to Statistics" (Croft, Trevor N., Aileen M. J. Marshall, Courtney K. Allen, et al. 2018, <https://dhsprogram.com/Data/Guide-to-DHS-Statistics/index.cfm>)
  and the DHS methodology of estimating the sampling errors indicators outlined in 
  the "DHS Sampling and Household Listing Manual" (ICF International 2012, <https://dhsprogram.com/pubs/pdf/DHSM4/DHS6_Sampling_Manual_Sept2012_DHSM4.pdf>).
 
# Datasets
First you need to install the package from the CRAN as follows:

```{r, eval = FALSE }
install.packages("DHS.rates")
```


Call any of the following datasets provided with the package:

1. The "AWIR70" for all women 15-49: 
   an artificial dataset of a DHS survey where all women age 15-49 were eligible for the survey. 

2. The "EMIR70" for ever-married women 15-49
   an artificial dataset of a DHS survey where only ever-married women age 15-49 were eligible for the survey. In  ever-married women surveys, inflation factors called _All-women factors_ have to be considered to produce indicators for all women.
   
3. The "ADBR70" for all Births: 
   an artificial dataset of a DHS survey that include all birth for interviewed women age 15-49. 

```{r }
library(DHS.rates)
data("AWIR70")
data("EMIR70")
data("ADBR70")
```


You can use your own DHS IR individual (women's) recode files or BR births recode files downloaded from <https://dhsprogram.com/data/available-datasets.cfm>

in this case you will need to install and use the "haven" library to read the data. In the example below, I'm reading a Stata file:

```{r, eval=FALSE }
library(haven)
XXIR70 <- read_dta("C:\\Users\\.............................\\XXIR7HFL.DTA")
XXIR70 <- as.data.frame(XXIR70)

```

# The _fert_ function

The _fert_ function calculates the following fertility indicators:

1. Total Fertility Rate (TFR)
2. General Fertility Rate (GFR) 
3. Age Specific Fertility Rate (ASFR).

The _fert_ function uses the DHS IR individual (women's) recode files

## Examples

### Total Fertility Rate (TFR):

_fert_ can calculate Total Fertility Rate (TFR) based on all women AWIR70 data

```{r }
(TFR <- fert(AWIR70,Indicator="tfr"))
```

#### Jackknife SE for TFR

in the previous example you can use the _JK_ argument to estimate SE, DEFT, RSE and CI.
the SE is based on Jackknife variance estimation

```{r }
(TFR <- fert(AWIR70,Indicator="tfr",JK="Yes"))
```

### General Fertility Rate (GFR)

_fert_ can calculate GFR and estimate SE, DEFT, RSE and CI based on ever-married women EMIR70 data

For ever-married samples, you need to call the _EverMW_ argument and use _AWFact_ to define the variable name of the All-women factor

```{r }
(GFR <- fert(EMIR70,Indicator="gfr",EverMW="YES",AWFact="awfactt"))
```

### Age Specific Fertility Rates (ASFR)

_fert_ can calculate ASFR and estimate SE, DEFT, RSE and CI based on all women AWIR70 data

```{r }
(ASFR <- fert(AWIR70,Indicator="asfr"))
```


### Sub-national indicators 

you can calculate sub-national TFR by using the "Class" argument.

```{r }
(TFR <- fert(AWIR70,Indicator="tfr",JK="Yes", Class="v025"))
```

### Sub-national indicators for Ever-married samples 

When _Class_ is used, you might need to use the relevent _AWFact_ as below; "awfactu" is used to produce indicators on the urban/rural level, "v025".

```{r }
(GFR <- fert(EMIR70,Indicator="gfr", EverMW="YES",AWFact="awfactu", Class="v025"))
```

# The _chmort_ function

The _chmort_ function calculates the following childhood mortality indicators:

1. Neonatal Mortality Rate (NNMR)
2. Post-neonatal Mortality Rate (PNNMR)
3. Infant Mortality Rate (IMR)
4. Child Mortality Rate (CMR)
5. Under-5 Mortality Rate (U5MR).

The _chmort_ function uses the DHS BR birth recode files

## Examples

### childhood mortality rates:

_chmort_ can calculate five-year childhood mortality rates based on birth ADBR70 data

```{r }
(chmort(ADBR70))
```


#### Jackknife SE for childhood mortality rates

in the previous example you can use the _JK_ argument to estimate SE, RSE and CI.
the SE is based on Jackknife variance estimation

```{r }
(chmort(ADBR70,JK="Yes"))
```

The study period in the previous examples are the default 60 months (5 years) previous to the survey. The ten-year children mortality rates can be calculated using the _Period_ argument as follows

```{r }
(chmort(ADBR70,Period = 120))
```

In the previous examples the study period ends at the time of the survey. To change the ending date to September 2013, _PeriodEnd_ can be used as follows

```{r }
(chmort(ADBR70,Period = 120, PeriodEnd = "2013-09"))
```

Similar to _fert_, in _chmort_ the _Class_ can be used to produce domain level indicators.  

# The _chmort_ function

The _chmortp_ function calculates childhood childhood mortality probabilities for 8 age segments 0, 1-2, 3-5, 6-11, 12-23, 24-35, 36-47, and 48-59 months.

The _chmortp_ function uses the DHS BR birth recode files

## Example

### childhood mortality probabilities:

_chmortp_ can calculate five-year childhood mortality probabilities based on birth ADBR70 data

```{r }
(chmortp(ADBR70))
```

Similar to _chmort_, in _chmortp_ the _Period_ and _PeriodEnd_ can be used to change the calculation reference period and the _Class_ can be used to produce domain level indicators.