Added updated documentation

tests/testthat/test_maraca.R

@@ -703,9 +703,9 @@ test_that("binaryEndpoints", {
   data <- data[data$AVAL0 != 0, ]
 
   column_names <- c(
-      outcome = "GROUP",
-      arm = "TRTP",
-      value = "AVAL0"
+    outcome = "GROUP",
+    arm = "TRTP",
+    value = "AVAL0"
   )
   step_outcomes <- c("Outcome I", "Outcome II",
                      "Outcome III", "Outcome IV")
@@ -845,7 +845,7 @@ test_that("winOddsPlot", {
   expect_equal(as.numeric(bar_p[bar_p$GROUP == "Outcome I" &
                                   bar_p$name == "Control wins", "value"]),
                sry_by_grp[sry_by_grp$GROUP == "Outcome I" &
-                          sry_by_grp$TRTP == "A", "LOSS"])
+                            sry_by_grp$TRTP == "A", "LOSS"])
 
   expect_equal(as.numeric(bar_p[bar_p$GROUP == "Overall" &
                                   bar_p$name == "Active wins", "value"]),
@@ -861,8 +861,8 @@ test_that("winOddsPlot", {
 
   expect_equal(forest_p[forest_p$GROUP == "Overall" &
                           forest_p$method == "win odds", "LCL"],
-                exp(log(win_odds_outcome$WO$WO) -
-                      qnorm(0.975) * win_odds_outcome$WO$SE))
+               exp(log(win_odds_outcome$WO$WO) -
+                     qnorm(0.975) * win_odds_outcome$WO$SE))
 
   output <- artifacts_path("winOddsPlot-without.pdf")
   expect_file_not_exists(output)

vignettes/faq.Rmd

@@ -63,4 +63,133 @@ plot <-
 plot
 ```
 
+## For my continuous outcome, lower values are better 
+
+In some cases, for the continuous outcome, lower values might be considered better
+than higher values. By default, the win odds are calculated assuming that higher
+values are better. In order to calculate the correct win odds, the user can set
+the `lowerBetter` parameter in the `maraca()` or `plot.hce()` function to `TRUE`.
+
+Additionally, it is possible to display the continuous outcome on a reverse scale
+using the parameter `trans = "reverse"` in the plotting functions.
+```{r fig.width = 7, fig.height = 6}
+Rates_A <- c(10, 15)
+Rates_P <- c(12, 15)
+dat <- simHCE(n = 2500, TTE_A = Rates_A, TTE_P = Rates_P,
+              CM_A = 6, CM_P = 10, CSD_A = 16, CSD_P = 15, fixedfy = 3, seed = 1)
+
+plot(dat, lowerBetter = TRUE, trans = "reverse")
+```
+
+## Outcome axis labels are overlapping
+
+Sometimes for some of the outcomes, only very few patients
+had an event. Since the x-axis range for each endpoint is based
+on the proportion of patients that had the event, this can lead
+to close x-axis ticks and overlapping labels.
+```{r fig.width = 7, fig.height = 6}
+data(hce_scenario_a, package = "maraca")
+data <- hce_scenario_a
+
+column_names <- c(
+    outcome = "GROUP",
+    arm = "TRTP",
+    value = "AVAL0"
+)
+step_outcomes <- c(
+  "Outcome I", "Outcome II", "Outcome III", "Outcome IV"
+)
+
+last_outcome <- "Continuous outcome"
+
+arm_levels = c(active = "Active", control = "Control")
+
+# We will only include a few patients with outcome III
+data2 <- data[data$GROUP == "Outcome II",]
+data3 <- data[data$GROUP == "Outcome III",]
+data <- rbind(data2[sample(1:nrow(data2),5),],
+              data3[sample(1:nrow(data3),5),],
+              data[!(data$GROUP %in% c("Outcome II","Outcome III")),])
+
+mar <- maraca(
+  data, step_outcomes, last_outcome, arm_levels, column_names, 
+  fixed_followup_days = 3*365,
+  compute_win_odds = TRUE
+)
+
+# Now the x-axis labels are overlapping
+plot(mar)
+```
+
+One potential workaround in this situation is to add a line break after or before
+one of the outcomes in order to space them further apart.
+```{r fig.width = 7, fig.height = 6}
+data[data$GROUP == "Outcome II","GROUP"] <- "Outcome II\n"
+step_outcomes <- c(
+  "Outcome I", "Outcome II\n", "Outcome III", "Outcome IV"
+)
+mar <- maraca(
+  data, step_outcomes, last_outcome, arm_levels, column_names, 
+  fixed_followup_days = 3*365,
+  compute_win_odds = TRUE
+)
+
+plot(mar)
+```
+
+
+## I get the error "outcome [XY] is not present in column"
+
+The maraca package expects that for every outcome specified in the
+`step_outcomes` parameter, at least one patient has had that event.
+```{r error = TRUE}
+data(hce_scenario_a, package = "maraca")
+data <- hce_scenario_a
+
+column_names <- c(
+    outcome = "GROUP",
+    arm = "TRTP",
+    value = "AVAL0"
+)
+step_outcomes <- c(
+  "Outcome I", "Outcome II", "Outcome III", "Outcome IV"
+)
+
+last_outcome <- "Continuous outcome"
+
+arm_levels = c(active = "Active", control = "Control")
+
+# Let's pretend no one in the study had outcome II
+data <- data[data$GROUP != "Outcome II", ]
+
+# Now we will get an error
+mar <- maraca(
+  data, step_outcomes, last_outcome, arm_levels, column_names, 
+  fixed_followup_days = 3*365,
+  compute_win_odds = TRUE
+)
+```
+
+If the outcome is not part of the data at all, it cannot be displayed
+as part of the plot. The outcome has to be removed from the 
+`step_outcomes` parameter. Additionally, the user can for example
+add a footnote explaining why the outcome is not included in the
+plot.
+
+```{r fig.width = 7, fig.height = 6}
+step_outcomes <- c(
+  "Outcome I", "Outcome III", "Outcome IV"
+)
+
+# Now we will get an error
+mar <- maraca(
+  data, step_outcomes, last_outcome, arm_levels, column_names, 
+  fixed_followup_days = 3*365,
+  compute_win_odds = TRUE
+)
+
+plot(mar) +
+  labs(caption = paste("No patient experienced Outcome II",
+                       "and it is therefore not included in the graph."))
+```
 

vignettes/maraca.Rmd

@@ -159,6 +159,26 @@ Note that some styling settings are already specified in the default plot versio
 themes for the convenience of the user, including a version without any preset stylings. For more details, please take a look at
 the vignette [Maraca Plots - Themes and Styling](themes.html).
 
+The user can also use transformations on the x-axis for the
+continuous outcomes in order to make the plot more readable,
+such as log-transforming it.
+One such transformation is to reverse the x-axis scale by
+setting `trans = "reverse"`. This
+could be of interest when lower values of the continuous outcome
+are better than higher ones. In such a case, one also has to make
+sure that the win odds are calculated correctly by 
+including the parameter `lowerBetter = TRUE` in the `maraca()` or
+`plot.hce()` function.
+```{r fig.width = 7, fig.height = 6}
+Rates_A <- c(1.72, 1.74, 0.58, 1.5, 1)
+Rates_P <- c(2.47, 2.24, 2.9, 4, 6)
+hce_dat <- hce::simHCE(n = 2500, TTE_A = Rates_A, TTE_P = Rates_P,
+              CM_A = -6, CM_P = 3, CSD_A = 15, CSD_P = 16, fixedfy = 3,
+              seed = 31337)
+plot(hce_dat, compute_win_odds = TRUE, lowerBetter = TRUE,
+     trans = "reverse")
+```
+
 # References
 
 Martin Karpefors, Daniel Lindholm and Samvel B. Gasparyan, "The maraca plot -- a novel visualization of hierarchical composite endpoints", Clinical Trials (2022).