version 1.0.1

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: SNSeg
 Title: Self-Normalization(SN) Based Change-Point Estimation for Time
         Series
-Version: 1.0.0
+Version: 1.0.1
 Authors@R: 
     c(person("Shubo","Sun",role=c("aut"),email = "sxs3935@miami.edu"),
       person("Zifeng","Zhao",role = c("aut","cre"),email = "zzhao2@nd.edu"),
@@ -23,11 +23,11 @@ Imports: Rcpp, mvtnorm, truncnorm, evd
 Suggests: rmarkdown, knitr
 VignetteBuilder: knitr
 NeedsCompilation: yes
-Packaged: 2023-07-05 15:32:21 UTC; Shubo Sun
+Packaged: 2024-01-08 13:25:12 UTC; sxs3935
 Author: Shubo Sun [aut],
   Zifeng Zhao [aut, cre],
   Feiyu Jiang [aut],
   Xiaofeng Shao [aut]
 Maintainer: Zifeng Zhao <zzhao2@nd.edu>
 Repository: CRAN
-Date/Publication: 2023-07-06 13:50:09 UTC
+Date/Publication: 2024-01-08 20:30:03 UTC

MD5

@@ -1,17 +1,18 @@
-d971d1bae85b2b8cae49b96f6f1a26bd *DESCRIPTION
-948a6410653dc44ecfa181fe5d76eca5 *NAMESPACE
+44ee9515308ff84d230442b033276b99 *DESCRIPTION
+3f19251c41233bf261dd2f5cd0c40d13 *NAMESPACE
 250746f564bdb9f86121331481df88b5 *R/MAR_all.R
 8c2b1ab1f398e682821767a3175a76d9 *R/RcppExports.R
 44a911a6ba84c360de7f276d35272c85 *R/SNHD.R
-52f4de16b6744017a1d84cf9300317ac *R/SNSeg.R
-9d89cea3b91e89350acef6a60a69acf8 *R/SNSeg_HD.R
-08017dbb1f983affad7c060b45bed699 *R/SNSeg_Multi.R
-b8ce0cf6cddab0648e423f4ce57e3f82 *R/SNSeg_Uni.R
-bf7df0e4d4b4d7786fadfda9f8179002 *R/SNSeg_Uni_multi_para.R
-afe66deab5164bf7e728db5f894318ff *R/SNSeg_Uni_single_para.R
+5fe285c33dce62bcf9d85320cf858488 *R/SNSeg.R
+8de1afd224e35cd057cb0f7fe538826c *R/SNSeg_HD.R
+3dc2fa9375b48ff4d07f999d2d20c2df *R/SNSeg_Multi.R
+8365303c10a8dc074901e1de03b78848 *R/SNSeg_Uni.R
+f24493f1d638daf6532516a2546f8bc2 *R/SNSeg_Uni_multi_para.R
+f727d8097d9e17fd7a636030f3019174 *R/SNSeg_Uni_single_para.R
 9b4aea565e59d70ba4c1b57ccc346a7c *R/SN_acf.R
 6281a50ae0e626b8e33e5af140574b8d *R/SN_bivcor.R
 36ac57f38cf8a2d16dbb292601efbfe2 *R/SN_divisive_path.R
+96fc8d4c2e8a7d89e8355d43365fc1a5 *R/SN_general.R
 880f6b19f08aa327de4cb5ff8304aa45 *R/SN_mean.R
 f7661990e0f057764d205b8642a37253 *R/SN_quantile.R
 12a05d768c20888f319c02dbbf17acec *R/SN_variance.R
@@ -21,25 +22,39 @@ a04e655e7ca31e669e581646eb8ca8c0 *R/max_SNsweep.R
 2285dcacb667fb9a4783a35ac7e05c23 *R/mts_covariance.R
 8e297ae2665c704231fa2e580ec4e73a *R/multimean.R
 13671bf745bd66b725f88d7e813ba0d4 *R/multiparameter.R
+5a04f9a6a42922b3e8f0f8b9b4f90f05 *R/plot_summary_print_HD.R
+60ac59496bb844de633f69bcc86eb40d *R/plot_summary_print_Multi.R
+b5149ca0693fb00c862af046cff34fe3 *R/plot_summary_print_Uni.R
+9ef45591dc9ca6ba130164446c095bf6 *R/summary.R
 8a9e17b6525b341039d9baf33fbb8862 *R/sysdata.rda
-89d03f8079d1c8cba6f608ab4a0fab4d *build/vignette.rds
+eb98c4ad08aef081944cd0c413fe8d3e *build/vignette.rds
 3fb15c729769bc117aa15876f53b2380 *data/critical_values_HD.rda
 dad7a4b4e50c26b1b869b7b566d23b7a *data/critical_values_multi.rda
 bfe54fd6b8192e42b42b3e0772968b5a *data/critical_values_single.rda
-306d9643b29006081fbdf5ecf5c9d65b *inst/doc/SNSeg.R
-5441f68e932b9959974bd4f9af49d75d *inst/doc/SNSeg.Rmd
-87ef01c9e7d23d6aeb36b564b7812914 *inst/doc/SNSeg.html
+2cde279b9730bb992348f784a2bd2e23 *inst/doc/SNSeg.R
+2aa55f1c6def191cf9b7844fd0743de5 *inst/doc/SNSeg.Rmd
+ddd8db7237d187cbd468404b8caa8f26 *inst/doc/SNSeg.html
 f99a880f5760fef934523411dd846299 *man/MAR.Rd
 a39eadafd7a5634213b42f4e5fdb4ca1 *man/MAR_MTS_Covariance.Rd
 d5af6e4d0b2bb7597c613833cd6ec9b2 *man/MAR_Variance.Rd
-95edd78f089a7eb47cec30636b971cbc *man/SNSeg.Rd
-552b478d4179fa1d125819d53a142b37 *man/SNSeg_HD.Rd
-6f0860409a4649c4f791d4eabd2e3f69 *man/SNSeg_Multi.Rd
-0b9c1eac3d472300af753d4938562fd6 *man/SNSeg_Uni.Rd
+82e275684126c21225eadd9216e6acc8 *man/SNSeg.Rd
+26db3c32009f51023ad873de81170de7 *man/SNSeg_HD.Rd
+14675339ea5978f7c59bc6a6be5ee18d *man/SNSeg_Multi.Rd
+dd4dd9c96b9eb745782dbebdccd0e9bf *man/SNSeg_Uni.Rd
+741cb5519626ff03d4199914a72d4162 *man/SNSeg_estimate.Rd
 905ae0ebdceaad0275dbc5a565e98fb4 *man/critical_values_HD.Rd
 9ff7cba113816526d933fda675f1c7e5 *man/critical_values_multi.Rd
 96493bae7e600515830fc39ca6cbb34a *man/critical_values_single.Rd
 efb935050c10092fa012f95a16621b4f *man/max_SNsweep.Rd
-92e3f0adbb3ed050399da54a2574689a *src/RcppExports.cpp
+99506a8494c6b3e430f11444588faf6e *man/plot.SNSeg_HD.Rd
+1782c4bc152591f0901a03a658fbd078 *man/plot.SNSeg_Multi.Rd
+075b34a9f46a06fd2e0bfa51d3629d20 *man/plot.SNSeg_Uni.Rd
+626f8a7fd9246dbd66ce440bfd37dc4d *man/print.SNSeg_HD.Rd
+08d09fdef70fcdfd1cef6d77aef3ec56 *man/print.SNSeg_Multi.Rd
+2d395a885d57814f83becb423b3313ec *man/print.SNSeg_Uni.Rd
+ed805ba99e796324432c4c4d3795367a *man/summary.SNSeg_HD.Rd
+44e5a4c7aa1f0bc33e9f16caa56e853b *man/summary.SNSeg_Multi.Rd
+8ff8251a4873bb270497746d9dc4565e *man/summary.SNSeg_Uni.Rd
+3dc9d199c6de4ce3b6092a8d5295851a *src/RcppExports.cpp
 c0924f945eb01aaf699e4a5991fd2072 *src/SN_Util.cpp
-5441f68e932b9959974bd4f9af49d75d *vignettes/SNSeg.Rmd
+2aa55f1c6def191cf9b7844fd0743de5 *vignettes/SNSeg.Rmd

NAMESPACE

@@ -1,19 +1,31 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method(plot,SNSeg_HD)
+S3method(plot,SNSeg_Multi)
+S3method(plot,SNSeg_Uni)
+S3method(print,SNSeg_HD)
+S3method(print,SNSeg_Multi)
+S3method(print,SNSeg_Uni)
+S3method(summary,SNSeg_HD)
+S3method(summary,SNSeg_Multi)
+S3method(summary,SNSeg_Uni)
 export(MAR)
 export(MAR_MTS_Covariance)
 export(MAR_Variance)
 export(SNSeg_HD)
 export(SNSeg_Multi)
 export(SNSeg_Uni)
+export(SNSeg_estimate)
 export(max_SNsweep)
 importFrom(Rcpp,evalCpp)
 importFrom(graphics,abline)
 importFrom(graphics,par)
 importFrom(graphics,plot)
 importFrom(mvtnorm,rmvnorm)
+importFrom(stats,acf)
 importFrom(stats,approx)
 importFrom(stats,cor)
+importFrom(stats,cov)
 importFrom(stats,pnorm)
 importFrom(stats,quantile)
 importFrom(stats,rnorm)

R/SNSeg.R

@@ -6,29 +6,51 @@
 #' \code{critical_values_multi} and \code{critical_values_HD}) were attached.
 #' Functions \code{MAR}, \code{MAR_Variance} and \code{MAR_MTS_Covariance} can be utilized
 #' to generate time series data that are used for the functions \code{SNSeg_Uni}, \code{SNSeg_Multi} and \code{SNSeg_HD}.
-#' The function \code{max_SNsweep} enables users to compute the SN test
-#' statistic and make the segmentation plot for these statistics.
+#' S3 methods plot(), print() and summary() are available for class "SNSeg_Uni",
+#' "SNSeg_Multi" and "SNSeh_HD" objects. The function \code{max_SNsweep} enables users
+#' to compute the SN test statistic and make the segmentation plot for these
+#' statistics. The function \code{SNSeh_estimate} allows users to compute parameter
+#' estimates of each segment that is separated by estimated change-points.
 #'
 #' @section SNSeg_Uni:
 #' \code{SNSeg_Uni} provides SN-based change point estimates for a univariate
 #' time series based on changes in a single parameter or multiple parameters.
 #'
 #' For the parameters of the SN test, the function
 #' \code{SNSeg_Uni} offers mean, variance, acf, bivariate
-#' correlation and numeric quantiles as available options. To visualize the
-#' estimated change points, users can set "plot_SN = TRUE" and "est_cp_loc = TRUE"
+#' correlation and numeric quantiles as available options. It also allows users
+#' to enter their own defined function as the input parameter. Besides, users can
+#' use a composite set of parameters including one or more from the mean, variance,
+#' acf or numeric quantiles quantile. To visualize the estimated change points,
+#' users can set "plot_SN = TRUE" and "est_cp_loc = TRUE"
 #' to generate the time series segmentation plot. The output comprises of the
-#' parameter(s), the window size, and the estimated change point locations.
+#' parameter(s), the window size, and the estimated change point locations. The
+#' function returns an S3 object of class "SNSeg_Uni", which can be applied to
+#' S3 methods plot(), print() and summary().
 #'
 #' @section SNSeg_Multi:
 #' \code{SNSeg_Multi} provides SN-based change point estimates for multivariate
-#' time series based on changes in multivariate means or covariance matrix.
-#' Different from the function \code{SNSeg_Uni}, \code{SNSeg_Multi} does not
-#' contain the option to generate the time series segmentation plot.
+#' time series based on changes in multivariate means or covariance matrix. The
+#' "plot_SN = TRUE" option allows users to plot each individual time series and
+#' the estimated change=points. The  function returns an S3 object of class
+#' "SNSeg_Multi", which can be applied to S3 methods plot(), print() and summary().
 #'
 #' @section SNSeg_HD:
 #' \code{SNSeg_HD} provides SN-based change point estimates for a
-#' high-dimensional time series based on changes in high-dimensional means.
+#' high-dimensional time series based on changes in high-dimensional means. The
+#' "plot_SN = TRUE" option allows users to plot each individual time series and
+#' the estimated change=points. The input argument "n_plot" enables users to plot
+#' the first "n_plot" number of time series. The function returns an S3 object of
+#' class "SNSeg_HD", which can be applied to S3 methods plot(), print() and
+#' summary().
+#'
+#' @section max_SNsweep:
+#' \code{max_SNsweep} provides SN based test statistic of each time point and
+#' generates a plot for these statistics and the estimated change-points.
+#'
+#' @section SNSeg_estimate:
+#' \code{SNSeg_estimate} computes the parameter estimates of each segment separated
+#' by the estimated change-points.
 #'
 #' @section critical values table:
 #' The package \code{SNSeg} provides three critical values table.

R/SNSeg_HD.R

@@ -22,10 +22,17 @@ NULL
 #' test. Since grid_size = n*grid_size_scale, where n is the length of time
 #' series, this function will compute the grid_size_scale by diving n from
 #' grid_size when it is not NULL.
-#' @return SNSeg_HD returns a list of numeric objects, including the local window
-#' size to cover a change point, the estimated change-point locations, the
-#' confidence level and the critical value of the SN test.
+#' @param plot_SN  Boolean value to plot the time series or not.
+#' The default setting is FALSE.
+#' @param est_cp_loc Boolean value to plot a red solid vertical line for
+#' estimated change-point locations if est_cp_loc = TRUE.
+#' @param n_plot Number of time series being plotted if plot_SN = TRUE.
+#' @return SNSeg_HD returns an S3 object of class "SNSeg_HD" including the time
+#' series, the local window size to cover a change point, the estimated change-point
+#' locations, the confidence level and the critical value of the SN test. It also
+#' generates time series segmentation plot when \code{plot_SN = TRUE}.
 #' \describe{
+#'   \item{\code{ts}}{A numeric matrix of the input time series.}
 #'   \item{\code{grid_size}}{A numeric value of the window size.}
 #'   \item{\code{SN_sweep_result}}{A list of n matrices where each matrix
 #'   consists of four columns: (1) SN-based test statistic for each change-point
@@ -37,6 +44,18 @@ NULL
 #'   \item{\code{critical_value}}{Critical value of the SN-based test statistic.}
 #' }
 #'
+#' Users can apply the functions \code{summary.SN} to compute the parameter estimate
+#' of each segment separated by the detected change-points. An additional function
+#' \code{plot.SN} can be used to plot the time series with estimated change-points.
+#' Users can set the option \code{plot_SN = TRUE} or use the function \code{plot.SN}
+#' to plot the time series.
+#'
+#' It deserves to note that some change-points could be missing due to the constraint
+#' on \code{grid_size_scale} or related \code{grid_size} that \code{grid_size_scale}
+#' has a minimum value of 0.05. Therefore, SNCP claims no change-points within the
+#' first n*\code{grid_size_scale} or the last n*\code{grid_size_scale} time points.
+#' This is a limitation of the function \code{SNSeg_HD}.
+#'
 #' For more examples of \code{SNSeg_HD} see the help vignette:
 #' \code{vignette("SNSeg", package = "SNSeg")}
 #'
@@ -69,9 +88,10 @@ NULL
 #' # vignette("SNSeg", package = "SNSeg")
 #' }
 #'
-#' @export SNSeg_HD
+#' @export
 SNSeg_HD <- function(ts, confidence = 0.9, grid_size_scale = 0.05,
-                     grid_size = NULL){
+                     grid_size = NULL, plot_SN = FALSE, est_cp_loc = TRUE,
+                     n_plot = 5){
   if(is.null(ts))
   {stop("Input of ts is missing!")}
   if(dim(ts)[1]<dim(ts)[2]){
@@ -154,6 +174,23 @@ SNSeg_HD <- function(ts, confidence = 0.9, grid_size_scale = 0.05,
   SN_sweep_result <- SN_sweep_mean_HD(ts, grid_size)
   SN_result <- SN_divisive_path(start=1, end=n, grid_size, SN_sweep_result, critical_value=critical_value)
 
-  return(list("grid_size" = grid_size,"est_cp" = SN_result,"confidence" = confidence,
-              "SN_sweep_result" = SN_sweep_result,"critical_value" = critical_value))
+  if(plot_SN == TRUE){
+    for(i in 1:n_plot){
+      plot(ts[,i], xlab = "Time", ylab = "Value",
+           main=paste0("SN Segmentation plot for Time Series ",i,""))
+      if(est_cp_loc){
+        abline(v = SN_result, col = 'red')
+      }
+    }
+  }
+
+  final_result <- structure(
+    list(
+      ts = ts, grid_size = grid_size,
+      SN_sweep_result = SN_sweep_result, est_cp = SN_result,
+      confidence = confidence, critical_value = critical_value
+    ), class = 'SNSeg_HD'
+  )
+  final_result
+
 }

R/SNSeg_Multi.R

@@ -4,6 +4,7 @@ NULL
 
 #' @importFrom utils data
 #' @importFrom stats approx
+#' @importFrom stats cov
 #' @importFrom mvtnorm rmvnorm
 NULL
 
@@ -30,11 +31,17 @@ NULL
 #' test. Since grid_size = n*grid_size_scale, where n is the length of time
 #' series, this function will compute the grid_size_scale by diving n from
 #' grid_size when it is not NULL.
-#' @return \code{SNSeg_Multi} returns a list of objects, including the type of
-#' parameter to be tested, the local window size to cover a change point, the
-#' estimated change-point locations, the confidence level and the critical value
-#' of the SN test.
+#' @param plot_SN  Boolean value to plot the time series or not.
+#' The default setting is FALSE.
+#' @param est_cp_loc Boolean value to plot a red solid vertical line for
+#' estimated change-point locations if est_cp_loc = TRUE
+#' @return \code{SNSeg_Multi} returns an S3 object of class "SNSeg_Multi" including
+#' the time series, the type of parameter to be tested, the local window size to
+#' cover a change point, the estimated change-point locations, the confidence level
+#' and the critical value of the SN test. It also generates time series segmentation
+#' plot when \code{plot_SN = TRUE}.
 #' \describe{
+#'   \item{\code{ts}}{A numeric matrix of the input time series.}
 #'   \item{\code{paras_to_test}}{the parameter used for the SN test as character.}
 #'   \item{\code{grid_size}}{A numeric value of the window size.}
 #'   \item{\code{SN_sweep_result}}{A list of n matrices where each matrix
@@ -47,6 +54,18 @@ NULL
 #'   \item{\code{critical_value}}{Critical value of the SN-based test statistic.}
 #' }
 #'
+#' Users can apply the functions \code{summary.SN} to compute the parameter estimate
+#' of each segment separated by the detected change-points. An additional function
+#' \code{plot.SN} can be used to plot the time series with estimated change-points.
+#' Users can set the option \code{plot_SN = TRUE} or use the function \code{plot.SN}
+#' to plot the time series.
+#'
+#' It deserves to note that some change-points could be missing due to the constraint
+#' on \code{grid_size_scale} or related \code{grid_size} that \code{grid_size_scale}
+#' has a minimum value of 0.05. Therefore, SNCP claims no change-points within the
+#' first n*\code{grid_size_scale} or the last n*\code{grid_size_scale} time points.
+#' This is a limitation of the function \code{SNSeg_Multi}.
+#'
 #' For more examples of \code{SNSeg_Multi} see the help vignette:
 #' \code{vignette("SNSeg", package = "SNSeg")}
 #'
@@ -83,9 +102,10 @@ NULL
 #' # vignette("SNSeg", package = "SNSeg")
 #' }
 #'
-#' @export SNSeg_Multi
+#' @export
 SNSeg_Multi <- function(ts, paras_to_test = "mean", confidence = 0.9,
-                        grid_size_scale = 0.05, grid_size = NULL){
+                        grid_size_scale = 0.05, grid_size = NULL,
+                        plot_SN = FALSE, est_cp_loc = TRUE){
 
   if(is.null(ts))
   {stop("Input of ts is missing!")}
@@ -193,7 +213,22 @@ SNSeg_Multi <- function(ts, paras_to_test = "mean", confidence = 0.9,
     SN_result <- SN_divisive_path(start=1, end=n, grid_size, SN_sweep_result, critical_value=critical_value)
   }
 
-  return(list("paras_to_test" = paras_to_test, "grid_size" = grid_size, "confidence" = confidence,
-              "est_cp" = SN_result, "SN_sweep_result" = SN_sweep_result,
-              "critical_value" = critical_value))
+  if(plot_SN == TRUE){
+    for(i in 1:dim(ts)[1]){
+      plot(ts[i,], xlab = "Time", ylab = "Value",
+           main=paste0("SN Segmentation plot for Time Series ",i,""))
+      if(est_cp_loc){
+        abline(v = SN_result, col = 'red')
+      }
+    }
+  }
+
+  final_result <- structure(
+    list(
+      ts = ts, paras_to_test = paras_to_test, grid_size = grid_size,
+      SN_sweep_result = SN_sweep_result, est_cp = SN_result,
+      confidence = confidence, critical_value = critical_value
+    ), class = 'SNSeg_Multi'
+  )
+  final_result
 }