-
Notifications
You must be signed in to change notification settings - Fork 19
/
README.Rmd
262 lines (155 loc) · 7.98 KB
/
README.Rmd
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
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.width=8,
fig.height=6,
fig.path="figs/",
echo = TRUE
)
```
Welcome to the *epicontacts* package!
---------------------------------------
<br>
[](https://travis-ci.org/reconhub/epicontacts)
[](https://ci.appveyor.com/project/thibautjombart/epicontacts/branch/master)
[](https://codecov.io/github/reconhub/epicontacts?branch=master)
[](https://cran.r-project.org/package=epicontacts)
[](https://cran.r-project.org/package=epicontacts)
[](http://www.r-pkg.org/pkg/epicontacts)
<br>
# Installing the package
To install the current stable, CRAN version of the package, type:
```{r install, eval = FALSE}
install.packages("epicontacts")
```
To benefit from the latest features and bug fixes, install the development, *github* version of the package using:
```{r install2, eval = FALSE}
devtools::install_github("reconhub/epicontacts")
```
Note that this requires the package *devtools* installed.
# What does it do?
The main features of the package include:
* **`epicontacts`:** a new S3 class for storing linelists and contacts data
* **`make_epicontacts`:** a constructor for the new `epicontacts` class
* **`get_id`:** access unique IDs in an `epicontacts` with various options
* **`get_pairwise`**: extract attributes of record(s) in contacts database using
information provided in the linelist data of an `epicontacts` object.
* **`get_degree`:** access degree of cases in `epicontacts` with various options
* **`x[i,j,contacts]`:** subset an `epicontacts` object by retaining specified
cases
* **`thin`:** retains matching cases in linelist / contacts
* **`summary`:** summary for `epicontacts` objects
* **`plot`:** plot for `epicontacts` objects; various types of plot are
available; default to `vis_epicontacts`
* **`vis_epicontacts`:** plot an `epicontacts` object using `visNetwork `
* **`as.igraph.epicontacts`:** create an `igraph` object from an epicontacts object
* **`get_clusters`:** assign clusters and corresponding cluster sizes to
linelist of an epicontacts object (clusters being groups of connected
individuals/nodes).
* **`subset_clusters_by_id`**: subset an `epicontacts` object based on a IDs of
cases of interest.
* **`subset_clusters_by_size`**: subset an `epicontacts` object based on size(s)
of clusters (clusters being groups of connected individuals/nodes).
* **`graph3D`**: 3D graph from an `epicontacts` object.
# Resources
## Vignettes
An overview of *epicontacts* is provided below in the worked example below.
More detailed tutorials are distributed as vignettes with the package:
```{r, vignettes2, eval = FALSE}
vignette("overview", package="epicontacts")
vignette("customize_plot", package="epicontacts")
vignette("epicontacts_class", package="epicontacts")
```
## Websites
The following websites are available:
- The official *epicontacts* website, providing an overview of the package's functionalities, up-to-date tutorials and documentation: <br>
[http://www.repidemicsconsortium.org/epicontacts/](http://www.repidemicsconsortium.org/epicontacts/)
- The *epicontacts* project on *github*, useful for developers, contributors, and users wanting to post issues, bug reports and feature requests: <br>
[http://github.com/reconhub/epicontacts](http://github.com/reconhub/epicontacts)
- The *epicontacts* page on CRAN: <br>
[https://CRAN.R-project.org/package=epicontacts](https://CRAN.R-project.org/package=epicontacts)
## Getting help online
Bug reports and feature requests should be posted on *github* using the [*issue*](http://github.com/reconhub/epicontacts/issues) system. All other questions should be posted on the **RECON forum**: <br>
[http://www.repidemicsconsortium.org/forum/](http://www.repidemicsconsortium.org/forum/)
# A quick overview
The following worked example provides a brief overview of the package's
functionalities. See the [*vignettes section*](#vignettes) for more detailed
tutorials.
## Obtaining an *epicontacts* object
*epicontacts* need two types of data:
- a **linelist**, i.e. a spreadsheet documenting cases where columns are
variables and rows correspond to unique cases
- a **list of edges**, defining connections between cases, identified by their
unique identifier
There does not need to be an one-to-one correspondance between cases documented
in the linelist and those appearing in the contacts. However, links will be made
between the two sources of data whenever unique identifiers match. This will be
especially handy when subsetting data, or when characterising contacts in terms
of 'node' (case) properties.
We illustrate the construction of an *epicontacts* using contact data from a
Middle East Respiratory Syndrom coronavirus (MERS CoV) from South Korea in 2015,
available as the dataset `mers_korea_2015` in the package *outbreaks*.
```{r}
library(outbreaks)
library(epicontacts)
names(mers_korea_2015)
dim(mers_korea_2015$linelist)
dim(mers_korea_2015$contacts)
x <- make_epicontacts(linelist = mers_korea_2015$linelist,
contacts = mers_korea_2015$contacts,
directed = TRUE)
x
class(x)
summary(x)
```
In practice, the linelist and contacts will usually be imported from a text file
(e.g. .txt, .csv) or a spreadsheet (e.g. .ods, .xls) using usual import
functions (e.g. `read.table`, `read.csv`, `gdata::read.xls`).
## Simple analyses
First, we plot the *epicontacts* object:
```{r, eval = FALSE}
plot(x, selector = FALSE)
```
<img src="https://github.com/reconhub/epicontacts/raw/master/figs/plot_x.png" width="600px">
This is a screenshot of the actual plot. For interactive graphs, see the [introductory vignette](http://www.repidemicsconsortium.org/epicontacts/articles/epicontacts.html).
We can look for patterns of contacts between genders:
```{r, eval = FALSE}
plot(x, "sex", col_pal = spectral)
```
<img src="https://github.com/reconhub/epicontacts/raw/master/figs/plot_x_gender.png" width="600px">
There is no obvious signs of non-random mixing patterns, but this is worth
testing. The function `get_pairwise` is particularly useful for this. In its
basic form, it reports nodes of attributes for all contacts. For instance:
```{r, check_gender}
get_pairwise(x, attribute = "sex")
```
However, one can specify the function to be used to compare the attributes of
connected nodes; for instance:
```{r, test_gender}
sex_tab <- get_pairwise(x, attribute = "sex", f = table)
sex_tab
fisher.test(sex_tab)
```
Indeed, there are no patterns of association between genders. We can also use
this function to compute delays between dates. For instance, to get the
distribution of the serial interval (delay between primary and secondary onset):
```{r, si}
si <- get_pairwise(x, attribute = "dt_onset")
si
summary(si)
hist(si, col = "grey", border = "white", nclass = 30,
xlab = "Time to secondary onset (days)",
main = "Distribution of the serial interval")
```
# Contributors (by alphabetic order):
- [Finlay Campbell](https://github.com/finlaycampbell)
- [Thomas Crellen](https://github.com/tc13)
- [Thibaut Jombart](https://github.com/thibautjombart)
- [Nistara Randhawa](https://github.com/nistara)
- Bertrand Sudre
See details of contributions on: <br>
https://github.com/reconhub/epicontacts/graphs/contributors
Contributions are welcome via **pull requests**.
Please note that this project is released with a [Contributor Code of Conduct](CONDUCT.md). By participating in this project you agree to abide by its terms.
**Maintainer:** Finlay Campbell ([email protected])