DemoKin/README.Rmd at main · MPIDR/DemoKin · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
devtools::load_all()
library(DemoKin)
library(knitr)
```


# DemoKin

:::::::::::::: {.columns}
::: {.column width="60%"}


`DemoKin` uses matrix demographic methods to compute expected (average) kin counts from demographic rates under a range of scenarios and assumptions. The package is an R-language implementation of Caswell (2019), Caswell (2020), and Caswell and Song (2021). It draws on previous theoretical development by Goodman, Keyfitz and Pullum (1974).

:::
::: {.column width="40%"}

<img src="DemoKin-Logo.png" align="right" width="200" />

:::
::::::::::::::

## Installation

You can install the development version from GitHub with:

``` {r, eval=FALSE}
# install.packages("devtools")
devtools::install_github("IvanWilli/DemoKin")
```

## Usage

Consider an average Swedish woman called 'Focal'. For this exercise, we assume a female closed population in which everyone experiences the Swedish 2015 mortality and fertility rates at each age throughout their life (the 'time-invariant' assumption in Caswell [2019]).

We then ask:

> How many living relatives does Focal have at each age?

Let's explore this using the Swedish data already included with `DemoKin`.

```{r, fig.height=6, fig.width=8}
library(DemoKin)
swe_surv_2015 <- swe_px[,"2015"]
swe_asfr_2015 <- swe_asfr[,"2015"]
swe_2015 <- kin(U = swe_surv_2015, f = swe_asfr_2015, time_invariant = TRUE)
```

*px* is the survival probability by age from a life table and *f* are the age specific fertility raties by age (see `?kin` for details).

Now, we can visualize the implied kin counts (i.e., the average number of living kin) of Focal at age 35 using a network or 'Keyfitz' kinship diagram with the function `plot_diagram`:

```{r, fig.height=6, dpi=1200,fig.width=8, message=FALSE, warning=FALSE}
# We need to reformat the data a little bit
kin_total <- swe_2015$kin_summary
# Keep only data for Focal's age 35
kin_total <- kin_total[kin_total$age_focal == 35 , c("kin", "count_living")]
names(kin_total) <- c("kin", "count")
plot_diagram(kin_total, rounding = 2)
```

Relatives are identified by a unique code:

```{r, fig.height=6, fig.width=8, echo=FALSE}
kable(DemoKin::demokin_codes()[-2])
```

## Vignette

For more details, including an extension to time varying-populations rates, deceased kin, and multi-state models, see `vignette("Reference", package = "DemoKin")`.
If the vignette does not load, you may need to install the package as `devtools::install_github("IvanWilli/DemoKin", build_vignettes = T)`.

## Citation

Williams, Iván; Alburez-Gutierrez, Diego; Song, Xi; and Hal Caswell. (2021) DemoKin: An R package to implement demographic matrix kinship models. URL: https://github.com/IvanWilli/DemoKin.

## Acknowledgments

 We thank Silvia Leek from the Max Planck Institute for Demographic Research for designing the DemoKin logo. The logo includes elements that have been taken or adapted [from this file](https://commons.wikimedia.org/wiki/File:Escudo_de_la_Orden_de_San_Jer%C3%B3nimo.svg), originally by Ansunando, [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0) via Wikimedia Commons. Sha Jiang provided useful comments for improving the package.

## Get involved!

`DemoKin` is under constant development.
If you're interested in contributing, please get in touch, create an issue, or submit a pull request.
We look forward to hearing from you!

## References

Caswell, H. 2019. The formal demography of kinship: A matrix formulation. Demographic Research 41:679–712. doi:10.4054/DemRes.2019.41.24.

Caswell, H. 2020. The formal demography of kinship II: Multistate models, parity, and sibship. Demographic Research 42: 1097-1144. doi:10.4054/DemRes.2020.42.38.

Caswell, Hal and Xi Song. 2021. “The Formal Demography of Kinship. III. Kinship Dynamics with Time-Varying Demographic Rates.” Demographic Research 45: 517–46. doi:10.4054/DemRes.2021.45.16.

Goodman, L.A., Keyfitz, N., and Pullum, T.W. (1974). Family formation and the frequency of various kinship relationships. Theoretical Population Biology 5(1):1–27. doi:10.1016/0040-5809(74)90049-5.

<!-- ## Next steps: -->

<!-- 1. Implement two-sex matrix kinship models -->
<!-- 1. Improve documentation and vignette of package  -->