*! aedots2 version 1.3 17Nov2021
help aedots2

Title

aedots2 -- Dot plot for summary level adverse event data with data table containing number of participants and number of events

Syntax

aedots2 varname , n1(varname) n2(varname) event1(varname) event2(varname) tot1(varname) tot2(varname) [options]

aedots2 requires summary data in long format with one row per event, where varname indicates the variable that contains the event name/identifier.
varname may be a numeric or a string variable.

* n1(varname) variable indicating the number of participants in the first treatment group with the event specified in varname (must be numeric)

* n2(varname) variable indicating the number of participants in the second treatment group with the event specified in varname (must be numeric)

* event1(varname) variable indicating the number of events of the type specified in varname in the first treatment group (must be numeric)

* event2(varname) variable indicating the number of events of the type specified in varname in the second treatment group (must be numeric)

* tot1(varname) variable indicating the total number of unique participants in the first treatment group (must be numeric)

* tot2(varname) variable indicating the total number of unique participants in the second treatment group (must be numeric)

saving(filename[, replace]) saves the dataset with event level summary data used for the plot in filename.dta

graphsave(filename[, replace]) saves the plot in filename.gph

clear if specified the newly created dataset is stored in memory. Without clear the original dataset is retained in memory

riskdiff(#) specify whether relative risk or risk difference plotted; riskdiff(0) plots the relative risk and riskdiff(1) plots the risk difference, default is riskdiff(0)

logoff(#) specify whether log relative risk or relative risk plotted; logoff(0) plots the log relative risk and logoff(1) plots the relative risk, default is logoff(0)

leftxtitle(string) title for the x-axis on the plot on the left; the default label is "Percentage"

leftcolor1(colorstyle) marker colour for the first treatment group values on the plot on the left; default is leftcolor1(blue)

leftcolsat1(#) marker colour saturation for the first treatment group values on the plot on the left; default is leftcolsat1(50)

leftcolor2(colorstyle) marker colour for the second treatment group values on the plot on the left; default is leftcolor2(red)

leftcolsat2(#) marker colour saturation for the second treatment group values on the plot on the left; default is leftcolsat2(50)

leftsymb1(symbolstyle) marker symbol for the first treatment group values on the plot on the left; default symbol is leftsymb1(circle)

leftsymb2(symbolstyle) marker symbol for the second treatment group values on the plot on the left; default symbol is leftsymb2(circle)

leftlabsize(#) size of labels on the y-axis for the plot on the left; default is leftlabsize(1)

leftlabang(#) label angle on the y-axis for the plot on the left; default is leftlabang(0) to give horizontal labels

leftlabel(string) used to override y-axis labels on the plot on the left. See graph dot relabel for further details

rightxline(#) vertical line position on the plot on the right; default is rightxline(0)

rightxlinepat(linepattern) vertical line style on the plot on the right; default is rightxlinepat(dash)

rightxlinecol(colorstyle) vertical line colour on the plot on the right; default is rightxlinecol(bluishgray)

rightdcolor(colorstyle) horizontal grid line colour on the plot on the right; default is rightdcolor(white)

rightdotcol(colorstyle) marker colour on the plot on the right; default is rightdotcol(black)

rightdotsat(#) marker colour saturation on the plot on the right; default is rightdotsat(60)

rightlincol(colorstyle) line colour of the confidence interval on the plot on the right; default is rightlincol(black)

rightlinsat(#) colour saturation of the confidence interval on the plot on the right; default is rightlinsat(60)

rightxlabel(numlist) allows the user to specify the x-axis value labels on the plot on the right

legendleftyn(#) specify whether legend appears on the plot on the left; legendleftyn(#) takes values 0 to indicate legend off or 1 to indicate legend on, default is legendleftyn(1)

legendleft1(string) specify text for the legend to describe the first treatment group for the plot on the left; default text is "Group 1"

legendleft2(string) specify text for the legend to describe the second treatment group for the plot on the left; default text is "Group 2"

legendleftpos(#) specify position of the legend on the plot on the left; default is legendleftpos(6)

legendleftcol(#) number of columns in the legend on the plot on the left; default is legendleftcol(2)

legendleftrow(#) number of rows in the legend on the plot on the left; default is legendleftrow(1)

legendrightyn(#) specify whether legend appears on the plot on the right; legendrightyn(#) takes values 0 to indicate legend off or 1 to indicate legend on, default is legendrightyn(1)

legendright1(string) specify text to describe the point estimate in the legend on the plot on the right; default text is "log10(Relative risk)" if riskdiff(0) and "Risk difference" if riskdiff(1)

legendright2(string) specify text to describe the 95% confidence interval in the legend on the plot on the right; default text is "95% CI"

legendrightpos(#) specify position of the legend on the plot on the right; default is legendrightpos(6)

legendrightcol(#) number of columns in the legend on the plot on the right; default is legendrightcol(2)

legendrightrow(#) number of rows in the legend on the plot on the right; default is legendrightrow(1)

bleftmargin(#) adds a margin of empty space to the bottom of the plot on the left; default is bleftmargin(0). This can be used to help align the plots.

tleftmargin(#) adds a margin of empty space to the top of the plot on the left; default is tleftmargin(0). This can be used to help align the plots.

aspectleft(#) sets the aspect of the plot on the left; default is aspectleft(0). See aspectratio for further details.

brightmargin(#) adds a margin of empty space to the bottom of the plot on the right; default is brightmargin(2). This can be used to help align the plots.

trightmargin(#) adds a margin of empty space to the top of the plot on the right; default is trightmargin(5). This can be used to help align the plots.

aspectright(#) sets the aspect of the plot on the right; default is aspectright(0). See aspectratio for further details.

nummargin(#) add a margin of empty space to one side of the plot on the right; default is nummargin(0). nummargin(1) is required to add space for inclusion of a data table of event frequencies.

margin(#) set the percentage increase of space to be added when nummargin(1); default is margin(0). See marginstyle for further details.

marginpos(string) to indicate if the data table of event frequencies is displayed on the right or left of the plot; marginpos() takes value l to indicate positioned to the left and r to indicate positioned to the right.

event1pos(#) specify x-axis position to place the column of event frequencies for the first treatment group

event2pos(#) specify x-axis position to place the column of event frequencies for the second treatment group

event1posy(#) specify y-axis position to place the main column titles indicating treatment groups; default is event1posy(0.4).

event2posy(#) specify y-axis position to place the column subtitles; default is event2posy(0.6).

event1name(string) specify text for the title of the column of event frequencies for the first treatment group; default text is "Group 1"

event2name(string) specify text for the title of the column of event frequencies for the second treatment group; default text is "Group 2"

numppl(string) specify text for the subtitle representing column with number of participants; default text is "n"

numevent(string) specify text for the subtitle representing column with number of events; default text is "events"

title(string) specify an overall title for the plot

subtitle(string) specify an overall subtitle for the plot

grphcol(colorstyle) colour of the graph background; default is grphcol(white)

plotcol(colorstyle) colour of the plot background; default is plotcol(white)

* n1, n2, event1, event2, tot1 and tot2 are
required.

Description

aedots2 creates a dot plot for summary level AE data from a two-arm clinical trial. The dot plot produces two graphs plotted adjacent to each other.
The first displays the incidence of each event by treatment group.
The second displays either the relative risk with corresponding 95% CI or the risk difference with corresponding 95% CI.

An optional data table containing the number of participants with each event and the number of events for each treatment group can also be included.

In the event that information on the number of events is unavailable a data table that only contains columns of the number of participants can be produced using the aedots command.

Options

n1(varname) variable indicating the number of participants in the first treatment group with the event specified in varname.
n1(varname) is required and must be a numeric variable.

n2(varname) variable indicating the number of participants in the second treatment group with the event specified in varname.
n2(varname) is required and must be a numeric variable.

event1(varname) variable indicating the number of events of type specified in varname in the first treatment group.
event1(varname) is required and must be a numeric variable.

event2(varname) variable indicating the number of events of type specified in varname in the second treatment group.
event2(varname) is required and must be a numeric variable.

tot1(varname) variable indicating the total number of unique participants in the first treatment group.
tot1(varname) is required and must be a numeric variable.

tot2(varname) variable indicating the total number of unique participants in the second treatment group.
tot2(varname) is required and must be a numeric variable.

saving(filename[, replace]) saves the dataset
with the newly generated event level summary data. This data is used to produce the plot.
A new filename is required unless replace is also specified.
replace allows the filename to be overwritten with new data.

graphsave(filename[, replace]) saves the plot in filename.gph.
A new filename is required unless replace is also specified.
replace allows the filename to be overwritten with new plot.

clear if specified the newly created dataset is stored in memory.
If clear not specified the original dataset is retained in memory.

riskdiff(#) specifies whether the relative risk and corresponding confidence
interval or risk difference and corresponding confidence interval will be plotted;
riskdiff(0) plots the relative risk and riskdiff(1) plots the risk difference.
riskdiff(#) can only take values 0 or 1. The default is riskdiff(0).

logoff(#) specifies whether the relative risk and corresponding confidence
interval is plotted on the log scale or not;
logoff(0) plots the log relative risk and logoff(1) plots the relative risk.
logoff(#) can only take values 0 or 1. The default is logoff(0).

leftxtitle(string) specifies the title for the x-axis on the
plot on the left of the overall plot.
The default label is "Percentage".

leftcolor1(colorstyle) specifies the marker colour for the first treatment group values
on the plot on the left of the overall plot.
leftcolor1() must be one of Stata's colorstyle. The default marker colour is leftcolor1(blue).

leftcolsat1(colorstyle) specifies the marker colour saturation for the first treatment group values
on the plot on the left of the overall plot.
leftcolsat1(#) accepts integer values between 0 and 100 inclusive. The default colour saturation value is leftcolsat1(50).

leftcolor2(colorstyle) specifies the marker colour for the second treatment group values
on the plot on the left of the overall plot.
leftcolor2() must be one of Stata's colorstyle. The default marker colour is leftcolor2(red).

leftcolsat2(colorstyle) specifies the marker colour saturation for the second treatment group values
on the plot on the left of the overall plot.
leftcolsat2(#) accepts integer values between 0 and 100 inclusive. The default value for colour saturation is leftcolsat2(50).

leftsymb1(symbolstyle) specifies the marker symbol for the first treatment group values
on the plot on the left of the overall plot.
leftsymb1() must be one of Stata's symbolstyle. The default marker symbol is leftsymb1(circle).

leftsymb2(symbolstyle) specifies the marker symbol for the second treatment group values
on the plot on the left of the overall plot.
leftsymb2() must be one of Stata's symbolstyle. Default marker symbol is leftsymb2(circle).

leftlabsize(#) specifies the label size for event names on the y-axis on the plot
on the left of the overall plot. The default label size is leftlabsize(1).

leftlabang(#) specifies the label angle for event names on the y-axis on the plot
on the left of the overall plot. The default label angle is leftlabang(0) which provides horizontal labels.

leftlabel(string) used to override y-axis labels on the plot on the left.
See graph dot relabel for further details.
If this is not specified the labels default to the labels of varname,
where varname indicates the variable that contains the event name/identifier.

rightxline(#) specifies the position of the vertical line on the plot
on the right of the overall plot.
The default line position rightxline(0). rightxline(#) must be numeric.

rightxlinepat(linepattern) specifies the line style of the vertical line on the
plot on the right of the overall plot.
rightxlinepat() must be one of Stata's linepattern. The default line pattern is rightxlinepat(dash).

rightxlinecol(colorstyle) specifies the colour of the vertical line on the
plot on the right of the overall plot.
rightxlinecol() must be one of Stata's colorstyle. The default line colour is rightxlinecol(bluishgray).

rightdcolor(colorstyle) specifies the colour of the horizontal grid lines on the
plot on the right of the overall plot.
rightdcolor() must be one of Stata's colorstyle. The default colour is rightdcolor(white).

rightdotcol(colorstyle) specifies the marker colour on the
plot on the right of the overall plot.
rightdotcol() must be one of Stata's colorstyle. The default colour is rightdotcol(black).

rightdotsat(#) specifies the marker colour saturation on the
plot on the right of the overall plot. rightdotsat(#) accepts integer values between 0 and 100 inclusive.
The default colour saturation is rightdotsat(60).

rightlincol(colorstyle) specifies the colour of the confidence interval on the
plot on the right of the overall plot.
rightlincol() must be one of Stata's colorstyle. The default line colour is rightlincol(black).

rightlinsat(#) specifies the colour saturation of the confidence interval on the
plot on the right of the overall plot. rightlinsat(#) accepts integer values between 0 and 100 inclusive.
The default colour saturation is rightlinsat(60).

rightxlabel(numlist) specifies the x-axis values to label on the plot on the right of the overall plot.
If not specified default values automatically generated, apart from when logoff(1) the defaults are specified as 0.5, 1 and 2, but the user can still specify own list to override this.

legendleftyn(#) specifies whether the legend appears on the plot on the left of the overall plot.
legendleftyn(0) indicates legend off and legendleftyn(1) indicates legend on.
legendleftyn(#) can only take values 0 or 1. The default setting is legendleftyn(1), legend on.

legendleft1(string) specifies legend text to describe the first treatment group for the
plot on the left of the overall plot. The default text is "Group 1".

legendleft2(string) specifies legend text to describe the second treatment group for the
plot on the left of the overall plot. The default text is "Group 2".

legendleftpos(#) specifies the position of the legend on the plot on the left of the overall plot.
legendleftpos(#) can take integer values between 1 to 12 inclusive. The default position is legendleftpos(6).

legendleftcol(#) specifies the number of columns in the legend on the plot on the left of the overall plot.
legendleftcol(#) can only take integer values. The default number of columns is legendleftcol(2).
Use with legendleftrow(#) to change legend appearance.

legendleftrow(#) specifies the number of rows in the legend on the plot on the left of the overall plot.
legendleftrow(#) can only take integer values. The default number of rows is legendleftrow(1).
Use with legendleftcol(#) to change legend appearance.

legendrightyn(#) specifies whether the legend appears on the plot on the right of the overall plot.
legendrightyn(0) indicates legend off and legendrightyn(1) indicates legend on. legendrightyn(#) can only take values 0 or 1.
The default is legendrightyn(1), legend on.

legendright1(string) specifies legend text for the point estimate on the plot on the right of the overall plot.
The default text is "log10(Relative risk)" if riskdiff(0) and "Risk difference" if riskdiff(1).

legendright2(string) specifies the legend text for the confidence interval on the plot on the right of the overall plot.
The default text is "95% CI".

legendrightpos(#) specifies the position of the legend on the plot on the right of the overall plot.
legendrightpos(#) can take integer values between 1 to 12 inclusive. The default position is legendrightpos(6).

legendrightcol(#) specifies the number of columns in the legend on the plot on the right of the overall plot.
legendrightcol(#) can only take integer values. The default number of columns is legendrightcol(2).
Use with legendrightrow(#) to change legend appearance.

legendrightrow(#) specifies the number of rows in the legend on the plot on the right of the overall plot.
legendrightrow(#) can only take integer values. The default number of rows is legendrightrow(1).
Use with legendrightcol(#) to change legend appearance.

bleftmargin(#) adds a margin of empty space to the bottom of the plot on the left;
default is bleftmargin(0). This can be used to help align the combined plots.

tleftmargin(#) adds a margin of empty space to the top of the plot on the left;
default is tleftmargin(0). This can be used to help align the combined plots.

aspectleft(#) sets the aspect of the plot on the left; default is aspectleft(0).
It is used to control the relationship between the height and width of a graph's plot region.
See aspectratio for further details.

brightmargin(#) adds a margin of empty space to the bottom of the plot on the right;
default is brightmargin(2). This can be used to help align the combined plots.

trightmargin(#) adds a margin of empty space to the top of the plot on the right;
default is trightmargin(5). This can be used to help align the combined plots.

aspectright(#) sets the aspect of the plot on the right; default is aspectright(0).
It is used to control the relationship between the height and width of a graph's plot region.
See aspectratio for further details.

nummargin(#) adds a margin of empty space to one side of the plot on the right; default is nummargin(0).
nummargin(1) is required to add space to the plot for inclusion of a data table of event frequencies.
nummargin(0) indicates no data table to be added to the plot.

marginpos(string) indicates where to add the margin of empty space for inclusion of the data table of event frequencies.
Position is relative to the plot on the right such that marginpos(l) indicates that it will be placed to the left and
marginpos(r) indicates that it will be placed to the right.

margin(string) sets the percentage increase of space to be added when nummargin(1) to accommodate the inclusion of the data table.
See marginstyle for further details.

event1pos(#) specifies x-axis position to place the column of event frequencies for the first treatment group. Note whether
working on log scale or not when specifying this option.

event2pos(#) specifies x-axis position to place the column of event frequencies for the second treatment group. Note whether
working on log scale or not when specifying this option. Also note position of event1pos() to prevent overlap.

event1posy(#) specifies y-axis position to place the main column titles indicating treatment groups;
default is event1posy(0.4). As the number of events increase titles may start to overlap, use these options to prevent overlap.

event2posy(#) specifies y-axis position to place the column subtitles; default is event2posy(0.6).
As the number of events increase titles may start to overlap, use these options to prevent overlap.

event1name(string) label for the title of the column of event frequencies for the first treatment group;
default text is "Group 1"

event2name(string) label for the title of the column of event frequencies for the second treatment group;
default text is "Group 2"

numppl(string) label for the subtitle representing column with number of participants;
default text is "n"

numevent(string) label for the subtitle representing column with number of events;
default text is "events"

grphcol(colorstyle) specifies the colour of the graph background.
grphcol() must be one of Stata's colorstyle, the default is grphcol(white).

plotcol(colorstyle) specifies the colour of the plot background.
plotcol() must be one of Stata's colorstyle, default is plotcol(white).

title(string) allows users to specify a title for the overall plot.

subtitle(string) allows users to specify a subtitle for the overall plot.

Remarks

General remarks

General remarks

(1) Summary data are required in long format with one row per event.

(2) The command creates a new dataset with one row per event containing summary level data.
Once the command finishes running the new dataset is stored in memory if clear is specified and is
saved in filename.dta if saving() is specified. If clear is
not specified the original dataset is kept in memory.

(3) Graphs are saved to the users current working directory if graphsave() is specified.

(4) If 0 events experienced in either treatment group the command adds half an event to each group
(numerator and denominator) to calculate the relative risk, standard error
and 95% confidence interval. This does not affect the percentages presented and calculation of the risk difference.

(5) Calculation of 95% confidence interval uses the normal approximation.

(6) The command will always process the lowest coded value first. For example:

n1(varname) / tot1(varname) - n2(varname) / tot2(varname)

(7) With a large number of events the plot can become incomprehensible,
therefore we advise users to split their data into groups of events and produce a separate plot for each group if necessary.

(8) If the dataset contains more than two treatment groups then we recommend users present separate graphs for each pairwise comparison.

(9) Event frequencies including number of participants with each event and the number of events by treatment group can be added to the plot in a separate data table in either the centre of the plot or on the far right.

(10) In the event that information on the number of events is unavailable a data table that only contains columns of the number of participants can be produced using the aedots command.

Examples

Analysing an example dataset

. use example_dot_summ2.dta

Dot plot

. aedots2 ae_pt, n1(n1) n2(n2) tot1(total1) tot2(total2) events1(N1) events2(N2)

Dot plot using the dotsymb1 option to change marker symbol for group 1 and the legendleft1 and legendleft2 options to change legend labels on the plot on the left

. use example_dot_summ2.dta, clear

. aedots2 ae_pt, n1(n1) n2(n2) tot1(total1) tot2(total2) events1(N1) events2(N2) leftsymb1(triangle) legendleft1(Placebo) legendleft2(Intervention)

Dot plot using the riskdiff option to plot risk difference instead of relative risk

. use example_dot_summ2.dta, clear

. aedots2 ae_pt, n1(n1) n2(n2) tot1(total1) tot2(total2) events1(N1) events2(N2) riskdiff(1)

Dot plot using the leftlabsize option to change the size of the event labels

. use example_dot_summ2.dta, clear

. aedots2 ae_pt, n1(n1) n2(n2) tot1(total1) tot2(total2) events1(N1) events2(N2) leftlabsize(0.8)

Dot plot using the rightxline option to change the position of the vertical line on the plot on the right

. use example_dot_summ2.dta, clear

. aedots2 ae_pt, n1(n1) n2(n2) tot1(total1) tot2(total2) events1(N1) events2(N2) rightxline(1.5)

Dot plot using the leftplot option to change the left plot x-axis label

. use example_dot_summ2.dta, clear

. aedots2 ae_pt, n1(n1) n2(n2) tot1(total1) tot2(total2) events1(N1) events2(N2) leftxtitle(%)

Dot plot using the brightmargin option to add space to the bottom and the trightmargin option to add space to the top of the plot on the right

. use example_dot_summ2.dta, clear

. aedots2 ae_pt, n1(n1) n2(n2) tot1(total1) tot2(total2) events1(N1) events2(N2) brightmargin(2) trightmargin(2)

Dot plot using the legendleftyn option and the legendrightyn option to remove legends from both plots

. use example_dot_summ2.dta, clear

. aedots2 ae_pt, n1(n1) n2(n2) tot1(total1) tot2(total2) events1(N1) events2(N2) legendleftyn(0) legendrightyn(0)

Saving the final graph with filename dot_example.gph

. use example_dot_summ2.dta, clear

. aedots2 ae_pt, n1(n1) n2(n2) tot1(total1) tot2(total2) events1(N1) events2(N2) graphsave(dot_example)

Dot plot using the logoff option to plot relative risks instead of the log relative risks

. use example_dot_summ2.dta, clear

. aedots2 ae_pt, n1(n1) n2(n2) tot1(total1) tot2(total2) events1(N1) events2(N2) logoff(1)

Dot plot using the logoff option to plot relative risks instead of the log relative risks and labelling the x-axis using rightxlabel

. use example_dot_summ2.dta, clear

. aedots2 ae_pt, n1(n1) n2(n2) tot1(total1) tot2(total2) events1(N1) events2(N2) logoff(1) rightxlabel(0.01 0.03 0.1 0.5 0 1 5 10 20 50 150)

Dot plot using the nummargin, margin, marginpos, event1pos and event2pos options to include a data table of event frequencies on the far right of the plot

. use example_dot_summ2.dta, clear

. aedots2 ae_pt, n1(n1) n2(n2) tot1(total1) tot2(total2) events1(N1) events2(N2) nummargin(1) margin(50) event1pos(8) event2pos(12) marginpos(r)

Dot plot using the options to include a data table of event frequencies on the far right of the plot and adjusting column label heights to prevent overlap

. use example_dot_summ2.dta, clear

. aedots2 ae_pt, n1(n1) n2(n2) tot1(total1) tot2(total2) events1(N1) events2(N2) nummargin(1) margin(50) event1pos(8) event2pos(12) marginpos(r) event1posy(-1) event2posy(0.2)

Dot plot using the nummargin, margin, marginpos, event1pos, event2pos, event1posy and event2posy options to include a data table in the centre of the plot and adjusting position of the column titles

. use example_dot_summ2.dta, clear

. aedots2 ae_pt, n1(n1) n2(n2) tot1(total1) tot2(total2) events1(N1) events2(N2) nummargin(1) margin(50) event1pos(-10) event2pos(-7) marginpos(l) event1posy(-1) event2posy(0.2)

Acknowledgments

We thank Emily Day (Imperial College London), Jack Elkes (Imperial College London) and
Giles Partington (Imperial College London) for their helpful comments on the program.

References

Amit, O., Heiberger, R. M. and Lane, P. W. 2008. Graphical approaches to the analysis of safety data from clinical trials.
Pharmaceut. Statist. 7: 20-35. doi:10.1002/pst.254

Cornelius, V., Cro, S. & Phillips, R. 2020. Advantages of visualisations to evaluate and communicate adverse event information in RCTs.
Trials. 21: 1028. doi.org/10.1186/s13063-020-04903-0

Authors

Rachel Phillips

Imperial College London, UK

r.phillips@imperial.ac.uk

Suzie Cro

Imperial College London, UK