bump doc and add new features

Author: weberse2

NAMESPACE

@@ -147,6 +147,7 @@ export(mn2gamma)
 export(mn2norm)
 export(ms2beta)
 export(ms2gamma)
+export(msr2mvnorm)
 export(oc1S)
 export(oc1Sdecision)
 export(oc2S)
@@ -159,10 +160,12 @@ export(postmix)
 export(preddist)
 export(qmix)
 export(qmixdiff)
+export(read_mix_json)
 export(rmix)
 export(rmixdiff)
 export(robustify)
 export(sigma)
+export(write_mix_json)
 import(Formula)
 import(Rcpp)
 import(abind)
@@ -175,6 +178,9 @@ import(rstantools)
 import(stats)
 importFrom(RcppParallel,CxxFlags)
 importFrom(RcppParallel,RcppParallelLibs)
+importFrom(jsonlite,fromJSON)
+importFrom(jsonlite,toJSON)
+importFrom(lifecycle,deprecated)
 importFrom(matrixStats,colLogSumExps)
 importFrom(matrixStats,colSums2)
 importFrom(matrixStats,logSumExp)

R/mixjson.R

@@ -0,0 +1,95 @@
+#' Write and Read a Mixture Object with JSON
+#'
+#' @description
+#' `r lifecycle::badge("experimental")`
+#'
+#' These functions write and read a mixture object in the JSON format.
+#'
+#' @param mix A mixture object to be saved to JSON.
+#' @param con A connection specifying where the JSON will be written
+#'   to or read.
+#' @param ... Additional arguments passed to the
+#'   [jsonlite::toJSON()] and
+#'   [jsonlite::fromJSON()] function for writing and
+#'   reading, respectively.
+#'
+#' @details The mixture objects are written or read from the connection
+#'   `con`, which can be a character string specifying a file
+#'   path or a connection object as detailed in
+#'   [base::connections()].
+#'
+#' When writing mixture objects as JSON it is strongly recommended to
+#'   explicitly set the number of digits (argument `digits`) to be
+#'   used for the numerical representation in order to control the
+#'   accuracy of the JSON representation of the mixture object. If the
+#'   mixture object inherits from the `"EM"` class (as is the
+#'   case when the mixture is created using the
+#'   [RBesT::mixfit()] function), then the mixture object
+#'   will be cast to a simple mixture object such that diagnostics
+#'   from the `"EM"` fitting procedure are dropped from the
+#'   object. For easier readability the user is encouraged to set the
+#'   argument `pretty=TRUE`, which is passed to the
+#'   [jsonlite::toJSON()] function and makes the output more
+#'   human readable.
+#'
+#' Note that when reading in mixture objects, then these are not
+#' necessarily equal to the mixtures passed to the `write_mix_json`
+#' function. This is a consequence of the limited precision of the
+#' textual representation as defined by the `digits` argument.
+#'
+#' @return The `write_mix_json` function does not return a value while
+#'   the `read_mix_json` returns the mixture object stored in the
+#'   connection specified.
+#'
+#' @family mixdist
+#'
+#' @examples
+#' \dontrun{
+#' nm <- mixnorm(rob = c(0.2, 0, 2), inf = c(0.8, 2, 2), sigma = 5)
+#'
+#' write_mix_json(nm, "normal_mixture.json", pretty=TRUE, digits=1)
+#'
+#' mix <- read_mix_json("normal_mixture.json")
+#' }
+#' @name mixjson
+NULL
+
+#' @rdname mixjson
+#' @export
+write_mix_json <- function(mix, con, ...) {
+  ## strip off all attributes which are added by the EM outputs and
+  ## recast the class into a mixture only object
+  if (inherits(mix, "EM")) {
+    message("Dropping EM information from mixture object before serialization.")
+    mix <- mixcombine(mix, weight = 1, rescale = FALSE)
+  }
+  dot_args <- list(...)
+  if (!("digits" %in% names(dot_args))) {
+    warning(
+      "JSON serialization by default restricts number of digits to ",
+      formals(jsonlite::toJSON)$digits,
+      ".\nIt is recommended to set this option explicitly."
+    )
+  }
+  umix <- unclass(mix)
+  amix <- attributes(mix)
+  amix$link <- amix$link$name
+  json <- jsonlite::toJSON(list(meta = amix, comp = umix), ...)
+  writeLines(json, con, useBytes = TRUE)
+}
+
+#' @rdname mixjson
+#' @param rescale A logical value indicating whether to rescale the
+#'   mixture weights so that they sum to 1. Defaults to `TRUE`.
+#' @export
+read_mix_json <- function(con, ..., rescale = TRUE) {
+  json <- readLines(con)
+  mix_list <- jsonlite::fromJSON(json, ...)
+  mix <- mix_list$comp
+  attributes(mix) <- mix_list$meta
+  attr(mix, "link") <- link_map[[mix_list$meta$link]]
+  if (rescale) {
+    mix[1, ] <- mix[1, ] / sum(mix[1, ])
+  }
+  mix
+}