Cleveland dot chart: one summary point per group, ordered by value, with a confidence interval and a reference line. Wraps ggstatsplot::ggdotplotstats and ggstatsplot::grouped_ggdotplotstats.
Usage
jjdotchart(
data,
dep = NULL,
group = NULL,
grvar = NULL,
testvalue = 0,
typestatistics = "parametric",
conflevel = 0.95,
k = 2,
resultssubtitle = TRUE,
showSummaryTable = TRUE,
centralityplotting = FALSE,
centralitytype = "parametric",
bfmessage = FALSE,
originaltheme = FALSE,
mytitle = "",
xtitle = "",
ytitle = "",
plotwidth = 650,
plotheight = 450
)Arguments
- data
The data as a data frame.
- dep
The continuous variable to summarise. Each group is reduced to one point on the chart - its mean, median, trimmed mean or MAP estimate, whichever matches the Statistical Test selected below.
- group
The grouping variable. Every level becomes one point on the chart, and the number of levels is the sample size of the statistical test.
- grvar
Optional variable producing a separate dot chart for each of its levels.
- testvalue
The value the k group summaries are tested against. Choose something clinically meaningful on the scale of your measurement - an upper limit of normal, a target turnaround time, a published benchmark. The default of 0 is rarely the right choice: for a measurement that is not centred near zero it makes the standardised effect enormous, and the statistics package then fails to compute a confidence interval for the effect size and returns NO statistics at all. The analysis detects this and says so rather than showing an empty result.
- typestatistics
The one-sample test comparing the k group summaries to the Reference Value. This also decides WHICH summary is plotted for each group - mean, median, 20 percent trimmed mean or MAP estimate respectively
so changing it moves the points, not just the caption.
- conflevel
Confidence level for the intervals, 0.95 giving 95 percent intervals.
- k
Number of decimal places for the reported statistics.
- resultssubtitle
Show the test result as a subtitle. Defaults to TRUE here, unlike the sibling plot analyses: the comparison against the Reference Value is the whole point of this chart, so hiding it leaves a figure whose title makes a claim nothing on the plot supports.
- showSummaryTable
Show the per-group table behind the chart - the number of observations, the plotted summary value, and its spread. This is what makes the aggregation auditable: it states how many observations each single plotted point represents. The summary column is labelled with the statistic actually used, which changes with the Statistical Test.
- centralityplotting
Draw a SECOND vertical line at the centre of the k plotted summaries - i.e. the average of the group averages. This is not the Reference Value; the Reference Value line is always drawn and is labelled. Off by default deliberately. The statistics package draws this line by default and draws NO line at the reference value, so the only vertical line on an unmodified figure sits at the centre of the data while the user believes it marks the threshold they typed in (measured: identical line position for reference values of 0, 12 and 999). This analysis inverts that - the reference line is always present, and this optional second line is drawn in a different style and named in the caption.
- centralitytype
Which centre to use for the optional second line, when 'Also mark the centre of the plotted points' is ticked. It affects that line ONLY - the plotted points always follow the Statistical Test. Leave it matching your Statistical Test unless you have a specific reason.
- bfmessage
Show the Bayes factor caption when the Bayesian test is selected.
- originaltheme
Use the original ggstatsplot theme rather than jamovi's default.
- mytitle
Main title for the plot. Leave blank for no title.
- xtitle
Label for the horizontal axis, which carries the measurement values. Leave blank to use the variable name.
- ytitle
Label for the vertical axis, which carries the group labels. Leave blank to use the variable name.
- plotwidth
Width of the plot in pixels.
- plotheight
Height of the plot in pixels. Increase it when there are many groups, since each one needs a labelled row.
Value
A results object containing:
results$todo | a html | ||||
results$notices | a html | ||||
results$summary | a table | ||||
results$plot2 | an image | ||||
results$plot | an image |
Tables can be converted to data frames with asDF or as.data.frame. For example:
results$summary$asDF
as.data.frame(results$summary)
Details
IMPORTANT - what is tested. Every observation in a group is collapsed to a SINGLE summary value, and the test is a ONE-SAMPLE test of those k summary values against your Reference Value. The sample size of the test is therefore the NUMBER OF GROUPS, not the number of patients: 120 patients in 3 groups gives a one-sample t-test with n = 3 and 2 degrees of freedom. It answers "are the group summaries, taken together, different from this value?" - NOT "do these groups differ from each other".
Which summary is plotted follows the Statistical Test you choose, and the test then runs on those same values: parametric plots the group MEANS, nonparametric the MEDIANS, robust the 20 percent TRIMMED MEANS, Bayesian the MAP estimates. Verified on skewed data where they differ sharply (mean 33.77 vs median 9.75 for the same group), so switching test type genuinely changes the picture, not just the caption.
To compare groups WITH EACH OTHER using every observation, use "Box-Violin Plots to Compare Between Groups" or "Horizontal Box-Violin Comparison" instead.
Best suited to many labels each contributing one meaningful summary - mean turnaround time across 20 laboratories, median biomarker by centre - which is what a Cleveland dot plot is designed for. With only two or three groups the test has 1-2 degrees of freedom and is of little value, even though the chart itself is still a fair picture of the group averages.