clean headers, fix some examples, export few more functions

NAMESPACE

@@ -65,8 +65,10 @@ export(gridplot)
 export(hidden_paths)
 export(mc_to_sc)
 export(mc_to_sc_data)
+export(most_probable_cluster)
 export(mssplot)
 export(plot_colors)
+export(posterior_cluster_probabilities)
 export(posterior_probs)
 export(separate_mhmm)
 export(seqdef)

R/most_probable_cluster.R

@@ -1,6 +1,23 @@
-most_probable_cluster <- function(x, type = "viterbi", hp) {
+#' Extract Most Probable Cluster for Each Sequence
+#' 
+#' @param x An object of class `mhmm` or `mnhmm`.
+#' @param type A character string specifying the method to use. Either
+#' `"viterbi"` (default) or `"posterior"`. Former uses the most probable hidden 
+#' path to determine the cluster membership for each sequence, while the latter 
+#' finds the cluster which has the largest sum of posterior probabilities of 
+#' states of that cluster. 
+#' @param hp An output from [hidden_paths()] function. Only used in case of 
+#' `type = "viterbi"`. If missing, hidden paths will be computed using `x`.
+#' @return A vector containing the most probable cluster for each sequence.
+#' @export
+most_probable_cluster <- function(x, type = "viterbi", hp = NULL) {
+  stopifnot_(
+    inherits(x, "mhmm") || inherits(x, "mnhmm"),
+    "Argument {.arg x} must be a {.cls mhmm} or {.cls mnhmm} object."
+  )
   type <- match.arg(type, c("viterbi", "posterior"))
   if (type == "viterbi") {
+    if (is.null(hp)) hp <- hidden_paths(x)
     mm <- NULL
     state_names <- unlist(x$state_names)
     clusters <- numeric(x$n_sequences)
@@ -11,15 +28,24 @@ most_probable_cluster <- function(x, type = "viterbi", hp) {
       } else {
         idx <- which(grepl(paste0(x$cluster_names[i], ": "), hp[, 1]))
       }
-      clusters[idx] <- x$cluster_names[i]
+      clusters[idx] <- i
     }
   } else {
     clusters <- apply(posterior_cluster_probabilities(x), 1, which.max)
   }
   factor(clusters, levels = seq_len(x$n_clusters), labels = x$cluster_names)
 }
-
+#' Extract Posterior Cluster Probabilities
+#' 
+#' @param x An object of class `mhmm` or `mnhmm`.
+#' @return matrix of posterior cluster probabilities for each sequence and 
+#' cluster.
+#' @export
 posterior_cluster_probabilities <- function(x) {
+  stopifnot_(
+    inherits(x, "mhmm") || inherits(x, "mnhmm"),
+    "Argument {.arg x} must be a {.cls mhmm} or {.cls mnhmm} object."
+  )
   pp <- posterior_probs(x, as_data_frame = FALSE)
   posterior_cluster_probabilities <- matrix(0, x$n_sequences, x$n_clusters)
   n_states <- rep(x$n_states, length.out = x$n_clusters)

R/mssplot-deprecated.R

@@ -151,23 +151,9 @@
 #' @param respect_void  If `TRUE` (default), states at the time points
 #' corresponding to TraMineR's void in the observed sequences are set to void
 #' in the hidden state sequences as well.
-#'
 #' @param ... Other arguments to be passed on to
 #'   [TraMineR::seqplot()].
 #'
-#' @examples
-#' # Loading mixture hidden Markov model (mhmm object)
-#' # of the biofam data
-#' data("mhmm_biofam")
-#'
-#' # Plotting the first cluster only
-#' mssplot(mhmm_biofam, which.plots = 1)
-#'
-#' if (interactive()) {
-#'   # Interactive plot
-#'   mssplot(mhmm_biofam)
-#' }
-#'
 #' @seealso [build_mhmm()] and [fit_model()] for building and
 #'   fitting mixture hidden Markov models, [hidden_paths()] for
 #'   computing the most probable paths (Viterbi paths) of hidden states,

R/plot.ssp-deprecated.R

@@ -14,25 +14,6 @@
 #'
 #' @references Helske S. and Helske J. (2019). Mixture Hidden Markov Models for Sequence Data: The seqHMM Package in R,
 #' Journal of Statistical Software, 88(3), 1-32. doi:10.18637/jss.v088.i03
-#'
-#' @examples
-#'
-#' data("biofam3c")
-#'
-#' ## Building sequence objects
-#' child_seq <- seqdef(biofam3c$children, start = 15)
-#' marr_seq <- seqdef(biofam3c$married, start = 15)
-#' left_seq <- seqdef(biofam3c$left, start = 15)
-#'
-#' ## Choosing colors
-#' attr(child_seq, "cpal") <- c("#66C2A5", "#FC8D62")
-#' attr(marr_seq, "cpal") <- c("#AB82FF", "#E6AB02", "#E7298A")
-#' attr(left_seq, "cpal") <- c("#A6CEE3", "#E31A1C")
-#'
-#'
-#' # Plotting state distribution plots of observations
-#' ssp1 <- ssp(list(child_seq, marr_seq, left_seq))
-#' plot(ssp1)
 plot.ssp <- function(x, ...) {
   .Deprecated("stacked_sequence_plot")
   plot.new()

R/simulate_mhmm.R

@@ -69,9 +69,8 @@
 #'   data = dataf, coefficients = coefs
 #' )
 #'
-#' ssplot(sim$observations,
-#'   hidden.paths = sim$states, plots = "both",
-#'   sortv = "from.start", sort.channel = 0, type = "I"
+#' stacked_sequence_plot(sim, 
+#'   sort_by = "start", sort_channel = "states", type = "i"
 #' )
 #'
 #' hmm <- build_mhmm(sim$observations,
@@ -87,10 +86,14 @@
 #'
 #' paths <- hidden_paths(fit$model)
 #'
-#' ssplot(list(estimates = paths, true = sim$states),
-#'   sortv = "from.start",
-#'   sort.channel = 2, ylab = c("estimated paths", "true (simulated)"),
-#'   type = "I"
+#' stacked_sequence_plot(
+#'   list(
+#'     "estimated paths" = paths, 
+#'     "true (simulated)" = sim$states
+#'   ),
+#'   sort_by = "start",
+#'   sort_channel = "true (simulated)",
+#'   type = "i"
 #' )
 #'
 simulate_mhmm <- function(

R/ssp-deprecated.R

@@ -154,91 +154,7 @@
 #' corresponding to TraMineR's void in the observed sequences are set to void
 #' in the hidden state sequences as well.
 #' @param ... Other arguments to be passed on to [TraMineR::seqplot()].
-#'
 #' @return Object of class `ssp`.
-#'
-#' @seealso [plot.ssp()] for plotting objects created with
-#'   the `ssp` function; [gridplot()] for plotting multiple `ssp`
-#'   objects; [build_hmm()] and [fit_model()] for building and
-#'   fitting hidden Markov models; [hidden_paths()] for
-#'   computing the most probable paths of hidden states; and [biofam3c()] and
-#'   [hmm_biofam()] for information on the data and model used in the example.
-#'
-#' @examples
-#' data("biofam3c")
-#'
-#' ## Building sequence objects
-#' child_seq <- seqdef(biofam3c$children, start = 15)
-#' marr_seq <- seqdef(biofam3c$married, start = 15)
-#' left_seq <- seqdef(biofam3c$left, start = 15)
-#'
-#' ## Choosing colors
-#' attr(child_seq, "cpal") <- c("#66C2A5", "#FC8D62")
-#' attr(marr_seq, "cpal") <- c("#AB82FF", "#E6AB02", "#E7298A")
-#' attr(left_seq, "cpal") <- c("#A6CEE3", "#E31A1C")
-#'
-#'
-#' # Defining the plot for state distribution plots of observations
-#' ssp1 <- ssp(list(
-#'   "Parenthood" = child_seq, "Marriage" = marr_seq,
-#'   "Residence" = left_seq
-#' ))
-#' # Plotting ssp1
-#' plot(ssp1)
-#'
-#' \dontrun{
-#' # Defining the plot for sequence index plots of observations
-#' ssp2 <- ssp(
-#'   list(child_seq, marr_seq, left_seq),
-#'   type = "I", plots = "obs",
-#'   # Sorting subjects according to the beginning of the 2nd channel (marr_seq)
-#'   sortv = "from.start", sort.channel = 2,
-#'   # Controlling the size, positions, and names for channel labels
-#'   ylab.pos = c(1, 2, 1), cex.lab = 1, ylab = c("Children", "Married", "Residence"),
-#'   # Plotting without legend
-#'   with.legend = FALSE
-#' )
-#' plot(ssp2)
-#'
-#' # Plotting hidden Markov models
-#'
-#' # Loading data
-#' data("hmm_biofam")
-#'
-#' # Plotting observations and most probable hidden states paths
-#' ssp3 <- ssp(
-#'   hmm_biofam,
-#'   type = "I", plots = "both",
-#'   # Sorting according to multidimensional scaling of hidden states paths
-#'   sortv = "mds.hidden",
-#'   # Controlling title
-#'   title = "Biofam", cex.title = 1.5,
-#'   # Labels for x axis and tick marks
-#'   xtlab = 15:30, xlab = "Age"
-#' )
-#' plot(ssp3)
-#'
-#' # Computing the most probable paths of hidden states
-#' hid <- hidden_paths(hmm_biofam)
-#' # Giving names for hidden states
-#' library(TraMineR)
-#' alphabet(hid) <- paste("Hidden state", 1:5)
-#'
-#' # Plotting observations and hidden state paths
-#' ssp4 <- ssp(
-#'   hmm_biofam,
-#'   type = "I", plots = "hidden.paths",
-#'   # Sequence object of most probable paths
-#'   hidden.paths = hid,
-#'   # Sorting according to the end of hidden state paths
-#'   sortv = "from.end", sort.channel = 0,
-#'   # Contolling legend position, type, and proportion
-#'   with.legend = "bottom.combined", legend.prop = 0.15,
-#'   # Plotting without title and y label
-#'   title = FALSE, ylab = FALSE
-#' )
-#' plot(ssp4)
-#' }
 ssp <- function(
     x, hidden.paths = NULL,
     plots = "obs", type = "d", tlim = 0,

R/ssplot-deprecated.R

@@ -155,82 +155,6 @@
 #'
 #' @param ... Other arguments to be passed on to
 #'   [TraMineR::seqplot()].
-#'
-#' @examples
-#' data("biofam3c")
-#'
-#' # Creating sequence objects
-#' child_seq <- seqdef(biofam3c$children, start = 15)
-#' marr_seq <- seqdef(biofam3c$married, start = 15)
-#' left_seq <- seqdef(biofam3c$left, start = 15)
-#'
-#' ## Choosing colors
-#' attr(child_seq, "cpal") <- c("#66C2A5", "#FC8D62")
-#' attr(marr_seq, "cpal") <- c("#AB82FF", "#E6AB02", "#E7298A")
-#' attr(left_seq, "cpal") <- c("#A6CEE3", "#E31A1C")
-#'
-#'
-#' # Plotting state distribution plots of observations
-#' ssplot(list(
-#'   "Children" = child_seq, "Marriage" = marr_seq,
-#'   "Residence" = left_seq
-#' ))
-#'
-#' \dontrun{
-#' # Plotting sequence index plots of observations
-#' ssplot(
-#'   list(child_seq, marr_seq, left_seq),
-#'   type = "I",
-#'   # Sorting subjects according to the beginning of the 2nd channel (marr_seq)
-#'   sortv = "from.start", sort.channel = 2,
-#'   # Controlling the size, positions, and names for channel labels
-#'   ylab.pos = c(1, 2, 1), cex.lab = 1, ylab = c("Children", "Married", "Residence"),
-#'   # Plotting without legend
-#'   with.legend = FALSE
-#' )
-#'
-#' # Plotting hidden Markov models
-#'
-#' # Loading a ready-made HMM for the biofam data
-#' data("hmm_biofam")
-#'
-#' # Plotting observations and hidden states paths
-#' ssplot(
-#'   hmm_biofam,
-#'   type = "I", plots = "both",
-#'   # Sorting according to multidimensional scaling of hidden states paths
-#'   sortv = "mds.hidden",
-#'   ylab = c("Children", "Married", "Left home"),
-#'   # Controlling title
-#'   title = "Biofam", cex.title = 1.5,
-#'   # Labels for x axis and tick marks
-#'   xtlab = 15:30, xlab = "Age"
-#' )
-#'
-#' # Computing the most probable paths of hidden states
-#' hidden.paths <- hidden_paths(hmm_biofam)
-#' hidden.paths_seq <- seqdef(hidden.paths, labels = paste("Hidden state", 1:5))
-#'
-#' # Plotting observations and hidden state paths
-#' ssplot(
-#'   hmm_biofam,
-#'   type = "I", plots = "hidden.paths",
-#'   # Sequence object of most probable paths
-#'   hidden.paths = hidden.paths_seq,
-#'   # Sorting according to the end of hidden state paths
-#'   sortv = "from.end", sort.channel = 0,
-#'   # Contolling legend position, type, and proportion
-#'   with.legend = "bottom", legend.prop = 0.15,
-#'   # Plotting without title and y label
-#'   title = FALSE, ylab = FALSE
-#' )
-#' }
-#' @seealso [ssp()] for creating `ssp` objects and [plot.ssp()]
-#' and [gridplot()] for plotting these;
-#' [build_hmm()] and [fit_model()] for building and
-#' fitting hidden Markov models; [hidden_paths()] for
-#' computing the most probable paths of hidden states; and [biofam3c()]
-#' [hmm_biofam()] for information on the data and model used in the example.
 ssplot <- function(x, hidden.paths = NULL,
                    plots = "obs", type = "d", tlim = 0,
                    sortv = NULL, sort.channel = 1, dist.method = "OM",