Merge pull request #2 from FrancisCrickInstitute/web_docs

Web docs

DESCRIPTION

@@ -43,7 +43,12 @@ Suggests:
     rmarkdown,
     knitr,
     testthat (>= 3.0.0),
-    roxygen2
+    roxygen2,
+    broom,
+    ggrepel,
+    rstatix,
+    survival,
+    survminer
 Config/testthat/edition: 3
 VignetteBuilder: knitr
 LazyData: true

NAMESPACE

@@ -39,6 +39,7 @@ export(cg_load)
 export(cg_plot)
 export(cg_plot_meta)
 export(cg_save)
+export(cg_select)
 export(cg_select_visit)
 export(cg_window_by_episode)
 export(cg_window_by_metadata)
@@ -52,6 +53,7 @@ export(glimpse_metadata)
 export(group_data_trim)
 export(new_grouped_chronogram)
 export(new_tbl2chronogram)
+export(validate_chronogram)
 importFrom(dplyr,dplyr_col_modify)
 importFrom(dplyr,dplyr_reconstruct)
 importFrom(dplyr,dplyr_row_slice)

R/cg_add_experiment.R

@@ -1,78 +1,48 @@
-#' A helper function to add experimental data to a chronogram
+#' Add experimental data to a chronogram
 #'
-#' @param cg a chronogram object (class tbl_chronogram)
-#' @param experiment a tibble containing experimental data (with
-#'   columns: calendar_date, and the specified ID)
+#' @param cg a chronogram object (`class cg_tbl`)
+#' @param experiment a `tibble::tibble()` containing experimental data. The dates
+#'   and IDs columns in `cg` must be present in `experiment`.
 #'
-#' @return An object of chronogram class
-#' @seealso [chronogram::chronogram_skeleton()], [chronogram::chronogram()]
+#' @return A chronogram
+#' @seealso [chronogram::cg_assemble()],
+#' [chronogram::cg_add_treatment()],
+#' [chronogram::chronogram_skeleton()],
+#'   [chronogram::chronogram()]
 #' @export
 #'
 #' @examples
-#' \dontrun{
-#' ## a 3-person chronogram_skeleton ##
-#' small_study <- chronogram_skeleton(
-#'   col_ids = elig_study_id,
-#'   ids = c(1, 2, 3),
-#'   start_date = c("01012020"),
-#'   end_date = "10102021",
-#'   col_calendar_date = calendar_date
+#' ## Example 1: A small study ##-------------------------------------
+#' data(built_smallstudy)
+#' 
+#' ## Setup ##
+#' cg <- built_smallstudy$chronogram
+#' 
+#' infections_to_add <- tibble::tribble(
+#'   ~calendar_date, ~elig_study_id, ~LFT, ~PCR, ~symptoms,
+#'   "01102020", "1", "pos", NA, NA,
+#'   "11102020", "1", "pos", NA, "severe"
 #' )
-#'
-#' ## Create a tibble containing some metadata for our 3 individuals ##
-#' small_study_metadata <- tibble::tribble(
-#'   ~elig_study_id, ~age, ~sex, ~dose_1, ~date_dose_1, ~dose_2, ~date_dose_2,
-#'   1, 40, "F", "AZD1222", "05/01/2021", "AZD1222", "05/02/2021",
-#'   2, 45, "F", "BNT162b2", "05/01/2021", "BNT162b2", "05/02/2021",
-#'   3, 35, "M", "BNT162b2", "10/01/2021", "BNT162b2", "10/03/2021"
-#' )
-#'
-#' ## Set appropriate metadata column classes ##
-#' small_study_metadata <- small_study_metadata %>%
-#'   mutate(across(c(sex, dose_1, dose_2), ~ as.factor(.x)))
-#'
-#' small_study_metadata <- small_study_metadata %>%
-#'   mutate(across(contains("date"), ~ lubridate::dmy(.x)))
-#'
-#' ## Make a chronogram ##
-#' small_study_chronogram <- chronogram(
-#'   small_study,
-#'   small_study_metadata
+#' ## Make calendar_date a date ##
+#' infections_to_add$calendar_date <- lubridate::dmy(
+#'   infections_to_add$calendar_date
 #' )
-#'
-#'
-#' ## Create a tibble of exemplar experimental data ##
-#' # suggest naming assays as {source}_{test}, eg serum_Ab
-#' # as SARS-CoV-2 PCRs could be reasonably performed
-#' # on stool, blood, sputum, BAL etc.
-#' # chronogram package does not enforce any rules here.
-#' #
-#' small_study_Ab <-
-#'   tibble::tribble(
-#'     ~elig_study_id, ~calendar_date, ~serum_Ab_S, ~serum_Ab_N,
-#'     1, "05/01/2021", 500, 100,
-#'     1, "15/01/2021", 4000, 100,
-#'     1, "03/02/2021", 3750, 100,
-#'     1, "15/02/2021", 10000, 100,
-#'     2, "05/01/2021", 0, 0,
-#'     2, "15/01/2021", 4000 / 2, 0,
-#'     2, "03/02/2021", 3750 / 2, 0,
-#'     2, "15/02/2021", 10000 / 2, 0,
-#'     3, "05/01/2021", 0, 0,
-#'     3, "25/01/2021", 4000 / 2, 0,
-#'     3, "03/02/2021", 3750 / 2, 0,
-#'     3, "20/03/2021", 10000 / 2, 0
-#'   )
-#'
-#' small_study_Ab <- small_study_Ab %>%
-#'   mutate(across(contains("date"), ~ lubridate::dmy(.x)))
-#'
-#' ## Add to chronogram ##
-#' small_study_chronogram <- cg_add_experiment(
-#'   small_study_chronogram,
-#'   small_study_Ab
+#' ## Add this new experiment data ##
+#' cg_added <- cg_add_experiment(cg, infections_to_add)
+#' 
+#' ## Example 2: Incorrect column names ##----------------------------
+#' 
+#' ## Setup as for Example 1 ##
+#' infections_to_add_renamed <- infections_to_add %>%
+#' dplyr::rename(ID = elig_study_id)
+#' 
+#' ## this fails ##
+#' try(
+#' cg_added_2 <- cg_add_experiment(cg, 
+#' infections_to_add_renamed)
 #' )
-#' }
+#' 
+#'##------------------------------------------------------------------
 cg_add_experiment <- function(
     cg,
     experiment) {

R/cg_add_treatment.R

@@ -1,37 +1,53 @@
-#' A helper function to add treatment data to a chronogram
+#' Add treatment data to a chronogram
 #'
-#' @param cg a chronogram object (class cg_tbl)
-#' @param treatment a tibble containing treatment dates (with columns:
-#'   the specified calendar_date, and ID columns, defined with
-#'   [chronogram::chronogram_skeleton()])
-#'
-#' This code wraps the`cg_add_experiment` function.
+#' @param cg a chronogram object (`class cg_tbl`)
+#' @param treatment a `tibble::tibble()` containing treatment data.
+#'   The dates and IDs columns in `cg` must be present in
+#'   `experiment`.
 #'
 #' @return A chronogram
 #' @seealso [chronogram::cg_add_experiment()]
 #' @export
 #'
 #' @examples
-#' \dontrun{
-#'
-#' ## Create a tibble of exemplar treatment data ##
+#' ## Example 1: A small study ##-------------------------------------
+#' library(dplyr)
+#' data(built_smallstudy)
+#' 
+#' ## Setup ##
+#' cg <- built_smallstudy$chronogram
+#' 
+#' # Create a tibble of exemplar treatment data
 #' # Here, we have treated ID=1 with B cell depletion
 #' # therapy, rituximab (RTX).
-#' #
-#' small_study_treatment <-
+#' 
+#' treatments_to_add <-
 #'   tibble::tribble(
 #'     ~elig_study_id, ~calendar_date, ~treatment,
 #'     1, "01/02/2021", "RTX"
 #'   )
-#' small_study_treatment <- small_study_treatment %>%
+#'   
+#' ## Make calendar_date a date class ##
+#' treatments_to_add <- treatments_to_add %>%
 #'   mutate(across(contains("date"), ~ lubridate::dmy(.x)))
-#'
-#' ## Add to chronogram ##
-#' small_study_chronogram <- cg_add_treatment(
-#'   small_study_chronogram,
-#'   small_study_treatment
+#'   
+#' ## Add this new treatment data ##
+#' cg_added <- cg_add_experiment(cg, treatments_to_add)
+#' 
+#' ## Example 2: Incorrect column names ##----------------------------
+#' 
+#' ## Setup as for Example 1 ##
+#' treatments_to_add_renamed <- treatments_to_add %>%
+#' dplyr::rename(ID = elig_study_id)
+#' 
+#' ## this fails ##
+#' try(
+#' cg_added_2 <- cg_add_experiment(cg, 
+#' treatments_to_add_renamed)
 #' )
-#' }
+#' 
+#'##------------------------------------------------------------------
+
 cg_add_treatment <- function(
     cg,
     treatment) {

R/cg_annotate_antigenic_history.R

@@ -1,6 +1,6 @@
 #' Calculate and assign flags based on infection history
 #'
-#' @param x a chronogram
+#' @param cg a chronogram
 #'
 #' @param episode_number a character vector to identify the
 #'   episode_number column. Default is "episode_number".
@@ -15,17 +15,85 @@
 #' @export
 #'
 #' @examples
-#' \dontrun{
-#' cg <- cg_annotate_label_episodes(cg)
-#' }
+#' library(dplyr)
+#' 
+#' data("built_smallstudy")
+#' cg <- built_smallstudy$chronogram
+#' 
+#' ## add infections to chronogram ##
+#' cg <- cg_add_experiment(
+#'   cg,
+#'   built_smallstudy$infections_to_add
+#' )
+#' 
+#' ## annotate infections ## 
+#' cg <- cg_annotate_episodes_find(
+#'    cg,
+#'    infection_cols = c("LFT", "PCR", "symptoms"),
+#'    infection_present = c("pos", "Post", "^severe")
+#' )
+#'
+#' ## annotate vaccines ## 
+#' cg <- cg %>% cg_annotate_vaccines_count(
+#'  ## the prefix to the dose columns: ##
+#'  dose = dose,
+#'  ## the output column name: ##
+#'  dose_counter = dose_number,
+#'  ## the prefix to the date columns: ##
+#'  vaccine_date_stem = date_dose,
+#'  ## use 14d to 'star' after a dose ##
+#'  intermediate_days = 14)
+#' 
+#' ## annotate exposures ##
+#'cg <- cg %>% cg_annotate_exposures_count(
+#'  episode_number = episode_number,
+#'  dose_number = dose_number,
+#'  ## we have not considered episodes of seroconversion
+#'  N_seroconversion_episode_number = NULL
+#'  )
+#'  
+#' ## assign variants ##
+#' cg <- cg %>%
+#' mutate(
+#' episode_variant =
+#' case_when(
+#'     # "is an episode" & "PCR positive" -> Delta #
+#'     (!is.na(episode_number)) & PCR == "Pos" ~ "Delta",
+#'     # "is an episode" & "PCR unavailable" -> Anc/Delta #
+#'     (!is.na(episode_number)) & PCR == "not tested" ~ "Anc/Alpha"
+#' )
+#' )
+#' ## ^ this gives a variant call on a SINGLE row of each episode
+#' 
+#' ## fill the variant call ##
+#'cg <- cg %>% cg_annotate_episodes_fill(
+#'  col_to_fill = episode_variant,
+#'  col_to_return = episode_variant_filled,
+#'  .direction = "updown",
+#'  episode_numbers_col = episode_number
+#'  )
+#'  
+#'  cg <- cg %>% 
+#'  mutate(
+#'  episode_variant_summarised =    episode_variant_filled
+#'  ) %>%
+#'  cg_annotate_antigenic_history(
+#'      episode_number = episode_number,
+#'          dose_number = dose_number,
+#'          episode_variant_summarised = episode_variant_summarised,
+#'              ag_col = antigenic_history
+#'              )
+#'
+#'  ## and finally:
+#'  summary(factor(cg$antigenic_history))
 #'
 cg_annotate_antigenic_history <- function(
-    x,
+    cg,
     episode_number = episode_number,
     dose_number = dose_number,
     episode_variant_summarised = episode_variant_summarised,
     ag_col = antigenic_history) {
-  attributes_x <- attributes(x)
+  attributes_x <- attributes(cg)
 
   ids_column_name <- attributes_x$col_ids
   calendar_date <- attributes_x$col_calendar_date
@@ -36,14 +104,14 @@ cg_annotate_antigenic_history <- function(
     )
 
   stopifnot(
-    "Chronogram x must contain a \"dose_number\" column,
+    "Chronogram must contain a \"dose_number\" column,
     showing number of doses at this calendar date.
     Consider using the cg_annotate_vaccines_count()
-    function first." = "dose_number" %in% colnames(x)
+    function first." = "dose_number" %in% colnames(cg)
   )
 
   ## make a vector of with times of individuals ##
-  y <- x %>%
+  y <- cg %>%
     tibble::as_tibble() %>%
     group_by({{ ids_column_name }}) %>%
     dplyr::filter(!is.na({{ episode_number }})) %>%
@@ -97,7 +165,7 @@ cg_annotate_antigenic_history <- function(
   ## that person does not have a combined
   ## reported ag_col.
 
-  z <- x %>%
+  z <- cg %>%
     tibble::as_tibble() %>%
     dplyr::group_by(
       dplyr::across(
@@ -130,7 +198,7 @@ cg_annotate_antigenic_history <- function(
 
   y <- dplyr::bind_rows(z, y)
 
-  y <- dplyr::left_join(x, y, by = ids_column_name)
+  y <- dplyr::left_join(cg, y, by = ids_column_name)
 
   validate_chronogram(y)