qqmathFitted: Q-Q Plot Using a Fitted Distribution
In christopherggreen/cggmisc: Christopher G Green's Miscellaneous Functions

Description Usage Arguments Details Value Author(s) See Also Examples

qqmathFitted is a modified version of qqmath that draws a quantile-quantile plot of sample data against a fitted reference distribution. The fitting is done during the panel construction using a user-provided function to estimate distributional parameters.

     qqmathFitted(formula, 
          data = NULL, 
          allow.multiple = is.null(groups) || outer, 
          outer = !is.null(groups), 
          distribution = qnorm, 
          f.value = NULL, 
          auto.key = FALSE, 
          aspect = "fill", 
          panel = panel.qqmath.fitted, 
          prepanel = prepanel.qqmath.fitted, 
          scales = list(), 
          strip = TRUE, 
          groups = NULL, 
          xlab, 
          xlim, 
          ylab, 
          ylim, 
          drop.unused.levels = lattice.getOption("drop.unused.levels"), 
          distribution.fit = function(y) list(mean = 0, sd = 1), 
          quantile.type = 7, 
          qqstyle = NULL, 
          add.qqline = c("none", "lm", "lmRob"), 
          add.qqline.par = if (!is.null(groups)) 
              trellis.par.get("panel.superpose") else 
                  trellis.par.get("add.line"), 
          envelope = TRUE, 
          rdist = rnorm, 
          rdist.args = NULL, 
          sig.level = 0.95, 
          mc.samples = 100, 
          seed = .Random.seed, 
          envstyle = NULL, 
          id.n = 3, 
          labelargs = FALSE, 
          verbose = FALSE, 
          ..., 
          lattice.options = NULL, 
          default.scales = list(), 
          subscripts = !is.null(groups), 
          subset = TRUE)

	Most of these arguments work just like they do for `qqmath`; see the help files for `qqmath` and `xyplot` for more detail.
`formula`	A lattice formula of the form `~ x \| g1 * g2 * ...`, where `x` is a numeric variable, and `g1`, `g2`, etc., are conditioning variables. Typically all of these variables will be contained in `data`.
`data`	A data source ( e.g., a data frame ) in which to find the variables referenced in `formula`.
`allow.multiple`	See `xyplot`.
`outer`	See `xyplot`.
`distribution`	function to compute quantiles from the reference distribution. Can be a named function (e.g., `qnorm`), a character string containing the name of a function (e.g., `"qnorm"`), or an anonymous function.
`f.value`	Vector of probabilities at which to compute quantiles. By default, `ppoints` is used to pick sensible values, so you generally don't need to specify `f.value`. See `qqmath` and `prepanel.qqmath.fitted` for more details.
`auto.key`	See `xyplot`.
`aspect`	See `xyplot`.
`panel`	A function that will be called once for each panel of the plot to do the actual plotting. See `xyplot` for details about panel functions in general. The default panel function here is `panel.qqmath.fitted`.
`prepanel`	Prepanel functions set sensible x- and y-limits for panels; see `xyplot` for more details about prepanel functions in general. The default prepanel function for `qqmathFitted` is `prepanel.qqmath.fitted`; it does the actual distributional fitting calculations. It is not recommended that you change the default function unless you've read and understood the code for `prepanel.qqmath.fitted`.
`scales`	See `xyplot`.
`strip`	See `xyplot`.
`groups`	See `xyplot`.
`xlab`	See `xyplot`.
`xlim`	See `xyplot`.
`ylab`	See `xyplot`.
`ylim`	See `xyplot`.
`drop.unused.levels`	See `xyplot`.
`distribution.fit`	function to fit the parameters of the reference distribution (defined in `distribution`). Can be a named function, a character string containing the name of a function, or an anonymous function. The function should return a list of parameters to `distribution` with names matching argument names to `distribution`.
`quantile.type`	Numeric value, passed to `quantile`. Controls the type of sample quantiles that will be taken from the observations `x`. See the help page for `quantile` for more detail.
`qqstyle`	List of graphical parameters to use for plotting the observed and reference quantiles.
`add.qqline`	Controls whether a fitted line should be added to the plot. The default option, `"none"`, does not add a line. The `"lm"` option adds a linear regression line (regressing observations on quantiles from the reference distribution) using `"lm"`. The `"lmRob"` option adds a robust regression line, and requires the `robust` library.
`add.qqline.par`	Optional list of parameters controlling the appearance of the fitted line.
`envelope`	If TRUE, plot a confidence region for the Q-Q plot via simulation. Envelopes are not supported when groups are used, as the resulting plot would be quite cluttered.
`rdist`	The distribution from which to draw random numbers for the confidence region simulation. It should correspond to the distribution assumed in `distribution` and `distribution.fit`. Just like `distribution`, `rdist` can be specified as a named function, a character string containing the name of a function, or an anonymous function.
`rdist.args`	A list containing additional arguments to the function specified in `rdist` (other than the parameters return by `distribution.fit`).
`sig.level`	Significance level to use for the confidence region. Default is a 95% condifence interval.
`mc.samples`	Number of random samples to use to construct the confidence region.
`seed`	Seed to use for the random number generator. If specified, `.Random.seed` will be set to `seed` prior to generation of the simulation envelopes. This is useful to do for reproducibility of results.
`envstyle`	List of graphical parameters to use for plotting the confidence region boundaries.
`id.n`	Number of outliers to label in each panel. Default is 3. Use `id.n = 0` or `id.n = FALSE` to omit labels for outliers. The outliers that will be flagged are the `id.n` largest in absolute value. The labels correspond to the index of each point in the provided vector of observations.
`labelargs`	Controls whether the fitted distributional parameters are added to each panel. Can be a logical value or a character value. If FALSE, no labels are added. If TRUE, labels are taken from the names of `rdist.args`. If a character vector is provided, those strings are used to subset the names of `rdist.args`. The panel function `panel.qqmath.fitted` will prepend each label to the corresponding distributional parameter estimate, rounded to two decimal places. `labelargs` is not supported when groups are used due to the difficulty of automatically producing readable labels for all groups in each panel.
`verbose`	If TRUE, additional debugging information will be printed.
`...`	Further arguments, often graphical parameters, passed to internal plotting functions and eventually on to `panel.superpose`, `panel.xyplot`, and `gpar`.
`lattice.options`	See `xyplot`.
`default.scales`	See `xyplot`.
`subscripts`	See `xyplot`.
`subset`	See `xyplot`.

qqmathFitted is a modified version of qqmath from Deepayan Sarkar's lattice package. It adds the ability to fit the reference distribution to the data during the plotting procedure, as well as the ability to simulation envelopes. The latter ability is based on code appearing in the function lmfmResQQPlot from the robust package maintained by Kjell Konis.

prepanel.qqmath.fitted does the actual distributional fitting for qqmathFitted.

An object of class "trellis".

Christopher G. Green christopher.g.green@gmail.com for qqmathFitted. qqmathFitted is a modified version of qqmath from the lattice package, written by Deepayan Sarkar. The plotting code for simulation envelopes is based on code appearing in the lmfmResQQPlot function from the robust package written by Kjell Konis et al.

prepanel.qqmath.fitted, panel.qqmath.fitted, qqmath, panel.qqmath

    # normal distribution example
    n.trials <- 4
    n.sample <- 250
    # generate sample data
    normal.sample.data <- as.data.frame(
        list(
            ret=rnorm(n.trials*n.sample, 
                mean=rep(seq(-5,5,length=n.trials),each=n.sample), 
                sd=rep(seq(0.1,10,length=n.trials),each=n.sample)),
            trial=rep(paste("TRIAL",
                c(paste("0",1:9,sep=""),
                    as.character(10:n.trials))),each=n.sample),
            case=rep(c("CASE A","CASE B"),
                each=n.trials*n.sample %/% 2)
        )
    )
    # normal q-q plot
    qqmathFitted( ~ret, 
        data=normal.sample.data, 
        subset=1:n.sample,
        panel = panel.qqmath.fitted,
        main = "Normally-distributed trial data",
        ylab = "Quantiles of sample data",
        xlab = "Quantiles of fitted normal distribution",
        aspect = 1,
        as.table=TRUE,
        layout=c(1,1),
        distribution=qnorm,
        distribution.fit=function(y) 
            list(mean=as.vector(median(y)), sd=mad(y)),
        rdist=rnorm,
        qqstyle=list(pch="+",col=2),
        envstyle=list(pch="o",col=3)
    )
    # normal q-q plot, one panel per trial
    qqmathFitted( ~ret|trial, 
        data=normal.sample.data,
        panel = panel.qqmath.fitted,
        main = "Normally-distributed trial data",
        ylab = "Quantiles of sample data",
        xlab = "Quantiles of fitted normal distribution",
        aspect = 1,
        as.table=TRUE,
        layout=c(2,2),
        distribution=qnorm,
        distribution.fit=function(y) 
            list(mean=median(y), sd=mad(y)),
        rdist=rnorm,
        scales = list(relation="free"),
        qqstyle=list(pch="+",col=2),
        envstyle=list(pch="o",col=3)
    )
    # normal q-q plot showing subsetting
    qqmathFitted( ~ret, 
        data=normal.sample.data,
        groups = trial,
        subset = (trial %in% c("TRIAL 01","TRIAL 05")),
        panel = panel.qqmath.fitted,
        main = "Normally-distributed trial data",
        ylab = "Quantiles of sample data",
        xlab = "Quantiles of fitted normal distribution",
        aspect = 1,
        as.table=TRUE,
        layout=c(1,1),
        distribution=qnorm,
        distribution.fit=function(y) 
            list(mean=median(y), sd=mad(y)),
        envelope=FALSE,
        add.qqline="lm",
        add.qqline.par=list(lty=c(2,rep(NA,3),3),
        col=c("green",rep("",3),"black"))
    )
    # student t example
    # generate sample data
    symt.sample.data <- as.data.frame(
        list(
            ret=rep(seq(-5,5,length=n.trials),each=n.sample) +
                1.2*rt(n.trials*n.sample, df=4),
            trial=rep(paste("TRIAL",
                c(paste("0",1:9,sep=""),
                    as.character(10:n.trials))),each=n.sample)
        )
    )
    # symmetric t q-q plot
    qqmathFitted( ~ret, 
        data=symt.sample.data, 
        subset=1:n.sample,
        panel = panel.qqmath.fitted,
        main = "Symmetric t-distributed trial data",
        ylab = "Quantiles of sample data",
        xlab = "Quantiles of fitted symmetric t distribution",
        aspect = 1,
        as.table=TRUE,
        layout=c(1,1),
        distribution=function(p,df,mu,sigma) 
            mu + sigma*qt(p,df),
        distribution.fit=function(y) fit.mle.t(y),
        rdist=function(n,df,mu,sigma) 
            mu + sigma*rt(n,df),
        qqstyle=list(pch="o",col=2),
        envstyle=list(pch="+",col=3),
        labelargs=c("df"),
        verbose = TRUE
    )