# ae.dotplot

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

A two-panel display of the most frequently occurring AEs in the active arm of a clinical study. The first panel displays their incidence by treatment group, with different symbols for each group. The second panel displays the relative risk of an event on the active arm relative to the placebo arm, with 95% confidence intervals for a \(2\times2\) table. By default, the AEs are ordered by relative risk so that events with the largest increases in risk for the active treatment are prominent at the top of the display. See the Details section for information on changing the sort order.

##### Usage

`ae.dotplot(ae, ...)`ae.dotplot.long(xr,
A.name = levels(xr$RAND)[1], B.name = levels(xr$RAND)[2],
col.AB = c("red","blue"), pch.AB = c(16, 17),
main.title = paste("Most Frequent On-Therapy Adverse Events",
"Sorted by Relative Risk"),
main.cex = 1,
cex.AB.points = NULL, cex.AB.y.scale = 0.6,
position.left = c(0, 0, 0.7, 1), position.right = c(0.61, 0, 0.98, 1),
key.y = -0.2, CI.percent=95)

logrelrisk(ae, A.name, B.name, crit.value=1.96)

panel.ae.leftplot(x, y, groups, col.AB, ...)

panel.ae.rightplot(x, y, ..., lwd=6, lower, upper, cex=.7)

panel.ae.dotplot(x, y, groups, ..., col.AB, pch.AB, lower, upper) ## R only

aeReshapeToLong(aewide)

##### Arguments

- ae
For

`ae.dotplot`

, either a data.frame containing the Adverse Event data in long format as described by the detail for`xr`

below, or a data.frame containing the Adverse event data in wide format as described by the detail for`aewide`

below. For`logrelrisk`

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

described below.- …
For

`ae.dotplot`

, all the arguments listed in the calling sequence for`ae.ddotplot.long`

and possibly standard panel function arguments.For the other functions, just standard panel function arguments.

- xr
`RAND`

: treatment as randomized (factor).`PREF`

: adverse event symptom name (factor).`SN`

: number of patients in treatment group.`SAE`

: number of patients in each group for whom the event PREF was observed.`PCT`

:`SAE`

/`SN`

as a percent.`relrisk`

: Relative risk defined as`PCT`

for the B treatment divided by`PCT`

for the A treatment.`logrelrisk`

: natural logarithm of`relrisk`

.`ase.logrelrisk`

: asymptotic standard error of`logrelrisk`

.`logrelriskCI.lower, logrelriskCI.upper`

: confidence interval for`logrelrisk`

.`relriskCI.lower, relriskCI.upper`

: back transform of the CI for the log relative risk into the relative risk scale.

- aewide
`Event`

: adverse event symptom name (factor).`N.A, N.B`

: number of patients in treatment groups A and B.`AE.A, AE.B`

: number of patients in treatment groups A and B for whom the event Event was observed.`PCT.A, PCT.B`

:`AE.A`

/`N.A`

and`AE.B`

/`N.B`

as a percent.`Relative.Risk`

: Relative risk defined as`PCT.B`

divided by`PCT.A`

.`logrelrisk`

: natural logarithm of`relrisk`

.`ase.logrelrisk`

: asymptotic standard error of`logrelrisk`

.`logrelriskCI.lower, logrelriskCI.upper`

: confidence interval for`logrelrisk`

.`relriskCI.lower, relriskCI.upper`

: back transform of the CI for the log relative risk into the relative risk scale.

- 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 symptom names).

- main.title, main.cex
Main title and character expansion for the combined plot in

`ae.dotplot`

.- cex
The character expansion for the points in the left and right plots.

- position.left, position.right
`position`

of the left and right plots. This argument is use in S-Plus only, not in R. See the discussion of`position`

in- key.y
Position of the key (legend) in the combined plot. This is the

`y`

argument of the`key`

.- 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.- x, y, groups, lwd
standard panel function arguments.

- lower, upper
`xr$logrelriskCI.lower`

and`xr$logrelriskCI.upper`

inside the panel functions.

##### Details

The second panel shows relative risk of an event on the active arm (treatment B) relative to the placebo arm (treatment A), 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 `ae.dotplot`

function sorts the events by relative risk.
To change the sort order, you must redefine the ordering of the
ordered factor `PREF`

. See the examples below.

##### Value

`logrelrisk`

takes an input data.frame of the form `x`

described in the argument list and returns a data.frame consisting of
the input argument with additional columns as described in the
argument `xr`

. The result column of symptom names `PREF`

is
an ordered factor, with the order specified by the relative risk.

`ae.leftplot`

returns a `"trellis"`

object containing a
horizontal dotplot of the percents against each of the symptom names.

`ae.rightplot`

returns a `"trellis"`

object containing a
horizontal plot on the log scale of the relative risk confidence
intervals against each of the symptom names.

`ae.dotplot`

calls both `ae.leftplot`

and `ae.rightplot`

and combines their plots into a single display with a single set of
left axis labels, a main title, and a key. The value returned
invisibly is a list of the full left trellis object and the right
trellis object with its left labels blanked out. Printing the value
will not usually be interesting as the main title and key are not
included.
It is better to call `ae.dotplot`

directly, perhaps with a change
in some of the positioning arguments.

##### 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.
https://onlinelibrary.wiley.com/doi/10.1002/pst.254

##### See Also

`AEdotplot`

for a three-panel version that also has
an associated shiny app.

##### Examples

```
# NOT RUN {
## 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
##
## Input sort order is PREF/RAND
data(aeanonym)
head(aeanonym)
## Calculate log relative risk and confidence intervals (95% by default).
## logrelrisk sets the sort order for PREF to match the relative risk.
aeanonymr <- logrelrisk(aeanonym) ## sorts by relative risk
head(aeanonymr)
## construct and print plot on current graphics device
ae.dotplot(aeanonymr,
A.name="TREATMENT A (N=216)",
B.name="TREATMENT B (N=431)")
## export.eps(h2("stdt/figure/aerelrisk.eps"))
## This looks great on screen and exports badly to eps.
## We recommend drawing this plot directly to the postscript device:
##
## trellis.device(postscript, color=TRUE, horizontal=TRUE,
## colors=ps.colors.rgb[
## c("black", "blue", "red", "green",
## "yellow", "cyan","magenta","brown"),],
## onefile=FALSE, print.it=FALSE,
## file=h2("stdt/figure/aerelrisk.ps"))
## ae.dotplot(aeanonymr,
## A.name="TREATMENT A (N=216)",
## B.name="TREATMENT B (N=431)")
## dev.off()
## To change the sort order, redefine the PREF factor.
## For this example, to plot alphabetically, use the statement
aeanonymr$PREF <- ordered(aeanonymr$PREF, levels=sort(levels(aeanonymr$PREF)))
ae.dotplot(aeanonymr,
A.name="TREATMENT A (N=216)",
B.name="TREATMENT B (N=431)",
main.title="change the main title to reflect the new sort order")
# }
# NOT RUN {
## to restore the order back to the default, use
relrisk <- aeanonymr[seq(1, nrow(aeanonymr), 2), "relrisk"]
PREF <- unique(aeanonymr$PREF)
aeanonymr$PREF <- ordered(aeanonymr$PREF, levels=PREF[order(relrisk)])
ae.dotplot(aeanonymr,
A.name="TREATMENT A (N=216)",
B.name="TREATMENT B (N=431)",
main.title="back to the original sort order")
## smaller artifical example with the wide format
aewide <- data.frame(Event=letters[1:6],
N.A=c(50,50,50,50,50,50),
N.B=c(90,90,90,90,90,90),
AE.A=2*(1:6),
AE.B=1:6)
aewtol <- aeReshapeToLong(aewide)
xr <- logrelrisk(aewtol)
ae.dotplot(xr)
# }
```

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