Merge pull request #4 from ashm97/main

Version v0.1.0

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: StEP
 Type: Package
 Title: Revealing missed transmission of infectious disease with contact mediated by movements
-Version: 0.0.1
+Version: 0.1.0
 Author: Ashleigh C. Myall
 Maintainer: Ashleigh C. Myall <a.myall19@imperial.ac.uk>
 Description: an R package implementing a novel contact model which recovers undetected transmission of healthcare-associated infections

R/cknneighbors_graph.R

@@ -1,18 +1,14 @@
-#' @title Implementation of of Continuous k-Nearest Neighbors (CKNN) in R
+#' @title Implementation of of Continuous k-Nearest Neighbors (CKNNs) in R
 #'
-#' @description See https://arxiv.org/pdf/1606.02353.pdf. CKNN connect points x,y
-#'
-#' if d(x,y) < lambda * ( d(x,x_k) * d(y,y_k) )^0.5
-#'
-#' Where d(x,y) is the distance between points x and y. And x_k, and y_k, are the
-#' k-th closest neighbors of points x and y respectively.
+#' @description CKNNs connect points x,y if \eqn{d(x,y) < lambda * (d(x,x_k) * d(y,y_k))^0.5}, where \eqn{d(x,y)} is the distance between points x and y, and variables \eqn{x_k} and \eqn{y_k}
+#' are the k-th closest neighbors of points x and y, respectively. See \url{https://arxiv.org/pdf/1606.02353.pdf} for details.
 #'
 #' @param k integer: number of neighbors
 #' @param lambda double: positive parameter regulating density.
 #' @param edges dataframe: weighted undirected edge list for similarity between
 #' trajectories.
 #'
-#' @return dataframe of edges with CKNN selected edges only.
+#' @return A dataframe of edges with CKNNs selected edges only.
 #' @export
 #' @author Ashleigh C. Myall (\email{a.myall19@@imperial.ac.uk})
 #  Copyright (C) 2020-2021 Ashleigh C. Myall

R/comp_dist.R

@@ -1,6 +1,6 @@
 #' @title Compute space and time distance matricies
 #'
-#' @descript Given two trajectories of length m and n respectively, form 2 m x n matricies
+#' @description Given two trajectories of length m and n respectively, form 2 m x n matricies
 #' corresponding to trajectory locations. One matrix dist_spatial, confers to
 #' distance across a background movement graph, and another matrix dist_temporal
 #' is the temporal distance between trajectory locations.
@@ -10,7 +10,7 @@
 #' @param D matrix: effective distance matrix, with elements the shortest path effective
 #' distance weight between nodes i and j
 #'
-#' @return list of ditance matricies
+#' @return A list of ditance matricies
 #' @export
 #' @author Ashleigh C. Myall (\email{a.myall19@@imperial.ac.uk})
 #  Copyright (C) 2020-2021 Ashleigh C. Myall

R/eff_dist.R

@@ -1,35 +1,34 @@
-#' @title Effective distances from background movement
+#' @title Effective distances from background movements
 #'
 #' @description Return shortest paths between locations in terms of effective distance given
-#' a background movement. Effective distance (as described in https://science.sciencemag.org/content/342/6164/1337),
+#' background movements. Effective distances are defined as per the paper at \url{https://science.sciencemag.org/content/342/6164/1337}.
 #'
+#' @section Details:
 #' Routes of disease spread are often dominated by a set of most probable trajectories.
 #' These probable trajectories can be derived using the effective distance given a
-#' flux connectivity matrix $P$ from a systems mobility patterns. In $P$, elements
-#' $P_{ij}$ confer to the fraction of departing individuals leaving node (representing
-#' hospital wards in this study) $v_i$ and arriving at node $v_j$, such that $1 < P_{ij} \leq  1$.
-#' Given $P$ define effective distance $d_ij$ between as,
+#' flux connectivity matrix $P$ from a systems mobility patterns. In P, elements
+#' \eqn{P_{ij}} confer to the fraction of departing individuals leaving node (representing
+#' hospital wards in this study) \eqn{v_i} and arriving at node \eqn{v_j}, such that \eqn{1 < P_{ij} \leq 1}.
+#' Given P, we define the effective distance d_{ij} between locations: \deqn{d_{ij}= (1 - \log P_{ij} ) \leq 1}
 #'
-#' d_{ij}= (1 - \log P_{ij} ) \leq 1.
-#'
-#' In $d_ij$ a low proportion of movement from $ v_i \rightarrow v_j$ is corresponds
-#' to a large effective distance. Explained in greater detail in https://science.sciencemag.org/content/342/6164/1337,
+#' In \eqn{d_{ij}}, a low proportion of movement from \eqn{v_i \rightarrow v_j} is corresponds
+#' to a large effective distance. Explained in greater detail in \url{https://science.sciencemag.org/content/342/6164/1337},
 #' the logarithm captures effective distances are additive along multi-step pathways.
-#' Hence, deriving the most probable trajectories of disease spread from $ v_i \rightarrow v_j$
-#' is given by the directed path $\delta_{ij} = \{v_i \rightarrow,...,\rightarrow v_j\}$
-#' with the smallest total effective distance $\lambda ( \Gamma )$:
+#' Hence, deriving the most probable trajectories of disease spread from \eqn{v_i \rightarrow v_j}
+#' is given by the directed path \eqn{\delta_{ij} = \{v_i \rightarrow,...,\rightarrow v_j\}}
+#' with the smallest total effective distance \eqn{\lambda(\Gamma)}:
 #'
-#' \hat{\delta_{ij}} =  \min_{ \lambda } \lambda \;( \delta_{ij} ).
+#' \deqn{\hat{\delta_{ij}} =  \min{\lambda}_\lambda \lambda(\delta_{ij})}
 #'
-#' Typically, $\hat{\delta_{ij}}  \neq \hat{\delta_{hi}}$, since patient movement
+#' Typically, \eqn{\hat{\delta_{ij}}  \neq \hat{\delta_{hi}}}, since patient movement
 #' patterns vary depending on procedures a given ward offers, and their starting
-#' locations. Also note, for paths a shortest path $\hat{\delta_{ij}}$ may not
+#' locations. Also note, for paths a shortest path \eqn{\hat{\delta_{ij}}} may not
 #' exist (i.e for wards which are purely entry or exit points in the hospital).
 #'
-#' @param edges dataframe: directed and weighted edge dataframe capturing bacgkround
-#' movement between source nodes and target nodes.
+#' @param edges dataframe: directed and weighted edge dataframe capturing the background
+#' movements between source nodes and target nodes.
 #'
-#' @return effective distance matrix, with elements the shortest path effective
+#' @return An effective-distance matrix, with elements the shortest path effective
 #' distance weight between nodes i and j
 #' @export
 #' @author Ashleigh C. Myall (\email{a.myall19@@imperial.ac.uk})

R/example_trajectories.R

@@ -3,7 +3,7 @@
 #' @description A pre-built function with no arguements to return example trajectories. Each trajectory
 #' contains a location (ward), and a corresponding time (date) on that location.
 #'
-#' @return Dataframe in long format with each row contiang the unique location-time
+#' @return A dataframe in long format with each row contiang the unique location-time
 #' positions of each trajectory
 #'
 #' @export

R/getSpatialTempProx.R

@@ -9,7 +9,7 @@
 #' proximity. beta can also be intepreted as speed of proporgation across the
 #' background mobility data. To pass when for the spatial temporal proximity kernal (matrix computation).
 #'
-#' @return weighted edge list of similarities between trajectories.
+#' @return A weighted-edge list of similarities between trajectories.
 #' @export
 #' @author Ashleigh C. Myall (\email{a.myall19@@imperial.ac.uk})
 #  Copyright (C) 2020-2021 Ashleigh C. Myall

R/kernal_dist.R

@@ -1,25 +1,27 @@
 #' @title Spatial temporal proximity kernal (matrix computation)
 #'
-#' @description Computes total spatial temporal proximities using the kernal. For every pair
-#' of patients, we define spatio-temporal proximity between ward-time locations
-#' $l_{i}$ and $l_{j}$ with the kernel:
+#' @description Computes total spatial temporal proximities using the kernal.
 #'
-#' \kappa(l_{i},l_{j})  = e^{-\delta_{ij}-\beta \tau_{ij}},
+#' @section Details:
+#' For every pair of patients, we define spatio-temporal proximity between ward-time locations
+#' \eqn{l_{i}} and \eqn{l_{j}} with the kernel:
 #'
-#' where $\tau_{ij}=\begin{vmatrix}t_i - t_j\end{vmatrix}$, parameter $\beta$
-#' represents a propagation speed, and $\delta_{ij}$ denotes the shortest-path
+#' \deqn{\kappa(l_{i},l_{j})  = e^{-\delta_{ij}-\beta \tau_{ij}}}
+#'
+#' where \eqn{tau_{ij}=\begin{vmatrix}t_i - t_j\end{vmatrix}}, parameter \eqn{\beta}
+#' represents a propagation speed, and \eqn{\delta_{ij}} denotes the shortest-path
 #' distance (the most probable pathway for disease propagation) between wards
-#' $v_i$ and $v_j$ across the background movement network $G$.
+#' \eqn{v_i} and \eqn{v_j} across the background movement network \eqn{G}.
 #' Note the equation reaches a maximum of one when
-#' $l_{ia} = l_{jb}$ (exact overlaps), and decays to zero as spatial-temporal
+#' \eqn{l_{ia} = l_{jb}} (exact overlaps), and decays to zero as spatial-temporal
 #' proximity becomes more distant. We then measure overall similarity between
-#' trajectories $T_m$ and $T_n$ by summing over pairwise proximity measures
-#' between $l_i \in T_n$ and $l_j \in T_m$:
-#'
-#' \mathcal{S}(T_n,T_m) =  \sum_{l_i \in T_n} \, \sum_{l_j \in T_m} \kappa(l_{i},l_{j}).
+#' trajectories \eqn{T_m} and \eqn{T_n} by summing over pairwise proximity measures
+#' between \eqn{l_i \in T_n$ and $l_j \in T_m}:
 #'
+#' \deqn{S(T_n,T_m) =  \sum_{l_i \in T_n}\sum_{l_j \in T_m}\kappa(l_{i},l_{j})}
 #'
-#' Full description found in XXXX LINK PAPER XXXXX
+#' A full description can be found in our paper: \url{https://doi.org/10.1101/2021.04.07.21254497}
+#' about this package.
 #'
 #' @param beta double: paramter regulating the effect of time in spatial-temporal
 #' proximity. beta can also be intepreted as speed of proporgation across the
@@ -29,7 +31,7 @@
 #' @param time_d matrix: pairwise time distances between locations of
 #' two trajectories.
 #'
-#' @return sum of spatial-temporal proximities
+#' @return Sum of spatial-temporal proximities
 #' @export
 #' @author Ashleigh C. Myall (\email{a.myall19@@imperial.ac.uk})
 #  Copyright (C) 2020-2021 Ashleigh C. Myall

R/plot_trajectories.R

@@ -1,10 +1,10 @@
 #' @title Plot pathways function
 #'
-#' @description Build ggplot visualisation for time components of trajectories
+#' @description Build ggplot visualisation for time components of trajectories.
 #'
-#' @param traj.l List: list of trajectory dataframes
+#' @param traj.l A list of trajectory dataframes
 #'
-#' @return GGplot visulisation
+#' @return A ggplot object for visualisation
 #'
 #' @export
 #'

R/preproNet.R

@@ -1,10 +1,12 @@
-#' @title Preprocess data for nodes and edges
+#' @title Preprocess data for creating nodes and edges
+#'
+#' @description A function creating nodes and edges from input trajectory data.
 #'
 #' @param trajectories dataframe: full trajectory dataframe (long format)
 #' @param edges dataframe: weighted undirected edge list for similarity between
 #' trajectories.
 #'
-#' @return list: list of nodes and edges for visualisation.
+#' @return list: A list of nodes and edges for visualisation.
 #' @export
 #' @author Ashleigh C. Myall (\email{a.myall19@@imperial.ac.uk})
 #  Copyright (C) 2020-2021 Ashleigh C. Myall

README.md

@@ -2,7 +2,11 @@
 
 ## Paper overview
 
-We introduce a novel contact model which recovers undetected transmission of infectious disease (*Myall et. al 2021*). Outbreaks of disease are both burdensome and extremely common. Contact tracing based on direct contacts is often used in disease outbreaks to prevent further spread. However, missing and indirect contacts pose severely limit contact tracing and result in misleading conclusions. 
+**Citation**
+
+Myall, A. C., Peach, R. L., Wan, Y., Mookerjee, S., Jauneikaite, E., Bolt, F., Price, J. R., Davies, F., Wiesse, A. Y., Holmes, A., & Barahona, M. (2021). Characterising contact in disease outbreaks via a network model of spatial-temporal proximity. *MedRxiv*, 2021.04.07.21254497. https://doi.org/10.1101/2021.04.07.21254497.
+
+In this article, we introduce a novel contact model which recovers undetected transmission of infectious disease. Outbreaks of disease are both burdensome and extremely common. Contact tracing based on direct contacts is often used in disease outbreaks to prevent further spread. However, missing and indirect contacts pose severely limit contact tracing and result in misleading conclusions. 
 
 <p align="center">
   <img src="images/fig_intro_missing_data.png" width="400">
@@ -18,7 +22,7 @@ Here, we propose a Spatial-temporal Epidemiological Proximity (StEP) model, base
 
 <sub>*Model overview. Firstly, patient movement histories are captured as a set of network trajectories passing through nodes of a background movement graph D (Panel A). Typically, only direct contact is considered when determine transmission from infected patient movement, however, this inherently missed indirect contact which can also be a source of disease transmission. Our model recovers both indirect and direct contact by measuring points between trajectories in terms of the spatial proximity delta (network-wise) and temporal proximity tau (Panel B). This spatial-temporal proximity allows us to quantifies how close patients have into a mathematical object (a patient trajectory similarity matrix) S (Panel C). Given disease portability of disease transmission increases the longer patients coincide, we recover the contact leading to transmission by forming a contact graph S hat by looking for strongest contact patterns (weighted by proximity) in S (Panel D).*</sub>
 
-In our preprint (*Myall et. al 2021*) we showcased StEP's ability to capture transmission routes in outbreaks of healthcare-acquired infections between hospital patients and demonstrated its efficacy with a partnered genomic analysis. Using a semi-supervised learning framework and bio-markers obtained from Whole Genome Sequencing, we showed that our model reveals missing patient interactions that improve disease transmission characterisation.
+In our preprint (*Myall et. al 2021*), we showcased StEP's ability to capture transmission routes in outbreaks of healthcare-acquired infections between hospital patients and demonstrated its efficacy with a partnered genomic analysis. Using a semi-supervised learning framework and bio-markers obtained from Whole Genome Sequencing, we showed that our model reveals missing patient interactions that improve disease transmission characterisation.
 
 
 ## Repo overview