Merge contributions from summit's challenge

.Rbuildignore

@@ -8,3 +8,4 @@
 ^\.lintr$
 ^.*\.Rproj$
 ^\.Rproj\.user$
+^scratch\.R$

.github/CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing to vaccineff
+
+This outlines how to propose a change to vaccineff.
+
+## Making changes
+
+If you want to make a change, it's a good idea to first file an issue and make sure someone from the team agrees that it’s needed.
+If you’ve found a bug, please file an issue that illustrates the bug with a minimal 
+[reprex](https://www.tidyverse.org/help/#reprex) (this will also help you write a unit test, if needed). See [bug report template](https://github.com/epiverse-trace/vaccineff/issues/new?assignees=&labels=&template=bug_report.md&title=). If you have a feature request see [feature request](https://github.com/epiverse-trace/vaccineff/issues/new?assignees=&labels=&template=feature_request.md&title=).
+
+### Pull request process
+
+See [pull request template](https://github.com/epiverse-trace/vaccineff/blob/main/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md)
+
+*   Fork the package and clone onto your computer. If you haven't done this before, we recommend using `usethis::create_from_github("epiverse-trace/vaccineff", fork = TRUE)`.
+
+*   Install all development dependencies with `devtools::install_dev_deps()`, and then make sure the package passes R CMD check by running `devtools::check()`. 
+    If R CMD check doesn't pass cleanly, it's a good idea to ask for help before continuing. 
+*   Create a Git branch for your pull request (PR). We recommend using `usethis::pr_init("brief-description-of-change")`.
+
+*   Make your changes, commit to git, and then create a PR by running `usethis::pr_push()`, and following the prompts in your browser.
+    The title of your PR should briefly describe the change.
+    The body of your PR should contain `Fixes #issue-number`.
+
+*  For user-facing changes, add a bullet to the top of `NEWS.md` (i.e. just below the first header). Follow the style described in <https://style.tidyverse.org/news.html>.
+
+### Code style
+
+*   New code should follow the tidyverse [style guide](https://style.tidyverse.org). 
+    You can use the [styler](https://CRAN.R-project.org/package=styler) package to apply these styles, but please don't restyle code that has nothing to do with your PR.  
+
+*  We use [roxygen2](https://cran.r-project.org/package=roxygen2), with [Markdown syntax](https://cran.r-project.org/web/packages/roxygen2/vignettes/rd-formatting.html), for documentation.  
+
+*  We use [testthat](https://cran.r-project.org/package=testthat) for unit tests. 
+   Contributions with test cases included are easier to accept.  
+
+## Code of Conduct
+
+Please note that the vaccineff project is released with a
+[Contributor Code of Conduct](https://github.com/epiverse-trace/.github/blob/main/CODE_OF_CONDUCT.md). By contributing to this
+project you agree to abide by its terms.

.gitignore

@@ -52,3 +52,6 @@ rsconnect/
 .DS_Store
 inst/doc
 docs
+
+# scratch file for development
+scratch.R

DESCRIPTION

@@ -1,30 +1,38 @@
 Package: vaccineff
-Title: Estimation of the Vaccines Effectiveness Based on Different Designs
+Title: Estimate Vaccine Effectiveness Based on Different Study Designs
 Version: 0.0.1
 Authors@R: c(
-    person(given = "Zulma M.", family = "Cucunubá", email = "zulma.cucunuba@javeriana.edu.co", role = c("aut", "cre")),
-    person(given = "David Santiago", family = "Quevedo", email = "ex-dsquevedo@javeriana.edu.co", role = c("aut")),
-    person(given = "Santiago", family = "Loaiza", email = "santiago.loaiza@javeriana.edu.co", role = c("aut")),
-    person(given = "Geraldine", family = "Gómez Millán", email = "geralidine.gomez@javeriana.edu.co", role = c("ctb"))
+    person(given = "Zulma M.", family = "Cucunubá", email = "zulma.cucunuba@javeriana.edu.co", role = c("aut", "cre"),
+        comment = c(ORCID = "https://orcid.org/0000-0002-8165-3198")),
+    person(given = "David Santiago", family = "Quevedo", email = "ex-dsquevedo@javeriana.edu.co", role = c("aut"),
+        comment = c(ORCID = "https://orcid.org/0000-0003-1583-4262)")),
+    person(given = "Santiago", family = "Loaiza", email = "santiago.loaiza@javeriana.edu.co", role = c("aut"),
+        comment = c(ORCID = "https://orcid.org/0000-0002-2092-3262")),
+    person(given = "Geraldine", family = "Gómez Millán", email = "geralidine.gomez@javeriana.edu.co", role = c("ctb"),
+        comment = c(ORCID = "https://orcid.org/0009-0007-8701-0568")),
+    person(given = "Pratik", family = "Gupte", email = "pratik.gupte@lshtm.ac.uk", role = c("ctb"), 
+           comment = c(ORCID = "https://orcid.org/0000-0001-5294-7819"))
   )
-Description: A package to estimate the vaccines effectiveness based on different designs.
-    following format: Author et al. (2023) <doi:10.5281/zenodo.6619350>.
+Description: Estimate vaccine effectiveness based on different observational study designs, as discussed in Torvaldsen and McIntyre (2020) <doi:10.3316/informit.511798489353134>.
+URL: https://github.com/epiverse-trace/vaccineff, https://epiverse-trace.github.io/vaccineff/
+BugReports: https://github.com/epiverse-trace/vaccineff/issues
 License: MIT + file LICENSE
 Encoding: UTF-8
 LazyData: true
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.2.3
+Depends: 
+    R (>= 3.5.0)
 Imports: 
-    data.table,
-    dplyr,
-    rlang,
     survival,
-    stats
+    stats,
+    checkmate
 Suggests: 
     knitr,
     rmarkdown,
     spelling,
-    testthat (>= 3.0.0)
+    testthat (>= 3.0.0),
+    qtl
 Config/testthat/edition: 3
 Config/Needs/website:
     epiverse-trace/epiversetheme

LICENSE

@@ -1,2 +1,2 @@
-YEAR: 2022
-COPYRIGHT HOLDER: readepi authors
+YEAR: 2023
+COPYRIGHT HOLDER: vaccineff authors

LICENSE.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright (c) 2022 readepi authors
+Copyright (c) 2023 vaccineff authors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

NAMESPACE

@@ -8,5 +8,3 @@ export(get_immunization_dose)
 export(get_immunization_vaccine)
 export(get_time_to_event)
 export(set_status)
-import(dplyr)
-importFrom(dplyr,"%>%")

R/all_data_prep.R

@@ -1,45 +1,76 @@
-#' Method for constructing age-group variable from age column
-#' This method splits an age interval from min_val to max_val into
-#' (max_val-min_val)/step intervals.
-#' By default min_val is set 0, however it can be assigned by
+#' @title Construct age-group variable from age column
+#'
+#' @description This method splits an age interval from `min_val` to `max_val`
+#' into `(max_val - min_val) / step` intervals.
+#' By default `min_val` is set to 0, however it can be assigned by
 #' convenience.
-#' If the method finds ages greater or equal than max_val
-#' it assigns the string ">{max_val}".
-#' To avoid errors it is necessary to set step < max_val.
+#' If the method finds ages greater or equal than `max_val`
+#' it assigns the string `">max_val"`.
+#' To avoid errors it is necessary to set `step < max_val`.
 #' It is also suggested to choose the step such
-#' that max_val%%(step+1) = 0
+#' that `max_val %% (step + 1) == 0`.
+#'
 #' @param data dataset with at least a column containing the age
 #' information
 #' @param col_age name of the column containing the age
 #' information
-#' @param  max_val maximum value of age interval to split
-#' @param  step step used to split the age interval
-#' @param  min_val minimum value of age interval to split
-#' @return age_group
-#' @examples
-#' \dontrun{
-#' cohortdata <- data(cohortdata)
-#' cohortdata$age.group <- get_age_group(
-#' data = cohortdata,
-#' col_age = "age",
-#' max_val = 80,
-#' step = 9)
-#' }
+#' @param max_val maximum value of age interval to split
+#' @param step step used to split the age interval
+#' @param min_val minimum value of age interval to split
+#' @return A `factor` object of the same length as the number of rows in `data`,
+#' with levels corresponding to age bins between `min_val` and `max_val`.
+#' Ages above `max_val` are represented as `>max_val`.
 #' @export
+#' @examples
+#' # load data provided with the package
+#' data(cohortdata)
+#'
+#' # assign age groups as a column of the data frame
+#' cohortdata$age_group <- get_age_group(
+#'   data = cohortdata,
+#'   col_age = "age",
+#'   max_val = 80,
+#'   step = 9
+#' )
+#'
+#' # view the data frame with new column
+#' head(cohortdata)
 get_age_group <- function(data, col_age, max_val, min_val = 0, step) {
+  # input checking
+  checkmate::assert_data_frame(
+    data,
+    min.rows = 1, min.cols = 1
+  )
+  checkmate::assert_string(col_age)
+  checkmate::assert_names(
+    names(data),
+    must.include = col_age
+  )
+  checkmate::assert_number(min_val, lower = 0)
+  checkmate::assert_number(max_val, lower = min_val)
+  checkmate::assert_number(step, lower = 1, upper = max_val)
+
+  # get breaks
   n_steps <- as.integer((max_val - min_val) / step) + 1
-  limits_low <- c(as.integer(seq(min_val,
-                                 max_val,
-                                 length.out = n_steps)))
-  limits_hgh <- limits_low + step
-  lim_labels <- paste(as.character(limits_low), as.character(limits_hgh),
-                      sep = "-")
-  lim_labels[length(lim_labels)] <- paste0("+",
-                                           limits_low[length(limits_low)])
-  lim_breaks <- c(-Inf, limits_low[2:length(limits_low)] - 1, Inf)
+  limits_low <- seq.int(
+    min_val, max_val,
+    length.out = n_steps
+  )
+  limits_high <- limits_low + step
 
+  # prepare labels
+  lim_labels <- paste(limits_low, limits_high, sep = "-")
+  lim_labels[length(lim_labels)] <- paste0(
+    ">",
+    limits_low[length(limits_low)]
+  )
+  lim_breaks <- c(-Inf, limits_low[seq(2, length(limits_low))] - 1, Inf)
+
+  # cut the age data and apply labels
   age_group <- cut(data[[col_age]],
-                   breaks = lim_breaks,
-                   labels = lim_labels)
+    breaks = lim_breaks,
+    labels = lim_labels
+  )
+
   return(age_group)
 }