Redesign the internal mechanism for grouping data

NAMESPACE

@@ -1,7 +1,10 @@
 # Generated by roxygen2: do not edit by hand
 
 S3method(aggregate,CompositionMatrix)
+S3method(aggregate,GroupedComposition)
 S3method(as.data.frame,CompositionMatrix)
+S3method(as.data.frame,GroupedComposition)
+S3method(as.data.frame,GroupedLogRatio)
 S3method(as.data.frame,LogRatio)
 S3method(as.data.frame,OutlierIndex)
 S3method(barplot,CompositionMatrix)
@@ -13,6 +16,7 @@ S3method(mahalanobis,CompositionMatrix)
 S3method(mahalanobis,ILR)
 S3method(mean,CompositionMatrix)
 S3method(plot,CompositionMatrix)
+S3method(plot,GroupedComposition)
 S3method(plot,LogRatio)
 S3method(plot,OutlierIndex)
 S3method(quantile,CompositionMatrix)
@@ -23,6 +27,7 @@ S3method(weights,ALR)
 S3method(weights,LR)
 S3method(weights,LogRatio)
 export(color)
+export(is_grouped)
 export(palette_color_continuous)
 export(palette_color_discrete)
 export(palette_color_picker)
@@ -38,9 +43,9 @@ exportMethods("%power%")
 exportMethods("[")
 exportMethods("[<-")
 exportMethods("[[<-")
-exportMethods("groups<-")
 exportMethods("totals<-")
 exportMethods(aggregate)
+exportMethods(all_assigned)
 exportMethods(any_assigned)
 exportMethods(as_amounts)
 exportMethods(as_composition)
@@ -52,8 +57,15 @@ exportMethods(covariance)
 exportMethods(describe)
 exportMethods(detect_outlier)
 exportMethods(dist)
-exportMethods(extract)
-exportMethods(groups)
+exportMethods(group)
+exportMethods(group_extract)
+exportMethods(group_indices)
+exportMethods(group_length)
+exportMethods(group_levels)
+exportMethods(group_names)
+exportMethods(group_rows)
+exportMethods(group_size)
+exportMethods(group_split)
 exportMethods(hist)
 exportMethods(is_assigned)
 exportMethods(is_element_major)
@@ -86,6 +98,7 @@ exportMethods(transform_ilr)
 exportMethods(transform_inverse)
 exportMethods(transform_lr)
 exportMethods(transform_plr)
+exportMethods(ungroup)
 exportMethods(univariate_ilr)
 exportMethods(variance)
 exportMethods(variance_total)

NEWS.md

@@ -1,5 +1,11 @@
 # nexus 0.3.0.9000
+## New classes and methods
+* Add `ReferenceGroups`, `GroupedComposition` and `GroupedLogRatio` classes to represent grouped data.
+* Add `group()`, `ungroup()`, `group_levels()`, `group_names()`, `group_indices()`, `group_rows()`, `group_length()`, `group_size()`, `group_extract()`, `group_split()` and `is_grouped()` to work with grouped data.
+* Add `transform_lr()`, `transform_clr()`, `transform_alr()`, `transform_ilr()`, `transform_plr()` and `transform_inverse()` methods for `GroupedComposition` and `GroupedLogRatio` objects.
+
 ## Breaking changes
+* Redesign the internal mechanism for grouping data.
 * `hist()` now produces a single histogram.
 
 # nexus 0.3.0

R/AllClasses.R

@@ -8,36 +8,43 @@ setOldClass("dist")
 ## (for 'i' in x[i], x[i, ], x[, i], etc.)
 setClassUnion("index", members = c("logical", "numeric", "character"))
 
-# CompositionMatrix ============================================================
-#' Numeric Matrix
+# ReferenceGroups ==============================================================
+#' Grouped Data
 #'
-#' S4 classes that represent a \eqn{m \times p}{m x p} numeric matrix.
-#' @slot .Data A \eqn{m \times p}{m x p} `numeric` [`matrix`].
-#' @note
-#'  This class inherits from [`matrix`].
+#' A virtual S4 class to represent reference groups.
+#' @slot group_indices An [`integer`] vector to store the group that each value
+#'  belongs to.
+#' @slot group_levels A [`character`] vector to store the values of the grouping
+#'  variables.
+#' @example inst/examples/ex-matrix.R
 #' @author N. Frerebeau
 #' @family classes
 #' @docType class
-#' @aliases NumericMatrix-class
+#' @aliases ReferenceGroups-class
 #' @keywords internal
-.NumericMatrix <- setClass(
-  Class = "NumericMatrix",
-  contains = "matrix"
+.ReferenceGroups <- setClass(
+  Class = "ReferenceGroups",
+  slots = c(
+    group_indices = "integer",
+    group_levels = "character"
+  ),
+  contains = c("VIRTUAL")
 )
 
-#' Logical Matrix
+# CompositionMatrix ============================================================
+#' Numeric Matrix
 #'
-#' S4 classes that represent a \eqn{m \times p}{m x p} logical matrix.
-#' @slot .Data A \eqn{m \times p}{m x p} `logical` [`matrix`].
+#' S4 classes that represent a \eqn{m \times p}{m x p} numeric matrix.
+#' @slot .Data A \eqn{m \times p}{m x p} `numeric` [`matrix`].
 #' @note
 #'  This class inherits from [`matrix`].
 #' @author N. Frerebeau
 #' @family classes
 #' @docType class
-#' @aliases LogicalMatrix-class
+#' @aliases NumericMatrix-class
 #' @keywords internal
-.LogicalMatrix <- setClass(
-  Class = "LogicalMatrix",
+.NumericMatrix <- setClass(
+  Class = "NumericMatrix",
   contains = "matrix"
 )
 
@@ -46,7 +53,6 @@ setClassUnion("index", members = c("logical", "numeric", "character"))
 #' An S4 class to represent compositional data.
 #' @slot totals A [`numeric`] vector to store the absolute row sums (before
 #'  the closure of the compositions).
-#' @slot groups A [`factor`] vector to store the group names.
 #' @section Coerce:
 #'  In the code snippets below, `x` is a `CompositionMatrix` object.
 #'  \describe{
@@ -58,7 +64,7 @@ setClassUnion("index", members = c("logical", "numeric", "character"))
 #'   \item{`x[i, j]`}{Extract parts of a matrix (see [`[`][subset]).}
 #'  }
 #' @note
-#'  This class inherits from [`matrix`].
+#'  This class inherits from [`NumericMatrix-class`].
 #' @seealso [as_composition()]
 #' @example inst/examples/ex-matrix.R
 #' @author N. Frerebeau
@@ -69,19 +75,40 @@ setClassUnion("index", members = c("logical", "numeric", "character"))
 .CompositionMatrix <- setClass(
   Class = "CompositionMatrix",
   slots = c(
-    totals = "numeric",
-    groups = "factor"
+    totals = "numeric"
   ),
   contains = c("NumericMatrix")
 )
 
+#' Grouped Compositional Matrix
+#'
+#' An S4 class to represent grouped compositional data.
+#' @section Coerce:
+#'  In the code snippets below, `x` is a `GroupedComposition` object.
+#'  \describe{
+#'   \item{`as.data.frame(x)`}{Coerces to a [`data.frame`].}
+#'  }
+#' @note
+#'  This class inherits from [`CompositionMatrix-class`] and
+#'  [`ReferenceGroups-class`].
+#' @seealso [as_composition()]
+#' @example inst/examples/ex-matrix.R
+#' @author N. Frerebeau
+#' @family classes
+#' @docType class
+#' @aliases GroupedComposition-class
+#' @keywords internal
+.GroupedComposition <- setClass(
+  Class = "GroupedComposition",
+  contains = c("CompositionMatrix", "ReferenceGroups")
+)
+
 # Transformations ==============================================================
 #' Log-Ratio Matrix
 #'
 #' S4 classes to represent log-ratio data transformations.
 #' @slot totals A [`numeric`] vector to store the absolute row sums (before
 #'  the closure of the compositions).
-#' @slot groups A [`factor`] vector to store the group names.
 #' @slot parts A [`character`] vector to store the original part names.
 #' @slot ratio A [`character`] vector to store the ratio names.
 #' @slot order An [`integer`] vector to store the original ordering of the
@@ -107,8 +134,6 @@ setClassUnion("index", members = c("logical", "numeric", "character"))
   Class = "LogRatio",
   slots = c(
     totals = "numeric",
-    groups = "factor",
-
     parts = "character",
     ratio = "character",
     order = "integer",
@@ -153,12 +178,71 @@ setClassUnion("index", members = c("logical", "numeric", "character"))
   contains = "ILR"
 )
 
+#' Grouped Log-Ratio Matrix
+#'
+#' An S4 class to represent grouped log-ratio.
+#' @section Coerce:
+#'  In the code snippets below, `x` is a `GroupedLogRatio` object.
+#'  \describe{
+#'   \item{`as.data.frame(x)`}{Coerces to a [`data.frame`].}
+#'  }
+#' @note
+#'  This class inherits from [`LogRatio-class`] and
+#'  [`ReferenceGroups-class`].
+#' @example inst/examples/ex-matrix.R
+#' @author N. Frerebeau
+#' @family classes
+#' @docType class
+#' @name GroupedLogRatio-class
+#' @rdname GroupedLogRatio-class
+#' @keywords internal
+NULL
+
+#' @rdname GroupedLogRatio-class
+#' @aliases GroupedLR-class
+.GroupedLR <- setClass(
+  Class = "GroupedLR",
+  contains = c("LR", "ReferenceGroups")
+)
+
+#' @rdname GroupedLogRatio-class
+#' @aliases GroupedCLR-class
+.GroupedCLR <- setClass(
+  Class = "GroupedCLR",
+  contains = c("CLR", "ReferenceGroups")
+)
+
+#' @rdname GroupedLogRatio-class
+#' @aliases GroupedALR-class
+.GroupedALR <- setClass(
+  Class = "GroupedALR",
+  contains = c("ALR", "ReferenceGroups")
+)
+
+#' @rdname GroupedLogRatio-class
+#' @aliases GroupedILR-class
+.GroupedILR <- setClass(
+  Class = "GroupedILR",
+  contains = c("ILR", "ReferenceGroups")
+)
+
+#' @rdname GroupedLogRatio-class
+#' @aliases GroupedPLR-class
+.GroupedPLR <- setClass(
+  Class = "GroupedPLR",
+  contains = c("PLR", "ReferenceGroups")
+)
+
+setClassUnion(
+  name = "GroupedLogRatio",
+  members = c("GroupedLR", "GroupedCLR", "GroupedALR", "GroupedILR", "GroupedPLR")
+)
+
 # OutlierIndex =================================================================
 #' Outliers
 #'
 #' An S4 class to store the result of outlier detection.
 #' @slot samples A [`character`] vector to store the sample identifiers.
-#' @slot groups A [`factor`] vector to store the group names.
 #' @slot standard A [`numeric`] matrix giving the standard squared Mahalanobis
 #'  distances.
 #' @slot robust A [`numeric`] matrix giving the robust squared Mahalanobis
@@ -180,7 +264,6 @@ setClassUnion("index", members = c("logical", "numeric", "character"))
   Class = "OutlierIndex",
   slots = c(
     samples = "character",
-    groups = "factor",
     standard = "numeric",
     robust = "numeric",
     limit = "numeric",