Merge pull request #103 from hsloot/feat/simplify-sampling-interface

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: rmo
 Title: A package for the Marshall-Olkin distribution
-Version: 0.7.1
+Version: 0.8
 Authors@R:
   person(given = "Henrik",
     family = "Sloot",
@@ -32,7 +32,7 @@ RdMacros:
 Encoding: UTF-8
 LazyData: true
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.1.1
+RoxygenNote: 7.1.2
 Collate:
     'RcppExports.R'
     'allClass-S4.R'

NAMESPACE

@@ -33,11 +33,10 @@ export(intensities_linear)
 export(intensities_pareto)
 export(intensities_poisson)
 export(levyDensity)
-export(rarmextmo_esm)
-export(rexmo_mdcm)
-export(rextmo_lfm)
-export(rmo_am)
-export(rmo_esm)
+export(rexmo)
+export(rextmo)
+export(rmo)
+export(rpextmo)
 export(stieltjesDensity)
 export(uexIntensities)
 export(valueOf)
@@ -55,6 +54,7 @@ exportMethods(valueOf)
 importFrom(Rcpp,sourceCpp)
 importFrom(Rdpack,reprompt)
 importFrom(checkmate,assert)
+importFrom(checkmate,assert_choice)
 importFrom(checkmate,check_complex)
 importFrom(checkmate,check_numeric)
 importFrom(checkmate,qassert)

NEWS.md

@@ -1,7 +1,13 @@
+# rmo 0.8
+
+- Create single entry point method for general MO sampling distributions, exchangeable MO sampling
+  routines, extendible MO sampling routines, and parametrized extendible MO sampling routines.
+- Improve documentation and add snaphot test for sampling routines.
+
 # rmo 0.7.1
 
 - Rename sampling method `*_markovian` and `*_arnold` to `*_mdcm` and `*_am`, respectively.
-- Rename internal CPP classes `arnold_mo_distribution`, `markovian_exmo_distribution`, and `armageddon_extmo_distribution` to `am_mo_distribution`, `mdcm_exmo_distribution`, and `esm_armextmo_distribution`, respectively. 
+- Rename internal CPP classes `arnold_mo_distribution`, `markovian_exmo_distribution`, and `armageddon_extmo_distribution` to `am_mo_distribution`, `mdcm_exmo_distribution`, and `esm_armextmo_distribution`, respectively.
 
 # rmo 0.7
 

R/rmo.R

@@ -5,45 +5,47 @@
 ## usethis namespace: end
 NULL
 
-#' rmo: A package for the Marshall-Olkin distribution.
+#' rmo: A package for the Marshall–Olkin distribution.
 #'
-#' The package contains fast implementations of sampling algorithms related to
-#' the Marshall-Olkin distribution. It also contains an S4-class system for
-#' Bernstein functions which can be used to create a large variety of
-#' Marshall-Olkin parameterisations.
+#' The package contains fast implementations of sampling algorithms related to the Marshall–Olkin
+#' distribution. It also contains an S4-class system for Bernstein functions which can be used to
+#' create a large variety of Marshall–Olkin parameterisations.
 #'
 #' @section Bernstein functions:
-#' A *Bernstein function* is a non-negative function with non-negative
-#' alternating iterative differences. These functions can be used to
-#' generated parameterisations for the exchangeable Marshall-Olkin
-#' distribution.
-#' - An object that derives from [BernsteinFunction-class] can be used to
-#'   generate the Marshall-Olkin intensities with [intensities()].
-#'   It can be used to generate (unscaled) exchangeable intensities with
-#'   [exIntensities()].
-#' - Many families of Bernstein functions are available, e.g.
-#'   [ParetoBernsteinFunction-class], [ExponentialBernsteinFunction-class], and
-#'   [AlphaStableBernsteinFunction-class].
-#' - Bernstein functions can be recombined by scaling, by summation or by
-#'   composition, which can be used to create new Bernstein functions with
-#'   [ScaledBernsteinFunction-class] and [SumOfBernsteinFunctions-class].
+#' A *Bernstein function* is a non-negative function with non-negative alternating iterative
+#' differences. These functions can be used to generated parameterisations the extendible
+#' Marshall–Olkin distributions.
+#' - An object that derives from [BernsteinFunction-class] can be used to generate the
+#'   Marshall–Olkin shock arrival intensities with [intensities()]. It can be used to generate
+#'   (scaled) exchangeable shock-size arrival intensities with [exIntensities()].
+#' - Many families of Bernstein functions are available, e.g. [ParetoBernsteinFunction-class],
+#'   [ExponentialBernsteinFunction-class], and [AlphaStableBernsteinFunction-class].
+#' - Bernstein functions can be recombined by scaling, by summation or by composition, which can be
+#'   used to create new Bernstein functions with [ScaledBernsteinFunction-class] and
+#'   [SumOfBernsteinFunctions-class].
 #'
 #'
 #' @section Sampling:
-#' Multiple sampling algorithms are provided. The semantic naming scheme `r*mo_*`
-#' is used, e.g. [rexmo_mdcm()] has *(scaled) exchangeable intensities*
-#' `ex_intensities` as input and uses the Markovian model for the default
-#' counting process.
-#' The following algorithms are implemented:
-#' - *Exogenous shock model* for arbitrary Marshall-Olkin distributions with
-#'   [rmo_esm()]. Not adviced for `d` much larger than 2.
-#' - *Arnold model* for arbitrary Marshall-Olkin distributions with [rmo_am()].
-#' - *Exchangeable Markovian model* for exchangeable Marshall-Olkin distributions
-#'   with [rexmo_mdcm()].
-#' - *Lévy-frailty model for compound Poisson subordinators* for the corresponding
-#'   subclass of extendible Marshall-Olkin distributions with [rextmo_lfm()].
-#' - *Exogenous shock model* for the armageddon ESM subclass with [rarmextmo_esm()].
+#' Multiple sampling algorithms are provided. The semantic naming scheme `r*mo` is used, e.g.,
+#' - [rmo()] allows the simulation from Marshall–Olkin distributions. It has *shock arrival
+#'   intensities* as input and uses the *Arnold model* or *exogenous shock model* for sampling; the
+#'   former can be used up until dimension \eqn{30}, but the latter should only be used in very
+#'   small dimensions.
+#' - [rexmo()] allows the simulation from exchangeable Marshall–Olkin distributions. It has
+#'   *exchangeable shock-size arrival intensities* as input and uses the *Markovian death-set
+#'   model*, the *Arnold model*, or the *exogenous shock model* for sampling; for the latter two
+#'   models, the corresponding *shock arrival intensities* are calculated and passed down to
+#'   [rmo()].
+#' - [rextmo()] allows the simulation from extendible Marshall–Olkin distributions. It has a
+#'   *Bernstein function* as input and calculates the corresponding *exchangeable shock-size arrival
+#'   intensities* and passes them down to [rexmo()].
+#' - [rpextmo()] allows the simulation from parametric families of extendible Marshall–Olkin
+#'   distributions. It has a *killing-rate*, a *drift*, a *scaling factor*, a *parameter vector*,
+#'   and a *family name* as input. All previous models can be used and the corresponding inputs are
+#'   calculated from the Bernstein function. For special families, which correspond to Lévy
+#'   exponents of compound Poisson subordinators, the *Lévy frailty model* can be used for
+#'   simulations.
 #'
 #' @docType package
-#' @name rmo
+#' @name rmo-package
 NULL