Feature suggestion: blq_trans for showing measurements below the LLOQ

[billdenney]

This is related to kestrel99/pmxTools#23 (more accurately, it replaces that). It is also related to #21.

Describe the feature Plotting values below the LLOQ with ggplot does not always clearly represent the data. A specific issue relates to the fact that zeros on the log scale are on the axis and difficult to observe.

The features are described with the example below:

# Loading the local copy of the code from the PR
source("c:/git/Not_my_repositories/xgxr/R/blq_trans.R")
library(tidyverse)

# First, a normal plot
ggplot(data=data.frame(x=1:10, y=1:10), aes(x=x, y=y)) +
  geom_point()

# Data are censored to 0.5*LLOQ, and the axis text shows "<[LLOQ value]" rather
# than a number
ggplot(data=data.frame(x=1:10, y=1:10), aes(x=x, y=y)) +
  geom_point() +
  scale_x_continuous(trans=blq_trans(lloq=3))

# If you prefer a different location than 0.5*LLOQ, you can provide that with
# the multiplier
ggplot(data=data.frame(x=1:10, y=1:10), aes(x=x, y=y)) +
  geom_point() +
  scale_x_continuous(trans=blq_trans(lloq=3, multiplier=0.9))

# If you prefer different text than "<[LLOQ value]", you can provide that with
# the lloq_text argument
ggplot(data=data.frame(x=1:10, y=1:10), aes(x=x, y=y)) +
  geom_point() +
  scale_x_continuous(trans=blq_trans(lloq=3, multiplier=0.9, lloq_text="BLQ plotting is handy"))

# It can work for both axes simultaneously
ggplot(data=data.frame(x=1:10, y=1:10), aes(x=x, y=y)) +
  geom_point() +
  scale_x_continuous(trans=blq_trans(lloq=3)) +
  scale_y_continuous(trans=blq_trans(lloq=3))

# Log scale works, too (with blq_log_trans)
ggplot(data=data.frame(x=1:10, y=1:10), aes(x=x, y=y)) +
  geom_point() +
  scale_x_continuous(trans=blq_log_trans(lloq=3))

^{Created on 2021-07-01 by the reprex package (v2.0.0)}

[billdenney]

For consideration when thinking about this and the related PR:

• If the LLOQ is not provided, it will be estimated from the data.
• This is a transformation function. It can change point values and axis text, but it can't change aesthetics (e.g. shape or color). That is due to the design of ggplot.

[iamstein]

Some thoughts, if we go ahead to add it

• In the first example above, should the point at x = 3 also be classified as BLQ?
• I'd propose adding some example code to the vignette and the functions showing how blq_trans() and log_blq_trans() works.

[billdenney]

• In the first example above, should the point at x = 3 also be classified as BLQ?

I would suggest making that an option. In the data I tend to receive, if a value is equal to the LLOQ, it is considered measured and values <LLOQ are considered censored. Both seem likely to happen at some point, so control makes sense.

• I'd propose adding some example code to the vignette and the functions showing how blq_trans() and log_blq_trans() works.

Definitely.

[billdenney]

From the team meeting discussion:

• Add an estimate_if_missing argument to control if the LLOQ is estimated or if an error is given for no LLOQ.
• Move the label for "<LLOQ" to the point where the values are (e.g. 0.5*lloq) instead of the LLOQ itself.

[iamstein]

We do not currently plan to implement this idea, but we may at a later date. Thanks for the suggestion!