---
title: "Maraca Plots - Frequently Asked Questions"
author: "Martin Karpefors, Stefano Borini, Monika Huhn"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Maraca Plots - Frequently Asked Questions}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(echo = TRUE, collapse = TRUE)
library(maraca)
```

## I get the warning "Removed 1 rows containing missing values (geom_point)." when plotting using density_plot_type scatter.

This happens because when using scatter, some points are jittered and may end up
visually outside of the plotting range, so they can't be displayed.
That warning informs you (in a cryptic way) of this fact. Given that the
jittering is randomised, sometimes you might get that warning, sometimes you
won't, even for the same input.

If you want to silence the warning, use suppressWarning() when you print
the plot for displaying.

## I want to add other information to the plot rather than win odds.

The `maraca` package can only display the win odds within the plot.
If the user wants to for example display the win ratio instead, they
need to calculate those themselves and then add them to the plot.

```{r fig.width = 7, fig.height = 6}
library(hce)

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 <- simHCE(n = 2500, TTE_A = Rates_A, TTE_P = Rates_P,
                  CM_A = -3, CM_P = -6, CSD_A = 16, CSD_P = 15, fixedfy = 3,
                  seed = 242424)

winRatio <- calcWINS(hce_dat)$WR1

plot <- plot(hce_dat, compute_win_odds = FALSE)
plot <-
  plot  +
  ggplot2::annotate(
    geom = "label",
    x = 0,
    y = Inf,
    label = paste(
      "Win ratio: ", round(winRatio[1,"WR"], 2),
      "\n95% CI: ", round(winRatio[1,"LCL1"], 2), " - ",
      round(winRatio[1,"UCL1"], 2), "\n",
      "p-value: ", format.pval(winRatio[1,"Pvalue1"], digits = 3, eps = 0.001),
      sep = ""
    ),
    hjust = 0, vjust = 1.4, size = 3
  )

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."))
```