Merge pull request #4 from MikeJaredS/performance_enhancements_quantile

Performance enhancements quantile

Author: MikeJaredS

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: hermiter
 Title: Efficient Sequential and Batch Estimation of Univariate and Bivariate Probability Density Functions and Cumulative Distribution Functions along with Quantiles (Univariate) and Spearman's Correlation (Bivariate)
-Version: 2.0.3
+Version: 2.1.0
 Authors@R: c(
   person("Michael","Stephanou",role=c("aut","cre"), email="[email protected]"),
   person("Melvin","Varughese",role="ctb"))
@@ -9,12 +9,12 @@ Author: Michael Stephanou [aut, cre],
 Maintainer: Michael Stephanou <[email protected]>
 Description: Facilitates estimation of full univariate and bivariate 
   probability density functions and cumulative distribution functions along with
-  full quantile functions (univariate) and Spearman's rank correlation 
+  full quantile functions (univariate) and nonparametric correlation 
   (bivariate) using Hermite series based estimators. These estimators are 
   particularly useful in the sequential setting (both stationary and 
   non-stationary) and one-pass batch estimation setting for large data sets. 
   Based on: Stephanou, Michael, Varughese, Melvin and Macdonald, Iain. "Sequential quantiles via Hermite series density estimation." Electronic Journal of Statistics 11.1 (2017): 570-607 <doi:10.1214/17-EJS1245>, 
-  Stephanou, Michael and Varughese, Melvin. "On the properties of Hermite series based distribution function estimators." Metrika (2020) <doi:10.1007/s00184-020-00785-z> and Stephanou, Michael and Varughese, Melvin. "Sequential Estimation of Nonparametric Correlation using Hermite Series Estimators." arXiv Preprint (2020) <arXiv:2012.06287>.
+  Stephanou, Michael and Varughese, Melvin. "On the properties of Hermite series based distribution function estimators." Metrika (2020) <doi:10.1007/s00184-020-00785-z> and Stephanou, Michael and Varughese, Melvin. "Sequential estimation of Spearman rank correlation using Hermite series estimators." Journal of Multivariate Analysis (2021) <doi:10.1016/j.jmva.2021.104783>.
 License: MIT + file LICENSE
 Depends: R (>= 3.5.0)
 Imports: 
@@ -23,7 +23,7 @@ Imports:
 LinkingTo: 
   Rcpp,
   BH
-RoxygenNote: 7.1.1
+RoxygenNote: 7.1.2
 Suggests: 
     testthat,
     magrittr,

NAMESPACE

@@ -12,19 +12,26 @@ S3method(calculate_running_std,hermite_estimator_bivar)
 S3method(update_batch,hermite_estimator_univar)
 S3method(update_sequential,hermite_estimator_univar)
 S3method(spearmans,hermite_estimator_bivar)
+S3method(kendall,hermite_estimator_bivar)
 S3method(spearmans,hermite_estimator_univar)
+S3method(kendall,hermite_estimator_univar)
 S3method(cum_prob,hermite_estimator_bivar)
 S3method(dens,hermite_estimator_bivar)
 S3method(update_batch,hermite_estimator_bivar)
 S3method(update_sequential,hermite_estimator_bivar)
 S3method(merge_pair,hermite_estimator_bivar)
+S3method(summary,hermite_estimator_univar)
+S3method(print,hermite_estimator_univar)
+S3method(summary,hermite_estimator_bivar)
+S3method(print,hermite_estimator_bivar)
 export(merge_hermite)
 export(merge_hermite_univar)
 export(merge_hermite_bivar)
 export(merge_pair)
 export(cum_prob)
 export(dens)
 export(spearmans)
+export(kendall)
 export(hermite_estimator)
 export(hermite_estimator_univar)
 export(hermite_estimator_bivar)
@@ -34,6 +41,7 @@ export(hermite_function_sum)
 export(hermite_integral_val)
 export(hermite_integral_val_upper)
 export(hermite_normalization)
+export(hermite_normalization_N)
 export(quant)
 export(standardizeInputs)
 export(standardizeInputsEW)

NEWS.md

@@ -1,3 +1,28 @@
+# hermiter v2.1.0
+
+## New features
+
+* A method has been added for estimating the Kendall rank correlation 
+coefficient in the bivariate setting.
+* The univariate quantile estimation method has been significantly enhanced in
+accuracy using series acceleration techniques. Series acceleration is enabled
+by default.
+* The univariate pdf and cdf methods have been significantly enhanced in
+accuracy using series acceleration techniques. Series acceleration is enabled
+by default.
+* The new default method for the univariate quantile estimation method, 
+'interpolate' is much faster than the alternate method, 'bisection' with nearly
+the same accuracy.
+* Added print and summary methods for both the univariate and bivariate 
+hermite_estimator objects.
+* Convenience function added to calculate sums of Hermite functions.
+
+## Documentation improvements
+
+* The vignette `hermiter`, namely `vignette("hermiter")` has been extended to 
+included examples pertaining to estimation of the Kendall Tau nonparametric
+correlation coefficient in the bivariate setting.
+
 # hermiter v2.0.3
 
 ## Minor improvements and bug fixes

R/hermite_estimator.R

@@ -25,11 +25,11 @@
 #' hermite_estimator_bivar. 
 #' @export
 #' @examples
-#' hermite_est <- hermite_estimator(N = 10, standardize = TRUE,
+#' hermite_est <- hermite_estimator(N = 30, standardize = TRUE,
 #' est_type="univariate")
 hermite_estimator <-
-  function(N = 10,
-           standardize = FALSE,
+  function(N = 30,
+           standardize = TRUE,
            exp_weight_lambda = NA, est_type = "univariate") {
     if (!is.numeric(N)) {
       stop("N must be numeric.")
@@ -204,6 +204,8 @@ calculate_running_std <- function(this)
 #' values at which to calculate the probability density.
 #' @param clipped A boolean value. This value determines whether
 #' probability densities are clipped to be bigger than zero.
+#' @param accelerate_series A boolean value. This value determines whether
+#' Hermite series acceleration is applied.
 #' @return A numeric vector of probability density values.
 #' @export
 #' @examples
@@ -217,7 +219,7 @@ calculate_running_std <- function(this)
 #' nrow=30, ncol=2,byrow=TRUE))
 #' pdf_est <- dens(hermite_est, matrix(c(0,0,0.5,0.5,1,1),nrow=3,
 #' ncol=2,byrow=TRUE))
-dens <- function(this, x, clipped) {
+dens <- function(this, x, clipped, accelerate_series = TRUE) {
   UseMethod("dens", this)
 }
 
@@ -235,6 +237,8 @@ dens <- function(this, x, clipped) {
 #' Values at which to calculate the cumulative probability.
 #' @param clipped A boolean value. This value determines whether
 #' cumulative probabilities are clipped to lie between 0 and 1.
+#' @param accelerate_series A boolean value. This value determines whether
+#' Hermite series acceleration is applied.
 #' @return A numeric vector of cumulative probability values.
 #' @export
 #' @examples
@@ -248,7 +252,7 @@ dens <- function(this, x, clipped) {
 #' nrow=30, ncol=2,byrow=TRUE))
 #' cdf_est <- cum_prob(hermite_est, matrix(c(0,0,0.5,0.5,1,1),nrow=3,
 #' ncol=2,byrow=TRUE))
-cum_prob <- function(this, x, clipped) {
+cum_prob <- function(this, x, clipped, accelerate_series = TRUE) {
   UseMethod("cum_prob", this)
 }
 
@@ -263,6 +267,16 @@ cum_prob <- function(this, x, clipped) {
 #'
 #' @param this A hermite_estimator_univar object.
 #' @param p A numeric vector. A vector of probability values.
+#' @param algorithm A string. Two possible values 'interpolate' which is faster
+#' but may be less accurate or 'bisection' which is slower but potentially more
+#' accurate.
+#' @param accelerate_series A boolean value. If set to TRUE, the series 
+#' acceleration methods described in:
+#'
+#' Boyd, John P., and Dennis W. Moore. "Summability methods for 
+#' Hermite functions." Dynamics of atmospheres and oceans 10.1 (1986): 51-62. 
+#'  
+#' are applied. If set to FALSE, then standard summation is applied.
 #' @return A numeric vector. The vector of quantile values associated with the
 #' probabilities p.
 #' @export
@@ -271,7 +285,7 @@ cum_prob <- function(this, x, clipped) {
 #' est_type="univariate")
 #' hermite_est <- update_batch(hermite_est, rnorm(30))
 #' quant_est <- quant(hermite_est, c(0.25, 0.5, 0.75))
-quant <- function(this, p) {
+quant <- function(this, p, algorithm="interpolate", accelerate_series = TRUE) {
   UseMethod("quant", this)
 }
 
@@ -298,3 +312,45 @@ spearmans <- function(this, clipped = FALSE)
 {
   UseMethod("spearmans",this)
 }
+
+#' Estimates the Kendall rank correlation coefficient
+#'
+#' This method calculates the Kendall rank correlation coefficient value. It 
+#' is only applicable to the bivariate Hermite estimator i.e. est_type = 
+#' "bivariate".
+#'
+#' The object must be updated with observations prior to the use of this method.
+#'
+#' @param this A hermite_estimator_bivar object.
+#' @param clipped A boolean value. Indicates whether to clip the Kendall rank 
+#' correlation estimates to lie between -1 and 1.
+#' @return A numeric value.
+#' @export
+#' @examples
+#' hermite_est <- hermite_estimator(N = 10, standardize = TRUE,
+#' est_type="bivariate")
+#' hermite_est <- update_batch(hermite_est, matrix(rnorm(30*2), nrow=30, 
+#' ncol=2, byrow = TRUE))
+#' kendall_est <- kendall(hermite_est)
+kendall <- function(this, clipped = FALSE)
+{
+  UseMethod("kendall",this)
+}
+
+# Internal helper function for print methods.
+describe_estimator <- function(this, est_type){
+  if (est_type == "univariate") {
+    cat("Univariate Hermite Estimator:\n")
+  } else {
+    cat("Bivariate Hermite Estimator:\n")
+  }
+  cat(paste0("N = ",this$N_param,"\n"))
+  cat(paste0("Standardize observations = ",this$standardize_obs,"\n"))
+  if (!is.na(this$exp_weight)){
+    cat(paste0("Exponential weighting for coefficents = TRUE, lambda = ", 
+               this$exp_weight,"\n"))
+  } else {
+    cat(paste0("Exponential weighting for coefficents = FALSE","\n"))
+  }
+  cat(paste0("Number of observations = ",this$num_obs,"\n"))
+}