Merge pull request #185 from MangiolaLaboratory/improve-documentation-sccomp_proportional_fold_change

improve the documentation of sccomp_proportional_fold_change

Author: stemangiola

R/methods.R

@@ -2068,26 +2068,59 @@ clear_stan_model_cache <- function(cache_dir = sccomp_stan_models_cache_dir) {
   }
 }
 
-#' Calculate Proportional Fold Change for sccomp Data
+#' Calculate Proportional Fold Change from sccomp Estimated Effects
 #'
-#' This function calculates the proportional fold change for single-cell composition data
-#' from sccomp analysis, comparing two conditions.
-#' 
-#' Note! This statistic is just descriptive and should not be used to define significance. Use sccomp_test() for that. 
-#' This statistics is just meant to help interpretation. While fold increase in proportion is easier to understand than
-#' fold change in logit space, the first is not linear (the same change for rare cell types does not necessarily have the same weight 
-#' that for abundant cell types), while the latter is linear, and used to infer probabilities.
+#' @description 
+#' This function calculates the proportional fold change between two conditions using the estimated effects from a sccomp model.
+#' The fold changes are derived from the model's posterior predictions rather than raw counts, providing a more robust estimate
+#' that accounts for the model's uncertainty and covariate effects.
 #' 
+#' Note! This statistic is descriptive and should not be used to define significance - use sccomp_test() for that. 
+#' While fold changes in proportions are easier to interpret than changes in logit space, they are not linear 
+#' (the same proportional change has different meaning for rare vs abundant cell types). In contrast, 
+#' the logit scale used internally by sccomp provides linear effects that are more appropriate for statistical inference.
+#'
+#' @param .data A sccomp estimate object (of class 'sccomp_tbl') obtained from running sccomp_estimate().
+#'              This object contains the fitted model and estimated effects.
+#' @param formula_composition The formula specifying which model effects to use for calculating fold changes.
+#'                          This should match or be a subset of the formula used in the original sccomp_estimate() call.
+#' @param from Character string specifying the reference/control condition (e.g., "benign").
+#' @param to Character string specifying the comparison condition (e.g., "cancer").
+#'
+#' @return A tibble with the following columns:
+#' \itemize{
+#'   \item cell_group - The cell group identifier
+#'   \item proportion_fold_change - The estimated fold change in proportions between conditions.
+#'                                 Positive values indicate increases, negative values indicate decreases.
+#'   \item average_uncertainty - The average uncertainty in the fold change estimate, derived from the credible intervals
+#'   \item statement - A text description of the fold change, including the direction and the estimated proportions
+#' }
 #'
-#' @param .data A `sccomp_tbl` object containing single-cell composition data.
-#' @param formula_composition The formula for the composition model.
-#' @param from The label for the control group (e.g., "healthy").
-#' @param to The label for the treatment group (e.g., "cancer").
-#' @return A tibble with cell groups and their respective proportional fold change.
 #' @examples
-#' \dontrun{
-#' # Example usage
-#' result <- sccomp_proportional_fold_change(sccomp_data, formula_composition, "healthy", "cancer")
+#' \donttest{
+#' if (instantiate::stan_cmdstan_exists()) {
+#'   # Load example data
+#'   data("counts_obj")
+#'
+#'   # First estimate the composition effects
+#'   estimate <- sccomp_estimate(
+#'       counts_obj,
+#'       ~ type,
+#'       ~1,
+#'       sample,
+#'       cell_group,
+#'       count,
+#'       cores = 1
+#'   )
+#'  
+#'   # Calculate proportional fold changes from the estimated effects
+#'   estimate |> 
+#'   sccomp_proportional_fold_change(
+#'     formula_composition = ~  type, 
+#'     from = "benign", 
+#'     to = "cancer"
+#'   ) 
+#' }
 #' }
 #' @export
 sccomp_proportional_fold_change <- function(.data, formula_composition, from, to) {