Requirements

The starting point to writing a new NCA parameter is writing the function that calculates the parameter value. The function can be passed any of the following arguments. The arguments must be named as described below:

• conc is the numeric vector of plasma concentrations for an interval for a single group (usually a single analyte for a single subject in a single study).
• time is the numeric vector of the time for plasma concentration measurements.
• duration.conc is the duration of a concentration measurement (usually for urine or fecal measurements)
• dose is the numeric vector of dose amounts for an interval for a single group. NOTE: This is a vector and not always a scalar. If your function expects a scalar, you should usually take the sum of the dose argument.
• time.dose is the numeric vector of time for the doses.
• duration.dose is the duration of a dose (usually for intravenous infusions)
• start and end are the scalar numbers for the start and end time of the current interval. NOTE: end may be Inf (infinity).
• options are the PKNCA options used for the current calculation usually as defined by the PKNCA.options function (though these options may be over-ridden by the options argument to the PKNCAdata function.
• Or, any NCA parameters by name (as given by names(get.interval.cols())).

The function should return either a scalar which is the value for the parameter (usually the case) or a data.frame with parameters named for each parameter calculated. For an example of returning a data.frame, see the half.life function.

The return value may have an attribute of exclude (set by attr(return_value, "exclude") <- "reason"). If the exclude attribute is set to a character string, then that string will be included in the exclude column for results. If any of the input parameters have an exclude attribute set, then those are also added to the exclude column. The exception to the setting of the exclude column is if the exclude attribute is "DO NOT EXCLUDE", then the exclude column is set to NA_character_.

Best Practices

• Use the function assert_conc_time if the function takes either conc or time as an input.
• Make sure that you check for missing values (NA) in your inputs.
• Don’t recalculate other NCA parameters within your function unless you absolutely must. Take the NCA parameter as an input. That way, PKNCA will track the calculation dependencies.
• For consistency with the rest of PKNCA, start the function name with “pk.calc” (like “pk.calc.cmax”).

Passing a Constant with formalsmap

A formalsmap value is normally the name of an NCA parameter or of one of the data inputs ("conc", "time", "dose", and the rest listed in help("add.interval.col")). Wrapping the value in I() passes it to the function unchanged instead of looking it up:

formalsmap = list(auc="aucall", auc.type=I("AUCall"))

Use this when one function serves several parameters and an argument selects which variant to calculate. pk.calc.auciv is shared by all six IV AUC parameters, and each registration names its own auc.type:

add.interval.col(
  name = "aucivlast",
  FUN = "pk.calc.auciv",
  unit_type = "auc",
  pretty_name = "AUClast (IV dosing)",
  depends = c("auclast", "c0"),
  desc = "AUClast, IV back-extrap C0",
  formalsmap = list(auc="auclast", auc.type=I("AUClast"), lambda.z=NULL, clast=NULL)
)

Without I(), "AUCall" would be looked up as a parameter name, not found, and the argument would silently keep its default.

Two related points:

• A constant is not a calculation dependency, so it does not appear in get.parameter.deps(recursive=TRUE) and does not affect whether PKNCA reports the parameter as needing dose or volume information.
• Mapping an argument to NULL (as with lambda.z and clast above) drops it from the call so that it keeps its default. Do this for any argument whose name matches an NCA parameter that this parameter does not use. An argument named lambda.z that is left out of the formalsmap is filled from the calculated lambda.z when one exists, and otherwise from the interval column of the same name, which is the TRUE/FALSE requesting the parameter rather than a value.

Parameters That Need Another Interval

A few parameters cannot be calculated from one interval of one profile. Renal clearance divides an amount excreted into a urine collection by the plasma AUC over the same times, and bioavailability compares two administrations. Wrapping a formalsmap value in pknca_ref says that the argument takes its value from the reference interval – the one named by the <parameter>_ref column of the interval specification – instead of from the interval being calculated:

add.interval.col("clr.last",
                 FUN="pk.calc.clr",
                 values=c(FALSE, TRUE),
                 unit_type="renal_clearance",
                 pretty_name="Renal clearance (based on AUClast)",
                 formalsmap=list(auc=pknca_ref("auclast")),
                 depends="ae",
                 desc="Renal clearance, AUClast",
                 selection = list(secondary = TRUE))

A pknca_ref anywhere in the formalsmap makes the parameter secondary, whether or not selection says so. pknca_parameter_table reports which parameters are secondary, and the vignette “Secondary Parameters” (vignette("v09-secondary-parameters", package="PKNCA")) covers requesting and linking them.

A secondary parameter is calculated after every interval has been calculated, from the results rather than from the concentrations, so its function may take only NCA parameter values as inputs. That imposes two requirements, which add.interval.col does not check when the parameter is registered (the parameters it names may not be registered yet) but which are checked, with an error naming the parameter, the first time it is calculated:

• Every formal of the function other than ... must be covered: either it is named in the formalsmap, or it is itself the name of a registered NCA parameter and is filled from the interval being calculated. A formal that is neither – conc, time, options, or a name of your own – cannot be filled, because the data and the options are no longer at hand. I() constants and NULL mappings work as they do for any parameter, since neither needs a value looked up.
• Every argument taken from the interval being calculated must be listed in depends, so that it is calculated there before the secondary calculation reads it. In the registration above, ae is a formal of pk.calc.clr named after a parameter, so it is filled from the interval calculating clr.last and appears in depends. auc comes from the reference interval and does not.

Exclusions cross the link with no help from the function. As for any parameter, the exclude reasons of all of the inputs – from either interval – are joined with "; ", the exclude attribute the function set on its own return value is added to them, and "DO NOT EXCLUDE" on the return value clears all of them. An excluded plasma AUC therefore cannot quietly become a reported renal clearance.

Units are the one thing a new secondary parameter does not get for free. Where units are given per group, the two intervals can report theirs differently, and pknca_units_table composes the units of pk.calc.clr, pk.calc.ratio, and pk.calc.f from both sides for that reason. A parameter built on a calculation function of your own is given the units of its unit_type under its own interval’s group, as any primary parameter is; supply a units table to PKNCAdata if that is not what its two sides mean.