From 14a28155f7b748d6c5afa5545071b6d967e10bba Mon Sep 17 00:00:00 2001
From: "Adam H. Sparks" <adam.sparks@curtin.edu.au>
Date: Sun, 23 Jun 2024 11:30:28 +0800
Subject: [PATCH] Return a custom S3 list object and use custom print method
 for oruns_test

---
 NAMESPACE         |  1 +
 R/oruns_test.R    | 52 +++++++++++++++++++++++++++++++++--------------
 man/oruns_test.Rd | 12 ++++++++++-
 3 files changed, 49 insertions(+), 16 deletions(-)

diff --git a/NAMESPACE b/NAMESPACE
index 977bdaf..81f2e47 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -1,5 +1,6 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method(print,r4pde.oruns_test)
 export(AFSD)
 export(BPL)
 export(CompMuCens)
diff --git a/R/oruns_test.R b/R/oruns_test.R
index a81f4d1..9c22814 100644
--- a/R/oruns_test.R
+++ b/R/oruns_test.R
@@ -3,11 +3,20 @@
 #' Perform a runs test on the input data to test for clustering or randomness.
 #'
 #' @param x A numeric vector representing the input data
-#' @return A list with elements U (number of runs), EU (expected number of runs), pvalue, and result (either "clustering" or "randomness").
 #' @examples
 #' oruns_test(c(1, 0, 1, 1, 0, 1, 0, 0, 1, 1))
 #'
 #' @importFrom stats pnorm
+#' @return an `r4pde.oruns` object.
+#'
+#' An `r4pde.oruns` object is a `list` containing:
+#'   * U, number of runs,
+#'   * EU, expected number of runs,
+#'   * sU, standard deviation of the expected number of runs
+#'   * Z, Z-score of the observed number of runs,
+#'   * pvalue, the p-value of the Z-score, and
+#'   * result, the test result of either "aggregation or clustering" or "randomness"
+#'
 #' @export
 oruns_test <- function(x) {
   # S is the input data
@@ -37,18 +46,31 @@ oruns_test <- function(x) {
   result <- ifelse(Z < -1.64,
                    c("aggregation or clustering"),
                    c("randomness"))
-  message <- paste(
-    "Ordinary Runs Test of Data Sequence:\n",
-    "-------------------------------------\n",
-    sprintf("Total Number of Runs (U): %d\n", U),
-    sprintf("Expected Number of Runs (EU): %.2f\n", EU),
-    sprintf("Standard Deviation of Runs (sU): %.2f\n", sU),
-    sprintf("Z-score: %.2f\n", Z),
-    sprintf("P-value: %.4f\n\n", pvalue),
-    "Interpretation:\n",
-    sprintf("Based on the Z-score, the sequence exhibits '%s'.\n", result)
-
-  )
-
-  cat(message)
+
+  out <- list(U = U, EU = EU, sU = sU, Z = Z, pvalue = pvalue, result = result)
+  class(out) <- union("r4pde.oruns_test", class(out))
+  return(out)
+}
+
+#' Prints r4pde.oruns Object
+#'
+#' Custom [print()] method for `r4pde.oruns_test` objects.
+#'
+#' @param x a `r4pde.oruns_test` object
+#' @param ... ignored
+#' @export
+#' @noRd
+
+print.r4pde.oruns_test <- function(x, ...) {
+  cat("Ordinary Runs Test of Data Sequence:\n")
+  cat("-------------------------------------\n")
+  cat(sprintf("Total Number of Runs (U): %d\n", x[[1]]))
+  cat(sprintf("Expected Number of Runs (EU): %.2f\n", x[[2]]))
+  cat(sprintf("Standard Deviation of Runs (sU): %.2f\n", x[[3]]))
+  cat(sprintf("Z-score: %.2f\n", x[[4]]))
+  cat(sprintf("P-value: %.4f\n\n", x[[4]]))
+  cat("Interpretation:\n")
+  cat(sprintf("Based on the Z-score, the sequence exhibits '%s'.\n", x[[6]]))
+
+  invisible(x)
 }
diff --git a/man/oruns_test.Rd b/man/oruns_test.Rd
index e50ddb4..9ea06d8 100644
--- a/man/oruns_test.Rd
+++ b/man/oruns_test.Rd
@@ -10,7 +10,17 @@ oruns_test(x)
 \item{x}{A numeric vector representing the input data}
 }
 \value{
-A list with elements U (number of runs), EU (expected number of runs), pvalue, and result (either "clustering" or "randomness").
+an \code{r4pde.oruns} object.
+
+An \code{r4pde.oruns} object is a \code{list} containing:
+\itemize{
+\item U, number of runs,
+\item EU, expected number of runs,
+\item sU, standard deviation of the expected number of runs
+\item Z, Z-score of the observed number of runs,
+\item pvalue, the p-value of the Z-score, and
+\item result, the test result of either "aggregation or clustering" or "randomness"
+}
 }
 \description{
 Perform a runs test on the input data to test for clustering or randomness.