distr: internals – R documentation

Pricing

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

Get Started for Free

Documentation

distr

internals

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 ith 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