add reference samples to divergence outputs (#100)

Signed-off-by: Daena Rys <rysdaena8@gmail.com>
Co-authored-by: TuomasBorman <tvborm@utu.fi>
Co-authored-by: Tuomas Borman <60338854+TuomasBorman@users.noreply.github.com>

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: miaTime
 Type: Package
 Title: Microbiome Time Series Analysis
-Version: 0.99.1
+Version: 0.99.2
 Authors@R:
      c(person(given = "Leo", family = "Lahti", role = c("aut"),
               email = "leo.lahti@iki.fi",

R/getBaselineDivergence.R

@@ -54,11 +54,9 @@
 #' \code{colData} that identifies the baseline samples to be used.
 #' (Default: \code{NULL})
 #'
-#' @param name \code{Character scalar}. Specifies a column name for storing
-#' divergence results. (Default: \code{"divergence"})
-#'
-#' @param name.time \code{Character scalar}. Specifies a column name for storing
-#' time differences. (Default: \code{"time_diff"})
+#' @param name \code{Character vector}. Specifies a column name for storing
+#' divergence results.
+#' (Default: \code{c("divergence", "time_diff", "ref_samples")})
 #'
 #' @param ... Optional arguments passed into
 #' \code{\link[mia:addDivergence]{mia::addDivergence()}}.
@@ -86,8 +84,8 @@
 #'     reference = "reference",
 #'     group = "subject",
 #'     time.col = "time",
-#'     name = "divergence_from_baseline",
-#'     name.time = "time_from_baseline",
+#'     name = c("divergence_from_baseline",
+#'         "time_from_baseline", "reference_samples"),
 #'     assay.type = "relabundance",
 #'     method = "bray")
 #'
@@ -153,20 +151,22 @@ setMethod("getBaselineDivergence", signature = c(x = "SummarizedExperiment"),
         reference <- args[["reference"]]
         time_res <- .get_time_difference(x, time.col, reference)
         # Create a DF to return
-        res <- .convert_divergence_to_df(x, res, time_res, ...)
+        res <- .convert_divergence_to_df(x, res, time_res, reference, ...)
         return(res)
     }
 )
 
 #' @rdname addBaselineDivergence
 #' @export
 setMethod("addBaselineDivergence", signature = c(x = "SummarizedExperiment"),
-    function(x, name = "divergence", name.time = "time_diff", ...){
+    function(
+        x, name = c("divergence", "time_diff", "ref_samples"), ...){
+        .check_input(name, c("character vector"), length = 3L)
         # Calculate divergence
         res <- getBaselineDivergence(x, ...)
         # Add to colData
         res <- as.list(res) |> unname()
-        x <- .add_values_to_colData(x, res, list(name, name.time), ...)
+        x <- .add_values_to_colData(x, res, name, ...)
         return(x)
     }
 )
@@ -321,7 +321,7 @@ setMethod("addBaselineDivergence", signature = c(x = "SummarizedExperiment"),
     return(res)
 }
 
-# This function get time difference between a sample and its referene sample
+# This function get time difference between a sample and its reference sample
 .get_time_difference <- function(x, time.col, reference){
     # Get timepoints
     time_point <- x[[time.col]]
@@ -334,13 +334,12 @@ setMethod("addBaselineDivergence", signature = c(x = "SummarizedExperiment"),
 
 # This function converts time divergence results to DF object
 .convert_divergence_to_df <- function(
-        x, res, time_res, name = "divergence", name.time = "time_diff", ...){
-    #
-    temp <- .check_input(name, list("character scalar"))
-    #
-    temp <- .check_input(name.time, list("character scalar"))
+        x, res, time_res, reference,
+        name = c("divergence", "time_diff", "ref_samples"), ...){
+    # Validate 'name' param
+    temp <- .check_input(name, list("character vector"), length = 3L)
     #
-    df <- DataFrame(res, time_res, row.names = colnames(x))
-    colnames(df) <- c(name, name.time)
+    df <- DataFrame(res, time_res, x[[reference]], row.names = colnames(x))
+    colnames(df) <- name
     return(df)
 }

R/getStepwiseDivergence.R

@@ -1,31 +1,31 @@
 #' @name addStepwiseDivergence
 #' @export
-#' 
+#'
 #' @title
 #' Beta diversity between consecutive time steps
-#' 
+#'
 #' @description
 #' Calculates sample dissimilarity between consecutive time points along with
 #' time difference.
-#' 
+#'
 #' @details
 #' These functions calculate time-wise divergence, meaning each sample is
 #' compared to the previous i-th sample, where i is the specified time
 #' interval (see \code{time.interval}). By default, the function calculates
 #' divergence by comparing all samples with each other. However, it is often
 #' more meaningful to calculate divergence within a specific patient or group
 #' (see the \code{group} parameter).
-#' 
+#'
 #' @return
 #' \code{getStepwiseDivergence} returns \code{DataFrame} object
 #' containing the sample dissimilarity and corresponding time difference between
 #' samples. \code{addStepwiseDivergence}, on the other hand, returns a
 #' \code{\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment}}
 #' object with these results in its \code{colData}.
-#' 
+#'
 #' @inheritParams addBaselineDivergence
-#' 
-#' @param time.interval \code{Integer scalar}. Indicates the increment between 
+#'
+#' @param time.interval \code{Integer scalar}. Indicates the increment between
 #' time steps. By default, the function compares each sample to the
 #' previous one. If you need to take every second, every third, or so, time
 #' step, then increase this accordingly. (Default: \code{1L})
@@ -35,7 +35,7 @@
 #'
 #' data(hitchip1006)
 #' tse <- transformAssay(hitchip1006, method = "relabundance")
-#' 
+#'
 #' # Calculate divergence
 #' tse <- addStepwiseDivergence(
 #'     tse,
@@ -44,10 +44,10 @@
 #'     time.col = "time",
 #'     assay.type = "relabundance"
 #'     )
-#' 
+#'
 #' @seealso
 #' \code{\link[mia:addDivergence]{mia::addDivergence()}}
-#' 
+#'
 NULL
 
 #' @rdname addStepwiseDivergence
@@ -102,20 +102,22 @@ setMethod("getStepwiseDivergence", signature = c(x = "ANY"),
         reference <- args[["reference"]]
         time_res <- .get_time_difference(x, time.col, reference)
         # Create a DF to return
-        res <- .convert_divergence_to_df(x, res, time_res, ...)
+        res <- .convert_divergence_to_df(x, res, time_res, reference, ...)
         return(res)
     }
 )
 
 #' @rdname addStepwiseDivergence
 #' @export
 setMethod("addStepwiseDivergence", signature = c(x = "SummarizedExperiment"),
-    function(x, name = "divergence", name.time = "time_diff", ...){
+    function(
+        x, name = c("divergence", "time_diff", "ref_samples"), ...){
+        .check_input(name, c("character vector"), length = 3L)
         # Calculate divergence
         res <- getStepwiseDivergence(x,  ...)
         # Add to colData
         res <- as.list(res) |> unname()
-        x <- .add_values_to_colData(x, res, list(name, name.time), ...)
+        x <- .add_values_to_colData(x, res, name, ...)
         return(x)
     }
 )

R/utils.R

@@ -6,7 +6,7 @@
 # Borrowed from HoloFoodR.
 .check_input <- function(
         variable, supported_class, supported_values = NULL, limits = NULL,
-        variable_name = .get_name_in_parent(variable)){
+        length = NULL, variable_name = .get_name_in_parent(variable)){
     # Convert supported classes to character
     classes_char <- lapply(supported_class, function(class){
         if( is.null(class) ){
@@ -54,6 +54,11 @@
         msg <- paste0(msg, ")")
     }
 
+    # If length was provided
+    if( !is.null(length) ){
+        msg <- paste0(msg, " The length must be ", length, ".")
+    }
+
     # List all the input types. Run the check if the variable must be that type.
     # If correct type was found, change the result to TRUE.
     input_correct <- FALSE
@@ -128,6 +133,10 @@
             input_correct <- FALSE
         }
     }
+    # Check length if provided
+    if( !is.null(length) && length(variable) != length ){
+        input_correct <- FALSE
+    }
     # Give error if variable was not correct type
     if( !input_correct ){
         stop(msg, call. = FALSE)