Specify canonical units (time, amount, and volume) for outputs

[john-harrold]

I think it would be useful to be able to specify output units more generally such as: have all volumes in mL, all time in days, and all amounts in mg. Then have the parameters automatically converted into those units (e.g. CL would be mL/day or ml/day/kg, half-life would be in day, etc).

[billdenney]

This is a good idea. My thoughts for this take two different forms, and I think that both of these would be helpful to implement. Please let me know your thoughts. (Do these seem like the right fit, is more needed?)

The two ways that users may want to specify outputs are:

1. My inputs used unit system X, and I want unit system Y for my outputs.
2. For all outputs that are of type X, I want these units.

To make these clearer, I'll give two examples:

1. Pretend that my input units were these

PKNCA::pknca_units_table(concu = "ng/mL", doseu = "mg", timeu = "hr", amountu = "mg")

For this, the idea would be to allow the user to change one or more types of input units to a different type of output units. For example, the user could say "I wish that my input were concentration of 'ug/mL' and time were 'days'."

For that, I would introduce 4 new parameters to pknca_units_table():

• out_concu
• out_doseu
• out_timeu
• out_amountu

Those would automatically generate the conversions between inputs and outputs as though the inputs were given as the outputs

2: I want units like these:

For what is likely a common unit input of

PKNCA::pknca_units_table(concu = "ng/mL", doseu = "mg", timeu = "hr", amountu = "mg")

you get units for Vss of mg/(ng/mL). That's not usually what people will want. They will usually want either "L" or "mL/kg" with that input.

As I started to write this as a set of additional inputs for each type of output, there are 11 (theoretically up to 16) new input arguments. That's too much, I think. The full set of unit classes that PKNCA supports is here:

pknca/R/001-add.interval.col.R

Lines 110 to 119 in 46a7091

	choices=c(
	"unitless", "fraction", "%", "count",
	"time", "inverse_time",
	"amount",
	"conc", "conc_dosenorm",
	"volume",
	"auc", "aumc",
	"auc_dosenorm", "aumc_dosenorm",
	"clearance", "renal_clearance"
	)

I'm trying to think of a good input method so that, for each type of unit, the user can specify the type of output that they would want. This is technically possible already with the conversions argument (which allows full control, so I want to keep it), but that argument is not the most user-friendly.

My initial brainstorm would be to have one more argument (that I think I'd call out_paramu; I'm open to suggestions). That argument would be a named list with preferred conversions. The conversions would be tested in order, and the first one that works would be chosen. If none work, then there would be a message (e.g. "no volume unit conversions worked, using the default"), and it would continue.

For volume here, I'm thinking something like c("L", "mL/kg"). That would tell PKNCA to try to convert volume output units first to "L" and second to "mL/kg". For clearance, the default would be c("L/{timeu}", "mL/kg/{timeu}"). And {timeu} would be automatically replaced by the out_timeu or timeu (in that order)

What if both are given

One other challenge here is what to do if both unit-modifiers are given. I think that the default would be first choice to use the second of the options above and the second choice would be to use the first of the options above.

Thoughts?

[john-harrold]

I think this sounds good. However I'm more likely to use option 1 only :). But I can see other folks would find option 2 quite useful. In the instance when both are specified, I think the logic you've laid out is reasonable. I can see it being triggered with some of the more esoteric unit requests.

[billdenney]

Option 1 is now handled. (Edit: it now does work with conversions.)