# AEdotplot.data.frame

##### AE (Adverse Events) dotplot of incidence and relative risk, support functions

Support functions for the `AEdotplot`

.

##### Usage

```
## S3 method for class 'data.frame':
AEdotplot(xr, ...,
conditionVariable=NULL,
conditionName=deparse(substitute(xr)),
useCondition=!is.null(conditionVariable),
sub=list(conditionName, cex=.7))
``` ## S3 method for class 'AElogrelrisk':
AEdotplot(xr,
A.name=paste(levels(xr$RAND)[1], " (n=", xr$SN[1], ")", sep=""),
B.name=paste(levels(xr$RAND)[2], " (n=", xr$SN[2], ")", sep=""),
col.AB=c("red","blue"), pch.AB=c(16,17),
main=if (sortbyRelativeRisk)
list("Most Frequent On-Therapy Adverse Events Sorted by Relative Risk",
cex=1)
else
list("Most Frequent On-Therapy Adverse Events", cex=1),
cex.AB.points=NULL, cex.AB.y.scale=.6, cex.x.scale=.6,
panel.widths=c(.55, .22, .23),
key.y=-.2, CI.percent=95,
conditionName=deparse(substitute(xr)),
sortbyRelativeRisk=TRUE,
...,
sub=list(conditionName, cex=.7),
par.strip.text=list(cex=.7))

## S3 method for class 'AEtable':
AEdotplot(xr, ..., useCondition=TRUE,
sub="sub for AEsecond")

## S3 method for class 'AEdotplot':
print(x, ...,
main=attr(x, "main"),
sub=attr(x,"sub"),
ae.key=attr(x, "ae.key"),
panel.widths=attr(x,"panel.widths"),
AEtable=TRUE)

## S3 method for class 'AEdotplot':
c(..., panel.widths=attr(aedp[[1]], "panel.widths"),
par.strip.text=list(cex=.7))

AElogrelrisk(ae,
A.name=levels(ae$RAND)[1],
B.name=levels(ae$RAND)[2],
crit.value=1.96,
sortbyRelativeRisk=TRUE, ...)

AEmatchSortorder(AEstandard,
AEsecond,
AEsecond.AEtable=attr(AEsecond, "AEtable"),
levels.order=
lapply(attr(AEstandard,"AEtable"),
function(AEsubtable) levels(AEsubtable$PREF)),
main.second=list(paste("Most Frequent On-Therapy Adverse Events",
"Sorted to Match First Table"),
cex=1))

## S3 method for class 'AEdotplot':
update(object, ...)

##### Arguments

- ae
- For
`AElogrelrisk`

, a data.frame containing at least the first 4 columns of`xr`

. - xr
- For the formula method documented in
`AEdotplot`

, a formula of the form`AE ~ nAE/nTRT | OrgSys`

, where the condition variable is optional. For the formula method only, the variable n - sortbyRelativeRisk
- logical. If
`TRUE`

, then make the Adverse Events an ordered factor ordering by relative risk. If`FALSE`

, then make the Adverse Events an ordered factor retaining the order of the input levels. - conditionVariable
- Vector of same length as number of rows in
`xr`

, it may be one of the columns in`xr`

in which case its full name in the form xr$varname must be used. It will be used to split the`data.frame`

into partitions. - conditionName
- Character. Name to be used in
`left.strip`

. - useCondition
- logical. If
`FALSE`

, then a non-`NULL`

`ConditionVariable`

won't be used. - x
- object to be printed.
- panel.widths
- Vector of three non-negative numerics that sum to 1. These are the widths of each of the three panels in the output plot. The left panel contains the AE names as y-tick labels and the Percent plot. The middle panel contains the Relative Ris
- AEtable
- logical. For the
`print.AEdotplot`

function. If`TRUE`

(the default), display all three panels. If`FALSE`

, then display only the Percent and Relative Risk plots. - main, sub
- Main title and subtitle for the combined plot
in
`AEdotplot`

. - main.second
- Main title for second plot whose sort order has been changed to match the first plot.
- A.name, B.name
- Names of treatment groups (in
`x$RAND`

). - col.AB, pch.AB, cex.AB.points
- color, plotting character and character expansion for the individual points on the left plot.
- cex.AB.y.scale
- Character expansion for the left tick labels (the Adverse Effects names).
- cex.x.scale
- Character expansion for the x-axis tick labels.
- key.y
- Position of the key (legend) in the combined plot. This
is the
`y`

argument of the`key`

. See the discussion of the`key`

argument to`xyplot`

in`xyplot`

- ae.key
- is a key as described in
`xyplot`

. - AEstandard, AEsecond, AEsecond.AEtable, levels.order
- Arguments
that force the Adverse Events in the panels of
`AEsecond`

to have the same sort order`levels.order`

of`PREF`

as the panels of`AEstandard`

.`AEstandard`

and`AEsecond`

- crit.value
- Critical value used to compute confidence intervals
on the log relative risk. Defaults to 1.96. User is responsible
for specifying both
`crit.value`

and`CI.percent`

consistently. - CI.percent
- Confidence percent associated with the
`crit.value`

Defaults to 95. User is responsible for specifying both`crit.value`

and`CI.percent`

consistently. - ...
- For
`AEdotplot`

and`AEdotplot.data.frame`

, all the arguments listed in the calling sequence for`AEddotplot.AErelrisk`

.. For`c.AEdotplot`

, one or more`"AEdotplot"`

objects. For - object
- An
`AEdotplot`

object. The`update`

method updates the components of each of the constituent`trellis`

objects. It does not update the`"main"`

and`"sub"`

attributes (nor any other attr - par.strip.text
- Default value for strip labels. See
`xyplot`

for details.

##### Details

The first panel is an ordinary dotplot of the percent of AE observed for each treatment by AE.

The second panel shows relative risk of an event on the Treatment B arm
(usually the active compound)
relative to the Treatment A arm (usually the placebo), with 95% confidence
intervals for a $2\times2$ table. Confidence intervals on the log
relative risk are calculated using the asymptotic standard error
formula given as Equation 3.18 in Agresti A., *Categorical Data
Analysis.* Wiley: New York, 1990.

By default the `AEdotplot`

function sorts the events by relative risk.
To retain the sort order implied by the `levels`

of the AE
factor, specify the argument `sortbyRelativeRisk=FALSE`

.
To control the sort order, make the AE factor in the input dataset
an `ordered`

factor
and specify the levels in the order you want.

The third panel shows the numerical values of the number and percent
of observed events on each arm and the relative risk.
The display of third panel can be suppressed by specifying the
`panel.widths`

argument.

##### Value

- The primary interest is in the display of the plot.
The function returns an

`AEdotplot`

object which is a list of three`trellis`

objects, one for the the Percent plot, one for the Relative Risk plot, and one for the Text plot containing the table of input values. The object has attributes`main`

and`sub`

hold the main and subtitles. Each must be a list containing the text in the first component.`ae.key`

is a key as described in`xyplot`

.`n.events`

is a vector containing the number of events in each subpanel.`panel.widths`

is a vector of relative widths of the three components of the graph. The numbers must sum to one. Zero values are permitted. The first width includes the left axis and the Percent plot. The second is the Relative Risk plot, and the third is the plot of the table values.`AEtable`

is a table containing the data plotted on its row.

##### References

Ohad Amit, Richard M. Heiberger, and Peter W. Lane. (2008)
``Graphical Approaches to the Analysis of Safety Data from Clinical Trials''.
*Pharmaceutical Statistics*,
**7**, 1, 20--35.

##### See Also

##### Examples

```
## variable names in the input data.frame aeanonym
## RAND treatment as randomized
## PREF adverse event symptom name
## SN number of patients in treatment group
## SAE number of patients in each group for whom the event PREF was observed
## OrgSys Organ System
##
## Input sort order is PREF/RAND
data(aeanonym)
head(aeanonym)
## variable names are hard-wired in the program
## names(aeanonym) <- c("RAND", "PREF", "SAE", "SN", "OrgSys")
## Calculate log relative risk and confidence intervals (95## AElogrelrisk sets the sort order for PREF to match the relative risk.
aeanonymr <- AElogrelrisk(aeanonym) ## PREF sorted by relative risk
head(aeanonymr)
class(aeanonymr$PREF)
levels(aeanonymr$PREF)
AEdotplot(aeanonym)
\dontrun{
AEdotplot(aeanonym, sort=FALSE)
}
AEdotplot(aeanonym, conditionVariable=aeanonym$OrgSys)
aefake <- rbind(cbind(aeanonym, group="ABC"), cbind(aeanonym, group="DEF"))
aefake$SAE[67:132] <- sample(aefake$SAE[67:132])
aefake$OrgSys.group <- with(aefake, interaction(OrgSys, group))
## fake 2
KEEP <- aefake$OrgSys %in% c("GI","Resp")AEfakeGR <- AEdotplot(aefake[KEEP,], conditionVariable=aefake$OrgSys.group[KEEP],
sub=list("ABC and DEF have different sort orders for PREF", cex=.7))
AEfakeGR ## ABC and DEF have different sort orders for PREF
AEfakeGR1 <- AEdotplot(aefake[KEEP & (1:132) <= 66,],
conditionVariable=aefake$OrgSys.group[KEEP & (1:132) <= 66])
AEfakeGR2 <- AEdotplot(aefake[KEEP & (1:132) >= 67,],
conditionVariable=aefake$OrgSys.group[KEEP & (1:132) >= 67])
AEfakeGR1
AEfakeGR2
AEfakeMatched <- AEmatchSortorder(AEfakeGR1, AEfakeGR2)
update(do.call(c, AEfakeMatched),
main="ABC sorted by Relative Risk; DEF matches ABC order")
## Please see ?AEdotplot for examples using the formula method
##
## Many more examples are in demo("AEdotplotManyExamples")
```

*Documentation reproduced from package HH, version 3.1-25, License: GPL (>= 2)*