R: Internal functions of package distr

internals_for_distr {distr} | R Documentation

## Internal functions of package distr

### Description

These functions are used internally by package distr.

### Usage

    .is.vector.lattice(x)
    .is.consistent(lattice, support, eq.space = TRUE)
    .make.lattice.es.vector(x)
    .inArgs(arg, fct)
    .isEqual(p0, p1, tol = min( getdistrOption("TruncQuantile")/2,
                                              .Machine$double.eps^.7))
    .isEqual01(x)
    .isIn(p0, pmat, tol = min( getdistrOption("TruncQuantile")/2,
                                              .Machine$double.eps^.7
                                              ))
    .isInteger(x, tol = .Machine$double.eps)
    .isNatural(x, tol = .Machine$double.eps)
    .isNatural0(x, tol = .Machine$double.eps)
    .setEqual(x, y, tol = 1e-7)
    .presubs(inp, frompat, topat)
    .makeD(object, argList,  stand = NULL, fac = NULL)
    .makeP(object, argList,  sign = TRUE, correct = NULL, fac =
                     NULL, fac2 = NULL)
    .makeQ(object, lastCall, sign = TRUE, Cont = TRUE)
    .plusm(e1, e2, Dclass = "DiscreteDistribution")
    .multm(e1, e2, Dclass = "DiscreteDistribution")
    .notwithLArg(D)
    .getObjName(i = 1)
    .discretizeP(D, lower, upper, h)
    .fm(x,f)
    .fM(x,f)
    .fM2(x,f)
    .makeDd(x,y, yleft, yright)
    .makePd(x,y, yleft, yright)
    .makeQd(x,y, yleft, yright)
    .makeQc(x,y, yleft, yright)
    .makeDNew(x, dx, h = NULL, Cont = TRUE, standM = "sum")
    .makePNew(x, dx, h = NULL, notwithLLarg = FALSE,
                          Cont = TRUE, myPf = NULL, pxl = NULL, pxu = NULL)
    .makeQNew(x, px.l, px.u, notwithLLarg = FALSE, yL , yR, Cont = TRUE)
    .mergegaps(gaps, support)
    .mergegaps2(gaps1, gaps2)
    .consolidategaps(gaps)
    .pmixfun(mixDistr, mixCoeff, leftright = "right")
    .dmixfun(mixDistr, mixCoeff, withStand = FALSE, supp = NULL)
    .rmixfun(mixDistr, mixCoeff)
    .qmixfun(mixDistr, mixCoeff, Cont = TRUE, pnew, gaps = NULL, leftright = "left")
    .del0dmixfun(mixDistr)
    .loupmixfun(mixDistr)
    .ULC.cast(x)
    .expm.d(e1)
    .expm.c(e1)
    .logm.d(e1)
    .logm.c(e1)
    .P2D (p, xx, ql, qu, ngrid = getdistrOption("DefaultNrGridPoints"))
    .P2Q (p, xx, ql,qu, ngrid = getdistrOption("DefaultNrGridPoints"),
                    qL = -Inf, qU = Inf)
    .D2P (d, xx, ql, qu,  ngrid = getdistrOption("DefaultNrGridPoints"))
    .Q2P (q, ngrid = getdistrOption("DefaultNrGridPoints"))
    .csimpsum(fx)
    .primefun(f,x, nm = NULL)
    .IssueWarn(Arith,Sim)
    .List(list0)
    .fillList(list0, len=length(list0))
    .trunc.up(object, upper)
    .trunc.low(object, lower)
    .modifyqgaps(pfun, qfun, gaps, leftright = "left")
    .DistrCollapse(support, prob, eps = getdistrOption("DistrResolution"))
    .EuclidAlgo(n1,n2)
    .getCommonWidth(x1,x2, tol=.Machine$double.eps)
    .convDiscrDiscr(e1,e2)
    .inWithTol(x,y,tol=.Machine$double.eps)
    .panel.mingle(dots,element)
    devNew(...)

### Arguments

`x` | a (numeric) vector, or (in case of `.ULC.cast`) an object of class `"AcDcLcDistribution"`
`y` | a (numeric) vector
`f` | a function in one (numeric) argument
`lattice` | a lattice (of class `Lattice`)
`support` | a support vector
`eq.space` | logical: shall we check for the support to be equally spaced?
`arg` | a formal argument as character
`fct` | a function
`p0,p1` | (numeric) vectors
`pmat` | (matrix) a matrix with two columns where row-wise the left column is smaller than the right one
`tol` | an error tolerance (numeric)
`e1` | a distribution object
`e2` | a numeric
`object` | a distribution object
`argList` | an (unevaluated) list of arguments passed to `m(object)` where `m` is in `d,p,q`
`stand` | factor for a (Lebesgue) density to integrate to 1
`sign` | the sign of the second operand — for multiplication at the moment
`correct` | unevaluated R-code to correct for right-continuity (for multiplication with negative numerics at the moment)
`fac` | factor to be multiplied with the return value
`fac2` | factor to be added to the return value
`lastCall` | unevaluated R-Code —gives how the result of a call to `q(e1)` is further transformed
`Cont` | logical: `TRUE` if `object` is continuous
`DClass` | character: name of distribution class
`D` | a distribution object
`i` | an integer
`yleft, yright` | extrapolation value beyond left/right endpoint of grid
`h` | numeric: grid width
`standM` | standardization method — summation or integration
`notwithLLarg` | logical — can we use `log.p`, `lower.tail` arguments for `p,q`-methods of first operand?
`dx` | numeric: vector of cell-probabilities for the (discretized) distribution
`myPf` | function with args `x,y, yleft, yright` (as `approxfun`): if given: replaces `approxfun` as interpolation method for continuos distributions
`pxl,pxu` | numeric: if given vector of (lower/upper) cumulative probabilities
`yL, yR` | argmin / argmax of p()-method
`inp` | either a language object or a character vector
`frompat` | vector of character strings containing regular expressions (or character string for `fixed = TRUE`) to be matched in the given character vector. Coerced by `as.character` to a character string if possible; (as argument `pattern` in `gsub` — but possibly of length >1).
`topat` | a (vector of) replacement(s) for matched pattern in `.presubs`. Coerced to character if possible. For `fixed = FALSE` this can include backreferences `"\1"` to `"\9"` to parenthesized subexpressions of `pattern`. For `perl = TRUE` only, it can also contain `"\U"` or `"\L"` to convert the rest of the replacement to upper or lower case; (as argument `replacement` in `gsub`— but possibly of length >1).
`gaps,gaps1,gaps2` | matrices `m` with two columns, such that `t(m)`, interpreted as vector, is ordered
`support` | support vector of a univariate discrete distribution
`prob` | probability vector for a univariate discrete distribution
`mixDistr` | an object of class `UnivarDistrList`
`mixCoeff` | an object of class `numeric`; a probability vector
`pnew` | a function `function(q, lower.tail = TRUE, log.p = FALSE` realizing slot `p` in a distribution object.
`withStand` | logical; if `TRUE` a standardization is made such that the sum of the values of the result evaluated at argument `supp` is 1
`supp` | NULL or `numeric`; if `withStand` is `TRUE` used to standardize such that the result is a probability density.
`p,pfun` | slot `p` of an object of class `"AbscontDistribution"`
`d` | slot `d` of an object of class `"AbscontDistribution"`
`q,qfun` | slot `q` of an object of class `"AbscontDistribution"`
`xx` | a given grid of x-values for functions `p`, `d` to be evaluated at
`ql,qu` | lower and upper `getdistrOption("TruncQuantile")`-quantile of the distribution; also, if argument `xx` is missing, left and right endpoint of a regular grid of `ngrid` gridpoints to be used in place of `xx`.
`qL,qU` | argmin / argmax of p()-method
`ngrid` | number of gridpoints
`fx` | a vector of function evaluations multiplied by the gridwidth
`f` | a vector of function evaluations
`nm` | an optional right asymptotic value
`Arith` | logical; slot `.withArith` of a distribution object, or logically-“any” of these slots in a collection of such objects
`Sim` | logical; slot `.withSim` of a distribution object, or logically-“any” of these slots in a collection of such objects
`list0` | list, the elements of which are to be copied to a new list using recycling if necessary
`len` | length of the list to be filled
`lower` | lower truncation point
`upper` | upper truncation point
`leftright` | character; for slot `q`: if partially matched to `"right"` function will return the right continuous version, else the left continuous version; for slot `p`: if partially matched to `"left"` the left continuous version, else the right continuous version;
`n1` | integer argument for `.EuclidAlgo`
`n2` | integer argument for `.EuclidAlgo`
`x1` | width argument for `.getCommonWidth`
`x2` | width argument for `.getCommonWidth`
`dots` | the unevaluated `...` argument
`element` | the name of the item in the unevaluated `...` argument
`...` | arguments passed through to other functions

### Details

`.is.vector.lattice` checks whether a given vector `x` is equally spaced. `.is.consistent` checks whether a given support vector `support` is consistent to a given lattice `lattice` — with or without checking if `support` is equally spaced. `.make.lattice.es.vector` makes an object of class `Lattice` out of a given (equally spaced) vector `x`.

`.inArgs` checks whether an argument `arg` is a formal argument of `fct` — not vectorized.

`.isEqual` checks whether `p0` and `p1` are equal to given tolerance. `.isIn` checks whether `p0` lies in any of the intervals given by matrix `pmat` to given tolerance. `.isEqual01`(x) checks whether `x` is 0 or 1 to given tolerance. `.setEqual` sets all elements of x which are equal to some element of y up to tolerance tol, to exactly the respective element of y.

`.notwithLArg` checks whether object `D` was generated by simulations or if its slots `p,q` do not have `lower.tail` arguments.

`.getObjName` returns the name of the object in the `i`th operand. `.discretizeP` discretizes `D` to a grid of probabilities from `lower` to `upper` with width `h`.

`.fm`, `.fM` return the smallest / biggest value in (0,1) such that `f`(x) is finite; `.fM2` is a variant of `.fM` using a `lower.tail = FALSE` argument.

`.makeD`, `.makeP`, `.makeQ` generate slots `p,d,q` for binary operations `e1 /op/ e2` for a distribution object `e1` and a numeric `e2` —for the moment only `/op/`'s `+,-,*,/` are implemented.

`.plusm`, `.multm` more specifically use `.makeD`, `.makeP`, `.makeQ` to generate slots `p,d,q` for `+`, `*`, respectively.

`.makeDd`, `.makePd`, `.makeQd` provide discrete analogues to `approxfun` for interpolation at non grid-values

`.makeQc` is an analogue to `makeQd` for absolutely continuous distributions using `approxfun`.

`.makeDNew` generates slot `d` for a new distribution object. In case of a discrete distribution it produces a step function with `stepfun` (using `.makeDd`) and standardizes to 1 by summation. In case of a continuous distribution it produces a density function with `approxfun` and standardizes to 1 by integration if the latter fails, it uses a trapezoid rule / summation for this purpose.

`.makePNew` generates slot `p` for a new distribution object. In case of a discrete distribution it produces a step function from `cumsum` applied to `dx` —or from `pxl` if this is given, with `stepfun` (using `.makePd`). In case of a continuous distribution it produces a cdf with `approxfun`. In case of `RtoDPQ`, `approxfun` is replaced by `myPf` which calls `ecdf` directly.

`.makeQNew` generates slot `q` for a new distribution object. In case of a discrete distribution it produces a step function (using `.makeQd`). Special care is taken for left continuity... In case of a continuous distribution it produces a quantile function with `approxfun`.

`.isInteger`, `.isNatural`, and `.isNatural0` test for each coordinate of argument `x` whether it is integer [natural / natural or 0] or not.

`.mergegaps` modifies the gaps matrix of an a.c. distribution according to the support slot of a discrete distribution; if necessary, a gap interval [a,b] is split into [a,c],[c,b] if `a<c<b`. `.mergegaps2` merges two gap matrices of two a.c. distributions `X1` and `X2` such that in the intervals of the resulting gap matrix, neither `X1` nor `X2` carries mass. `.consolidategaps` consolidates a gap matrix, i.e. joins adjacent gap intervals.

`.pmixfun`, `.dmixfun`, `.rmixfun`, and `.qmixfun` fill the slots `p`, `d`, `r`, and `q` of a corresponding mixing distribution according to the arguments in `mixDistr`, `mixCoeff`.

`.loupmixfun` finds commun lower and upper bounds for the support of the mixing distribution.

`.del0dmixfun` sets (if slot `d.ac` is not `NULL`) the return value of slot function `d.ac` of `mixDistr` for argument `0` to `0`.

`.ULC.cast` coerces an object of class `"AcDcLcDistribution"` to class `"UnivarLebDecDistribution"`, using `simplifyD`.

`.expm.d,.expm.c` for discrete, resp. a.c. argument `e1` fill the slots `p`, `d`, `r`, and `q` of the transformation `exp(e1)` exactly. `.logm.d,.logm.c` for discrete, resp. a.c. argument `e1` fill the slots `p`, `d`, `r`, and `q` of the transformation `log(e1)` exactly.

For objects of class `AbscontDistribution`, `.P2D` and `.P2Q` reconstruct function slots `d` resp. `q` from function slot `p` by means of function `D1ss` from package sfsmisc; and of function `.makeQNew`, respectively. The other way round, `.D2P` and `.Q2P` reconstruct function slot `p` from from function slots `d` resp. `q` by means of function `.makePNew` and explicite numeric inversion, respectively.

`.csimpsum` is used internally in `.makePNew` to produce a primitive function out of function evaluations by means of vectorized Simpson quadrature method, returning already the function values of the prime function on a grid; it is to mimick the behaviour of `cumsum`. `.primefun` is similar but more flexible and produces the prime function as a function.

`.List` checks if argument already is a list, and if so leaves it as it is, otherwise casts it to a list by a call to `list`.

`.fillList` fills a new list with the elements of a given list `list0` until length `len` is reached using recycling if necessary. Argument `list0` is cast to `list` by a call to `.List` if necessary.

`.trunc.up`, `.trunc.low` provide common routines for classes `DiscreteDistribution` and `AbscontDistribution` for one-sided truncation, using (for slot `r`) Peter Dalgaard's clever log-tricks as indicated in http://r.789695.n4.nabble.com/help-on-sampling-from-the-truncated-normal-gamma-distribution-on-the-far-end-probability-is-very-low-td868119.html#a868120.

`.modifyqgaps` modifies slot `q` for objects of class `AbscontDistribution` in the presence of gaps, i.e.; if slot `gaps` is not `NULL`. If argument `leftright` does not partially match `"right"` (default) returns the left continuous version of the quantile function, else the right continuous one.

`.EuclidAlgo` computes the greatest common divisor of two integers by means of the Euclidean algorithm. `.getCommonWidth` for two lattices with widths `x1` and `x2` computes the smallest common lattice width for convolution. `.convDiscrDiscr` computes the convolution of two discrete distributions by brute force. `.inWithTol` works like `%in%` but with a given tolerance.

`.panel.mingle` is used for mingling arguments `panel.first`, `panel.last` in a plot; it returns the evaluated argument `element` within dots, if it is a symbol; else if it can be interpreted as a call, and if the top call is `list`, it returns a list of the items of the call to `list`, unevaluated, and otherwise the unchanged argument.

`devNew` opens a new device. This function is for back compatibility with R versions < 2.8.0. To control the number of opened devices, when `length(dev.list())>20`, in interactive mode we ask the user to shut some windows until `length(dev.list())<=20`; in non-interactive mode we shut the first 15 open devices (except for the first one) before opening a new one.

### Value

`.is.vector.lattice` | `logical` (length 1).
`.is.consistent` | `logical` (length 1).
`.notwithLArg` | `logical` (length 1).
`.make.lattice.es.vector` | an object of class `Lattice`.
`.inArgs` | `logical` (length 1).
`.isIn, .isEqual,.isEqual01` | vector of `logical`.
`.fm,.fM, .fM2` | a `numeric` of length 1.
`.plusm,.multm` | an object of class `DiscreteDistribution` or `AbscontDistribution` according to argument `DClass`.
`.getObjName` | `character`.
`.discretizeP` | `numeric` — the probabilities for the grid-values.
`.makeDd,.makePd, .makeQd` | a function with args `x, y, yleft, yright`.
`.makeD,.makeDNew` | a function with args `x, log = FALSE`.
`.makeP,.makePNew` | a function with args `q, lower.tail = TRUE, log.p = FALSE`.
`.makeQ,.makeQNew` | a function with args `p, lower.tail = TRUE, log.p = FALSE`.
`.isInteger,.isNatural,.isNatural0` | `logical` (same length as argument `x`).
`.mergegaps,.mergegaps2` | a `gaps`-matrix, i.e.; a matrix `m` with two columns, such that `t(m)`, interpreted as vector, is ordered.
`.pmixfun` | slot `p` for a mixing distribution, i.e. a function `function(q, lower.tail = TRUE, log.p = FALSE)`, which is the cdf of the distribution.
`.dmixfun` | slot `d` for a mixing distribution, i.e. a function `function(x, log = FALSE)`, which is the density of the distribution.
`.qmixfun` | slot `q` for a mixing distribution, i.e. a function `function(p, lower.tail = TRUE, log.p = FALSE)`, which is the quantile function of the distribution.
`.rmixfun` | slot `r` for a mixing distribution, i.e. a function `function(n)` generating r.v.'s according to the distribution.
`.deldmixfun` | a possibly modified argument `mixDistr`.
`.loupmixfun` | a list of four components: `qL`, the minimal value of `q(x)(0)`, `ql`, the minimal value of `q(x)(getdistrOption("TruncQuantile"))`, `qU`, the maximal value of `q(x)(1)`, `qu`, the maximal value of `q(x)(getdistrOption("TruncQuantile"), lower.tail = FALSE)`, `x` running through the members of `mixDistr` in each case.
`.ULC.cast` | an object of class `"UnivarLebDecDistribution"`.
`.expm.d,.logm.d` | an object of class `"DiscreteDistribution"`.
`.expm.c,.logm.c` | an object of class `"AbscontDistribution"`.
`.P2D` | a density `d` as function `function(x, log = FALSE)`.
`.P2Q` | a quantile function `q` as function `function(p, lower.tail = TRUE, log.p = FALSE)`
`.D2P, .Q2P` | a cdf `p` as function `function(q, lower.tail = TRUE, log.p = FALSE)`.
`.csimpsum` | a vector of evaluations of the prime function at the grid points.
`.primefun` | the prime function as a function.
`.IssueWarn` | a list with two warnings to be issued each of which may be empty.
`.List` | a list.
`.fillList` | a list.
`.trunc.up,.trunc.low` | a list with elements `r,p,d,q` (in this order).
`.DistrCollapse` | upon a suggestion by Jacob van Etten, jacobvanetten@yahoo.com: help function to collapse the support points of a discrete distributions if they are too close to each other; here argument `support` is the (original; already sorted) support and `prob` a corresponding probability vector of same length. Criterium for collapsing: a distance smaller than argument `eps`.
`.EuclidAlgo` | returns the greatest common divisor (an integer).
`.getCommonWidth` | returns the smallest common lattice width (a numeric).
`.convDiscrDiscr` | returns the convolution of two discrete distributions.
`.inWithTol` | returns a logical vector of same lenght as `x` for the matches (up to tolerance) with vector `y`.
`.panel.mingle` | used for mingling arguments `panel.first`, `panel.last`; returns the evaluated argument `element` within dots, if it is a symbol; else if it can be interpreted as a call, and if the top call is `list`, it returns a list of the items of the call to `list`, unevaluated, and otherwise the unchanged argument.
`devNew` | returns the return value of the device opened, usually invisible `NULL`.

### Author(s)

Peter Ruckdeschel peter.ruckdeschel@uni-oldenburg.de, Matthias Kohl Matthias.Kohl@stamats.de

### See Also

`AbscontDistribution`, `DiscreteDistribution`, `LatticeDistribution`, `RtoDPQ`, `RtoDPQ.d`, `convpow`, `operators`, `plot-methods` `dev.new`

[Package distr version 2.8.0 Index]