AEdotplot.data.frame
AE (Adverse Events) dotplot of incidence and relative risk, support functions
Support functions for the AEdotplot
.
Usage
# S3 method for data.frame
AEdotplot(xr, ...,
conditionVariable=NULL,
conditionName=deparse(substitute(xr)),
useCondition=!is.null(conditionVariable),
sub=list(conditionName, cex=.7)) # S3 method for 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 AEtable
AEdotplot(xr, ..., useCondition=TRUE,
sub="sub for AEsecond")
# S3 method for 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 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, ...,
sortbyVar=c("PREF", ## Event name
"PCT", ## Percent
"SN", ## Number of Patients
"SAE", ## Number of Observed Events
"relrisk", ## Relative Risk (RR)
"ase.logrelrisk", ## Asymptotic Standard Error(log(RR))
"relriskCI.lower", ## Confidence Interval Bounds
"relriskCI.upper"),
sortbyVarBegin=1) ## 1 for A treatment, 2 for B treatment
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 AEdotplot
update(object, ...)
Arguments
- ae
For
AElogrelrisk
, a data.frame containing at least the first 4 columns ofxr
.- xr
For the formula method documented in
AEdotplot
, a formula of the formAE ~ nAE/nTRT | OrgSys
, where the condition variable is optional. For the formula method only, the variable names are not restricted.For the other methods,
xr
is adata.frame
containing the Adverse Event data in long format. It must have variables namedRAND
: treatment as randomized (factor with exactly two levels).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.If the
xr
object is aAElogrelrisk
object, then it must also have variablesPCT
:SAE
/SN
as a percent.relrisk
: Relative risk defined asPCT
for the B treatment divided byPCT
for the A treatment.logrelrisk
: natural logarithm ofrelrisk
.ase.logrelrisk
: asymptotic standard error oflogrelrisk
.logrelriskCI.lower, logrelriskCI.upper
: confidence interval forlogrelrisk
.relriskCI.lower, relriskCI.upper
: back transform of the CI for the log relative risk into the relative risk scale.- sortbyRelativeRisk
logical. If
TRUE
, then make the Adverse Events an ordered factor ordering by relative risk. IfFALSE
, 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 inxr
in which case its full name in the form xr$varname must be used. It will be used to split thedata.frame
into partitions. It may be used to partition the plot, for example by organ system or by gender.- 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 Risk plot. The right panel contains a table of the numerical values of number of patients for each treatment, number of adverse events for each treatment, and relative risk. Setting the third value to 0 suppresses the table of numerical values from the display.
- AEtable
logical. For the
print.AEdotplot
function. IfTRUE
(the default), display all three panels. IfFALSE
, 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 thekey
. See the discussion of thekey
argument toxyplot
inxyplot
- 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 orderlevels.order
ofPREF
as the panels ofAEstandard
.AEstandard
andAEsecond
are two"AEdotplot"
objects with the same set of panels and the same Adverse Events in corresponding panels.AEsecond.AEtable
is theAEtable
object fromAEsecond
.levels.order
is the new order forAEsecond
; normally the same order as inAEprimary
.- 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
andCI.percent
consistently.- CI.percent
Confidence percent associated with the
crit.value
Defaults to 95. User is responsible for specifying bothcrit.value
andCI.percent
consistently.- …
For
AEdotplot
andAEdotplot.data.frame
, all the arguments listed in the calling sequence forAEddotplot.AErelrisk
.. Forc.AEdotplot
, one or more"AEdotplot"
objects. Forprint.AEdotplot
, the…
arguments are ignored.- sortbyVar
Specify which variable will be used to provide the sort order in the plot. The names are the internal names for the variables.
- sortbyVarBegin
1 for A treatment, 2 for B treatment.
- object
An
AEdotplot
object. Theupdate
method updates the components of each of the constituenttrellis
objects. It does not update the"main"
and"sub"
attributes (nor any other attribute) of theAEdotplot
object.- 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
andsub
hold the main and subtitles. Each must be a list containing the text in the first component.ae.key
is a key as described inxyplot
.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. https://onlinelibrary.wiley.com/doi/10.1002/pst.254
See Also
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
## 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<!-- % by default). -->
## 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")
<!-- %% 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")
# }
# NOT RUN {
## Please see ?AEdotplot for examples using the formula method
##
## Many more examples are in demo("AEdotplotManyExamples")
# }