Skip to content

Commit 814d747

Browse files
Monika-HMonika-H
committed
Added updated documentation
1 parent 6d5a5de commit 814d747

File tree

3 files changed

+155
-6
lines changed

3 files changed

+155
-6
lines changed

‎tests/testthat/test_maraca.R

+6-6
Original file line numberDiff line numberDiff line change
@@ -703,9 +703,9 @@ test_that("binaryEndpoints", {
703703
data <- data[data$AVAL0 != 0, ]
704704

705705
column_names <- c(
706-
outcome = "GROUP",
707-
arm = "TRTP",
708-
value = "AVAL0"
706+
outcome = "GROUP",
707+
arm = "TRTP",
708+
value = "AVAL0"
709709
)
710710
step_outcomes <- c("Outcome I", "Outcome II",
711711
"Outcome III", "Outcome IV")
@@ -845,7 +845,7 @@ test_that("winOddsPlot", {
845845
expect_equal(as.numeric(bar_p[bar_p$GROUP == "Outcome I" &
846846
bar_p$name == "Control wins", "value"]),
847847
sry_by_grp[sry_by_grp$GROUP == "Outcome I" &
848-
sry_by_grp$TRTP == "A", "LOSS"])
848+
sry_by_grp$TRTP == "A", "LOSS"])
849849

850850
expect_equal(as.numeric(bar_p[bar_p$GROUP == "Overall" &
851851
bar_p$name == "Active wins", "value"]),
@@ -861,8 +861,8 @@ test_that("winOddsPlot", {
861861

862862
expect_equal(forest_p[forest_p$GROUP == "Overall" &
863863
forest_p$method == "win odds", "LCL"],
864-
exp(log(win_odds_outcome$WO$WO) -
865-
qnorm(0.975) * win_odds_outcome$WO$SE))
864+
exp(log(win_odds_outcome$WO$WO) -
865+
qnorm(0.975) * win_odds_outcome$WO$SE))
866866

867867
output <- artifacts_path("winOddsPlot-without.pdf")
868868
expect_file_not_exists(output)

‎vignettes/faq.Rmd

+129
Original file line numberDiff line numberDiff line change
@@ -63,4 +63,133 @@ plot <-
6363
plot
6464
```
6565

66+
## For my continuous outcome, lower values are better
67+
68+
In some cases, for the continuous outcome, lower values might be considered better
69+
than higher values. By default, the win odds are calculated assuming that higher
70+
values are better. In order to calculate the correct win odds, the user can set
71+
the `lowerBetter` parameter in the `maraca()` or `plot.hce()` function to `TRUE`.
72+
73+
Additionally, it is possible to display the continuous outcome on a reverse scale
74+
using the parameter `trans = "reverse"` in the plotting functions.
75+
```{r fig.width = 7, fig.height = 6}
76+
Rates_A <- c(10, 15)
77+
Rates_P <- c(12, 15)
78+
dat <- simHCE(n = 2500, TTE_A = Rates_A, TTE_P = Rates_P,
79+
CM_A = 6, CM_P = 10, CSD_A = 16, CSD_P = 15, fixedfy = 3, seed = 1)
80+
81+
plot(dat, lowerBetter = TRUE, trans = "reverse")
82+
```
83+
84+
## Outcome axis labels are overlapping
85+
86+
Sometimes for some of the outcomes, only very few patients
87+
had an event. Since the x-axis range for each endpoint is based
88+
on the proportion of patients that had the event, this can lead
89+
to close x-axis ticks and overlapping labels.
90+
```{r fig.width = 7, fig.height = 6}
91+
data(hce_scenario_a, package = "maraca")
92+
data <- hce_scenario_a
93+
94+
column_names <- c(
95+
outcome = "GROUP",
96+
arm = "TRTP",
97+
value = "AVAL0"
98+
)
99+
step_outcomes <- c(
100+
"Outcome I", "Outcome II", "Outcome III", "Outcome IV"
101+
)
102+
103+
last_outcome <- "Continuous outcome"
104+
105+
arm_levels = c(active = "Active", control = "Control")
106+
107+
# We will only include a few patients with outcome III
108+
data2 <- data[data$GROUP == "Outcome II",]
109+
data3 <- data[data$GROUP == "Outcome III",]
110+
data <- rbind(data2[sample(1:nrow(data2),5),],
111+
data3[sample(1:nrow(data3),5),],
112+
data[!(data$GROUP %in% c("Outcome II","Outcome III")),])
113+
114+
mar <- maraca(
115+
data, step_outcomes, last_outcome, arm_levels, column_names,
116+
fixed_followup_days = 3*365,
117+
compute_win_odds = TRUE
118+
)
119+
120+
# Now the x-axis labels are overlapping
121+
plot(mar)
122+
```
123+
124+
One potential workaround in this situation is to add a line break after or before
125+
one of the outcomes in order to space them further apart.
126+
```{r fig.width = 7, fig.height = 6}
127+
data[data$GROUP == "Outcome II","GROUP"] <- "Outcome II\n"
128+
step_outcomes <- c(
129+
"Outcome I", "Outcome II\n", "Outcome III", "Outcome IV"
130+
)
131+
mar <- maraca(
132+
data, step_outcomes, last_outcome, arm_levels, column_names,
133+
fixed_followup_days = 3*365,
134+
compute_win_odds = TRUE
135+
)
136+
137+
plot(mar)
138+
```
139+
140+
141+
## I get the error "outcome [XY] is not present in column"
142+
143+
The maraca package expects that for every outcome specified in the
144+
`step_outcomes` parameter, at least one patient has had that event.
145+
```{r error = TRUE}
146+
data(hce_scenario_a, package = "maraca")
147+
data <- hce_scenario_a
148+
149+
column_names <- c(
150+
outcome = "GROUP",
151+
arm = "TRTP",
152+
value = "AVAL0"
153+
)
154+
step_outcomes <- c(
155+
"Outcome I", "Outcome II", "Outcome III", "Outcome IV"
156+
)
157+
158+
last_outcome <- "Continuous outcome"
159+
160+
arm_levels = c(active = "Active", control = "Control")
161+
162+
# Let's pretend no one in the study had outcome II
163+
data <- data[data$GROUP != "Outcome II", ]
164+
165+
# Now we will get an error
166+
mar <- maraca(
167+
data, step_outcomes, last_outcome, arm_levels, column_names,
168+
fixed_followup_days = 3*365,
169+
compute_win_odds = TRUE
170+
)
171+
```
172+
173+
If the outcome is not part of the data at all, it cannot be displayed
174+
as part of the plot. The outcome has to be removed from the
175+
`step_outcomes` parameter. Additionally, the user can for example
176+
add a footnote explaining why the outcome is not included in the
177+
plot.
178+
179+
```{r fig.width = 7, fig.height = 6}
180+
step_outcomes <- c(
181+
"Outcome I", "Outcome III", "Outcome IV"
182+
)
183+
184+
# Now we will get an error
185+
mar <- maraca(
186+
data, step_outcomes, last_outcome, arm_levels, column_names,
187+
fixed_followup_days = 3*365,
188+
compute_win_odds = TRUE
189+
)
190+
191+
plot(mar) +
192+
labs(caption = paste("No patient experienced Outcome II",
193+
"and it is therefore not included in the graph."))
194+
```
66195

‎vignettes/maraca.Rmd

+20
Original file line numberDiff line numberDiff line change
@@ -159,6 +159,26 @@ Note that some styling settings are already specified in the default plot versio
159159
themes for the convenience of the user, including a version without any preset stylings. For more details, please take a look at
160160
the vignette [Maraca Plots - Themes and Styling](themes.html).
161161

162+
The user can also use transformations on the x-axis for the
163+
continuous outcomes in order to make the plot more readable,
164+
such as log-transforming it.
165+
One such transformation is to reverse the x-axis scale by
166+
setting `trans = "reverse"`. This
167+
could be of interest when lower values of the continuous outcome
168+
are better than higher ones. In such a case, one also has to make
169+
sure that the win odds are calculated correctly by
170+
including the parameter `lowerBetter = TRUE` in the `maraca()` or
171+
`plot.hce()` function.
172+
```{r fig.width = 7, fig.height = 6}
173+
Rates_A <- c(1.72, 1.74, 0.58, 1.5, 1)
174+
Rates_P <- c(2.47, 2.24, 2.9, 4, 6)
175+
hce_dat <- hce::simHCE(n = 2500, TTE_A = Rates_A, TTE_P = Rates_P,
176+
CM_A = -6, CM_P = 3, CSD_A = 15, CSD_P = 16, fixedfy = 3,
177+
seed = 31337)
178+
plot(hce_dat, compute_win_odds = TRUE, lowerBetter = TRUE,
179+
trans = "reverse")
180+
```
181+
162182
# References
163183

164184
Martin Karpefors, Daniel Lindholm and Samvel B. Gasparyan, "The maraca plot -- a novel visualization of hierarchical composite endpoints", Clinical Trials (2022).

0 commit comments

Comments
 (0)