Merge pull request #44 from bladder-ca/new_release

preparing for CRAN release of 0.1.4

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: nhppp
 Title: Simulating Nonhomogeneous Poisson Point Processes 
-Version: 0.1.3.9007
+Version: 0.1.4
 Authors@R: 
     c(person(given = "Thomas", 
              family = "Trikalinos", 

NAMESPACE

@@ -23,12 +23,15 @@ export(rng_stream_rztpois)
 export(rztpois)
 export(simpson_num_integr)
 export(vdraw)
+export(vdraw_intensity_step_regular)
 export(vdraw_intensity_step_regular_R)
 export(vdraw_intensity_step_regular_cpp)
 export(vdraw_sc_step_regular)
 export(vdraw_sc_step_regular_R)
 export(vdraw_sc_step_regular_cpp)
+export(vztdraw_intensity_step_regular)
 export(vztdraw_intensity_step_regular_R)
+export(vztdraw_sc_step_regular)
 export(vztdraw_sc_step_regular_R)
 export(vztdraw_sc_step_regular_cpp)
 export(ztdraw_cumulative_intensity)

NEWS.md

@@ -1,7 +1,16 @@
-# nhppp (development version)
+# nhppp 0.1.4
+
+* Function arguments are now more consistent.
+
+* More extensive numerical checks.  
+
+* Added C++ code for vectorized functions -- for computational speed and memory efficiency.  
 
 # nhppp 0.1.3
 
+
+* CRAN release
+
 # nhppp 0.1.2
 
 * Renamed functions to start from `draw` (instead of `nhppp_t`), `draw_zt` (instead of `ztnhppp_t`), and `vdraw` (instead of ending in `_vec()`) 

R/vdraw_intensity_step_regular.R

@@ -0,0 +1,54 @@
+#' Vectorized sampling from a non homogeneous Poisson Point Process (NHPPP) from
+#'    an interval (thinning method) with piecewise constant_majorizers (C++)
+#'
+#' Vectorized sampling from a non homogeneous Poisson Point Process (NHPPP) from
+#'    an interval (thinning method) with piecewise constant_majorizers.
+#'    The majorizers are step functions over equal-length time intevals.
+#'
+#' @param lambda (function) a vectorized intensity function, with one or two arguments.
+#'  The first is time. The optional second is a named list with additional arguments.
+#' @param lambda_args (list) optional list of named arguments for `lambda()`
+#' @param Lambda_maj_matrix (matrix) for the majorizeintegrated intensity rates at the end of each interval
+#' @param lambda_maj_matrix (matrix) intensity rates, one per interval
+#' @param range_t (vector, or matrix) `t_min` and `t_max`, possibly vectorized
+#' @param subinterval (matrix, double) subinterval of `range_t` to sample from
+#' @param tol (scalar, double) tolerance for the number of events
+#' @param atmost1 boolean, draw at most 1 event time
+#' @param atmostB If not NULL, draw at most B (B>0) event times. NULL means ignore.
+#'
+#' @return a matrix of event times (columns) per draw (rows)
+#'         NAs are structural empty spots
+#' @export
+#'
+#' @examples
+#' Z <- vdraw_intensity_step_regular(
+#'   lambda = function(x, lambda_args = NULL) 0.1 * x,
+#'   range_t = c(1, 10),
+#'   lambda_maj_matrix = matrix(rep(1, 5), nrow = 1)
+#' )
+#' @export
+
+
+vdraw_intensity_step_regular <- function(lambda = NULL,
+                                         lambda_args = NULL,
+                                         Lambda_maj_matrix = NULL,
+                                         lambda_maj_matrix = NULL,
+                                         range_t = NULL,
+                                         subinterval = NULL,
+                                         tol = 10^-6,
+                                         atmost1 = FALSE,
+                                         atmostB = NULL) {
+  return(
+    vdraw_intensity_step_regular_cpp(
+      lambda = lambda,
+      lambda_args = lambda_args,
+      Lambda_maj_matrix = Lambda_maj_matrix,
+      lambda_maj_matrix = lambda_maj_matrix,
+      range_t = range_t,
+      subinterval = subinterval,
+      tol = tol,
+      atmost1 = atmost1,
+      atmostB = atmostB
+    )
+  )
+}

R/vdraw_intensity_step_regular_R.R

@@ -13,7 +13,7 @@
 #' @param range_t (vector, or matrix) `t_min` and `t_max`, possibly vectorized
 #' @param tol (scalar, double) tolerance for the number of events
 #' @param atmost1 boolean, draw at most 1 event time
-#' @param force_zt_majorizer boolean, force the use of the zero-truncated majorizer; - used for flexibility in calling from other function. Keep the default `FALSE` unless you know what you are doing.
+#' @param force_zt_majorizer boolean, force the use of the zero-truncated majorizer; - used for flexibility in calling from other functions. Keep the default `FALSE` unless you know what you are doing.
 #' @param ... (any) other arguments (ignored  -- used for flexibility in calling from other functions)
 #'
 #' @return a matrix of event times (columns) per draw (rows)

R/vztdraw_intensity_step_regular.R

@@ -0,0 +1,49 @@
+#' Vectorized sampling from a zero-truncated non homogeneous Poisson Point Process (NHPPP) from
+#'    an interval (thinning method) with piecewise constant_majorizers
+#'
+#' Vectorized sampling from a zero-truncated non homogeneous Poisson Point Process (NHPPP) from
+#'    an interval (thinning method) with piecewise constant_majorizers.
+#'    The majorizers are step functions over equal-length time intevals.
+#'
+#' @param lambda (function) a vectorized intensity function, with one or two arguments.
+#'  The first is time. The optional second is a named list with additional arguments.
+#' @param lambda_args (list) optional list of named arguments for `lambda()`
+#' @param Lambda_maj_matrix (matrix) for the majorizeintegrated intensity rates at the end of each interval
+#' @param lambda_maj_matrix (matrix) intensity rates, one per interval
+#' @param range_t (vector, or matrix) `t_min` and `t_max`, possibly vectorized
+#' @param tol (scalar, double) tolerance for the number of events
+#' @param atmost1 boolean, draw at most 1 event time
+#' @param ... (any) other arguments (ignored  -- used for flexibility in calling from other functions)
+#'
+#' @return a matrix of event times (columns) per draw (rows)
+#'         NAs are structural empty spots
+#' @export
+#'
+#' @examples
+#' Z <- vztdraw_intensity_step_regular(
+#'   lambda = function(x, lambda_args = NULL) 0.1 * x,
+#'   range_t = c(1, 10),
+#'   lambda_maj_matrix = matrix(rep(1, 5), nrow = 1)
+#' )
+#' @export
+vztdraw_intensity_step_regular <- function(lambda = NULL,
+                                           lambda_args = NULL,
+                                           Lambda_maj_matrix = NULL,
+                                           lambda_maj_matrix = NULL,
+                                           range_t = NULL,
+                                           tol = 10^-6,
+                                           atmost1 = FALSE,
+                                           ...) {
+  return(
+    vztdraw_intensity_step_regular_R(
+      lambda = lambda,
+      lambda_args = lambda_args,
+      Lambda_maj_matrix = Lambda_maj_matrix,
+      lambda_maj_matrix = lambda_maj_matrix,
+      range_t = range_t,
+      tol = tol,
+      atmost1 = atmost1,
+      ...
+    )
+  )
+}

R/vztdraw_sc_step_regular.R

@@ -0,0 +1,37 @@
+#' Vectorized sampling from zero-truncated NHPPPs with piecewise constant intensities
+#' with same interval lengths
+#'
+#' Simulate a piecewise constant-rate Poisson Point Process over `(t_min, t_max]` (inversion method)
+#' where the intervals have the same length (are "regular").
+#'
+#' @param Lambda_matrix (matrix) integrated intensity rates at the end of each interval
+#' @param lambda_matrix (matrix) intensity rates, one per interval
+#' @param range_t (vector, double) `t_min` and `t_max`
+#' @param subinterval (vector, double) optional -- the subinterval of `range_t` to sample. If `NULL`, the whole range_t is used.
+#' @param atmost1 boolean, draw at most 1 event time
+#' @param ... (any) other arguments (ignored  -- used for flexibility in calling from other functions)
+#'
+#' @return a vector of event times t
+#'         if no events realize, it will have 0 length
+#' @export
+#'
+#' @examples
+#' x <- vztdraw_sc_step_regular(Lambda_matrix = matrix(1:5, nrow = 1))
+#' @export
+vztdraw_sc_step_regular <- function(Lambda_matrix = NULL,
+                                    lambda_matrix = NULL,
+                                    range_t = c(0, 10),
+                                    subinterval = NULL,
+                                    atmost1 = FALSE,
+                                    ...) {
+  return(
+    vztdraw_sc_step_regular_cpp(
+      Lambda_matrix = Lambda_matrix,
+      lambda_matrix = lambda_matrix,
+      range_t = range_t,
+      subinterval = subinterval,
+      atmost1 = atmost1,
+      ...
+    )
+  )
+}

README.Rmd

@@ -21,7 +21,7 @@ set.seed(2024)
 [![R-CMD-check](https://github.com/bladder-ca/nhppp-fast/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/bladder-ca/nhppp-fast/actions/workflows/R-CMD-check.yaml)
 <!-- badges: end -->
 
-nhppp is a package for simulating events from one dimensional nonhomogeneous Poisson point processes (NHPPPs). Its functions are based on three algorithms that provably sample from a target NHPPP: the time-transformation of a homogeneous Poisson process (of intensity one) via the inverse of the integrated intensity function; the generation of a Poisson number of order statistics from a fixed density function; and the thinning of a majorizing NHPPP via an acceptance-rejection scheme. 
+nhppp is a package for simulating events from one dimensional nonhomogeneous Poisson point processes (NHPPPs). Its functions are based on three algorithms that provably sample from a target NHPPP: the time-transformation of a homogeneous Poisson process (of intensity one) via the inverse of the integrated intensity function; the generation of a Poisson number of order statistics from a fixed density function; and the thinning of a majorizing NHPPP via an acceptance-rejection scheme. It was developed to provide fast and memory efficient functions for discrete event and statistical simulations. For a description of the algorithms and a numerical comparison with other R packages, see Trikalinos and Sereda (2024), accessible at [https://arxiv.org/abs/2402.00358](https://arxiv.org/abs/2402.00358). 
 
 ## Installation
 
@@ -40,7 +40,7 @@ devtools::install_github("bladder-ca/nhppp-fast")
 
 ## Example
 
-These examples use the generic function `draw()`, which is a wrapper for the packages specific functions. 
+These examples use the generic function `draw()`, which is a wrapper for the packages specific functions. `draw()` is a non-vectorized function, but `nhppp` includes vectorized functions that are fast and have small memory footprint. 
 
 Consider the time varying intensity function $\lambda(t) = e^{(0.2t)} (1 + \sin t)$, which is a sinusoidal intensity function with an exponential amplitude. To draw samples over the interval $(0, 6\pi]$ execute 
 

README.md

@@ -17,6 +17,11 @@ time-transformation of a homogeneous Poisson process (of intensity one)
 via the inverse of the integrated intensity function; the generation of
 a Poisson number of order statistics from a fixed density function; and
 the thinning of a majorizing NHPPP via an acceptance-rejection scheme.
+It was developed to provide fast and memory efficient functions for
+discrete event and statistical simulations. For a description of the
+algorithms and a numerical comparison with other R packages, see
+Trikalinos and Sereda (2024), accessible at
+<https://arxiv.org/abs/2402.00358>.
 
 ## Installation
 
@@ -38,7 +43,9 @@ devtools::install_github("bladder-ca/nhppp-fast")
 ## Example
 
 These examples use the generic function `draw()`, which is a wrapper for
-the packages specific functions.
+the packages specific functions. `draw()` is a non-vectorized function,
+but `nhppp` includes vectorized functions that are fast and have small
+memory footprint.
 
 Consider the time varying intensity function
 $\lambda(t) = e^{(0.2t)} (1 + \sin t)$, which is a sinusoidal intensity

cran-comments.md

@@ -1,7 +1,5 @@
 ## R CMD check results
 
-0 errors | 0 warnings | 1 note
+0 errors | 0 warnings | 0 notes
 
-* This is a new release.
-
-* Per feedback from CRAN (Uwe Ligges) I removed file LICENSE and `+ file` from the description. 
+* This is a new version of the package. It adds vectorized functions and many numerical tests/checks.