A start to better documentation

Author: tystan

DESCRIPTION

@@ -13,4 +13,4 @@ Imports: compositions,
     robCompositions,
     testthat,
     ggplot2
-RoxygenNote: 7.1.0
+RoxygenNote: 7.1.1

R/append_ilr_coords.R

@@ -1,3 +1,29 @@
+#' Add ILR coordinates to a data.frame containing composition variables
+#'
+#' @description Add ILR coordinates to a data.frame containing composition variables
+#' @param dataf data.frame containing composition variables
+#' @param comps character vector of composition variable names in dataf
+#' @param psi ilrBase passed to \code{compositions::ilr()}
+#' @export
+#' 
+#' @examples
+#' library(deltacomp)
+#' data(fat_data)
+#' head(fat_data)
+#' comp_vars <- c("sl", "sb", "lpa", "mvpa")
+#' # create sequential binary partition
+#' sbp <- create_seq_bin_part(length(comp_vars))
+#' # The orthonormal transformation matrix
+#' psi <- compositions::gsi.buildilrBase(sbp)
+#' head(append_ilr_coords(
+#'   fat_data,
+#'   comp_vars,
+#'   psi
+#' ))
+#' 
+#' 
+#' 
+
 
 append_ilr_coords <- function(dataf, comps, psi) {
 

R/check_input_args.R

@@ -1,4 +1,30 @@
 
+#' Sanity checks for arguments passed to predict_delta_comps()
+#'
+#' @description Sanity checks for arguments passed to predict_delta_comps()
+#'
+#' @param dataf A \code{data.frame} containing data
+#' @param y Name (as string/character vector of length 1) of outcome variable in \code{dataf}
+#' @param comps Character vector of names of compositions in \code{dataf}. See details for more information.
+#' @param covars Character vector of covariates names  (non-comp variables) in \code{dataf} or NULL for none (default).
+#' @param deltas A vector of time-component changes (as proportions of compositions , i.e., values between -1 and 1). Optional. 
+#' @export
+#' @details 
+#' Throws errors for any problematic input. Returns \code{TRUE} invisibly if no issues found.
+#' @examples
+#' check_input_args(
+#'   dataf = fat_data,
+#'   y = "fat",
+#'   comps = c("sl", "sb", "lpa", "mvpa"),
+#'   covars = NULL,
+#'   deltas = seq(-60, 60, by = 5) / (24 * 60)
+#' )
+#' 
+#' 
+
+
+
+
 check_input_args <- function(dataf, y, comps, covars, deltas) {
 
 

R/check_strictly_positive_vals.R

@@ -1,3 +1,19 @@
+#' Check if compositional variable are strictly greater than 0
+#'
+#' @param dataf data.frame containing composition variables
+#' @param comps character vector of composition variable names in dataf
+#' @param tol a numeric value that compositional values are expected to be greater or equal than. 1e-6 is deafult
+#'
+#' @return
+#' If any compositional values are found to be strictly less than \code{tol} and erro is thrown. 
+#' Returns \code{TRUE} invisibly otherwise.
+#' @export
+#'
+#' @examples
+#' data(fat_data)
+#' check_strictly_positive_vals(fat_data, c("lpa", "sl"), tol = 1e-6) 
+#' # not run (throws error):
+#' # check_strictly_positive_vals(data.frame(a = rnorm(10)), "a", tol = 1e-6) 
 check_strictly_positive_vals <- function(dataf, comps, tol = 1e-6) {
 
   vals <- dataf[, comps]

R/cols_exist.R

@@ -1,3 +1,18 @@
+#' Check whether columns exist in a data.frame
+#'
+#' @param dataf a data.frame
+#' @param cols character vector of columns to be checked in \code{dataf}
+#'
+#' @return
+#' An error if all \code{cols} not present in \code{dataf}. 
+#' Returns \code{TRUE} invisibly otherwise.
+#' @export
+#'
+#' @examples
+#' data(fat_data)
+#' cols_exist(fat_data, c("lpa", "sl")) 
+#' # not run (throws error):
+#' # cols_exist(fat_data, "a") 
 cols_exist <- function(dataf, cols) {
 
   if (is_null_or_na(cols)) {

R/create_comparison_matrix.R

@@ -1,27 +1,45 @@
 
 
-# comparisons = "one-v-all"
-# comparisons = "prop-realloc"
-# comparisons = "one-v-one"
 
+#' Creates row-wise perturbations of compositions from the mean composition
+#'
+#' @param comparisons currently two choices:  \code{"one-v-one"} or  \code{"prop-realloc"} (default).
+#' @param comps the names (character vector) of the compositional variables
+#' @param mean_comps the mean composition of \code{comps}
+#' @details 
+#' \code{comparisons = "one-v-one"} creates a matrix with \code{length(comps)} columns and \code{length(comps) * (length(comps) - 1)} rows. 
+#' The rows contain all pairs of variables with 1 and -1 values.
+#' 
+#' \code{comparisons = "prop-realloc"} creates a matrix with \code{length(comps)} columns and \code{length(comps)} rows. 
+#'  Each rows contains a 1 value for a compositional variable and the remaining values sum to -1 proportional to the \code{mean_comps} value for those variables. 
+#' 
+#' Note that for both \code{comparisons} options the net change is 0 (each row sums to 0).
+#' @export
+#'
+#' @examples
+#' create_comparison_matrix("one-v-one", LETTERS[1:3], c(0.5, 0.3, 0.2))
+#' create_comparison_matrix("prop-realloc", LETTERS[1:3], c(0.5, 0.3, 0.2))
 create_comparison_matrix <- function(comparisons, comps, mean_comps) {
 
   K <- poss_comps0 <- NULL
   n_comp <- length(comps)
 
-  if (comparisons == "one-v-all") {
+  ### depreciated
+  # if (comparisons == "one-v-all") {
+  #   
+  #   # number of combinations is:
+  #   # K = n_comps as only one combination per composition
+  #   K <- n_comp
+  #   poss_comps0 <- matrix(0, nrow = K, ncol = n_comp, dimnames = list(NULL, comps))
+  #   
+  #   for (k in 1:K) {
+  #     poss_comps0[k, k] <- 1
+  #     poss_comps0[k, -k] <- -1 / (K - 1) # equal distribution of allocation to other comps
+  #   }
+  #   
+  # } else 
 
-    # number of combinations is:
-    # K = n_comps as only one combination per composition
-    K <- n_comp
-    poss_comps0 <- matrix(0, nrow = K, ncol = n_comp, dimnames = list(NULL, comps))
-    
-    for (k in 1:K) {
-      poss_comps0[k, k] <- 1
-      poss_comps0[k, -k] <- -1 / (K - 1) # equal distribution of allocation to other comps
-    }
-    
-  } else if (comparisons == "prop-realloc") {
+  if (comparisons == "prop-realloc") {
 
     ### same as "one-vs-all" except the "1 / (K - 1)"s replaced by weighted means to sum to 1
     # number of combinations is:
@@ -64,4 +82,4 @@ create_comparison_matrix <- function(comparisons, comps, mean_comps) {
 
   return(poss_comps0)
 
-}
+}

R/create_seq_bin_part.R

@@ -1,12 +1,29 @@
 
 
+#' Create a sequential binary partition indication matrix
+#'
+#' @param n_comp the number of compositional variables to partition
+#'
+#' @return
+#' A \code{n_comp} by \code{n_comp - 1} matrix where each column relates to one partition.
+#' 
+#' The partitions are made so that the numerator (\code{1} values) for the \code{i}th column is in the \code{i}th row. 
+#' All values below the \code{1} in the column are set to \code{-1} (the denominator).
+#' 
+#' The generated sequential binary partition for 3 comp vars is \code{(1, -1, -1), (0, 1, -1)}.
+#' 
+#' The generated sequential binary partition for 4 comp vars is \code{(1, -1, -1, -1), (0, 1, -1, -1), (0, 0, 1, -1)}.
+#' 
+#' etc
+#' @export
+#'
+#' @examples
+#' create_seq_bin_part(3)
+#' create_seq_bin_part(4)
+#' create_seq_bin_part(10)
 create_seq_bin_part <- function(n_comp) {
 
-  # sequential binary partition for 3 comp vars can be
-  # (1, -1, -1), (0, 1, -1)
-  # sequential binary partition for 4 comp vars can be
-  # (1, -1, -1, -1), (0, 1, -1, -1), (0, 0, 1, -1)
-  # etc
+
   base_zeros <- rep(0, n_comp)
 
   sbp <- matrix(0, nrow = n_comp, ncol = n_comp - 1)
@@ -16,7 +33,7 @@ create_seq_bin_part <- function(n_comp) {
     this_col[(j + 1):n_comp] <- -1
     sbp[, j] <- this_col
   }
-  # can also do ilrBase(D = n_comp) etc
+  # alternative ilr bases can be made via ilrBase(D = n_comp) etc
 
   return(sbp)
 

R/extract_lm_quantities.R

@@ -1,3 +1,20 @@
+#' Extract critical quantities from a lm object (for confidence interval calculations)
+#'
+#' @param lm_X a lm object
+#' @param alpha level of significance. Defaults to 0.05.
+#'
+#' @return
+#' A list containing the \code{lm}'s model matrix (\code{dmX}), 
+#' the inverse of \code{t(dmX) %*% dmX} (\code{XtX_inv}), 
+#' the standard error (\code{s_e}),
+#' the estimated single column beta matrix (\code{beta_hat}), and
+#' the critical value of the relevant degrees of freedom t-dist (\code{crit_val}).
+#' @export
+#'
+#' @examples
+#' data(fat_data)
+#' lm_fat <- lm(fat ~ sl, data = fat_data)
+#' extract_lm_quantities(lm_fat)
 extract_lm_quantities <- function(lm_X, alpha = 0.05) {
 
   # get the design matrix from the LM

R/fairclough.R

@@ -1,4 +1,4 @@
-#' Data from Fairclough (2017). Fitness, fatness and the reallocation of time between children’s daily movement behaviours: an analysis of compositional data
+#' Data from Fairclough (2017). Fitness, fatness and the reallocation of time between children's daily movement behaviours: an analysis of compositional data
 #'
 #' A dataset containing z_bmi (outcome), time-use compositions (sl,sb,lpa,mvpa), and covariates
 #'  from the Fairclough (2017) paper. The data can be found in supp file 7 of the paper

R/fat_data.R

@@ -1,14 +1,14 @@
-#' Randomly generated data to simulate child fat percentage regressed on time-use composiitonal data
+#' Randomly generated data to simulate child fat percentage regressed on time-use compositional data
 #'
 #' A dataset containing fat percentage (outcome), time-use compositions (sl,sb,lpa,mvpa), and covariates
-#'  (sibs,parents,ed). Note sl+sb+lpa+mvpa=1440minutes for each subject. The variables are as follows:
+#'  (sibs,parents,ed). Note sl+sb+lpa+mvpa=1440 minutes for each subject. The variables are as follows:
 #'
 #' \itemize{
 #'   \item fat. child fat percentage (11.29--29.99)
 #'   \item sl. daily sleep in minutes (283--765)
 #'   \item sb. sedentary behaviour in minutes (354--789)
 #'   \item lpa. low-intensity physical activity in minutes (157--507)
-#'   \item mvpa. moderate- to vigourous-intensity physical activity in minutes (35--155)
+#'   \item mvpa. moderate- to vigorous-intensity physical activity in minutes (35--155)
 #'   \item sibs. number of siblings (0,1,2,3,4)
 #'   \item parents. number of parents/caregivers at home (1,2)
 #'   \item ed. education level of parent(s) (0=high school, 1=diploma, 2=degree)