Upload app.R

app.R

@@ -2,16 +2,117 @@ library(plumber)
 
 #* @apiTitle Effect Size Calculator API
 
-d.quantile <- function(x1, x2, degree = 5, CI = NA, silent = T) {
+
+
+#' Calculate a Distribution-Free Effect Size (d_reg)
+#'
+#' This function computes a distribution-free effect size by modeling the 
+#' empirical distribution function (eCDF) of two groups via polynomial 
+#' regression. The effect size is computed as the standardized
+#' difference between the means of the smoothed distributions.
+#'
+#' The method involves:
+#' 1. Fitting polynomials to each group's quantile function: x = f(z)
+#' 2. Computing moments (mean, variance) of the polynomials
+#' 3. Calculating d(reg) using the pooled standard deviation
+#'
+#' @param x1 A numeric vector of data for the first group.
+#' @param x2 A numeric vector of data for the second group.
+#' @param degree The degree of the polynomial to fit (default = 5).
+#'        Higher degrees capture more complex distributional shapes but
+#'        may overfit with small samples.
+#' @param CI Confidence level for confidence interval (default = NA, no CI computed).
+#'        If specified (e.g., 0.95), uses asymptotic normal approximation.
+#'        WARNING: CI formula assumes Cohen's d distribution and may not be accurate for d_reg.
+#' @param silent Logical; if TRUE, suppresses warnings during fitting (default = TRUE).
+#'
+#' @return A list (S3 class "d_reg") containing:
+#'   \item{d_reg}{The distribution-free effect size (standardized mean difference).}
+#'   \item{group1_mean}{Mean of the smoothed distribution for group 1.}
+#'   \item{group1_variance}{Variance of the smoothed distribution for group 1.}
+#'   \item{group1_sd}{Standard deviation of the smoothed distribution for group 1.}
+#'   \item{group2_mean}{Mean of the smoothed distribution for group 2.}
+#'   \item{group2_variance}{Variance of the smoothed distribution for group 2.}
+#'   \item{group2_sd}{Standard deviation of the smoothed distribution for group 2.}
+#'   \item{pooled_sd}{Pooled standard deviation.}
+#'   \item{n1}{Sample size of group 1.}
+#'   \item{n2}{Sample size of group 2.}
+#'   \item{model1}{Fitted polynomial model for group 1.}
+#'   \item{model2}{Fitted polynomial model for group 2.}
+#'   \item{default_degree}{Polynomial degree used.}
+#'   \item{tie_proportion_1}{Proportion of tied values in group 1.}
+#'   \item{tie_proportion_2}{Proportion of tied values in group 2.}
+#'   \item{n_unique_1}{Number of unique values in group 1.}
+#'   \item{n_unique_2}{Number of unique values in group 2.}
+#'   \item{ci_lower}{Lower bound of confidence interval (if CI specified).}
+#'   \item{ci_upper}{Upper bound of confidence interval (if CI specified).}
+#'   \item{ci_level}{Confidence level (if CI specified).}
+#'
+#' @details
+#' The method is distribution-free and converges to Cohen's d under normality with 
+#' increasing group size. It is robust to outliers and skewness compared to 
+#' classical parametric methods.
+#' 
+#' Sample size requirements: At least (degree + 1) observations per group.
+#' Recommended: n > 10 per group for stable polynomial fits.
+#' For small samples (n < 20), consider using degree = 3 or lower.
+#'
+#' Confidence intervals use an asymptotic approximation based on Cohen's d 
+#' distribution and may not accurately reflect the true sampling distribution 
+#' of d_reg, especially in small samples or non-normal data.
+#'
+#' @author Wolfgang Lenhard and Alexandra Lenhard
+#' @references
+#'   Lenhard, W. & Lenhard, A. (submitted). Distribution-Free Effect Size Estimation: 
+#'   A Robust Alternative to Cohen's d.
+#'
+#' @examples
+#' # Normal distributions
+#' set.seed(123)
+#' x1 <- rnorm(30, mean = 0, sd = 1)
+#' x2 <- rnorm(30, mean = 0.5, sd = 1)
+#' result <- d.reg(x1, x2)
+#' print(result)
+#' 
+#' # With confidence interval
+#' result_ci <- d.reg(x1, x2, CI = 0.95)
+#' print(result_ci)
+#' 
+#' # Skewed distributions
+#' x1 <- rexp(50, rate = 1)
+#' x2 <- rexp(50, rate = 0.8)
+#' result <- d.reg(x1, x2, degree = 4)
+#' print(result)
+#'
+#' @export
+d.reg <- function(x1, x2, degree = 5, CI = NA, silent = TRUE) {
+  
+  # ============================================================================
+  # Input Validation
+  # ============================================================================
   
-  # Input validation
   if (!is.numeric(x1) || !is.numeric(x2)) {
     stop("Both x1 and x2 must be numeric vectors.")
   }
   
+  # Handle missing values
+  if (any(is.na(x1)) || any(is.na(x2))) {
+    if (!silent) {
+      warning("Missing values detected and will be removed.")
+    }
+    x1 <- x1[!is.na(x1)]
+    x2 <- x2[!is.na(x2)]
+  }
+  
   n1 <- length(x1)
   n2 <- length(x2)
   
+  # Check for empty groups
+  if (n1 == 0 || n2 == 0) {
+    stop("Cannot compute effect size with empty groups after removing NAs.")
+  }
+  
+  # Check sufficient sample size for polynomial degree
   if (n1 < degree + 1) {
     stop("Group 1 has insufficient data: need at least ", degree + 1, 
          " observations for degree ", degree, " polynomial (got ", n1, ").")
@@ -22,26 +123,26 @@ d.quantile <- function(x1, x2, degree = 5, CI = NA, silent = T) {
          " observations for degree ", degree, " polynomial (got ", n2, ").")
   }
   
-  if (any(is.na(x1)) || any(is.na(x2))) {
-    warning("Missing values detected and will be removed.")
-    x1 <- x1[!is.na(x1)]
-    x2 <- x2[!is.na(x2)]
-    n1 <- length(x1)
-    n2 <- length(x2)
-  }
-  
-  if (n1 == 0 || n2 == 0) {
-    stop("Cannot compute effect size with empty groups after removing NAs.")
+  # Validate CI parameter if provided
+  if (!is.na(CI)) {
+    if (!is.numeric(CI) || length(CI) != 1) {
+      stop("CI must be a single numeric value or NA.")
+    }
+    if (CI <= 0 || CI >= 1) {
+      stop("CI must be between 0 and 1 (exclusive).")
+    }
   }
-  
-  # Step 1: Fit the polynomial models for each group
-  model1 <- fit_quantile_function(x1, degree)
-  model2 <- fit_quantile_function(x2, degree)
 
-  # Check for ties and warn user
+  model1 <- fit_polynomial(x1, degree)
+  model2 <- fit_polynomial(x2, degree)
+  
+  # Extract tie information
   tie1 <- attr(model1, "tie_proportion")
   tie2 <- attr(model2, "tie_proportion")
+  n_unique1 <- attr(model1, "n_unique")
+  n_unique2 <- attr(model2, "n_unique")
   
+  # Warn about substantial ties
   if (!silent && (tie1 > 0.3 || tie2 > 0.3)) {
     message(sprintf(
       "Note: Substantial ties detected (Group 1: %.1f%%, Group 2: %.1f%%).",
@@ -50,83 +151,97 @@ d.quantile <- function(x1, x2, degree = 5, CI = NA, silent = T) {
     message("This suggests discrete/ordinal data. Results should be interpreted cautiously.")
     message("Consider comparing multiple effect size measures for discrete data.")
   }
-  
-  # Step 2: Get the moments from each fitted model
+
   moments1 <- get_moments(model1, group_label = "Group 1")
   moments2 <- get_moments(model2, group_label = "Group 2")
-  
-  # Step 3: Calculate the pooled standard deviation
+
+  # Weighted pooled variance (population formula, not sample formula)
   weighted_pooled_variance <- (n1 * moments1$variance + n2 * moments2$variance) / (n1 + n2)
   pooled_sd <- sqrt(weighted_pooled_variance)
-  
-  # Step 4: Compute the effect size d_q
   mean_diff <- moments2$mean - moments1$mean
   
   # Handle edge cases
   if (pooled_sd == 0) {
     if (mean_diff == 0) {
-      d_q <- 0
+      d_reg <- 0
     } else {
-      d_q <- sign(mean_diff) * Inf
-      warning("Pooled SD is zero but means differ. Returning Inf with appropriate sign.")
+      d_reg <- sign(mean_diff) * Inf
+      if (!silent) {
+        warning("Pooled SD is zero but means differ. Returning Inf with appropriate sign.")
+      }
     }
   } else {
-    d_q <- mean_diff / pooled_sd
+    d_reg <- mean_diff / pooled_sd
   }
-  
-  # Return results
+
   result <- list(
-    d_q = d_q,
+    d_reg = d_reg,
+    
+    # Group 1 statistics
     group1_mean = moments1$mean,
     group1_variance = moments1$variance,
     group1_sd = sqrt(moments1$variance),
+    
+    # Group 2 statistics
     group2_mean = moments2$mean,
     group2_variance = moments2$variance,
     group2_sd = sqrt(moments2$variance),
+    
+    # Pooled statistics
     pooled_sd = pooled_sd,
+    
+    # Sample sizes
     n1 = n1,
     n2 = n2,
+    
+    # Models
     model1 = model1,
     model2 = model2,
-    default_degree = degree
+    
+    # Metadata
+    default_degree = degree,
+    tie_proportion_1 = tie1,
+    tie_proportion_2 = tie2,
+    n_unique_1 = n_unique1,
+    n_unique_2 = n_unique2
   )
-  
-  
-  if(!is.na(CI)) {
-    if(CI <= 0 || CI >= 1) {
-      stop("CI must be between 0 and 1 (exclusive).")
-    }
+
+  if (!is.na(CI)) {
     
-    # Standard error for d_q
-    se_dq <- sqrt((n1 + n2) / (n1 * n2) + (d_q^2) / (2 * (n1 + n2)))
+    # Standard error using asymptotic approximation
+    # NOTE: This formula assumes Cohen's d distribution and may not be 
+    # accurate for d_reg, especially in small samples or non-normal data
+    se_dreg <- sqrt((n1 + n2) / (n1 * n2) + (d_reg^2) / (2 * (n1 + n2)))
     
+    # Degrees of freedom
     df <- n1 + n2 - 2
+    
+    # Critical value from t-distribution
     alpha <- 1 - CI
     t_crit <- qt(1 - alpha / 2, df)
     
-    ci_lower <- d_q - t_crit * se_dq
-    ci_upper <- d_q + t_crit * se_dq
+    # Confidence interval bounds
+    ci_lower <- d_reg - t_crit * se_dreg
+    ci_upper <- d_reg + t_crit * se_dreg
     
+    # Add to result
     result$ci_lower <- ci_lower
     result$ci_upper <- ci_upper
     result$ci_level <- CI
+    result$ci_se <- se_dreg
+    result$ci_df <- df
   }
-  
-  result$tie_proportion_1 <- tie1
-  result$tie_proportion_2 <- tie2
-  result$n_unique_1 <- attr(model1, "n_unique")
-  result$n_unique_2 <- attr(model2, "n_unique")
-  
-  class(result) <- "d_quantile"
+
+  class(result) <- "d_reg"
   return(result)
 }
 
 
-#' Fit a Polynomial to the Quantile Function
+#' Fit a Polynomial to eCDF
 #'
 #' This helper function fits a polynomial regression model to represent the
-#' quantile function of a distribution. It models the relationship between
-#' standard normal quantiles (z-scores) and observed raw scores.
+#' distribution. It models the relationship between
+#' z-scores and observed raw scores.
 #'
 #' @param x A numeric vector of observations.
 #' @param poly_degree The degree of the polynomial to fit.
@@ -166,15 +281,15 @@ d.quantile <- function(x1, x2, degree = 5, CI = NA, silent = T) {
 #'   A Robust Alternative to Cohen’s d.
 #'
 #' @export
-fit_quantile_function <- function(x, poly_degree, 
-                                  check_monotonicity = FALSE,
+fit_polynomial <- function(x, poly_degree, 
+                                  check_monotonicity = TRUE,
                                   min_degree = 1) {
   
   # Step 1: Input validation and tie detection
   n <- length(x)
   
   if (n < 3) {
-    stop("Need at least 3 observations to fit a polynomial quantile function.")
+    stop("Need at least 3 observations to fit a polynomial.")
   }
   
   # Count unique values to detect ties
@@ -237,9 +352,7 @@ fit_quantile_function <- function(x, poly_degree,
     while (current_degree >= min_degree) {
       
       model <- lm(x ~ poly(z, current_degree, raw = TRUE))
-      
-      # Use the NEW analytic check
-      check <- check_monotonicity_analytic(model, z_range = check_range)
+      check <- check_monotonicity(model, z_range = check_range)
       
       if (check$is_monotonic) {
         monotonic <- TRUE
@@ -256,7 +369,7 @@ fit_quantile_function <- function(x, poly_degree,
       current_degree <- min_degree
       # Fit linear even if non-monotonic (rare/impossible for degree 1 unless negative correlation)
       model <- lm(x ~ poly(z, current_degree, raw = TRUE))
-      check <- check_monotonicity_analytic(model, z_range = check_range)
+      check <- check_monotonicity(model, z_range = check_range)
       monotonic <- check$is_monotonic
     }
     
@@ -268,10 +381,12 @@ fit_quantile_function <- function(x, poly_degree,
   
   # Metadata
   attr(model, "sample_size") <- n
+  attr(model, "n_unique") <- n_unique              # ADD THIS
+  attr(model, "tie_proportion") <- tie_proportion  # ADD THIS
   attr(model, "poly_degree") <- current_degree
   attr(model, "monotonic") <- monotonic
   attr(model, "min_derivative") <- check$min_derivative
-  
+
   return(model)
 }
 
@@ -411,11 +526,10 @@ check_monotonicity <- function(model, z_range = c(-4, 4),
 
 
 
-#' Calculate Moments from a Fitted Polynomial Quantile Function (Analytical)
+#' Calculate Moments from a Fitted Polynomial Function
 #'
 #' This function computes the mean and variance of the distribution represented 
-#' by a polynomial quantile function using closed-form analytical formulas 
-#' based on the raw moments of the standard normal distribution.
+#' by a polynomial function using Iserlis (1918) theorem.
 #'
 #' @param model An lm model object from \code{\link{fit_quantile_function}()}.
 #'   The model should represent the relationship x = f(z) where z are standard 
@@ -428,53 +542,6 @@ check_monotonicity <- function(model, z_range = c(-4, 4),
 #'   \item{mean}{The expected value E[X] where X = f(Z), Z ~ N(0,1).}
 #'   \item{variance}{The variance Var(X) = E[X²] - (E[X])².}
 #'
-#' @details
-#' This function provides an analytical alternative to numerical integration 
-#' for computing distributional moments. It exploits the fact that when the 
-#' quantile function is represented as a polynomial:
-#' 
-#' \deqn{f(z) = \sum_{j=0}^{k} \beta_j z^j}
-#' 
-#' the moments can be computed in closed form using the known raw moments of 
-#' the standard normal distribution.
-#' 
-#' \strong{Mathematical Foundation:}
-#' 
-#' The mean is computed as:
-#' \deqn{\mu = E[f(Z)] = \sum_{j=0}^{k} \beta_j E[Z^j]}
-#' 
-#' where \eqn{E[Z^j]} are the raw moments of the standard normal distribution:
-#' \itemize{
-#'   \item For odd j: \eqn{E[Z^j] = 0} (due to symmetry)
-#'   \item For even j: \eqn{E[Z^j] = (j-1)!!} (double factorial)
-#' }
-#' 
-#' The double factorial is defined as:
-#' \deqn{(j-1)!! = (j-1) \times (j-3) \times \ldots \times 3 \times 1}
-#' 
-#' Examples: \eqn{E[Z^0] = 1}, \eqn{E[Z^2] = 1}, \eqn{E[Z^4] = 3}, 
-#' \eqn{E[Z^6] = 15}, \eqn{E[Z^8] = 105}.
-#' 
-#' For a polynomial of degree k=5, the mean simplifies to:
-#' \deqn{\mu = \beta_0 + \beta_2 \cdot 1 + \beta_4 \cdot 3}
-#' 
-#' The variance is computed as:
-#' \deqn{\sigma^2 = E[X^2] - \mu^2}
-#' 
-#' where:
-#' \deqn{E[X^2] = E\left[\left(\sum_{i=0}^{k} \beta_i Z^i\right)^2\right] 
-#'       = \sum_{i=0}^{k} \sum_{j=0}^{k} \beta_i \beta_j E[Z^{i+j}]}
-#' 
-#' @section Theoretical Background:
-#' This approach is based on the principle that any random variable X can be 
-#' expressed as a transformation of a standard normal variable:
-#' \deqn{X = f(Z), \quad Z \sim N(0,1)}
-#' 
-#' Expectations with respect to X can then be computed as:
-#' \deqn{E[g(X)] = E[g(f(Z))] = \int_{-\infty}^{\infty} g(f(z)) \phi(z) dz}
-#' 
-#' When f is a polynomial, these integrals reduce to linear combinations of 
-#' standard normal moments, which are known analytically.
 #'
 #' @author Wolfgang Lenhard and Alexandra Lenhard
 #' Licensed under the MIT License
@@ -484,12 +551,9 @@ check_monotonicity <- function(model, z_range = c(-4, 4),
 #'   A Robust Alternative to Cohen’s d.
 #'
 #' @seealso 
-#' \code{\link{get_moments}} for the numerical integration implementation.
-#' 
-#' \code{\link{fit_quantile_function}} for fitting the polynomial model.
+#' \code{\link{fit_polynomial}} for fitting the polynomial model.
+#' \code{\link{d.reg}} for the main effect size calculation.
 #' 
-#' \code{\link{d.quantile}} for the main effect size calculation.
-#'
 #' @examples
 #' # Generate sample data
 #' set.seed(123)
@@ -502,8 +566,8 @@ check_monotonicity <- function(model, z_range = c(-4, 4),
 #' z <- qnorm(p)
 #' model <- lm(x ~ poly(z, 5, raw = TRUE))
 #' 
-#' # Compute moments analytically
-#' moments <- get_moments_analytical(model, group_label = "Test Group")
+#' # Compute moments 
+#' moments <- get_moments(model, group_label = "Test Group")
 #' 
 #' cat("Mean:", moments$mean, "\n")
 #' cat("Variance:", moments$variance, "\n")
@@ -513,8 +577,6 @@ check_monotonicity <- function(model, z_range = c(-4, 4),
 #' cat("\nSample mean:", mean(x), "\n")
 #' cat("Sample variance:", var(x), "\n")
 #' 
-#' # The smoothed estimates will be similar but not identical,
-#' # with the analytical method providing regularization
 #' 
 #'
 #' @export
@@ -596,9 +658,9 @@ get_moments <- function(model, group_label = "Unknown") {
 
 
 
-#' Print Method for d_quantile Objects
+#' Print Method for d_reg Objects
 #'
-#' @param x An object of class "d_quantile"
+#' @param x An object of class "d_reg"
 #' @param ... Additional arguments (not used)
 #' 
 #' @author Wolfgang Lenhard and Alexandra Lenhard
@@ -609,10 +671,10 @@ get_moments <- function(model, group_label = "Unknown") {
 #'   A Robust Alternative to Cohen’s d.
 #'   
 #' @export
-print.d_quantile <- function(x, ...) {
-  cat("\nDistribution-Free Effect Size (d_q)\n")
+print.d_reg <- function(x, ...) {
+  cat("\nDistribution-Free Effect Size (d_reg)\n")
   cat("===================================\n\n")
-  cat("Effect size d_q:", round(x$d_q, 4), "\n")
+  cat("Effect size d_reg:", round(x$d_reg, 4), "\n")
   
   # Display CI if available
   if (!is.null(x$ci_lower)) {
@@ -627,16 +689,15 @@ print.d_quantile <- function(x, ...) {
   cat("Group 2: n =", x$n2, ", mean =", round(x$group2_mean, 4), 
       ", SD =", round(x$group2_sd, 4), "\n")
   cat("Pooled SD:", round(x$pooled_sd, 4), "\n")
-  cat("Polynomial degree:", x$degree, "\n")
+  cat("Polynomial degree:", x$default_degree, "\n")
   invisible(x)
 }
 
-#' Summary Method for d_quantile Objects
+#' Summary Method for d_reg Objects
 #'
 #' Provides detailed summary statistics and diagnostic information.
 #'
-#' @param object An object of class "d_quantile"
-#' @param ... Additional arguments (not used)
+#' @param object An object of class "d_reg"
 #'
 #' @author Wolfgang Lenhard and Alexandra Lenhard
 #' Licensed under the MIT License
@@ -646,18 +707,18 @@ print.d_quantile <- function(x, ...) {
 #'   A Robust Alternative to Cohen’s d.
 #'   
 #' @export
-summary.d_quantile <- function(object, ...) {
+summary.d_reg <- function(object, ...) {
   
   cat("\n")
   cat("=======================================================\n")
-  cat("  Distribution-Free Effect Size Analysis (d_quantile)\n")
+  cat("  Distribution-Free Effect Size Analysis (d_reg)\n")
   cat("=======================================================\n\n")
   
   cat("Effect Size:\n")
-  cat("  d_q =", round(object$d_q, 4), "\n")
+  cat("  d_reg =", round(object$d_reg, 4), "\n")
   
   # Interpretation
-  abs_d <- abs(object$d_q)
+  abs_d <- abs(object$d_reg)
   interpretation <- if (abs_d < 0.2) {
     "negligible"
   } else if (abs_d < 0.5) {
@@ -686,7 +747,7 @@ summary.d_quantile <- function(object, ...) {
   cat("  Mean difference:  ", round(object$group2_mean - object$group1_mean, 4), "\n\n")
   
   cat("Model Details:\n")
-  cat("  Polynomial degree:", object$degree, "\n")
+  cat("  Polynomial degree:", object$default_degree, "\n")
   cat("  Model 1 R²:       ", round(summary(object$model1)$r.squared, 4), "\n")
   cat("  Model 2 R²:       ", round(summary(object$model2)$r.squared, 4), "\n\n")
   
@@ -702,6 +763,7 @@ summary.d_quantile <- function(object, ...) {
 }
 
 
+
 # API endpoint
 #* Calculate effect size from two groups
 #* @param group1 Comma-separated numeric values for group 1