---
title: "HospitalNetwork-Workflow"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{HospitalNetwork-Workflow}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Context

This R package contains functions to help interested researchers construct networks from data on movement of individual between locations. Although this package was initially developed in the context of networks of healthcare facilities, where the links represent transfer of subjects between facilities, the process can be generalized to the movement of any type of subject between any type of locations.

Formally, a network is composed of *nodes* which may or may not be connected by *edges* (or links). In the context of this package, the nodes are the facilities, and the links represent connections between facilities. Although the definition of a node is straightforward, one can define a *connection* between two facilities in different ways. This package allows to construct a network using various definition of a connection, which are discussed in detail here [ref].

In terms of data structure, a common way of representing a network is with a simple $n*n$ matrix (often called adjacency matrix, or contact matrix). The rows and columns contain the nodes (which appear once in each), and each cell contains the information on whether or not the two nodes are connected.


```{r adjacency-matrix, echo = FALSE, dev = 'svg', results = 'asis'}
data = c(0,0,602,0,339,687,0,0,0,0,373,1294,0,718,86,296,263,0,0,35,0,598,0,0,0)
mat = matrix(data, nrow = 5, ncol = 5)
colnames(mat) = LETTERS[1:5]
rownames(mat) = colnames(mat)
pander::pandoc.table(mat, caption = 'Example of a matrix representation of a 5-nodes network. By convention, the rows contain the facilities of origin, and the columns contain the target facilities. Each cell contains the number of subjects transfered.', )
```

At its core, the purpose of this package is to compute the contact matrix from raw data on movement between facilities. Additionally, this package provides the researcher with various tools to analyze and visualize the constructed network.


## Data

The package requires a minimal set of information in order to build a network of facilities. This set of data is describe under the section "Required data". To proceed to further analysis, the package can use additional information in case they are available. These informations are listed under the section "Optional informations". 

### Required data

The minimal data needed to construct the network is a simple table with four variables:

* **subject ID:** an identifier unique to each subject
* **facility ID:** an identifier unique to each facility
* **admission date:** the date of admission of the subject in the facility
* **discharge date:** the date of discharge of the subject from the facility

Therefore, each row must correspond to a unique stay of a subject in a facility. Stays are not allowed to overlap (see [Data management](#datamanagement)).

```{r data_example}
library(HospitalNetwork)
data = create_fake_subjectDB(n_subjects = 3, n_facilities = 3)
data
```

### Optional data (in the same database)

TODO

| Item          | Variable name     | Description                 |
|---------------|:-----------------:|-----------------------------|
|Mode of entry | entry | a variable indicating whether the subject arrived from home (0), or from a facility (1) |
|Mode of discharge | discharge | a variable indicating whether the subject is discharged back home (0), or to a facility (1) |
|Subject residential postcode | postcode | a variable indicating the postal code of the subject residency |
|Wards visited by the subject | ward | a single type of ward predominantly visited by the subject, coded as 1 for ICU or acute care and 0 for others |

### Optional data (in a separate database)

TODO

|Item| Variable name |Description|
|----|:-------------:|-----------|
|Facility localization| localization | GPS coordinates of the facility|
|Facility capacity | capacity | the number of beds available in the facility|
|Facility type | type | the type of facility (ECDC level definitions)|

## Workflow

The main function of the package is ```hospinet_from_subject_database()```, which takes the database as argument.
It will first performs various diagnostic tests by calling the function ```checkBase()```, to check for possible issues, and to ensure that the data is formatted correctly. 

If the tests are successful, ```hospinet_from_subject_database()``` will proceed with several operations and function calls to construct the network. The return value is an ```HospiNet``` R6 object that contains the network itself, as well as different metrics and information on the network.

### Diagnostic tests {#diag}

The diagnostic tests on the database are performed by the function ```checkBase()```.

The function will check for possible errors in the database. It also offer the possibility to automatically correct the issues it may have found in the database. However, since we cannot guarantee having checked for every possible issue, we encourage you to ensure the data is in the correct format, and is free of errors, prior to run the function. By default, ```checkBase()``` will not modify the database, but return informative messages on the issues found. If you wish the function to try to autocorrect the database, you must set the corresponding arguments (see [Data management](#datamanagement)). We recommend that you carefully check the result afterwards. 

```{r check_example, error = TRUE}
# Example
library(HospitalNetwork)
base = create_fake_subjectDB(n_subjects = 100, n_facilities = 10, with_errors = TRUE)
checkBase(base)
```

#### Requirements

The requirements to pass the diagnostic tests are the following:

* the database must be of class ```data.frame``` or ```data.table```. The functions are implemented in the ```data.table``` framework, so if a ```data.frame``` is provided, it will be converted to a ```data.table```.

* the database must have at least four columns. By default the column names must be: ```c("sID", "fID", "Adate", "Ddate"```. Although we recommend using these column names, it is possible to use different names by providing them as arguments.

* columns ```"sID"``` and ```"fID"``` must be of type ```character```.

* dates are handled using functions from the ```lubridate``` package. They should be ```POSIXct date-time objects```. Alternatively, they can be provided as character strings. In that case, you can use ```checkBase()``` to try to parse them to date-time objects using ```lubridate``` functions (see [Data management](#datamanagement)).

* stays should not overlap (see [Data management](#datamanagement) for more details).

#### Data management {#datamanagement}

The diagnostic functions of ```checkBase()``` will check for the following issues:

* missing values: the following values will be flagged as missing: actual missing values of the form ```NA``` or ```NaN```, character strings ``` "NA", "na", "Na", "N/A", "n/a", "N/a", "NaN")```, and empty character strings or empty quotes ```"", "''"```.

* discharge date of a stay anterior to its admission date.

* overlapping stays: **TODO**

You can use the function ```checkBase()``` to try to correct automatically the issues it has found by setting the corresponding arguments.

* missing values: to remove entries with missing values, set the argument ```deleteMissing```. If set to ```"record"```, the record with the missing value will be removed. If set to ```"subject"```, all records of the same subject will be removed.

* errors: to remove errors, such as discharge date of a stay anterior to admission date, set the argument ```deleteErrors```. If set to ```"record"```, the record with the error will be removed. If set to ```"subject"```, all records of the same subject will be removed.

* overlapping stays: ```checkBase()``` will automatically handle overlapping stays as follows: **TODO**

* dates: if admission and discharge dates are provided as character strings, you can use ```checkBase()``` to try to parse them to a date-time object, which uses internally the ```lubridate``` functions. To do that, set the argument ```convertDates = TRUE```. You must also specify in what format are the dates ("year-month-day", "day-month-year", etc.) by setting the argument ```dateFormat = c("ymd", "ydm", "dmy", "dym", "mdy", "myd")```.


## The *HospiNet* object

*HospiNet* is an R6 object containing the facility matrix as well as specific information regarding the network. We have developed a *summary* and a *print* method for this object. 
The information contained in an *HospiNet* objects are: 

* *n_facilities*, the number of facilities in the network,
* *n_subjects*, the number of subjects in the network,
* *n_movements*, the number direct or indirect (depending on the window size) transfers,
* *window_threshold*, the size of the movement window in days (0 for direct transfers between facilities),
* *hist_degrees*, *\_in*, *\_out*, are named vectors containing the number of nodes for each degree, indegree, or outdegree,
* ...


## Using the package

```{r setup, eval = FALSE}
library(HospitalNetwork)

```
```{r setup2, eval = TRUE}
mydbmed = create_fake_subjectDB(n_subjects = 100, n_facilities = 10)
hn = hospinet_from_subject_database(base = mydbmed, noloops = FALSE)
hn
```
```{r setup3, eval = TRUE}
plot(hn)
```
```{r setup4, eval = TRUE}
plot(hn, type = "degree")
```
```{r setup5, eval = TRUE}
plot(hn , type = "clustered_matrix")
```
```{r setup6, cache = FALSE, eval = TRUE}

mydb = create_fake_subjectDB_clustered(n_subjects = 10000, n_facilities = 100, n_clusters = 5)
hn = hospinet_from_subject_database(base = mydb, noloops = FALSE)
hn
```

```{r setup7, eval = TRUE}
plot(hn)
```

```{r setup8, eval = TRUE}
plot(hn, type = "degree")
```

```{r setup9, eval = TRUE}
plot(hn , type = "clustered_matrix")
```

```{r setup10, eval = TRUE}
#this plot may not work on some systems
#plot(hn , type = "circular_network")
```