Documentation request: Formulas on the website

[Gero1999]

I was wondering if it would be nice to include within the defining functions for a parameter an optional argument formula that expresses in LaTeX format the mathematical equation used for a calculation:

pk.calc.cmax <- function(conc, check=TRUE) {
  if (check) {
    assert_conc(conc = conc)
  }
  if (length(conc) == 0 | all(is.na(conc))) {
    NA
  } else {
    max(conc, na.rm=TRUE)
  }
}
# Add the column to the interval specification
add.interval.col("cmax",
                 FUN="pk.calc.cmax",
                 values=c(FALSE, TRUE),
                 unit_type="conc",
                 pretty_name="Cmax",
                 desc="Maximum observed concentration",
                 depends=NULL)
PKNCA.set.summary(
  name="cmax",
  description="geometric mean and geometric coefficient of variation",
  point=business.geomean,
  spread=business.geocv
)

it would be something like this:

pretty_formula <- "$$C_{\\max} = \\max_{i = 1,\\dots,n} C(t_i)$$"

and then be used to be render them to a PKNCA website page. That way we would have one webpage with automatically all the in-package parameters and their formulas.

We might probably want to do it anyway in aNCA, but I think it might make more sense to develop it directly here. How does this sound?

[billdenney]

I love it!

Yes, I think that it should be an argument to add.interval.col() with a default of NULL. The reason for the default NULL rather than being a required argument is that interval definitions like start do not need it, and all the variants could default to pointing to the main function rather than repeating the same formula many, many times.

What do you think about this as a format for the vignette where this would live:

Parameter	Formula	Other parameters using this formula
cmax	$$C_{\max} = \max_{i = 1,\dots,n} C(t_i)$$	<list of other parameters with the same FUN argument to add.interval.col()>
...	...	...

There is already a parameter selection vignette (that people don't often find). I think that it would make sense to create a new vignette that moves the current parameter table into it and adds this formula table, too.

[Gero1999]

Awesome! Yes I agree that this is hidden, I often forget it even exists because I never manage to find it. I would make it a whole different vignette.

And if you want we can keep the other columns as well, so it is all one big table instead of two

[billdenney]

I'm open to it being better as one table than two. Whatever seems to fit best.