The R Project SVN R

Rev

Rev 88598 | Show entire file | Ignore whitespace | Details | Blame | Last modification | View Log | RSS feed

Rev 88598 Rev 88827
Line 1... Line 1...
1 
% File src/library/base/man/jitter.Rd
 1 
% File src/library/base/man/jitter.Rd
2 
% Part of the R package, https://www.R-project.org
 2 
% Part of the R package, https://www.R-project.org
3 
% Copyright 1995-2011 R Core Team
 3 
% Copyright 1995-2025 R Core Team
4 
% Distributed under GPL 2 or later
 4 
% Distributed under GPL 2 or later
5 
 
 5 
 
6 
\name{jitter}
 6 
\name{jitter}
7 
\alias{jitter}
 7 
\alias{jitter}
8 
\title{\sQuote{Jitter} (Add Noise) to Numbers}
 8 
\title{\sQuote{Jitter} (Add Noise) to Numbers}
9 
\usage{
 9 
\usage{
10 
jitter(x, factor = 1, amount = NULL)
 10 
jitter(x, factor = 1, amount = NULL)
11 
}
 11 
}
12 
\arguments{
 12 
\arguments{
13 
  \item{x}{numeric vector to which \emph{jitter} should be added.}
 13 
  \item{x}{numeric vector to which \emph{jitter} should be added.}
14 
  \item{factor}{numeric.}
 - 
 
15 
  \item{amount}{numeric; if positive, used as \emph{amount} (see below),
 14 
  \item{factor}{numeric; used in calculation of \code{amount} when
16 
    otherwise, if \code{= 0} the default is \code{factor * z/50}.
 15 
   the provided \code{amount} is 0 or \code{NULL}.}
17 
 
 - 
 
18 
    Default (\code{NULL}): \code{factor * d/5} where \code{d} is about
 16 
  \item{amount}{number or \code{NULL}; when positive, specifies
19 
    the smallest difference between \code{x} values.}
 17 
    the amount of jitter; see Details, also for other cases.}
20 
}
 18 
}
21 
\description{
 19 
\description{
22 
  Add a small amount of noise to a numeric vector.
 20 
  Add a small amount of noise (\dQuote{jitter}) to a numeric vector.
23 
}
 21 
}
24 
\value{
 22 
\value{
25 
  \code{jitter(x, \dots)} returns a numeric of the same length as
 23 
  \code{jitter(x, \dots)} returns a numeric of the same length as
26 
  \code{x}, but with an \code{amount} of noise added in order to break
 24 
  \code{x}, but with an \code{amount} of noise added in order to break
27 
  ties.
 25 
  ties.
28 
}
 26 
}
29 
\details{
 27 
\details{
30 
  The result, say \code{r}, is \code{r <- x + runif(n, -a, a)}
 28 
  The result of \code{r <-  x + amount * runif(n, -1, 1)}
31 
  where \code{n <- length(x)} and \code{a} is the \code{amount}
 29 
  where \code{n <- length(x)}.
32 
  argument (if specified).
 - 
 
33 
 
 30 
 
34 
  Let \code{z <- max(x) - min(x)} (assuming the usual case).
 31 
  When \code{amount} is \code{NULL} (the default)
35 
  The amount \code{a} to be added is either provided as \emph{positive}
 32 
  \code{amount <- factor * d/5} where \emph{d} is about the smallest
36 
  argument \code{amount} or otherwise computed from \code{z}, as
 33 
  difference between adjacent unique (up to fuzz) \code{x} values.
37 
  follows:
 - 
 
38 
 
 34 
 
39 
  If \code{amount == 0}, we set \code{a <- factor * z/50} (same as S).
 35 
  If \code{amount == 0}, \code{amount <- factor * (max(x) - min(x))/50},
- 
 
 36 
  (using only finite \code{x} values), which is the same as in S and the
- 
 
 37 
  references.
- 
 
 38 
  In the above cases, the final \code{amount} is always ensured to be positive.
40 
 
 39 
 
41 
  If \code{amount} is \code{NULL} (\emph{default}), we set
 - 
 
42 
  \code{a <- factor * d/5} where \emph{d} is the smallest
 - 
 
43 
  difference between adjacent unique (apart from fuzz) \code{x} values.
 40 
  The short \code{jitter()} function is itself a succinct definition.
44 
}
 41 
}
45 
\references{
 42 
\references{
46 
  \bibinfo{R:Chambers+Cleveland+Kleiner:1983}{note}{(Figures 2.8, 4.22, 5.4.)}
 43 
  \bibinfo{R:Chambers+Cleveland+Kleiner:1983}{note}{(Figures 2.8, 4.22, 5.4.)}
47 
  \bibshow{R:Chambers+Cleveland+Kleiner:1983, R:Chambers+Hastie:1992}
 44 
  \bibshow{R:Chambers+Cleveland+Kleiner:1983, R:Chambers+Hastie:1992}
48 
}
 45 
}
Line 50... Line 47...
50 
\seealso{
 47 
\seealso{
51 
  \code{\link{rug}} which you may want to combine with \code{jitter}.
 48 
  \code{\link{rug}} which you may want to combine with \code{jitter}.
52 
}
 49 
}
53 
\examples{
 50 
\examples{
54 
round(jitter(c(rep(1, 3), rep(1.2, 4), rep(3, 3))), 3)
 51 
round(jitter(c(rep(1, 3), rep(1.2, 4), rep(3, 3))), 3)
55 
## These two 'fail' with S-plus 3.x:
 52 
## These two had failed with S-plus 3.x: max(x) - min(x) == 0
56 
jitter(rep(0, 7))
 53 
jitter(rep(0, 7))
57 
jitter(rep(10000, 5))
 54 
jitter(rep(10000, 5))
58 
}
 55 
}
59 
\keyword{dplot}
 56 
\keyword{dplot}
60 
\keyword{utilities}
 57 
\keyword{utilities}