Clarify and handle missing values in the outcome variable `y`

[hoxo-m]

Background

create_ship() takes an outcome variable via y = ... and uses it to compute rate metrics. However, the behavior is currently unclear when the outcome variable contains missing values (NA).

This matters because y is used to compute both the numerator and the rate metric. If NA values are not handled explicitly, they can propagate to the overall score, subgroup rates, and contribution values.

Current behavior

Currently, missing values in y appear to be left unchanged during preprocessing.

The internal calculations use expressions such as:

mean(.outcome)
sum(.outcome)

without na.rm = TRUE. Therefore, if y contains NA, the resulting values may become NA.

For example, this can affect:

• the overall rate for each group
• subgroup-level counts such as x1 and x2
• subgroup-level rates such as rate1 and rate2
• contribution values returned by table()
• plots generated by plot() and plot_flip()

Minimal example

library(TheseusPlot)

data1 <- data.frame(
  segment = c("A", "A", "B", "B"),
  y = c(1, NA, 0, 1)
)

data2 <- data.frame(
  segment = c("A", "A", "B", "B"),
  y = c(1, 0, NA, 1)
)

ship <- create_ship(data1, data2, y = y, labels = c("Group 1", "Group 2"))

ship$table(segment)

Expected behavior

We should explicitly define how missing values in the outcome variable should be handled.

Possible options include:

1. Raise an informative error when y contains NA.
2. Drop rows with NA in y from both the numerator and denominator, possibly with a warning.
3. Add an argument such as na.rm or missing_y to allow users to choose the behavior.

My current preference is option 1: raise an informative error by default. This avoids silently changing denominators and makes users handle missing outcome values intentionally before calling create_ship().