R-Package
"distr"
What is "distr" meant for?
The aim of
package "distr" is to
provide a conceptual treatment of random variables (r.v.'s) by means of
S4--classes. A mother class "Distribution"
is introduced with slots for a parameter and - most important - for the
four constitutive methods "r",
"d", "p", and "q" for simulation,
respectively for evaluation of density / c.d.f. and quantile function
of the corresponding distribution. All distributions of the "base" package for which
corresponding "r", "d", "p", and "q"- <distr.name>
functions exist (like normal, Poisson, etc.) are implemented as
subclasses of either "AbscontDistribution"
or "DiscreteDistribution",
which themselves are again subclasses of "Distribution".
This approach seems very appealing to us from a conceptual viewpoint:
Just pass an object of some derived
distribution class to a generic function as argument and let the
dispatching mechanism decide what to do on run-time.
As an example, we may automatically generate new objects of these
classes with corresponding "r",
"d", "p", and "q"-slots for the laws of
r.v.'s under standard mathematical univariate transformations and under
convolution of independent r.v.'s. For "Distribution" objects X and Y expressions like 3*X+sin(exp(-Y/4+3)) have
their natural interpretation as corresponding image distributions.
Note: Arithmetics on
distribution objects are understood as operations on corresponding
r.v.'s and not
on distribution functions or densities.
You may set global options by distroptions()
confer ?distroptions .
Up to version 1.5, additionally, we also provided classes for a
standardized treatment of simulations (also under contaminations) and
evaluations of statistical procedures on such simulations. These are
now delegated to packages distrSim
and distrTEst (see
below).
Attention:
This package has been reorganized in version 1.6; if you cannot find a
class/method/function previously in the package, also search the new
packages
Further packages built on top of package "
distr":
Manual
for version
prior to 1.8, a somewhat more detailed manual to this package in
pdf-format
is available here;
from version 1.8 on, we have converted this manual into a common
vignette to packages
distr,
distrEx,
distrSim,
distrTEst,
distrMod, distrTeach,
which is available in the mere documentation package
distrDoc. To use it you may type
require("distrDoc"); V<-vignette("distr"); print(V); edit(V)
License
Download
Windows
- to be installed by
- to be removed by
remove.packages("distr")
- to be used by
library("distr")
or
require("distr")
Linux
Sources
- included into the .tar.gz.file
- as zipped
source (for Versions <1.8.0)
- procede as follows:
- unzip the zip File
- consult the README -File in the zip-archive and follow the
instructions therein
- (is the only possiblity for versions 1.7.0 and 1.7.1)
Demos
also see demo(package="distr")
--- after installation of "distr"
Version history:
Changes from 1.0 to
1.1 (03-12-04)
Changes from 1.1 to
1.2, 1.3
- changes in the Help-File to pass Rcmd check
Changes from 1.3 to
1.4
Changes from 1.4 to
1.5
- package is now using lazy
loading
- minor changes in the help pages
- minor enhancements in plot for distributions (Gamma, discrete distributions)
- package now includes a demo - folder; try demo("distr")
- class Gamma has
been renamed Gammad to
avoid name collisions
- we have a CITATION file now; consider citation("distr")
- enhanced demos:
- convolution of uniform variables now includes exact expressions
- min/ max of two variables now
available for discrete distributions
- rd-Files have now a keyword entry for distribution and thus may
be found by the search engine
- exact formula for "Unif"
o "numeric" where o \in
{ +,-,*,/ }
Changes from 1.5 to
1.6
- Our package is reorganized:
- distr from now
on only comprises distribution classes and methods
- simulation classes and methods have been moved to the new
package distrSim
- evalation classes and methods have been moved to the new
package distrTEst
- a new class distrEx has been added by
Matthias Kohl,
providing additional features like distances between distributions,
expectation operators etc
- a new class RandVar has been added by
Matthias Kohl,
providing conceptual treatment of random variables as measurable
mappings
Changes from 1.6 to
1.7
- taking up a suggestion by Martin Mächler, we now issue warnings
as to the intepretation of arithmetics applied to distributions, as
well as to the
accuracy of slots p,d,q filled by means of simulations; these warnings
are issued at two places:
- (1) on attaching the package
- (2) at every show/print of a distribution
- (2) can be cancelled by switching off a corresponding global
option in distroptions()
-- see ?distroptions
.
- distroptions() / getdistrOption() now behave
exactly like options() /
getOption() options
--- also compare mail
"Re: [Rd] How to implement package-specific options?" by Brian Ripley
on
r-devel, Fri 09 Dec 2005 - 11:52:46, see http://tolstoy.newcastle.edu.au/R/devel/05/12/3408.html
- all specific distributions (those realized as [r|d|p|q]<name>
like rnorm in package stats)
now have valid prototypes
- fixed arguments xlim and
ylim for plot(signature("AbscontDistribution"
or
"DiscreteDistribution"))
thus: plot(Cauchy(),xlim=c(-4,4))
gives reasonable result (and plot(Cauchy())
does not)
- Internationalization: use of gettext, gettextf for output
- explicitly implemented is()
relations: R "knows" that
- an Exponential(lambda) distribution also is a Weibull(shape =
1, scale = 1/lambda) distribution, as well as a Gamma(shape = 1, scale
= 1/lambda) distribution
- a Geometric(p) distribution also is a Negativ Binomial(size =
1,p) distribution
- a Uniform(0,1) distribution also is a Beta(1,1) distribution
- a Cauchy(0,1) distribution also is a T(df=1, ncp=0)
distribution
- a Chisq(df=n, ncp=0) distribution also is a Gamma(shape=n/2,
scale=2) distribution
- noncentrality parameter included for Beta, T, F distribution
Changes from 1.7 to
1.8
- a class "DExp" for
Laplace/Double Exponential distributions
- a method dim which
for distributions returns the dimension of the
support
- show for
distributions now acts as print
Changes from 1.8 to
1.9
- in demos, made calls to uniroot(),
integrate(), optim(ize)() compliant to https://stat.ethz.ch/pipermail/r-devel/2007-May/045791.html
- new methods shape()
and scale() for class "Chisq" with ncp==0
- derivation of a class LatticeDistribution from DiscreteDistribution to be
able to easily apply FFT
- new class 'Lattice' to formalize an
affine linearly generated grid of
(support) points pivot +
(0:(Length-1)) * width
- usual accessor /prelacement functions to
handle slots
- new class 'LatticeDistribution' as
intermediate class between 'DiscreteDistribution'
and all specific discrete distributions from 'stats' package
- with a particular convolution method
using FFT (also for 'convpow')
- usual accessor function 'lattice' for slot 'lattice'
- moved some parts from
from package 'distrEx'
to package 'distr'
- generating function 'DiscreteDistribution'
- univariate methods of 'liesInSupport()'
- classes 'DistrList' and 'UnivariateDistrList'
- generating functions EuclideanSpace() ,Reals(), Naturals()
- cleaning up of source files:
- checked all source file to adhere to the
80char's-per-line rule
- added S4-method 'convpow' for convolutional
powers from the examples
of package 'distr' with
methods for
- 'LatticeDistribution'
and 'AbscontDistribution'
- and particular methods for
- Norm,
Cauchy, Pois, Nbinom, Binom, Dirac,
and ExpOrGammaOrChisq
(if summand 'is' of class Gammad)
- new exact arithmetic formulae:
+ 'Cauchy' + 'Cauchy'
: gives 'Cauchy'
+ 'Weibull'
* 'numeric'
: gives 'Weibull' resp. 'Dirac'
resp 'AbscontDistribution'
: acc. to 'numeric' >, =, <
0
+ 'Logis'
* 'numeric'
: gives 'Logis' resp. 'Dirac' resp 'AbscontDistribution'
: acc. to 'numeric' >, =, <
0
+ 'Logis'
+ 'numeric'
: gives 'Logis'
+ 'Lnorm'
* 'numeric'
: gives 'Lnorm' resp. 'Dirac' resp 'AbscontDistribution'
: acc. to 'numeric'
>, =, <
0
+ 'numeric'
/ 'Dirac'
: gives 'Dirac' resp. error acc.
to 'location(Dirac)' ==, != 0
+
'DiscreteDistribution' * 1 returns
the original distribution
+
'AbscontDistribution' * 1 returns
the original distribution
+
'DiscreteDistribution' + 0 returns
the original distribution
+
'AbscontDistribution' + 0 returns
the original distribution
- new file MASKING and corresponding command 'distrMASK()' to
describe the intended maskings
- mentioned in package-help: startup messages
may now also be suppressed by
suppressPackageStartupMessages()
(from package 'base')
- revised generating functions/initialize
methods according to
http://tolstoy.newcastle.edu.au/R/e2/devel/07/01/1976.html
in particular all Parameter(-sub-)classes gain a valid prototype
- formals for slots p,q,d
as in package stats to
enhance accuracy
- p(X)(q, lower.tail = TRUE,
log.p = FALSE)
- q(X)(p, lower.tail = TRUE,
log.p = FALSE)
- d(X)(x, log = FALSE)
- used wherever possible;
but backwards compatibility: always checked whether lowert.tail / log / log.p are
formals
- unified form for automatically generated r, d, p, q-slots:
- using (internal) standardized generators
- .makeDNew, .makePNew, .makeQNew
- .makeD, .makeP, .makeQ
- revised "*",
"+" ("Discrete/AbscontDistribution","numeric") methods (using .makeD, .makeP, .makeQ)
- revised RtoDPQ[.d]
(using .makeDNew, .makePNew, .makeQNew)
- revised convolution
methods (using .makeDNew,
.makePNew, .makeQNew)
- revised convpow()
methods (using .makeDNew, .makePNew, .makeQNew)
- cleaning up of environment of r,d,p,q-slot - removed
no longer needed objects
- left-continuous c.d.f. method (p.l) and
right-continuous quantile function (q.r) for DiscreteDistributions
- methods getLow, getUp for upper and lower
endpoint of support of DiscreteDistribution
or AbscontDistribution
(truncated to lower/upper TruncQuantile if infinite)
- analytically exact slots d,p (and higher accuracy for q) for
distribution objects generated by functions
abs, exp, log for classes AbscontDistribution
and DiscreteDistribution
- new (internally used) classes AffLinAbscontDistribution,
AffLinLatticeDistribution
and AffLinLatticeDistribution to
capture the results of transformations
Y <- a * X0 + b
for a, b numeric and X0 Abscont/Discrete/LatticeDistribution
and a class union AffLinDistribution
of AffLinAbscontDistribution and AffLinLatticeDistribution
to use this for more exact evaluations of functionals in package 'distrEx'
- Version-management for changed class definitions to
- AbscontDistribution
(gains slot gaps)
- subclasses of LatticeDistribution
(Geom, Binom, Nbinom, Dirac,
Pois, Hyper):
(changed by inheriting from LatticeDistribution,
gaining slot lattice
!)
realized by
- moved generics to isOldVersion(),
conv2NewVersion()
from 'distrSim'
to 'distr'
- moved (slightly generalized version of) isOldVersion()
(now for signature ANY) from 'distrSim'
to 'distr'
- new methods for conv2NewVersion
for signature
- ANY : fills
missing slots with
corresponding entries from prototype
- LatticeDistribution:
generates a new
instance (with slot lattice(!))
by new(class(object),
<list of parameters>)
- enhanced plot()
methods (see ?"plot-methods" )
- for both AbscontDistributions
and DiscreteDistributions
- optional width
and height argument for
the display (default
16in : 9in)
- opens a new window for each plot
- does not work with Sweave;
workaround: argument withSweave
= TRUE
in .Rnw-file: use width and height argument like in
<<plotex1,eval=TRUE,fig=TRUE, width=8,height=4.5>>=
....
@
- optional main, inner titles and subtitles with main / sub / inner
- preset strings substituted in both expression and character
vectors (x : argument
with which plot() was
called)
- %A deparsed argument x
- %C class of argument x
- %P comma-separated list of parameter values of slot
param of
argument x
- %Q comma-separated list of parameter values of slot param of argument x in () unless this list is
empty - then ""
- %N comma-separated <name>=<value> - list of
parameter values of slot param
of argument x
- %D time/date at which plot is/was generated
- title sizes with cex.main
/ cex.inner / cex.sub
- bottom / top margin with bmar, tmar
- setting of colors with col / col.main / col.inner / col.sub
- can cope with log-arguments
- setting of plot symbols with pch
/ pch.a / pch.u
- different symbols for unattained [pch.u] / attained [pch.a] one-sided
limits
- do.points
argument as in plot.stepfun()
- verticals
argument as in plot.stepfun()
- setting of colors with col
/ col.points / col.vert / col.hor
- setting of symbol size with with cex / cex.points
- for AbscontDistributions
- (panel "q"): takes
care of finite left/right endpoints of
support
- (panel "q"):
optionally takes care of constancy region (via do.points / verticals)
- ngrid argument
to set the number of grid points
- for DiscreteDistributions
:
- DEPRECATED:
- class 'GeomParameter' --- no longer
needed
as this the parameter
of a 'Nbinom'
with size 1
Changes from 1.9 to
2.0
- made calls to 'uniroot()', 'integrate()', 'optim(ize)()'
compliant to
https://stat.ethz.ch/pipermail/r-devel/2007-May/045791.html
- new generating function 'AbscontDistribution'
- new class 'UnivarMixingDistribution' for mixing
distributions with
methods / functions:
- 'UnivarMixingDistribution' (generating function)
- flat.mix to make out of it a distribution of class
'UnivarLebDecDistribution'
- new class 'AffLinUnivarLebDecDistribution' for affine
linear transformations
of 'UnivarLebDecDistribution' (in particular for use with E())
- new class union 'AcDcLcDistribution' as common mother
class
for 'UnivarLebDecDistribution', 'AbscontDistribution',
'DiscreteDistribution'; corresponding methods / functions:
- enhanced arithmetic: (for 'AcDcLcDistribution')
- convolution for 'UnivarLebDecDistribution'
- affine linear trafos for 'UnivarLebDecDistribution'
- 'numeric' / 'AcDcLcDistribution'
- 'numeric' ^ 'AcDcLcDistribution'^
- 'AcDcLcDistribution' ^ 'numeric'
- binary operations for independent distributions:
- 'AcDcLcDistribution' * 'AcDcLcDistribution'
- 'AcDcLcDistribution' / 'AcDcLcDistribution'
- 'AcDcLcDistribution' ^ 'AcDcLcDistribution'
- (better) exact transformations for exp() and log()
- Minimum Maximum Truncation Huberization
- convpow for 'UnivarLebDecDistribution'
- new generating function 'AbscontDistribution'
- 'decomposePM' decomposes distributions in positive /
negative part
(and in Dirac(0) if discrete)
- 'simplifyD' tries to cast to simpler classes (e.g. if a
weight is 0)
Changes from 2.0 to
2.1
- DISTRIBUTIONS
- DISCRETE DISTRIBUTIONS
- collapsing discrete distributions:
- getdistrOption(".DistrCollapse.Unique.Warn")
- implemented proposal by jacob van etten (collapsing support)
- enhance accuracy
- improvement of .multm (now sets density for discrete
distributions for non-support arguments actively to 0)
- We are a bit more careful about hitting support points in
.multm for DiscreteDistribution (i.e., for D * e2, e2 numeric, D
DiscreteDistribution)
- CONTINUOUS DISTRIBUTIONS
- gaps/support :
- gaps matrix could falsely have 0 rows (instead of being set
to NULL)
- class UnivarMixingDistribution gains overall slots gaps
support
- added corresponding accessors
- correspondingly, for UnivarLebDecDistribution as daughter
class, accessors gaps(), support() refer to "overall" slots, not to
slots of acPart, discretePart
- deleted special support, gaps method for
UnivarLebDecDistribution; now inherits from UnivarMixingDistribution´
- new utility function .consolidategaps to "merge" adjacent
gaps
- setgaps method for UnivarMixingDistribution
- methods
- "*", c("AffLinUnivarLebDecDistribution","numeric"),
- "+", c("AffLinUnivarLebDecDistribution","numeric"),
- "*", c("UnivarLebDecDistribution","numeric"),
- "+", c("UnivarLebDecDistribution","numeric"),
- generating function "UnivarLebDecDistribtion"
- had to be modified
- utility 'mergegaps' catches situation where support has
length 0
- abs - and Truncate - methods for AbscontDistribution use
'.consolidategaps'
- COMPOUND DISTRIBUTIONS
- Compound Distributions are now implemented; see
?CompoundDistribution, class?CompoundDistribution
- UNIVARIATE MIXING DISTRIBUTIONS
- fixed some errors / made some enhancements acc. to mail by
Krunoslav Sever
- ENHANCED ACCURACY BY LOG SCALE
- enhanced accuracy for Truncation with Peter Dalgaard's trick
- passed over to log-scale for getUp, getLow (again to
enhance accuracy for distributions with unbounded support)
- introduced new slots .lowerExact and .logExact for
objects of class "Distribution" (or inheriting) to control whether
the argument parts log[.p], lower.tail are implemented carefully in
order to preserve accuracy
.
- ARITHMETICS
- enhanced "+" method
- for DiscreteDistribution,DiscreteDistribution ---
catches addition with Dirac-Distribution
- we enforce to use FFT-based algorithm for
LatticeDistributions if the supports of both summands may be arranged
on a common lattice whenever the length of convolutional grid
(=unique(sort(outer(support1, support2, "+"))) ) is smaller than
the length of the product grid ( = length(support1) * length(support2)
)
--- covers in particular m1*Binom(p,size) + m2*Binom(p',size) when m1,
m2 are naturals > 1 ...
- convpow:
- some minor enhancements in convpow and "+",
"LatticeDistribution","LatticeDistribution"
and correction of a buglet there (e.g., lattice width oould get
too small)
- method for AcDcLcDistribution gains argument 'ep' to
control
when to ignore discrete parts (or a.c. parts) which summands in
binomial expansion of (acPart+discretePart)^\ast n to ignore
- minor fix in method for DiscreteDistribution
- automatic image distribution generation
- slot r is now /much/ faster / slimmer for results of
*,/,^
(no split in pos/neg part necessary for this!)
- slot d for results of *,/, exp() now is correct at 0 by
extrapolation (and deletion wir .del0dmixfun of half of the part to
avoid double counting in *,/)
- affine linear trafos return slot X0 of AffLin-Construction if
resulting a=1 and b=0
- method sqrt() for distributions
- PLOTTING
- enhanced automatic plotting range selection (calling in both
scale and quantile based methods)
- plot-methods in branches/distr-2.1 now accept to.draw.arg no
matter whether mfColRow==TRUE or FALSE
- fixed xlim and ylim args for plots; ylim can now be
matrix-valued...
- realized suggestions by A. Unwin, Augsburg;
plot for L2paramFamilies may be restricted to
selected subplots;
- also named parameters are used in axis annotation if available.
- changed devNew to only open a device if length(dev.list())>0
- plot (for distribution objects) now is conformal to the
(automatic) generic, i.e. it dispatches on signature (x,y) and has
methods for signature(x=<distributionclass>,y="missing")
- enhanced plotting (correct dispatch; opening of new device is
controlled by option("newDevice") )
- new plot function for 'UnivarLebDecDistribution' : now plots 3
lines
- first line common cdf and quantile function
- second line abscont part
- third line discrete part
- NEW / ENHANCED METHODS
- getLow/getUp:
now available for UnivarLebDecDistribution, UnivarMixingDistribution
- q.r, p.l (methods for right continuous quantile function
and left continuous cdf)
- for class AbscontDistribution (q.r with 'modifyqgaps')
- for class UnivarLebDecDistribution
- for class UnivarMixingDistribution
- prob methods:
- prob() for DiscreteDistribution-class returns vector of
probabilities for the support points (named by values of support
points)
- method for UnivarLebDecDistribution: returns a
two-row matrix with
- column names values of support points
- first row named "cond" the probabilities of discrete
part
- second row named "abd" the probabilities of discrete part
multiplied with discreteWeight; hence the absolute probabilities of the
support points
- methods p.ac, d.ac, p.discrete, d.discrete:
- they all have an extra argument 'CondOrAbs' with default
value
"cond" which if it does not partially match "abs", returns exactly slot
p (resp. d) the respective acPart/discretePart of the object
- else return value is weighted by acWeight/discreteWeight
- new function 'makeAbscontDistribution'
- to convert arbitrary univariate distributions to
AbscontDistribution: takes slot p and uses AbscontDistribution(); in
order to smear out mass points on the border,
makeAbscontDistribution() enlarges upper and lower bounds
- flat.LCD:
setgaps is called only if slot gaps is not yet filled
- general technique: more freguent use of .isEqual
- new / enhanced utilities (non-exported)
- 'modifyqgaps' in order to achieve correct values for slot
q
in case slot p hast constancy regions (gaps)
- .qmixfun can cope with gaps and may return both left and
right continuous versions
- .pmixfun may return both left and right continuous versions
in case slot p hast constancy regions (gaps)
- DOCUMENTATION
- new section "Extension packages" in package-help file
0distr-package.Rd
- mention of CompoundDistribution-class in package-help file
0distr-package.Rd of devel version
- new vignette "How to generate new distributions in packages
distr, distrEx" in package distr ...
- Rd-style:
- several buglets detected with the fuzzier checking
mechanism
- cf [Rd] More intensive checking of R help files, Prof Brian
Ripley, 09.01.2009 10:25)
- [Rd] Warning: missing text for item ... in \describe? ,
Prof Brian Ripley
- S4 ISSUES:
- fixed setGenerics- error reported by Kurt Hornik...
"log", "log10", "gamma", "lgamma" are no longer redefined as generics.
- explicit method "+" for Dirac,DiscreteDistribution
- some changes to the connections between LatticeDistribution and
DiscreteDistribution resp. between AffLinLatticeDistribution and
AffLinDiscreteDistribution.
- key issues:
- JMC has changed the way non-simple inheritance [i.e. in the
presence of setIs relations] is treated (see distr; in particular
show, and operator methods for LatticeDistribution)
- introduced some explicit methods for LatticeDistribution, as
due to setIs Relation
it may no longer be inherited automatically from DiscreteDistribution
since JMC's changes in S4 inheritance mechanism Sep/Oct 08
- BUGFIXES
- fixed a buglet in initialize for Cauchy Distribution
- fixed bug in "+",LatticeDistribution,LatticeDistribution
- it may be that even if both lattices of e1, e2 have same
width,
the convoluted support has another width! example: c(-1.5,1.5),
c(-3,0,3)
- matrix-valued ylim argument has not yet been dealt with
correctly
- fixed bug in plot-methods for argument "inner" under use of
to.draw.arg argument
- fixed a bug in convpow-method for AbscontDistribution
- small buglets in plot-methods.R and plot-methods_LebDec.R
(moved setting of owarn/oldPar outside)
- fixed a bug in UnivarMixingDistribution.R (with new argument
Dlist)
- fixed a bug discovered by Prof. Unwin --- "+" trapped in
a dead-lock coercing between DiscreteDistribution and
LatticeDistribution
- fixed a small buglet in convpow().
- fixed buglet in devel version of distr: getLow.R (wrong place
of ")" )
- fixed some errors in plotting LCD and CompoundDistribution(and
enhanced automatic axis labels by some tricky castings...)
- UnivarMixingDistribution was too strict with sum mixCoeff == 1
- deleted some erroneous prints left over from debugging in
ExtraConvolutionMethods.R
- fixed some buglets in plot for distr (only in branch)
- fixed redundant code in bAcDcLcDistribution.R
- Patch to bug with AffLinAbscontDistribution
- correction of small buglet in validity to Norm-class
- fixed bug with AffLinAbscontDistribution for a*X+b,
distribution X >=0
- LICENSE: moved license to LGPL-3
Changes from 2.1 onwards
see NEWS-file
Our plans for
the next version:
Things we invite
other people to do
- multivariate distributions
- conditional distributions
- copula
This page is
maintained by
Peter
Ruckdeschel (and was created by Thomas Stabla
)
and last updated on 2013-09-18.