Title: | Perform Pharmacokinetic Non-Compartmental Analysis |
---|---|
Description: | Compute standard Non-Compartmental Analysis (NCA) parameters for typical pharmacokinetic analyses and summarize them. |
Authors: | Bill Denney [aut, cre] , Clare Buckeridge [aut], Sridhar Duvvuri [ctb] |
Maintainer: | Bill Denney <[email protected]> |
License: | AGPL-3 |
Version: | 0.11.0.9000 |
Built: | 2024-12-13 19:24:03 UTC |
Source: | https://github.com/billdenney/pknca |
Add columns for calculations within PKNCA intervals
add.interval.col( name, FUN, values = c(FALSE, TRUE), unit_type, pretty_name, depends = NULL, desc = "", sparse = FALSE, formalsmap = list(), datatype = c("interval", "individual", "population") )
add.interval.col( name, FUN, values = c(FALSE, TRUE), unit_type, pretty_name, depends = NULL, desc = "", sparse = FALSE, formalsmap = list(), datatype = c("interval", "individual", "population") )
name |
The column name as a character string |
FUN |
The function to run (as a character string) or |
values |
Valid values for the column |
unit_type |
The type of units to use for assigning and converting units. |
pretty_name |
The name of the parameter to use for printing in summary tables with units. (If an analysis does not include units, then the normal name is used.) |
depends |
Character vector of columns that must be run before this column. |
desc |
A human-readable description of the parameter (<=40 characters to comply with SDTM) |
sparse |
Is the calculation for sparse PK? |
formalsmap |
A named list mapping parameter names in the function call
to NCA parameter names. See the details for information on use of
|
datatype |
The type of data used for the calculation |
The formalsmap
argument enables mapping some alternate formal
argument names to parameters. It is used to generalize functions that may
use multiple similar arguments (such as the variants of mean residence time).
The names of the list should correspond to function formal parameter names
and the values should be one of the following:
For the current interval:
The value of the parameter calculated for the current interval.
Concentration measurements for the current interval.
Times associated with concentration measurements for the current interval (values start at 0 at the beginning of the current interval).
Volume associated with concentration measurements for the current interval (typically applies for excretion parameters like urine).
Durations associated with concentration measurements for the current interval.
Dose amounts assocuated with the current interval.
Time of dose start associated with the current interval (values start at 0 at the beginning of the current interval).
Duration of dose (typically infusion duration) for doses in the current interval.
Route of dosing for the current interval.
Time of interval start.
Time of interval end.
PKNCA.options governing calculations.
For the current group:
Concentration measurements for the current group.
Times associated with concentration measurements for the current group (values start at 0 at the beginning of the current interval).
Volume associated with concentration measurements for the current interval (typically applies for excretion parameters like urine).
Durations assocuated with concentration measurements for the current group.
Dose amounts assocuated with the current group.
Time of dose start associated with the current group (values start at 0 at the beginning of the current interval).
Duration of dose (typically infusion duration) for doses in the current group.
Route of dosing for the current group.
NULL (Calling this function has a side effect of changing the available intervals for calculations)
Other Interval specifications:
check.interval.deps()
,
check.interval.specification()
,
choose.auc.intervals()
,
get.interval.cols()
,
get.parameter.deps()
## Not run: add.interval.col("cmax", FUN="pk.calc.cmax", values=c(FALSE, TRUE), unit_type="conc", pretty_name="Cmax", desc="Maximum observed concentration") add.interval.col("cmax.dn", FUN="pk.calc.dn", values=c(FALSE, TRUE), unit_type="conc_dosenorm", pretty_name="Cmax (dose-normalized)", desc="Maximum observed concentration, dose normalized", formalsmap=list(parameter="cmax"), depends="cmax") ## End(Not run)
## Not run: add.interval.col("cmax", FUN="pk.calc.cmax", values=c(FALSE, TRUE), unit_type="conc", pretty_name="Cmax", desc="Maximum observed concentration") add.interval.col("cmax.dn", FUN="pk.calc.dn", values=c(FALSE, TRUE), unit_type="conc_dosenorm", pretty_name="Cmax (dose-normalized)", desc="Maximum observed concentration, dose normalized", formalsmap=list(parameter="cmax"), depends="cmax") ## End(Not run)
Add a hash and associated information to enable checking object provenance.
addProvenance(object, replace = FALSE)
addProvenance(object, replace = FALSE)
object |
The object to add provenance |
replace |
Replace provenance if the object already has a provenance
attribute. (If the object already has provenance and |
The object with provenance as an added item
Calculate the adjusted r-squared value
adj.r.squared(r.sq, n)
adj.r.squared(r.sq, n)
r.sq |
The r-squared value |
n |
The number of points |
The numeric adjusted r-squared value
Determine if there are any sparse or dense calculations requested within an interval
any_sparse_dense_in_interval(interval, sparse)
any_sparse_dense_in_interval(interval, sparse)
interval |
An interval specification |
sparse |
Are the concentration-time data sparse PK (commonly used in small nonclinical species or with terminal or difficult sampling) or dense PK (commonly used in clinical studies or larger nonclinical species)? |
A logical value indicating if the interval requests any sparse (if
sparse=TRUE
) or dense (if sparse=FALSE
) calculations.
Convert an object into a PKNCAconc object
as_PKNCAconc(x, ...) as_PKNCAdose(x, ...) as_PKNCAdata(x, ...) as_PKNCAresults(x, ...)
as_PKNCAconc(x, ...) as_PKNCAdose(x, ...) as_PKNCAdata(x, ...) as_PKNCAresults(x, ...)
x |
The object to convert |
... |
Passed to subsequent methods |
A converted object
as_PKNCAdose()
: Convert an object into a PKNCAdose object
as_PKNCAdata()
: Convert an object into a PKNCAdata object
as_PKNCAresults()
: Convert an object into a PKNCAresults object
Generate a sparse_pk object
as_sparse_pk(conc, time, subject)
as_sparse_pk(conc, time, subject)
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
subject |
Subject identifiers (may be any class; may not be null) |
A sparse_pk object which is a list of lists. The inner lists have elements named: "time", The time of measurement; "conc", The concentration measured; "subject", The subject identifiers. The object will usually be modified by future functions to add more named elements to the inner list.
Other Sparse Methods:
pk.calc.sparse_auc()
,
sparse_auc_weight_linear()
,
sparse_mean()
Extract the parameter results from a PKNCAresults and return them as a data.frame.
## S3 method for class 'PKNCAresults' as.data.frame( x, ..., out_format = c("long", "wide"), filter_requested = FALSE, filter_excluded = FALSE, out.format = deprecated() )
## S3 method for class 'PKNCAresults' as.data.frame( x, ..., out_format = c("long", "wide"), filter_requested = FALSE, filter_excluded = FALSE, out.format = deprecated() )
x |
The object to extract results from |
... |
Ignored (for compatibility with generic |
out_format |
Should the output be 'long' (default) or 'wide'? |
filter_requested |
Only return rows with parameters that were specifically requested? |
filter_excluded |
Should excluded values be removed? |
out.format |
Deprecated in favor of |
A data.frame (or usually a tibble) of results
Assert that a value is a valid AUC method
assert_aucmethod(method = c("lin up/log down", "linear", "lin-log"))
assert_aucmethod(method = c("lin up/log down", "linear", "lin-log"))
method |
The method for integration (one of 'lin up/log down', 'lin-log', or 'linear') |
method
or an informative error
If the concentrations or times are invalid, will provide an error. Reasons for being invalid are
time
is not a number
conc
is not a number
Any time
value is NA
time
is not monotonically increasing
conc
and time
are not the same length
assert_conc(conc, any_missing_conc = TRUE) assert_time(time, sorted_time = TRUE) assert_conc_time(conc, time, any_missing_conc = TRUE, sorted_time = TRUE)
assert_conc(conc, any_missing_conc = TRUE) assert_time(time, sorted_time = TRUE) assert_conc_time(conc, time, any_missing_conc = TRUE, sorted_time = TRUE)
conc |
Measured concentrations |
any_missing_conc |
Are any concentration values allowed to be |
time |
Time of the measurement of the concentrations |
sorted_time |
Must the time be unique and monotonically increasing? |
Some cases may generate warnings but allow the data to proceed.
A negative concentration is often but not always an error; it will generate a warning.
conc
or give an informative error
time
or give an informative error
A data.frame with columns named "conc" and "time" or an informative error
Assert that a value is a dosing interval
assert_dosetau(tau)
assert_dosetau(tau)
tau |
The dosing interval |
tau
or an informative error
Verifies that an interval definition is valid for a PKNCAdata object. Valid means that intervals are a data.frame (or data.frame-like object), that the column names are either the groupings of the PKNCAconc part of the PKNCAdata object or that they are one of the NCA parameters allowed (i.e. names(get.interval.cols())). It will return the intervals argument unchanged, or it will raise an error.
assert_intervals(intervals, data)
assert_intervals(intervals, data)
intervals |
Proposed intervals |
data |
PKNCAdata object |
The intervals argument unchanged, or it will raise an error.
Assert that an interval is accurately defined as an interval, and return the interval
assert_intervaltime_single(interval = NULL, start = NULL, end = NULL)
assert_intervaltime_single(interval = NULL, start = NULL, end = NULL)
interval |
Numeric vector of two numbers for the start and end time of integration |
start |
The start time of the interval |
end |
The end time of the interval |
interval
(or c(start, end)
)
Assert that a lambda.z value is valid
assert_lambdaz( lambda.z, any.missing = TRUE, .var.name = checkmate::vname(lambda.z) )
assert_lambdaz( lambda.z, any.missing = TRUE, .var.name = checkmate::vname(lambda.z) )
lambda.z |
The elimination rate (in units of inverse time) for extrapolation |
any.missing |
[ |
.var.name |
[ |
lambda.z
or an informative error
Confirm that a value is greater than another value
assert_number_between( x, ..., na.ok = FALSE, len = 1, .var.name = checkmate::vname(x) )
assert_number_between( x, ..., na.ok = FALSE, len = 1, .var.name = checkmate::vname(x) )
x |
[any] |
... |
Passed to |
na.ok |
[ |
len |
Ignored (must be 1) |
.var.name |
[ |
x
or an informative error
Confirm that a value is greater than another value
assert_numeric_between( x, any.missing = FALSE, null.ok = FALSE, lower_eq = -Inf, lower = -Inf, upper = Inf, upper_eq = Inf, ..., .var.name = checkmate::vname(x) )
assert_numeric_between( x, any.missing = FALSE, null.ok = FALSE, lower_eq = -Inf, lower = -Inf, upper = Inf, upper_eq = Inf, ..., .var.name = checkmate::vname(x) )
x |
[any] |
any.missing |
[ |
null.ok |
[ |
lower_eq , upper_eq
|
Values where equality is not allowed |
lower |
[ |
upper |
[ |
... |
Passed to |
.var.name |
[ |
x
Assert that an object is a PKNCAdata object
assert_PKNCAdata(object)
assert_PKNCAdata(object)
object |
The PKNCAdata object |
The PKNCAdata object (confirmed to be usable)
Support function for AUC integration
auc_integrate( conc, time, clast, tlast, lambda.z, interval_method, fun_linear, fun_log, fun_inf )
auc_integrate( conc, time, clast, tlast, lambda.z, interval_method, fun_linear, fun_log, fun_inf )
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
clast |
The last concentration above the limit of quantification |
tlast |
Time of last concentration above the limit of quantification (will be calculated, if not provided) |
lambda.z |
The elimination rate (in units of inverse time) for extrapolation |
interval_method |
The method for integrating each interval of |
fun_linear |
The function to use for integration of the linear part of the curve (not required for AUC or AUMC functions) |
fun_log |
The function to use for integration of the logarithmic part of the curve (if log integration is used; not required for AUC or AUMC functions) |
fun_inf |
The function to use for extrapolation from the final measurement to infinite time (not required for AUC or AUMC functions. |
Generate functions to do the named function (e.g. mean) applying the business rules.
business.mean(x, ...) business.sd(x, ...) business.cv(x, ...) business.geomean(x, ...) business.geocv(x, ...) business.min(x, ...) business.max(x, ...) business.median(x, ...) business.range(x, ...)
business.mean(x, ...) business.sd(x, ...) business.cv(x, ...) business.geomean(x, ...) business.geocv(x, ...) business.min(x, ...) business.max(x, ...) business.median(x, ...) business.range(x, ...)
x |
vector to be passed to the various functions |
... |
Additional arguments to be passed to the underlying function. |
The value of the various functions or NA if too many values are missing
business.sd()
: Compute the standard deviation with business rules.
business.cv()
: Compute the coefficient of variation with business rules.
business.geomean()
: Compute the geometric mean with business rules.
business.geocv()
: Compute the geometric coefficient of variation with business rules.
business.min()
: Compute the minimum with business rules.
business.max()
: Compute the maximum with business rules.
business.median()
: Compute the median with business rules.
business.range()
: Compute the range with business rules.
Check that the conversion to a data type does not change the number of NA values
check.conversion(x, FUN, ...)
check.conversion(x, FUN, ...)
x |
the value to convert |
FUN |
the function to use for conversion |
... |
arguments passed to |
FUN(x, ...)
or an error if the set of NAs change.
Take in a single row of an interval specification and return that row updated with any additional calculations that must be done to fulfill all dependencies.
check.interval.deps(x)
check.interval.deps(x)
x |
A data frame with one or more rows of the PKNCA interval |
The interval specification with additional calculations added where requested outputs require them.
Other Interval specifications:
add.interval.col()
,
check.interval.specification()
,
choose.auc.intervals()
,
get.interval.cols()
,
get.parameter.deps()
Calculation interval specifications are data frames defining what calculations will be required and summarized from all time intervals. Note: parameters which are not requested may be calculated if it is required for (or computed at the same time as) a requested parameter.
check.interval.specification(x)
check.interval.specification(x)
x |
The data frame specifying what to calculate during each time interval |
start
and end
time must always be given as columns, and the start
must
be before the end
. Other columns define the parameters to be calculated
and the groupings to apply the intervals to.
x The potentially updated data frame with the interval calculation specification.
The vignette "Selection of Calculation Intervals"
Other Interval specifications:
add.interval.col()
,
check.interval.deps()
,
choose.auc.intervals()
,
get.interval.cols()
,
get.parameter.deps()
Check the hash of an object to confirm its provenance.
checkProvenance(object)
checkProvenance(object)
object |
The object to check provenance for |
TRUE
if the provenance is confirmed to be consistent, FALSE
if
the provenance is not consistent, or NA
if provenance is not present.
Choose how to interpolate, extrapolate, or integrate data in each concentration interval
choose_interval_method(conc, time, tlast, method, auc.type, options)
choose_interval_method(conc, time, tlast, method, auc.type, options)
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
tlast |
Time of last concentration above the limit of quantification (will be calculated, if not provided) |
method |
The method for integration (one of 'lin up/log down', 'lin-log', or 'linear') |
auc.type |
The type of AUC to compute. Choices are 'AUCinf', 'AUClast', and 'AUCall'. |
options |
List of changes to the default PKNCA options (see
|
A character vector of methods for interpolation/extrapolation
methods that is the same length as conc
which indicates how to
interpolate/integrate between each of the concentrations (all but the last
value in the vector) and how to extrapolate after tlast
(the last item in
the vector). Possible values in the vector are: 'zero', 'linear', 'log',
and 'extrap_log'
Intervals for AUC are selected by the following metrics:
If only one dose is administered, use the
PKNCA.options("single.dose.aucs")
If more than one dose is administered, estimate the AUC between any two doses that have PK taken at both of the dosing times and at least one time between the doses.
For the final dose of multiple doses, try to determine the
dosing interval () and estimate the AUC in that
interval if multiple samples are taken in the interval.
If there are samples after the last dose,
calculate the half life after the last dose.
choose.auc.intervals( time.conc, time.dosing, options = list(), single.dose.aucs = NULL )
choose.auc.intervals( time.conc, time.dosing, options = list(), single.dose.aucs = NULL )
time.conc |
Time of concentration measurement |
time.dosing |
Time of dosing |
options |
List of changes to the default PKNCA options (see
|
single.dose.aucs |
The AUC specification for single dosing. |
A data frame with columns for start
, end
, auc.type
, and
half.life
. See check.interval.specification()
for column definitions.
The data frame may have zero rows if no intervals could be found.
pk.calc.auc()
, pk.calc.aumc()
, pk.calc.half.life()
,
PKNCA.options()
Other Interval specifications:
add.interval.col()
,
check.interval.deps()
,
check.interval.specification()
,
get.interval.cols()
,
get.parameter.deps()
Other Interval determination:
find.tau()
Handle BLQ values in the concentration measurements as requested by the user.
clean.conc.blq( conc, time, ..., options = list(), conc.blq = NULL, conc.na = NULL, check = TRUE )
clean.conc.blq( conc, time, ..., options = list(), conc.blq = NULL, conc.na = NULL, check = TRUE )
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
... |
Additional arguments passed to clean.conc.na |
options |
List of changes to the default PKNCA options (see
|
conc.blq |
How to handle a BLQ value that is between above LOQ values? See details for description. |
conc.na |
How to handle NA concentrations. (See |
check |
Run |
NA
concentrations (and their associated times) will be handled as
described in clean.conc.na()
before working with the BLQ values. The
method for handling NA concentrations can affect the output of which points
are considered BLQ and which are considered "middle". Values are
considered BLQ if they are 0.
conc.blq
can be set either a scalar indicating what should be done for
all BLQ values or a list with elements either named "first", "middle" and "last" or "before.tmax" and "after.tmax"
each set to a scalar.
The meaning of each of the list elements is:
Values up to the first non-BLQ value. Note that if all values are BLQ, this includes all values.
Values that are BLQ between the first and last non-BLQ values.
Values that are BLQ after the last non-BLQ value
Values that are BLQ before the time at first maximum concentration
Values that are BLQ after the time at first maximum concentration
The valid settings for each are:
Drop the BLQ values
Keep the BLQ values
Set the BLQ values to that number
The concentration and time measurements (data frame) filtered and cleaned as requested relative to BLQ in the middle.
Other Data cleaners:
clean.conc.na()
NA concentrations (and their associated times) will be removed then the BLQ values in the middle
clean.conc.na(conc, time, ..., options = list(), conc.na = NULL, check = TRUE)
clean.conc.na(conc, time, ..., options = list(), conc.na = NULL, check = TRUE)
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
... |
Additional items to add to the data frame |
options |
List of changes to the default PKNCA options (see
|
conc.na |
How to handle NA concentrations? Either 'drop' or a number to impute. |
check |
Run |
The concentration and time measurements (data frame) filtered and cleaned as requested relative to NA in the concentration.
Other Data cleaners:
clean.conc.blq()
The calculation follows equation A3 in Holder 2001 (see references below):
cov_holder(sparse_pk)
cov_holder(sparse_pk)
sparse_pk |
A sparse_pk object from |
If , then
is
defined as zero (rather than dividing by zero).
Where:
The covariance of times i and j
and
The number of subjects (usually animals) at times i and j, respectively
The number of subjects (usually animals) at both times i and j
and
The concentration measured for animal k at times i and j, respectively
and
The mean of the concentrations at times i and j, respectively
The Cauchy-Schwartz inequality is enforced for covariances to keep correlation coefficients between -1 and 1, inclusive, as described in equations 8 and 9 of Nedelman and Jia 1998.
A matrix with one row and one column for each element of
sparse_pk_attribute
. The covariances are on the off diagonals, and for
simplicity of use, it also calculates the variance on the diagonal
elements.
Holder DJ. Comments on Nedelman and Jia’s Extension of Satterthwaite’s Approximation Applied to Pharmacokinetics. Journal of Biopharmaceutical Statistics. 2001;11(1-2):75-79. doi:10.1081/BIP-100104199
Nedelman JR, Jia X. An extension of Satterthwaite’s approximation applied to pharmacokinetics. Journal of Biopharmaceutical Statistics. 1998;8(2):317-328. doi:10.1080/10543409808835241
The following functions are defunct
check.conc.time(...)
check.conc.time(...)
... |
Ignored |
check.conc.time()
: Defunct as of version 0.11
Exclude data points or results from calculations or summarization.
exclude(object, reason, mask, FUN) ## Default S3 method: exclude(object, reason, mask, FUN)
exclude(object, reason, mask, FUN) ## Default S3 method: exclude(object, reason, mask, FUN)
object |
The object to exclude data from. |
reason |
The reason to add as a reason for exclusion. |
mask |
A logical vector or numeric index of values to exclude (see details). |
FUN |
A function to operate on the data (one group at a time) to select reasons for exclusions (see details). |
Only one of mask
or FUN
may be given. If FUN
is given, it
will be called with two arguments: a data.frame (or similar object) that
consists of a single group of the data and the full object (e.g. the
PKNCAconc object), FUN(current_group, object)
, and it must return a
logical vector equivalent to mask
or a character vector with the reason
text given when data should be excluded or NA_character_
when the data
should be included (for the current exclusion test).
The object with updated information in the exclude column. The
exclude column will contain the reason
if mask
or FUN
indicate. If a
previous reason for exclusion was given, then subsequent reasons for
exclusion will be added to the first with a semicolon space ("; ")
separator.
exclude(default)
: The general case for data exclusion
Other Result exclusions:
exclude_nca
myconc <- PKNCAconc(data.frame(subject=1, time=0:6, conc=c(1, 2, 3, 2, 1, 0.5, 0.25)), conc~time|subject) exclude(myconc, reason="Carryover", mask=c(TRUE, rep(FALSE, 6)))
myconc <- PKNCAconc(data.frame(subject=1, time=0:6, conc=c(1, 2, 3, 2, 1, 0.5, 0.25)), conc~time|subject) exclude(myconc, reason="Carryover", mask=c(TRUE, rep(FALSE, 6)))
Exclude NCA parameters based on examining the parameter set.
exclude_nca_span.ratio(min.span.ratio) exclude_nca_max.aucinf.pext(max.aucinf.pext) exclude_nca_min.hl.r.squared(min.hl.r.squared)
exclude_nca_span.ratio(min.span.ratio) exclude_nca_max.aucinf.pext(max.aucinf.pext) exclude_nca_min.hl.r.squared(min.hl.r.squared)
min.span.ratio |
The minimum acceptable span ratio (uses
|
max.aucinf.pext |
The maximum acceptable percent AUC extrapolation (uses
|
min.hl.r.squared |
The minimum acceptable r-squared value for half-life
(uses |
exclude_nca_span.ratio()
: Exclude based on span.ratio
exclude_nca_max.aucinf.pext()
: Exclude based on AUC percent extrapolated (both
observed and predicted)
exclude_nca_min.hl.r.squared()
: Exclude based on half-life r-squared
Other Result exclusions:
exclude()
my_conc <- PKNCAconc(data.frame(conc=1.1^(3:0), time=0:3, subject=1), conc~time|subject) my_data <- PKNCAdata(my_conc, intervals=data.frame(start=0, end=Inf, aucinf.obs=TRUE, aucpext.obs=TRUE)) my_result <- pk.nca(my_data) my_result_excluded <- exclude(my_result, FUN=exclude_nca_max.aucinf.pext()) as.data.frame(my_result_excluded)
my_conc <- PKNCAconc(data.frame(conc=1.1^(3:0), time=0:3, subject=1), conc~time|subject) my_data <- PKNCAdata(my_conc, intervals=data.frame(start=0, end=Inf, aucinf.obs=TRUE, aucpext.obs=TRUE)) my_result <- pk.nca(my_data) my_result_excluded <- exclude(my_result, FUN=exclude_nca_max.aucinf.pext()) as.data.frame(my_result_excluded)
dplyr filtering for PKNCA
## S3 method for class 'PKNCAresults' filter(.data, ..., .preserve = FALSE) ## S3 method for class 'PKNCAconc' filter(.data, ..., .preserve = FALSE) ## S3 method for class 'PKNCAdose' filter(.data, ..., .preserve = FALSE)
## S3 method for class 'PKNCAresults' filter(.data, ..., .preserve = FALSE) ## S3 method for class 'PKNCAconc' filter(.data, ..., .preserve = FALSE) ## S3 method for class 'PKNCAdose' filter(.data, ..., .preserve = FALSE)
.data |
A data frame, data frame extension (e.g. a tibble), or a lazy data frame (e.g. from dbplyr or dtplyr). See Methods, below, for more details. |
... |
< |
.preserve |
Relevant when the |
Other dplyr verbs:
group_by.PKNCAresults()
,
inner_join.PKNCAresults()
,
mutate.PKNCAresults()
This is intended to find the interval over which x repeats by the rule
unique(mod(x, interval))
is minimized.
find.tau(x, na.action = stats::na.omit, options = list(), tau.choices = NULL)
find.tau(x, na.action = stats::na.omit, options = list(), tau.choices = NULL)
x |
the vector to find the interval within |
na.action |
What to do with NAs in |
options |
List of changes to the default PKNCA options (see
|
tau.choices |
the intervals to look for if the doses are not all equally spaced. |
A scalar indicating the repeating interval with the most repetition.
If all values are NA
then NA is returned.
If all values are the same, then 0 is returned.
If all values are equally spaced, then that spacing is returned.
If one of the choices
can minimize the number of
unique values, then that is returned.
If none of the choices
can minimize the number of
unique values, then -1 is returned.
Other Interval determination:
choose.auc.intervals()
Find the first occurrence of an operator in a formula and return the left, right, or both sides of the operator.
findOperator(x, op, side)
findOperator(x, op, side)
x |
The formula to parse |
op |
The operator to search for (e.g. |
side |
Which side of the operator would you like to see: 'left', 'right', or 'both'. |
The side of the operator requested, NA if requesting the left side of a unary operator, and NULL if the operator is not found.
Other Formula parsing:
parse_formula_to_cols()
Perform the half-life fit given the data. The function simply fits the data without any validation. No selection of points or any other components are done.
fit_half_life(data, tlast, conc_units)
fit_half_life(data, tlast, conc_units)
data |
The data to fit. Must have two columns named "log_conc" and "time" |
tlast |
The time of last observed concentration above the limit of quantification. |
conc_units |
NULL or the units to set for concentration measures |
A data.frame with one row and columns named "r.squared", "adj.r.squared", "PROB", "lambda.z", "clast.pred", "lambda.z.n.points", "half.life", "span.ratio"
Extract the formula from a PKNCAconc object.
## S3 method for class 'PKNCAconc' formula(x, ...) ## S3 method for class 'PKNCAdose' formula(x, ...)
## S3 method for class 'PKNCAconc' formula(x, ...) ## S3 method for class 'PKNCAdose' formula(x, ...)
x |
The object to extract the formula from. |
... |
Unused |
A formula object
Compute the geometric mean, sd, and CV
geomean(x, na.rm = FALSE) geosd(x, na.rm = FALSE) geocv(x, na.rm = FALSE)
geomean(x, na.rm = FALSE) geosd(x, na.rm = FALSE) geocv(x, na.rm = FALSE)
x |
A vector to compute the geometric mean of |
na.rm |
Should missing values be removed? |
The scalar value of the geometric mean, geometric standard deviation, or geometric coefficient of variation.
geosd()
: Compute the geometric standard deviation, exp(sd(log(x)))
.
geocv()
: Compute the geometric coefficient of variation,
sqrt(exp(sd(log(x))^2)-1)*100
.
Kirkwood T. B.L. Geometric means and measures of dispersion. Biometrics 1979; 35: 908-909
geomean(1:3) geosd(1:3) geocv(1:3)
geomean(1:3) geosd(1:3) geocv(1:3)
Get the impute function from either the intervals column or from the method
get_impute_method(intervals, impute)
get_impute_method(intervals, impute)
intervals |
the data.frame of intervals |
impute |
the imputation definition |
The imputation function vector
Extract the best model from a list of models using the AIC.
get.best.model(object, ...)
get.best.model(object, ...)
object |
the list of models |
... |
Parameters passed to AIC.list |
The model which is assessed as best. If more than one are equal, the first is chosen.
Get the first model from a list of models
get.first.model(object)
get.first.model(object)
object |
the list of (lists of, ...) models |
The first item in the object
that is not a list or NA
. If NA
is passed in or the list (of lists) is all NA
, then NA
is returned.
Get the columns that can be used in an interval specification
get.interval.cols()
get.interval.cols()
A list with named elements for each parameter. Each list element contains the parameter definition.
check.interval.specification()
and the vignette "Selection of
Calculation Intervals"
Other Interval specifications:
add.interval.col()
,
check.interval.deps()
,
check.interval.specification()
,
choose.auc.intervals()
,
get.parameter.deps()
get.interval.cols()
get.interval.cols()
Get all columns that depend on a parameter
get.parameter.deps(x)
get.parameter.deps(x)
x |
The parameter name (as a character string) |
A character vector of parameter names that depend on the parameter
x
. If none depend on x
, then the result will be an empty vector.
Other Interval specifications:
add.interval.col()
,
check.interval.deps()
,
check.interval.specification()
,
choose.auc.intervals()
,
get.interval.cols()
Retrieve the value of an attribute column.
getAttributeColumn(object, attr_name, warn_missing = c("attr", "column"))
getAttributeColumn(object, attr_name, warn_missing = c("attr", "column"))
object |
The object to extract the attribute value from. |
attr_name |
The name of the attribute to extract |
warn_missing |
Give a warning if the "attr"ibute or "column" is missing. Character vector with zero, one, or both of "attr" and "column". |
The value of the attribute (or NULL
if the attribute is not set or
the column does not exist)
Get the value from a column in a data frame if the value is a column there, otherwise, the value should be a scalar or the length of the data.
getColumnValueOrNot(data, value, prefix = "X")
getColumnValueOrNot(data, value, prefix = "X")
data |
A data.frame or similar object |
value |
A character string giving the name of a column in the |
prefix |
The prefix to use if a column must be added (it will be used as the full column name if it is not already in the dataset or it will be prepended to the maximum column name if not.) |
A list with elements named "data", "name" giving the data
with a
column named "name" with the value in that column.
Get the name of the element containing the data for the current object.
## S3 method for class 'PKNCAconc' getDataName(object) ## S3 method for class 'PKNCAdose' getDataName(object) ## S3 method for class 'PKNCAresults' getDataName(object) getDataName(object) ## Default S3 method: getDataName(object)
## S3 method for class 'PKNCAconc' getDataName(object) ## S3 method for class 'PKNCAdose' getDataName(object) ## S3 method for class 'PKNCAresults' getDataName(object) getDataName(object) ## Default S3 method: getDataName(object)
object |
The object to get the data name from. |
A character scalar with the name of the data object (or NULL
if the
method does not apply).
getDataName(default)
: If no data name exists, returns NULL.
Other PKNCA object extractors:
getDepVar()
,
getIndepVar()
Get the dependent variable (left hand side of the formula) from a PKNCA object.
getDepVar(x, ...)
getDepVar(x, ...)
x |
The object to extract the formula from |
... |
Unused |
The vector of the dependent variable from the object.
Other PKNCA object extractors:
getDataName.PKNCAconc()
,
getIndepVar()
|
from a PKNCA
object).Get the groups (right hand side after the |
from a PKNCA
object).
Get the groups (right hand side after the |
from a PKNCA
object).
## S3 method for class 'PKNCAconc' getGroups( object, form = stats::formula(object), level, data = as.data.frame(object), sep ) ## S3 method for class 'PKNCAdata' getGroups(object, ...) ## S3 method for class 'PKNCAdose' getGroups(...) ## S3 method for class 'PKNCAresults' getGroups( object, form = formula(object$data$conc), level, data = object$result, sep )
## S3 method for class 'PKNCAconc' getGroups( object, form = stats::formula(object), level, data = as.data.frame(object), sep ) ## S3 method for class 'PKNCAdata' getGroups(object, ...) ## S3 method for class 'PKNCAdose' getGroups(...) ## S3 method for class 'PKNCAresults' getGroups( object, form = formula(object$data$conc), level, data = object$result, sep )
object |
The object to extract the data from |
form |
The formula to extract the data from (defaults to the formula
from |
level |
optional. If included, this specifies the level(s) of the
groups to include. If a numeric scalar, include the first |
data |
The data to extract the groups from (defaults to the data from
|
sep |
Unused (kept for compatibility with the nlme package) |
... |
Arguments passed to other getGroups functions |
A data frame with the (selected) group columns.
A data frame with the (selected) group columns.
Get the independent variable (right hand side of the formula) from a PKNCA object.
getIndepVar(x, ...)
getIndepVar(x, ...)
x |
The object to extract the formula from |
... |
Unused |
The vector of the independent variable from the object.
Other PKNCA object extractors:
getDataName.PKNCAconc()
,
getDepVar()
dplyr grouping for PKNCA
## S3 method for class 'PKNCAresults' group_by(.data, ..., .add = FALSE, .drop = dplyr::group_by_drop_default(.data)) ## S3 method for class 'PKNCAconc' group_by(.data, ..., .add = FALSE, .drop = dplyr::group_by_drop_default(.data)) ## S3 method for class 'PKNCAdose' group_by(.data, ..., .add = FALSE, .drop = dplyr::group_by_drop_default(.data)) ## S3 method for class 'PKNCAresults' ungroup(x, ...) ## S3 method for class 'PKNCAconc' ungroup(x, ...) ## S3 method for class 'PKNCAdose' ungroup(x, ...)
## S3 method for class 'PKNCAresults' group_by(.data, ..., .add = FALSE, .drop = dplyr::group_by_drop_default(.data)) ## S3 method for class 'PKNCAconc' group_by(.data, ..., .add = FALSE, .drop = dplyr::group_by_drop_default(.data)) ## S3 method for class 'PKNCAdose' group_by(.data, ..., .add = FALSE, .drop = dplyr::group_by_drop_default(.data)) ## S3 method for class 'PKNCAresults' ungroup(x, ...) ## S3 method for class 'PKNCAconc' ungroup(x, ...) ## S3 method for class 'PKNCAdose' ungroup(x, ...)
.data |
A data frame, data frame extension (e.g. a tibble), or a lazy data frame (e.g. from dbplyr or dtplyr). See Methods, below, for more details. |
... |
In |
.add |
When This argument was previously called |
.drop |
Drop groups formed by factor levels that don't appear in the
data? The default is |
x |
A |
Other dplyr verbs:
filter.PKNCAresults()
,
inner_join.PKNCAresults()
,
mutate.PKNCAresults()
Get grouping variables for a PKNCA object
## S3 method for class 'PKNCAconc' group_vars(x) ## S3 method for class 'PKNCAdose' group_vars(x)
## S3 method for class 'PKNCAconc' group_vars(x) ## S3 method for class 'PKNCAdose' group_vars(x)
x |
The PKNCA object |
A character vector (possibly empty) of the grouping variables
group_vars(PKNCAdose)
: Get group_vars for a PKNCAdose object
dplyr joins for PKNCA
## S3 method for class 'PKNCAresults' inner_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE ) ## S3 method for class 'PKNCAresults' left_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE ) ## S3 method for class 'PKNCAresults' right_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE ) ## S3 method for class 'PKNCAresults' full_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE ) ## S3 method for class 'PKNCAconc' inner_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE ) ## S3 method for class 'PKNCAconc' left_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE ) ## S3 method for class 'PKNCAconc' right_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE ) ## S3 method for class 'PKNCAconc' full_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE ) ## S3 method for class 'PKNCAdose' inner_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE ) ## S3 method for class 'PKNCAdose' left_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE ) ## S3 method for class 'PKNCAdose' right_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE ) ## S3 method for class 'PKNCAdose' full_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE )
## S3 method for class 'PKNCAresults' inner_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE ) ## S3 method for class 'PKNCAresults' left_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE ) ## S3 method for class 'PKNCAresults' right_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE ) ## S3 method for class 'PKNCAresults' full_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE ) ## S3 method for class 'PKNCAconc' inner_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE ) ## S3 method for class 'PKNCAconc' left_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE ) ## S3 method for class 'PKNCAconc' right_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE ) ## S3 method for class 'PKNCAconc' full_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE ) ## S3 method for class 'PKNCAdose' inner_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE ) ## S3 method for class 'PKNCAdose' left_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE ) ## S3 method for class 'PKNCAdose' right_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE ) ## S3 method for class 'PKNCAdose' full_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = FALSE )
x , y
|
A pair of data frames, data frame extensions (e.g. a tibble), or lazy data frames (e.g. from dbplyr or dtplyr). See Methods, below, for more details. |
by |
A join specification created with If To join on different variables between To join by multiple variables, use a
For simple equality joins, you can alternatively specify a character vector
of variable names to join by. For example, To perform a cross-join, generating all combinations of |
copy |
If |
suffix |
If there are non-joined duplicate variables in |
... |
Other parameters passed onto methods. |
keep |
Should the join keys from both
|
Other dplyr verbs:
filter.PKNCAresults()
,
group_by.PKNCAresults()
,
mutate.PKNCAresults()
Interpolate or extrapolate concentrations using the provided method
interpolate_conc_linear(conc_1, conc_2, time_1, time_2, time_out) interpolate_conc_log(conc_1, conc_2, time_1, time_2, time_out) extrapolate_conc_lambdaz(clast, lambda.z, tlast, time_out)
interpolate_conc_linear(conc_1, conc_2, time_1, time_2, time_out) interpolate_conc_log(conc_1, conc_2, time_1, time_2, time_out) extrapolate_conc_lambdaz(clast, lambda.z, tlast, time_out)
conc_1 , conc_2
|
The concentration at time1 and time2 |
time_1 , time_2
|
The time value associated with conc1 and conc2 |
time_out |
Time when interpolation is requested |
clast |
The concentration at the last time above the lower LOQ |
lambda.z |
The elimination rate (in units of inverse time) for extrapolation |
tlast |
The time of the last concentration above the lower limit of quantification (LOQ) |
The interpolated or extrapolated value using the correct method
interpolate.conc()
and extrapolate.conc()
returns an interpolated (or
extrapolated) concentration. interp.extrap.conc()
will choose whether
interpolation or extrapolation is required and will also operate on many
concentrations. These will typically be used to estimate the concentration
between two measured concentrations or after the last measured concentration.
Of note, these functions will not extrapolate prior to the first point.
interp.extrap.conc( conc, time, time.out, lambda.z = NA, clast = pk.calc.clast.obs(conc, time), options = list(), method = NULL, auc.type = "AUCinf", interp.method, extrap.method, ..., conc.blq = NULL, conc.na = NULL, check = TRUE ) interpolate.conc( conc, time, time.out, options = list(), method = NULL, interp.method, conc.blq = NULL, conc.na = NULL, conc.origin = 0, ..., check = TRUE ) extrapolate.conc( conc, time, time.out, lambda.z = NA, clast = pk.calc.clast.obs(conc, time), auc.type = "AUCinf", extrap.method, options = list(), conc.na = NULL, conc.blq = NULL, ..., check = TRUE ) interp.extrap.conc.dose( conc, time, time.dose, route.dose = "extravascular", duration.dose = NA, time.out, out.after = FALSE, options = list(), conc.blq = NULL, conc.na = NULL, ..., check = TRUE )
interp.extrap.conc( conc, time, time.out, lambda.z = NA, clast = pk.calc.clast.obs(conc, time), options = list(), method = NULL, auc.type = "AUCinf", interp.method, extrap.method, ..., conc.blq = NULL, conc.na = NULL, check = TRUE ) interpolate.conc( conc, time, time.out, options = list(), method = NULL, interp.method, conc.blq = NULL, conc.na = NULL, conc.origin = 0, ..., check = TRUE ) extrapolate.conc( conc, time, time.out, lambda.z = NA, clast = pk.calc.clast.obs(conc, time), auc.type = "AUCinf", extrap.method, options = list(), conc.na = NULL, conc.blq = NULL, ..., check = TRUE ) interp.extrap.conc.dose( conc, time, time.dose, route.dose = "extravascular", duration.dose = NA, time.out, out.after = FALSE, options = list(), conc.blq = NULL, conc.na = NULL, ..., check = TRUE )
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
time.out |
Time when interpolation is requested (vector for
|
lambda.z |
The elimination rate (in units of inverse time) for extrapolation |
clast |
The last observed concentration above the limit of
quantification. If not given, |
options |
List of changes to the default PKNCA options (see
|
method |
The method for integration (one of 'lin up/log down', 'lin-log', or 'linear') |
auc.type |
The type of AUC to compute. Choices are 'AUCinf', 'AUClast', and 'AUCall'. |
interp.method , extrap.method
|
deprecated in favor of method and auc.type |
... |
Additional arguments passed to |
conc.blq |
How to handle BLQ values. (See |
conc.na |
How to handle NA concentrations. (See |
check |
Run |
conc.origin |
The concentration before the first measurement.
|
time.dose |
Time of the dose |
route.dose |
What is the route of administration ("intravascular" or "extravascular"). See the details for how this parameter is used. |
duration.dose |
What is the duration of administration? See the details for how this parameter is used. |
out.after |
Should interpolation occur from the data before ( |
An NA
value for the lambda.z
parameter will prevent extrapolation.
Use lambda.z to extrapolate beyond the last point with the half-life.
If the last point is above the limit of quantification or missing, this is identical to 'AUCinf'. If the last point is below the limit of quantification, then linear interpolation between the Clast and the next BLQ is used for that interval and all additional points are extrapolated as 0.
Extrapolates all points after the last above the limit of quantification as 0.
duration.dose
and direction.out
are ignored if route.dose == "extravascular"
. direction.out
is ignored if duration.dose > 0
.
route.dose
and duration.dose
affect how interpolation/extrapolation of
the concentration occurs at the time of dosing. If route.dose == "intravascular"
and duration.dose == 0
then extrapolation occurs for an IV
bolus using pk.calc.c0()
with the data after dosing. Otherwise (either
route.dose == "extravascular"
or duration.dose > 0
), extrapolation occurs
using the concentrations before dosing and estimating the half-life (or more
precisely, estimating lambda.z
). Finally, direction.out
can change the
direction of interpolation in cases with route.dose == "intravascular"
and
duration.dose == 0
. When direction.out == "before"
interpolation occurs
only with data before the dose (as is the case for route.dose == "extravascular"
), but if direction.out == "after"
interpolation occurs
from the data after dosing.
The interpolated or extrapolated concentration value as a scalar
double (or vector for interp.extrap.conc()
).
interpolate.conc()
: Interpolate concentrations through Tlast (inclusive)
extrapolate.conc()
: Extrapolate concentrations after Tlast
interp.extrap.conc.dose()
: Interpolate and extrapolate concentrations
without interpolating or extrapolating beyond doses.
pk.calc.clast.obs()
, pk.calc.half.life()
, pk.calc.c0()
Is a PKNCA object used for sparse PK?
## S3 method for class 'PKNCAconc' is_sparse_pk(object) ## S3 method for class 'PKNCAdata' is_sparse_pk(object) ## S3 method for class 'PKNCAresults' is_sparse_pk(object) is_sparse_pk(object)
## S3 method for class 'PKNCAconc' is_sparse_pk(object) ## S3 method for class 'PKNCAdata' is_sparse_pk(object) ## S3 method for class 'PKNCAresults' is_sparse_pk(object) is_sparse_pk(object)
object |
The object to see if it includes sparse PK |
TRUE
if sparse and FALSE
if dense (not sparse)
Extract the columns used in the formula (in order) from a PKNCAconc or PKNCAdose object.
## S3 method for class 'PKNCAconc' model.frame(formula, ...) ## S3 method for class 'PKNCAdose' model.frame(formula, ...)
## S3 method for class 'PKNCAconc' model.frame(formula, ...) ## S3 method for class 'PKNCAdose' model.frame(formula, ...)
formula |
The object to use (parameter name is |
... |
Unused |
A data frame with the columns from the object in formula order.
dplyr mutate-based modification for PKNCA
## S3 method for class 'PKNCAresults' mutate(.data, ...) ## S3 method for class 'PKNCAconc' mutate(.data, ...) ## S3 method for class 'PKNCAdose' mutate(.data, ...)
## S3 method for class 'PKNCAresults' mutate(.data, ...) ## S3 method for class 'PKNCAconc' mutate(.data, ...) ## S3 method for class 'PKNCAdose' mutate(.data, ...)
.data |
A data frame, data frame extension (e.g. a tibble), or a lazy data frame (e.g. from dbplyr or dtplyr). See Methods, below, for more details. |
... |
< The value can be:
|
Other dplyr verbs:
filter.PKNCAresults()
,
group_by.PKNCAresults()
,
inner_join.PKNCAresults()
Normalize the exclude column by setting blanks to NA
normalize_exclude(object)
normalize_exclude(object)
object |
The object to extract the exclude column from |
The exclude vector where NA
indicates not to exclude and anything
else indicates to exclude.
Convert a formula representation to the columns for input data
parse_formula_to_cols(form)
parse_formula_to_cols(form)
form |
the formula (or something coercible into a formula) to extract into its parts |
A list of column names for various formula parts
Other Formula parsing:
findOperator()
Convert the grouping info and list of results for each group into a results data.frame
pk_nca_result_to_df(group_info, result)
pk_nca_result_to_df(group_info, result)
group_info |
A data.frame of grouping columns |
result |
A list of data.frames with the results from NCA parameter calculations |
A data.frame with group_info and result combined, warnings filtered out, and results unnested.
PKNCA.options("max.missing")
.Note that all missing values are removed prior to calling the function.
pk.business(FUN, zero.missing = FALSE, max.missing)
pk.business(FUN, zero.missing = FALSE, max.missing)
FUN |
function to run. The function is called as |
zero.missing |
Are zeros counted as missing? If |
max.missing |
The maximum fraction of the data allowed to be missing (a number between 0 and 1, inclusive). |
A version of FUN that can be called with parameters that are checked
for missingness (and zeros) with missing (and zeros) removed before the
call. If max.missing
is exceeded, then NA is returned.
my_mean <- pk.business(FUN=mean) mean(c(1:3, NA)) # Less than half missing results in the summary statistic of the available # values. my_mean(c(1:3, NA)) # More than half missing results in a missing value my_mean(c(1:3, rep(NA, 4)))
my_mean <- pk.business(FUN=mean) mean(c(1:3, NA)) # Less than half missing results in the summary statistic of the available # values. my_mean(c(1:3, NA)) # More than half missing results in a missing value my_mean(c(1:3, rep(NA, 4)))
Calculate amount excreted (typically in urine or feces)
pk.calc.ae(conc, volume, check = TRUE)
pk.calc.ae(conc, volume, check = TRUE)
conc |
Measured concentrations |
volume |
The volume (or mass) of the sample |
check |
Should the concentration and volume data be checked? |
ae is sum(conc*volume)
.
The units for the concentration and volume should match such that
sum(conc*volume)
has units of mass or moles.
The amount excreted during the interval
Concentrations below the given concentration (conc_above
) will be set
to zero.
pk.calc.aucabove(conc, time, conc_above = NA_real_, ..., options = list())
pk.calc.aucabove(conc, time, conc_above = NA_real_, ..., options = list())
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
conc_above |
The concentration to be above |
... |
Extra arguments. Currently, the only extra argument that is used
is |
options |
List of changes to the default PKNCA options (see
|
The AUC of the concentration above the limit
Calculate the AUC over an interval with interpolation and/or extrapolation of concentrations for the beginning and end of the interval.
pk.calc.aucint( conc, time, interval = NULL, start = NULL, end = NULL, clast = pk.calc.clast.obs(conc, time), lambda.z = NA, time.dose = NULL, route = "extravascular", duration.dose = 0, method = NULL, auc.type = "AUClast", conc.blq = NULL, conc.na = NULL, check = TRUE, ..., options = list() ) pk.calc.aucint.last( conc, time, start = NULL, end = NULL, time.dose, ..., options = list() ) pk.calc.aucint.all( conc, time, start = NULL, end = NULL, time.dose, ..., options = list() ) pk.calc.aucint.inf.obs( conc, time, start = NULL, end = NULL, time.dose, lambda.z, clast.obs, ..., options = list() ) pk.calc.aucint.inf.pred( conc, time, start = NULL, end = NULL, time.dose, lambda.z, clast.pred, ..., options = list() )
pk.calc.aucint( conc, time, interval = NULL, start = NULL, end = NULL, clast = pk.calc.clast.obs(conc, time), lambda.z = NA, time.dose = NULL, route = "extravascular", duration.dose = 0, method = NULL, auc.type = "AUClast", conc.blq = NULL, conc.na = NULL, check = TRUE, ..., options = list() ) pk.calc.aucint.last( conc, time, start = NULL, end = NULL, time.dose, ..., options = list() ) pk.calc.aucint.all( conc, time, start = NULL, end = NULL, time.dose, ..., options = list() ) pk.calc.aucint.inf.obs( conc, time, start = NULL, end = NULL, time.dose, lambda.z, clast.obs, ..., options = list() ) pk.calc.aucint.inf.pred( conc, time, start = NULL, end = NULL, time.dose, lambda.z, clast.pred, ..., options = list() )
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
interval |
Numeric vector of two numbers for the start and end time of integration |
start |
The start time of the interval |
end |
The end time of the interval |
clast , clast.obs , clast.pred
|
The last concentration above the limit of quantification; this is used for AUCinf calculations. If provided as clast.obs (observed clast value, default), AUCinf is AUCinf,obs. If provided as clast.pred, AUCinf is AUCinf,pred. |
lambda.z |
The elimination rate (in units of inverse time) for extrapolation |
time.dose , route , duration.dose
|
The time of doses, route of
administration, and duration of dose used with interpolation and
extrapolation of concentration data (see |
method |
The method for integration (one of 'lin up/log down', 'lin-log', or 'linear') |
auc.type |
The type of AUC to compute. Choices are 'AUCinf', 'AUClast', and 'AUCall'. |
conc.blq |
How to handle BLQ values in between the first and last above
LOQ concentrations. (See |
conc.na |
How to handle missing concentration values. (See
|
check |
Run |
... |
Additional arguments passed to |
options |
List of changes to the default PKNCA options (see
|
When pk.calc.aucint()
needs to extrapolate using lambda.z
(in other
words, using the half-life), it will always extrapolate using the logarithmic
trapezoidal rule to align with using a half-life calculation for the
extrapolation.
The AUC for an interval of time as a number
pk.calc.aucint.last()
: Interpolate or extrapolate concentrations for
AUClast
pk.calc.aucint.all()
: Interpolate or extrapolate concentrations for
AUCall
pk.calc.aucint.inf.obs()
: Interpolate or extrapolate concentrations for
AUCinf.obs
pk.calc.aucint.inf.pred()
: Interpolate or extrapolate concentrations for
AUCinf.pred
PKNCA.options()
, interp.extrap.conc.dose()
Other AUC calculations:
pk.calc.auxc()
Calculate AUC for intravenous dosing
pk.calc.auciv(conc, time, c0, auc, ..., check = TRUE) pk.calc.auciv_pbext(auc, auciv)
pk.calc.auciv(conc, time, c0, auc, ..., check = TRUE) pk.calc.auciv_pbext(auc, auciv)
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
c0 |
The concentration at time 0, typically calculated using
|
auc |
The AUC calculated using |
... |
For functions other than |
check |
Run |
auciv |
The AUC calculated using |
The AUC for intravenous (IV) dosing extrapolates the AUC back from the first measurement to time 0 using c0 and the AUC calculated by another method (for example the auclast).
The calculation method takes the following steps:
time = 0
must be present in the data with a measured concentration.
The AUC between time = 0
and the next time point is calculated (auc_first
).
The AUC between time = 0
with c0
and the next time point is calculated (auc_second
).
The final AUC is the initial AUC plus the difference between the two AUCs (auc_final <- auc + auc_second - auc_first
).
The calculation for back-extrapolation is 100*(1 - auc/auciv)
.
pk.calc.auciv
: The AUC calculated using c0
pk.calc.auciv_pctbackextrap
: The AUC percent back-extrapolated
pk.calc.auciv_pbext()
: Calculate the percent back-extrapolated AUC for IV
administration
Calculate the AUC percent extrapolated
pk.calc.aucpext(auclast, aucinf)
pk.calc.aucpext(auclast, aucinf)
auclast |
the area under the curve from time 0 to the last measurement above the limit of quantification |
aucinf |
the area under the curve from time 0 to infinity |
aucpext is 100*(1-auclast/aucinf)
.
The numeric value of the AUC percent extrapolated or NA_real_
if
any of the following are true is.na(aucinf)
, is.na(auclast)
,
aucinf <= 0
, or auclast <= 0
.
Compute the area under the curve (AUC) and the area under the moment curve (AUMC) for pharmacokinetic (PK) data. AUC and AUMC are used for many purposes when analyzing PK in drug development.
pk.calc.auxc( conc, time, interval = c(0, Inf), clast = pk.calc.clast.obs(conc, time, check = FALSE), lambda.z = NA, auc.type = c("AUClast", "AUCinf", "AUCall"), options = list(), method = NULL, conc.blq = NULL, conc.na = NULL, check = TRUE, fun_linear, fun_log, fun_inf ) pk.calc.auc(conc, time, ..., options = list()) pk.calc.auc.last(conc, time, ..., options = list()) pk.calc.auc.inf(conc, time, ..., options = list(), lambda.z) pk.calc.auc.inf.obs(conc, time, clast.obs, ..., options = list(), lambda.z) pk.calc.auc.inf.pred(conc, time, clast.pred, ..., options = list(), lambda.z) pk.calc.auc.all(conc, time, ..., options = list()) pk.calc.aumc(conc, time, ..., options = list()) pk.calc.aumc.last(conc, time, ..., options = list()) pk.calc.aumc.inf(conc, time, ..., options = list(), lambda.z) pk.calc.aumc.inf.obs(conc, time, clast.obs, ..., options = list(), lambda.z) pk.calc.aumc.inf.pred(conc, time, clast.pred, ..., options = list(), lambda.z) pk.calc.aumc.all(conc, time, ..., options = list())
pk.calc.auxc( conc, time, interval = c(0, Inf), clast = pk.calc.clast.obs(conc, time, check = FALSE), lambda.z = NA, auc.type = c("AUClast", "AUCinf", "AUCall"), options = list(), method = NULL, conc.blq = NULL, conc.na = NULL, check = TRUE, fun_linear, fun_log, fun_inf ) pk.calc.auc(conc, time, ..., options = list()) pk.calc.auc.last(conc, time, ..., options = list()) pk.calc.auc.inf(conc, time, ..., options = list(), lambda.z) pk.calc.auc.inf.obs(conc, time, clast.obs, ..., options = list(), lambda.z) pk.calc.auc.inf.pred(conc, time, clast.pred, ..., options = list(), lambda.z) pk.calc.auc.all(conc, time, ..., options = list()) pk.calc.aumc(conc, time, ..., options = list()) pk.calc.aumc.last(conc, time, ..., options = list()) pk.calc.aumc.inf(conc, time, ..., options = list(), lambda.z) pk.calc.aumc.inf.obs(conc, time, clast.obs, ..., options = list(), lambda.z) pk.calc.aumc.inf.pred(conc, time, clast.pred, ..., options = list(), lambda.z) pk.calc.aumc.all(conc, time, ..., options = list())
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
interval |
Numeric vector of two numbers for the start and end time of integration |
clast , clast.obs , clast.pred
|
The last concentration above the limit of quantification; this is used for AUCinf calculations. If provided as clast.obs (observed clast value, default), AUCinf is AUCinf,obs. If provided as clast.pred, AUCinf is AUCinf,pred. |
lambda.z |
The elimination rate (in units of inverse time) for extrapolation |
auc.type |
The type of AUC to compute. Choices are 'AUCinf', 'AUClast', and 'AUCall'. |
options |
List of changes to the default PKNCA options (see
|
method |
The method for integration (one of 'lin up/log down', 'lin-log', or 'linear') |
conc.blq |
How to handle BLQ values in between the first and last above
LOQ concentrations. (See |
conc.na |
How to handle missing concentration values. (See
|
check |
Run |
fun_linear |
The function to use for integration of the linear part of the curve (not required for AUC or AUMC functions) |
fun_log |
The function to use for integration of the logarithmic part of the curve (if log integration is used; not required for AUC or AUMC functions) |
fun_inf |
The function to use for extrapolation from the final measurement to infinite time (not required for AUC or AUMC functions. |
... |
For functions other than |
pk.calc.auc.last
is simply a shortcut setting the interval
parameter to c(0, "last")
.
Extrapolation beyond Clast occurs using the half-life and Clast,obs; Clast,pred is not yet supported.
If all conc input are zero, then the AU(M)C is zero.
You probably do not want to call pk.calc.auxc()
. Usually, you will call
one of the other functions for calculating AUC like pk.calc.auc.last()
,
pk.calc.auc.inf.obs()
, etc.
A numeric value for the AU(M)C.
pk.calc.auc()
: Compute the area under the curve
pk.calc.auc.last()
: Compute the AUClast.
pk.calc.auc.inf()
: Compute the AUCinf
pk.calc.auc.inf.obs()
: Compute the AUCinf with the observed Clast.
pk.calc.auc.inf.pred()
: Compute the AUCinf with the predicted Clast.
pk.calc.auc.all()
: Compute the AUCall.
pk.calc.aumc()
: Compute the area under the moment curve
pk.calc.aumc.last()
: Compute the AUMClast.
pk.calc.aumc.inf()
: Compute the AUMCinf
pk.calc.aumc.inf.obs()
: Compute the AUMCinf with the observed Clast.
pk.calc.aumc.inf.pred()
: Compute the AUMCinf with the predicted Clast.
pk.calc.aumc.all()
: Compute the AUMCall.
Gabrielsson J, Weiner D. "Section 2.8.1 Computation methods - Linear trapezoidal rule." Pharmacokinetic & Pharmacodynamic Data Analysis: Concepts and Applications, 4th Edition. Stockholm, Sweden: Swedish Pharmaceutical Press, 2000. 162-4.
Gabrielsson J, Weiner D. "Section 2.8.3 Computation methods - Log-linear trapezoidal rule." Pharmacokinetic & Pharmacodynamic Data Analysis: Concepts and Applications, 4th Edition. Stockholm, Sweden: Swedish Pharmaceutical Press, 2000. 164-7.
Other AUC calculations:
pk.calc.aucint()
myconc <- c(0, 1, 2, 1, 0.5, 0.25, 0) mytime <- c(0, 1, 2, 3, 4, 5, 6) pk.calc.auc(myconc, mytime, interval=c(0, 6)) pk.calc.auc(myconc, mytime, interval=c(0, Inf))
myconc <- c(0, 1, 2, 1, 0.5, 0.25, 0) mytime <- c(0, 1, 2, 3, 4, 5, 6) pk.calc.auc(myconc, mytime, interval=c(0, 6)) pk.calc.auc(myconc, mytime, interval=c(0, Inf))
Estimate the concentration at dosing time for an IV bolus dose.
pk.calc.c0( conc, time, time.dose = 0, method = c("c0", "logslope", "c1", "cmin", "set0"), check = TRUE ) pk.calc.c0.method.logslope(conc, time, time.dose = 0, check = TRUE) pk.calc.c0.method.c0(conc, time, time.dose = 0, check = TRUE) pk.calc.c0.method.c1(conc, time, time.dose = 0, check = TRUE) pk.calc.c0.method.set0(conc, time, time.dose = 0, check = TRUE) pk.calc.c0.method.cmin(conc, time, time.dose = 0, check = TRUE)
pk.calc.c0( conc, time, time.dose = 0, method = c("c0", "logslope", "c1", "cmin", "set0"), check = TRUE ) pk.calc.c0.method.logslope(conc, time, time.dose = 0, check = TRUE) pk.calc.c0.method.c0(conc, time, time.dose = 0, check = TRUE) pk.calc.c0.method.c1(conc, time, time.dose = 0, check = TRUE) pk.calc.c0.method.set0(conc, time, time.dose = 0, check = TRUE) pk.calc.c0.method.cmin(conc, time, time.dose = 0, check = TRUE)
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
time.dose |
The time when dosing occurred |
method |
The order of methods to test (see details) |
check |
Check the |
Methods available for interpolation are below, and each has its own specific function.
c0
If the observed conc
at time.dose
is nonzero, return that. This method should usually be used first for single-dose IV bolus data in case nominal time zero is measured.
logslope
Compute the semilog line between the first two measured times, and use that line to extrapolate backward to time.dose
c1
Use the first point after time.dose
cmin
Set c0 to cmin during the interval. This method should usually be used for multiple-dose oral data and IV infusion data.
set0
Set c0 to zero (regardless of any other data). This method should usually be used first for single-dose oral data.
The estimated concentration at time 0.
pk.calc.c0.method.logslope()
: Semilog regress the first and second points
after time.dose. This method will return NA
if the second
conc
after time.dose
is 0 or greater than the first.
pk.calc.c0.method.c0()
: Use C0
= conc[time %in% time.dose]
if it is
nonzero.
pk.calc.c0.method.c1()
: Use C0
= C1
.
pk.calc.c0.method.set0()
: Use C0
= 0 (typically used for single dose oral and
IV infusion)
pk.calc.c0.method.cmin()
: Use C0
= Cmin (typically used for multiple dose oral
and IV infusion but not IV bolus)
Calculate the average concentration during an interval.
pk.calc.cav(auc, start, end)
pk.calc.cav(auc, start, end)
auc |
The area under the curve during the interval |
start |
The start time of the interval |
end |
The end time of the interval |
cav is auc/(end-start)
.
The Cav (average concentration during the interval)
Determine the concentration at the end of infusion
pk.calc.ceoi(conc, time, duration.dose = NA, check = TRUE)
pk.calc.ceoi(conc, time, duration.dose = NA, check = TRUE)
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
duration.dose |
The duration for the dosing administration (typically from IV infusion) |
check |
Run |
The concentration at the end of the infusion, NA
if
duration.dose
is NA
, or NA
if all time != duration.dose
Calculate the (observed oral) clearance
pk.calc.cl(dose, auc)
pk.calc.cl(dose, auc)
dose |
the dose administered |
auc |
The area under the concentration-time curve. |
cl is dose/auc
.
If dose
is the same length as the other inputs, then the output
will be the same length as all of the inputs; the function assumes that you
are calculating for multiple intervals simultaneously. If the inputs other
than dose
are scalars and dose
is a vector, then the function assumes
multiple doses were given in a single interval, and the sum of the dose
s
will be used for the calculation.
the numeric value of the total (CL) or observed oral clearance (CL/F)
Gabrielsson J, Weiner D. "Section 2.5.1 Derivation of clearance." Pharmacokinetic & Pharmacodynamic Data Analysis: Concepts and Applications, 4th Edition. Stockholm, Sweden: Swedish Pharmaceutical Press, 2000. 86-7.
If all concentrations are missing, NA_real_
is returned. If all
concentrations are zero (below the limit of quantification) or missing, zero
is returned. If Tlast is NA (due to no non-missing above LOQ measurements),
this will return NA_real_
.
pk.calc.clast.obs(conc, time, check = TRUE)
pk.calc.clast.obs(conc, time, check = TRUE)
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
check |
Run |
The last observed concentration above the LOQ
Other NCA parameters for concentrations during the intervals:
pk.calc.cmax()
,
pk.calc.count_conc()
,
pk.calc.cstart()
,
pk.calc.ctrough()
Calculate renal clearance
pk.calc.clr(ae, auc)
pk.calc.clr(ae, auc)
ae |
The amount excreted in urine (as a numeric scalar or vector) |
auc |
The area under the curve (as a numeric scalar or vector) |
clr is sum(ae)/auc
.
The units for the ae
and auc
should match such that ae/auc
has
units of volume/time.
The renal clearance as a number
Determine maximum observed PK concentration
pk.calc.cmax(conc, check = TRUE) pk.calc.cmin(conc, check = TRUE)
pk.calc.cmax(conc, check = TRUE) pk.calc.cmin(conc, check = TRUE)
conc |
Measured concentrations |
check |
Run |
a number for the maximum concentration or NA if all concentrations are missing
pk.calc.cmin()
: Determine the minimum observed PK
concentration
Other NCA parameters for concentrations during the intervals:
pk.calc.clast.obs()
,
pk.calc.count_conc()
,
pk.calc.cstart()
,
pk.calc.ctrough()
Other NCA parameters for concentrations during the intervals:
pk.calc.clast.obs()
,
pk.calc.count_conc()
,
pk.calc.cstart()
,
pk.calc.ctrough()
count_conc
is typically used for quality control on the data to ensure that
there are a sufficient number of non-missing samples for a calculation and to
ensure that data are consistent between individuals.
pk.calc.count_conc(conc, check = TRUE)
pk.calc.count_conc(conc, check = TRUE)
conc |
Measured concentrations |
check |
Run |
a count of the non-missing concentrations (0 if all concentrations are missing)
Other NCA parameters for concentrations during the intervals:
pk.calc.clast.obs()
,
pk.calc.cmax()
,
pk.calc.cstart()
,
pk.calc.ctrough()
Determine the concentration at the beginning of the interval
pk.calc.cstart(conc, time, start)
pk.calc.cstart(conc, time, start)
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
start |
The start time of the interval |
The concentration when time == end
. If none match, then NA
Other NCA parameters for concentrations during the intervals:
pk.calc.clast.obs()
,
pk.calc.cmax()
,
pk.calc.count_conc()
,
pk.calc.ctrough()
Determine the trough (end of interval) concentration
pk.calc.ctrough(conc, time, end)
pk.calc.ctrough(conc, time, end)
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
end |
The end time of the interval |
The concentration when time == end
. If none match, then NA
Other NCA parameters for concentrations during the intervals:
pk.calc.clast.obs()
,
pk.calc.cmax()
,
pk.calc.count_conc()
,
pk.calc.cstart()
Determine the degree of fluctuation
pk.calc.deg.fluc(cmax, cmin, cav)
pk.calc.deg.fluc(cmax, cmin, cav)
cmax |
The maximum observed concentration |
cmin |
The minimum observed concentration |
cav |
The average concentration in the interval |
deg.fluc is 100*(cmax - cmin)/cav
.
The degree of fluctuation around the average concentration.
Determine dose normalized NCA parameter
pk.calc.dn(parameter, dose)
pk.calc.dn(parameter, dose)
parameter |
Parameter to dose normalize |
dose |
Dose in units compatible with the area under the curve |
a number for dose normalized AUC
pk.calc.dn(90, 10)
pk.calc.dn(90, 10)
Calculate the absolute (or relative) bioavailability
pk.calc.f(dose1, auc1, dose2, auc2)
pk.calc.f(dose1, auc1, dose2, auc2)
dose1 |
The dose administered in route or method 1 |
auc1 |
The AUC from 0 to infinity or 0 to tau administered in route or method 1 |
dose2 |
The dose administered in route or method 2 |
auc2 |
The AUC from 0 to infinity or 0 to tau administered in route or method 2 |
f is (auc2/dose2)/(auc1/dose1)
.
Calculate fraction excreted (typically in urine or feces)
pk.calc.fe(ae, dose)
pk.calc.fe(ae, dose)
ae |
The amount excreted (as a numeric scalar or vector) |
dose |
The dose (as a numeric scalar or vector) |
fe is sum(ae)/dose
The units for ae
and dose
should be the same so that ae/dose
is a unitless fraction.
The fraction of dose excreted
The terminal elimination half-life is estimated from the final points in the
concentration-time curve using semi-log regression (log(conc)~time
)
with automated selection of the points for calculation (unless
manually.selected.points
is TRUE
).
pk.calc.half.life( conc, time, tmax, tlast, manually.selected.points = FALSE, options = list(), min.hl.points = NULL, adj.r.squared.factor = NULL, conc.blq = NULL, conc.na = NULL, first.tmax = NULL, allow.tmax.in.half.life = NULL, check = TRUE )
pk.calc.half.life( conc, time, tmax, tlast, manually.selected.points = FALSE, options = list(), min.hl.points = NULL, adj.r.squared.factor = NULL, conc.blq = NULL, conc.na = NULL, first.tmax = NULL, allow.tmax.in.half.life = NULL, check = TRUE )
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
tmax |
Time of maximum concentration (will be calculated and included in the return data frame if not given) |
tlast |
Time of last concentration above the limit of quantification (will be calculated and included in the return data frame if not given) |
manually.selected.points |
Have the input points ( |
options |
List of changes to the default PKNCA options (see
|
min.hl.points |
The minimum number of points that must be included to calculate the half-life |
adj.r.squared.factor |
The allowance in adjusted r-squared for adding another point. |
conc.blq |
See |
conc.na |
See |
first.tmax |
See |
allow.tmax.in.half.life |
Allow the concentration point for tmax to be included in the half-life slope calculation. |
check |
Run |
See the "Half-Life Calculation" vignette for more details on the calculation methods used.
If manually.selected.points
is FALSE
(default), the
half-life is calculated by computing the best fit line for all points at or
after tmax (based on the value of allow.tmax.in.half.life
). The best
half-life is chosen by the following rules in order:
At least min.hl.points
points included
A lambda.z
> 0 and at the same time the best adjusted r-squared
(within adj.r.squared.factor
)
The one with the most points included
If manually.selected.points
is TRUE
, the conc
and time
data are used as-is without any form of selection for
the best-fit half-life.
A data frame with one row and columns for
Time of maximum observed concentration (only included if not given as an input)
Time of last observed concentration above the LOQ (only included if not given as an input)
coefficient of determination
adjusted coefficient of determination
elimination rate
first time for half-life calculation
number of points in half-life calculation
Concentration at tlast as predicted by the half-life line
half-life
span ratio [ratio of half-life to time used for half-life calculation
Gabrielsson J, Weiner D. "Section 2.8.4 Strategies for estimation of lambda-z." Pharmacokinetic & Pharmacodynamic Data Analysis: Concepts and Applications, 4th Edition. Stockholm, Sweden: Swedish Pharmaceutical Press, 2000. 167-9.
Calculate the elimination rate (Kel)
pk.calc.kel(mrt)
pk.calc.kel(mrt)
mrt |
the mean residence time |
kel |
is |
the numeric value of the elimination rate
Calculate the mean residence time (MRT) for single-dose data or linear multiple-dose data.
pk.calc.mrt(auc, aumc) pk.calc.mrt.iv(auc, aumc, duration.dose)
pk.calc.mrt(auc, aumc) pk.calc.mrt.iv(auc, aumc, duration.dose)
auc |
the AUC from 0 to infinity or 0 to tau |
aumc |
the AUMC from 0 to infinity or 0 to tau |
duration.dose |
The duration of the dose (usually an infusion duration for an IV infusion) |
mrt is aumc/auc - duration.dose/2
where duration.dose = 0
for oral administration.
the numeric value of the mean residence time
pk.calc.mrt.iv()
: MRT for an IV infusion
Calculate the mean residence time (MRT) for multiple-dose data with nonlinear kinetics.
pk.calc.mrt.md(auctau, aumctau, aucinf, tau)
pk.calc.mrt.md(auctau, aumctau, aucinf, tau)
auctau |
the AUC from time 0 to the end of the dosing interval (tau). |
aumctau |
the AUMC from time 0 to the end of the dosing interval (tau). |
aucinf |
the AUC from time 0 to infinity (typically using single-dose data) |
tau |
The dosing interval |
mrt.md is aumctau/auctau + tau*(aucinf-auctau)/auctau
and should
only be used for multiple dosing with equal intervals between doses.
Note that if aucinf == auctau
(as would be the assumption with
linear kinetics), the equation becomes the same as the single-dose MRT.
Determine the peak-to-trough ratio
pk.calc.ptr(cmax, ctrough)
pk.calc.ptr(cmax, ctrough)
cmax |
The maximum observed concentration |
ctrough |
The last concentration in an interval |
ptr is cmax/ctrough
.
The ratio of cmax to ctrough (if ctrough == 0, NA)
The AUC is calculated as:
pk.calc.sparse_auc( conc, time, subject, method = NULL, auc.type = "AUClast", ..., options = list() ) pk.calc.sparse_auclast(conc, time, subject, ..., options = list())
pk.calc.sparse_auc( conc, time, subject, method = NULL, auc.type = "AUClast", ..., options = list() ) pk.calc.sparse_auclast(conc, time, subject, ..., options = list())
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
subject |
Subject identifiers (may be any class; may not be null) |
method |
The method for integration (one of 'lin up/log down', 'lin-log', or 'linear') |
auc.type |
The type of AUC to compute. Choices are 'AUCinf', 'AUClast', and 'AUCall'. |
... |
For functions other than |
options |
List of changes to the default PKNCA options (see
|
Where:
is the estimated area under the concentration-time curve
is the weight applied to the concentration at time i (related to the time which it affects, see sparse_auc_weight_linear()
)
is the average concentration at time i
pk.calc.sparse_auclast()
: Compute the AUClast for sparse PK
Other Sparse Methods:
as_sparse_pk()
,
sparse_auc_weight_linear()
,
sparse_mean()
Determine the PK swing
pk.calc.swing(cmax, cmin)
pk.calc.swing(cmax, cmin)
cmax |
The maximum observed concentration |
cmin |
The minimum observed concentration |
swing is 100*(cmax - cmin)/cmin
.
The swing above the minimum concentration. If cmin
is zero, then
the result is infinity.
Calculate the effective half-life
pk.calc.thalf.eff(mrt)
pk.calc.thalf.eff(mrt)
mrt |
the mean residence time to infinity |
thalf.eff is log(2)*mrt
.
the numeric value of the effective half-life
Interpolation is performed aligning with PKNCA.options("auc.method")
.
Extrapolation outside of the measured times is not yet implemented. The
method
may be changed by giving a named method
argument, as well.
pk.calc.time_above(conc, time, conc_above, ..., options = list(), check = TRUE)
pk.calc.time_above(conc, time, conc_above, ..., options = list(), check = TRUE)
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
conc_above |
The concentration to be above |
... |
Extra arguments. Currently, the only extra argument that is used
is |
options |
List of changes to the default PKNCA options (see
|
check |
Run |
For 'lin up/log down'
, if clast
is above conc_above
and there are
concentrations BLQ after that, linear down is used to extrapolate to the BLQ
concentration (equivalent to AUCall).
the time above the given concentration
Determine the observed lag time (time before the first concentration above the limit of quantification or above the first concentration in the interval)
pk.calc.tlag(conc, time)
pk.calc.tlag(conc, time)
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
The time associated with the first increasing concentration
NA
will be returned if all conc
are NA
or 0.
pk.calc.tlast(conc, time, check = TRUE) pk.calc.tfirst(conc, time, check = TRUE)
pk.calc.tlast(conc, time, check = TRUE) pk.calc.tfirst(conc, time, check = TRUE)
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
check |
Run |
The time of the last observed concentration measurement
pk.calc.tfirst()
: Determine the first concentration above
the limit of quantification.
Input restrictions are:
the conc
and time
must be the same length,
the time
may have no NAs,
NA
will be returned if:
the length of conc
and time
is 0
all conc
is 0 or NA
pk.calc.tmax(conc, time, options = list(), first.tmax = NULL, check = TRUE)
pk.calc.tmax(conc, time, options = list(), first.tmax = NULL, check = TRUE)
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
options |
List of changes to the default PKNCA options (see
|
first.tmax |
If there is more than time that matches the maximum concentration, should the first be considered as Tmax? If not, then the last is considered Tmax. |
check |
Run |
The time of the maximum concentration
Extract the dose used for calculations
pk.calc.totdose(dose)
pk.calc.totdose(dose)
dose |
the dose administered |
The total dose for an interval
Calculate the steady-state volume of distribution (Vss)
pk.calc.vss(cl, mrt)
pk.calc.vss(cl, mrt)
cl |
the clearance |
mrt |
the mean residence time |
vss is cl*mrt
.
the volume of distribution at steady-state
Calculate the terminal volume of distribution (Vz)
pk.calc.vz(cl, lambda.z)
pk.calc.vz(cl, lambda.z)
cl |
the clearance (or apparent observed clearance) |
lambda.z |
The elimination rate (in units of inverse time) for extrapolation |
vz is cl/lambda.z
.
The pk.nca
function computes the NCA parameters from a PKNCAdata
object.
All options for the calculation and input data are set in prior functions
(PKNCAconc
, PKNCAdose
, and PKNCAdata
). Options for calculations are
set either in PKNCAdata
or with the current default options in
PKNCA.options
.
pk.nca(data, verbose = FALSE)
pk.nca(data, verbose = FALSE)
data |
A PKNCAdata object |
verbose |
Indicate, by |
When performing calculations, all time results are relative to the start of
the interval. For example, if an interval starts at 168 hours, ends at 192
hours, and and the maximum concentration is at 169 hours, tmax=169-168=1
.
A PKNCAresults
object.
PKNCAdata()
, PKNCA.options()
, summary.PKNCAresults()
,
as.data.frame.PKNCAresults()
, exclude()
For one subject/time range, compute all available PK parameters. All the
internal options should be set by PKNCA.options()
prior to running. The
only part that changes with a call to this function is the conc
entration
and time
.
pk.nca.interval( conc, time, volume, duration.conc, dose, time.dose, duration.dose, route, conc.group = NULL, time.group = NULL, volume.group = NULL, duration.conc.group = NULL, dose.group = NULL, time.dose.group = NULL, duration.dose.group = NULL, route.group = NULL, impute_method = NA_character_, include_half.life = NULL, exclude_half.life = NULL, subject, sparse, interval, options = list() )
pk.nca.interval( conc, time, volume, duration.conc, dose, time.dose, duration.dose, route, conc.group = NULL, time.group = NULL, volume.group = NULL, duration.conc.group = NULL, dose.group = NULL, time.dose.group = NULL, duration.dose.group = NULL, route.group = NULL, impute_method = NA_character_, include_half.life = NULL, exclude_half.life = NULL, subject, sparse, interval, options = list() )
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
volume , volume.group
|
The volume (or mass) of the concentration measurement for the current interval or all data for the group (typically for urine and fecal measurements) |
duration.conc , duration.conc.group
|
The duration of the concentration measurement for the current interval or all data for the group (typically for urine and fecal measurements) |
dose , dose.group
|
Dose amount (may be a scalar or vector) for the current interval or all data for the group |
time.dose , time.dose.group
|
Time of the dose for the current interval or
all data for the group (must be the same length as |
duration.dose , duration.dose.group
|
The duration of the dose administration for the current interval or all data for the group (typically zero for extravascular and intravascular bolus and nonzero for intravascular infusion) |
route , route.group
|
The route of dosing for the current interval or all data for the group |
conc.group |
All concentrations measured for the group |
time.group |
Time of all concentrations measured for the group |
impute_method |
The method to use for imputation as a character string |
include_half.life |
An optional boolean vector of the concentration measurements to include in the half-life calculation. If given, no half-life point selection will occur. |
exclude_half.life |
An optional boolean vector of the concentration measurements to exclude from the half-life calculation. |
subject |
Subject identifiers (used for sparse calculations) |
sparse |
Should only sparse calculations be performed (TRUE) or only dense calculations (FALSE)? |
interval |
One row of an interval definition (see
|
options |
List of changes to the default PKNCA options (see
|
A data frame with the start and end time along with all PK
parameters for the interval
check.interval.specification()
Compute NCA for multiple intervals
pk.nca.intervals( data_conc, data_dose, data_intervals, sparse, options, impute, verbose = FALSE )
pk.nca.intervals( data_conc, data_dose, data_intervals, sparse, options, impute, verbose = FALSE )
data_conc |
A data.frame or tibble with standardized column names as
output from |
data_dose |
A data.frame or tibble with standardized column names as
output from |
data_intervals |
A data.frame or tibble with standardized column names
as output from |
sparse |
Should only sparse calculations be performed (TRUE) or only dense calculations (FALSE)? |
options |
List of changes to the default PKNCA options (see
|
impute |
The column name in |
verbose |
Indicate, by |
A data.frame with all NCA results
Compute the time to steady-state (tss)
pk.tss(..., type = c("monoexponential", "stepwise.linear"), check = TRUE)
pk.tss(..., type = c("monoexponential", "stepwise.linear"), check = TRUE)
... |
Passed to |
type |
The type of Tss to calculate, either |
check |
A data frame with columns as defined from pk.tss.monoexponential
and/or pk.tss.stepwise.linear
.
Other Time to steady-state calculations:
pk.tss.monoexponential()
,
pk.tss.stepwise.linear()
Clean up the time to steady-state parameters and return a data frame for use by the tss calculators.
pk.tss.data.prep( conc, time, subject, treatment, subject.dosing, time.dosing, options = list(), conc.blq = NULL, conc.na = NULL, check = TRUE, ... )
pk.tss.data.prep( conc, time, subject, treatment, subject.dosing, time.dosing, options = list(), conc.blq = NULL, conc.na = NULL, check = TRUE, ... )
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
subject |
Subject identifiers (used as a random effect in the model) |
treatment |
Treatment description (if missing, all subjects are assumed to be on the same treatment) |
subject.dosing |
Subject number for dosing |
time.dosing |
Time of dosing |
options |
List of changes to the default PKNCA options (see
|
conc.blq |
See |
conc.na |
See |
check |
Run |
... |
Discarded inputs to allow generic calls between tss methods. |
a data frame with columns for conc
entration, time
, subject
,
and treatment
.
Trough concentrations are selected as concentrations at the time of dosing.
An exponential curve is then fit through the data with a different magnitude
by treatment (as a factor) and a random steady-state concentration and time
to stead-state by subject (see random.effects
argument).
pk.tss.monoexponential( ..., tss.fraction = 0.9, output = c("population", "popind", "individual", "single"), check = TRUE, verbose = FALSE )
pk.tss.monoexponential( ..., tss.fraction = 0.9, output = c("population", "popind", "individual", "single"), check = TRUE, verbose = FALSE )
... |
|
tss.fraction |
The fraction of steady-state required for calling steady-state |
output |
Which types of outputs should be produced? |
check |
See |
verbose |
Describe models as they are run, show convergence of the model (passed to the nlme function), and additional details while running. |
A scalar float for the first time when steady-state is achieved or
NA
if it is not observed.
Maganti, L., Panebianco, D.L. & Maes, A.L. Evaluation of Methods for Estimating Time to Steady State with Examples from Phase 1 Studies. AAPS J 10, 141–147 (2008). https://doi.org/10.1208/s12248-008-9014-y
Other Time to steady-state calculations:
pk.tss()
,
pk.tss.stepwise.linear()
This function is not intended to be called directly. Please use
pk.tss.monoexponential
.
pk.tss.monoexponential.individual( data, output = c("individual", "single"), verbose = FALSE )
pk.tss.monoexponential.individual( data, output = c("individual", "single"), verbose = FALSE )
data |
a data frame as prepared by |
output |
a character vector requesting the output types. |
verbose |
Show verbose output. |
If no model converges, then the tss.monoexponential.single
and/or
tss.monoexponential.individual
column will be set to NA.
A data frame with either one row (if population
output is
provided) or one row per subject (if popind
is provided). The columns
will be named tss.monoexponential.population
and/or
tss.monoexponential.popind
.
This function is not intended to be called directly. Please use
pk.tss.monoexponential
.
pk.tss.monoexponential.population( data, output = c("population", "popind"), verbose = FALSE )
pk.tss.monoexponential.population( data, output = c("population", "popind"), verbose = FALSE )
data |
a data frame as prepared by |
output |
a character vector requesting the output types. |
verbose |
Show verbose output. |
If no model converges, then the tss.monoexponential.population
column will
be set to NA. If the best model does not include a random effect for subject
on Tss then the tss.monoexponential.popind
column of the output will be set
to NA.
A data frame with either one row (if population
output is
provided) or one row per subject (if popind
is provided). The columns
will be named tss.monoexponential.population
and/or
tss.monoexponential.popind
.
A linear slope is fit through the data to find when it becomes
non-significant. Note that this is less preferred than the
pk.tss.monoexponential
due to the fact that with more time or more subjects
the performance of the test changes (see reference).
pk.tss.stepwise.linear( ..., min.points = 3, level = 0.95, verbose = FALSE, check = TRUE )
pk.tss.stepwise.linear( ..., min.points = 3, level = 0.95, verbose = FALSE, check = TRUE )
... |
|
min.points |
The minimum number of points required for the fit |
level |
The confidence level required for assessment of steady-state |
verbose |
Describe models as they are run, show convergence of the model (passed to the nlme function), and additional details while running. |
check |
The model is fit with a different magnitude by treatment (as a factor, if
given) and a random slope by subject (if given). A minimum of min.points
is required to fit the model.
A scalar float for the first time when steady-state is achieved or
NA
if it is not observed.
Maganti L, Panebianco DL, Maes AL. Evaluation of Methods for Estimating Time to Steady State with Examples from Phase 1 Studies. AAPS Journal 10(1):141-7. doi:10.1208/s12248-008-9014-y
Other Time to steady-state calculations:
pk.tss()
,
pk.tss.monoexponential()
Compute pharmacokinetic (PK) noncompartmental analysis (NCA) parameters.
PKNCA has been cross-validated with both Phoenix WinNonlin(R) and Pumas (click here for the cross-validation article)
A common workflow would load data from a file or database into a data.frame then run the following code.
Maintainer: Bill Denney [email protected] (ORCID)
Authors:
Clare Buckeridge [email protected]
Other contributors:
Sridhar Duvvuri [contributor]
Useful links:
Report bugs at https://github.com/billdenney/pknca/issues
## Not run: # Load concentration-time data into a data.frame called d.conc # with columns named "conc", "time", and "subject". my.conc <- PKNCAconc(d.conc, conc~time|subject) # Load dose-time data into a data.frame called d.dose # with columns named "dose", "time", and "subject". my.dose <- PKNCAdose(d.dose, dose~time|subject) # Combine the concentration-time and dose-time data into an object # ready for calculations. my.data <- PKNCAdata(my.conc, my.dose) # Perform the calculations my.results <- pk.nca(my.data) # Look at summary results summary(my.results) # Look at a listing of results as.data.frame(my.results) ## End(Not run)
## Not run: # Load concentration-time data into a data.frame called d.conc # with columns named "conc", "time", and "subject". my.conc <- PKNCAconc(d.conc, conc~time|subject) # Load dose-time data into a data.frame called d.dose # with columns named "dose", "time", and "subject". my.dose <- PKNCAdose(d.dose, dose~time|subject) # Combine the concentration-time and dose-time data into an object # ready for calculations. my.data <- PKNCAdata(my.conc, my.dose) # Perform the calculations my.results <- pk.nca(my.data) # Look at summary results summary(my.results) # Look at a listing of results as.data.frame(my.results) ## End(Not run)
Find NCA parameters with a given unit type
pknca_find_units_param(unit_type)
pknca_find_units_param(unit_type)
unit_type |
The type of unit as assigned with |
A character vector of parameters with a given unit type
An error will be raised if the functions are not found.
PKNCA_impute_fun_list(x)
PKNCA_impute_fun_list(x)
x |
The character vector of PKNCA imputation method functions (without
the |
This function is not for use by users of PKNCA.
A list of character vectors of functions to run.
Methods for imputation of data with PKNCA
PKNCA_impute_method_start_conc0(conc, time, start = 0, ..., options = list()) PKNCA_impute_method_start_cmin(conc, time, start, end, ..., options = list()) PKNCA_impute_method_start_predose( conc, time, start, end, conc.group, time.group, ..., max_shift = NA_real_, options = list() )
PKNCA_impute_method_start_conc0(conc, time, start = 0, ..., options = list()) PKNCA_impute_method_start_cmin(conc, time, start, end, ..., options = list()) PKNCA_impute_method_start_predose( conc, time, start, end, conc.group, time.group, ..., max_shift = NA_real_, options = list() )
conc |
Measured concentrations |
time |
Time of the measurement of the concentrations |
start |
The start time of the interval |
... |
ignored |
options |
List of changes to the default PKNCA options (see
|
end |
The end time of the interval |
conc.group |
All concentrations measured for the group |
time.group |
Time of all concentrations measured for the group |
max_shift |
The maximum amount of time to shift a concentration forward
(defaults to 5% of the interval duration, i.e. |
A data.frame with one column named conc with imputed concentrations and one column named time with the times.
PKNCA_impute_method_start_conc0()
: Add a new concentration of 0 at the start
time, even if a nonzero concentration exists at that time (usually used
with single-dose data)
PKNCA_impute_method_start_cmin()
: Add a new concentration of the minimum during
the interval at the start time (usually used with multiple-dose data)
PKNCA_impute_method_start_predose()
: Shift a predose concentration to become the
time zero concentration (only if a time zero concentration does not exist)
Perform unit conversion (if possible) on PKNCA results
pknca_unit_conversion(result, units)
pknca_unit_conversion(result, units)
result |
The results data.frame |
units |
The unit conversion table |
The result table with units converted
Add parentheses to a unit value, if needed
pknca_units_add_paren(unit)
pknca_units_add_paren(unit)
unit |
The text of the unit |
The unit with parentheses around it, if needed
This data.frame is typically used for the units
argument for PKNCAdata()
.
If a unit is not given, then all of the units derived from that unit will be
NA
.
pknca_units_table( concu, doseu, amountu, timeu, concu_pref = NULL, doseu_pref = NULL, amountu_pref = NULL, timeu_pref = NULL, conversions = data.frame() )
pknca_units_table( concu, doseu, amountu, timeu, concu_pref = NULL, doseu_pref = NULL, amountu_pref = NULL, timeu_pref = NULL, conversions = data.frame() )
concu , doseu , amountu , timeu
|
Units for concentration, dose, amount, and time in the source data |
concu_pref , doseu_pref , amountu_pref , timeu_pref
|
Preferred units for
reporting; |
conversions |
An optional data.frame with columns of c("PPORRESU",
"PPSTRESU", "conversion_factor") for the original calculation units, the
standardized units, and a conversion factor to multiply the initial value
by to get a standardized value. This argument overrides any preferred unit
conversions from |
A unit conversion table with columns for "PPTESTCD" and "PPORRESU"
if conversions
is not given, and adding "PPSTRESU" and
"conversion_factor" if conversions
is given.
The units
argument for PKNCAdata()
pknca_units_table() # only parameters that are unitless pknca_units_table( concu="ng/mL", doseu="mg/kg", amountu="mg", timeu="hr" ) pknca_units_table( concu="ng/mL", doseu="mg/kg", amountu="mg", timeu="hr", # Convert clearance and volume units to more understandable units with # automatic unit conversion conversions=data.frame( PPORRESU=c("(mg/kg)/(hr*ng/mL)", "(mg/kg)/(ng/mL)"), PPSTRESU=c("mL/hr/kg", "mL/kg") ) ) pknca_units_table( concu="mg/L", doseu="mg/kg", amountu="mg", timeu="hr", # Convert clearance and volume units to molar units (assuming conversions=data.frame( PPORRESU=c("mg/L", "(mg/kg)/(hr*ng/mL)", "(mg/kg)/(ng/mL)"), PPSTRESU=c("mmol/L", "mL/hr/kg", "mL/kg"), # Manual conversion of concentration units from ng/mL to mmol/L (assuming # a molecular weight of 138.121 g/mol) conversion_factor=c(1/138.121, NA, NA) ) ) # This will make all time-related parameters use "day" even though the # original units are "hr" pknca_units_table( concu = "ng/mL", doseu = "mg/kg", timeu = "hr", amountu = "mg", timeu_pref = "day" )
pknca_units_table() # only parameters that are unitless pknca_units_table( concu="ng/mL", doseu="mg/kg", amountu="mg", timeu="hr" ) pknca_units_table( concu="ng/mL", doseu="mg/kg", amountu="mg", timeu="hr", # Convert clearance and volume units to more understandable units with # automatic unit conversion conversions=data.frame( PPORRESU=c("(mg/kg)/(hr*ng/mL)", "(mg/kg)/(ng/mL)"), PPSTRESU=c("mL/hr/kg", "mL/kg") ) ) pknca_units_table( concu="mg/L", doseu="mg/kg", amountu="mg", timeu="hr", # Convert clearance and volume units to molar units (assuming conversions=data.frame( PPORRESU=c("mg/L", "(mg/kg)/(hr*ng/mL)", "(mg/kg)/(ng/mL)"), PPSTRESU=c("mmol/L", "mL/hr/kg", "mL/kg"), # Manual conversion of concentration units from ng/mL to mmol/L (assuming # a molecular weight of 138.121 g/mol) conversion_factor=c(1/138.121, NA, NA) ) ) # This will make all time-related parameters use "day" even though the # original units are "hr" pknca_units_table( concu = "ng/mL", doseu = "mg/kg", timeu = "hr", amountu = "mg", timeu_pref = "day" )
Choose either the value from an option list or the current set value for an option.
PKNCA.choose.option(name, value = NULL, options = list())
PKNCA.choose.option(name, value = NULL, options = list())
name |
The option name requested. |
value |
A value to check for the option ( |
options |
List of changes to the default PKNCA options (see
|
The value of the option first from the options
list and if it is
not there then from the current settings.
Other PKNCA calculation and summary settings:
PKNCA.options()
,
PKNCA.set.summary()
This function will set the default PKNCA options. If given no inputs, it
will provide the current option set. If given name/value pairs, it will set
the option (as in the options()
function). If given a name, it will return
the value for the parameter. If given the default
option as true, it will
provide the default options.
PKNCA.options(..., default = FALSE, check = FALSE, name, value)
PKNCA.options(..., default = FALSE, check = FALSE, name, value)
... |
options to set or get the value for |
default |
(re)sets all default options |
check |
check a single option given, but do not set it (for validation of the values when used in another function) |
name |
An option name to use with the |
value |
An option value (paired with the |
Options are either for calculation or summary functions. Calculation options
are required for a calculation function to report a result (otherwise the
reported value will be NA
). Summary options are used during summarization
and are used for assessing what values are included in the summary.
See the vignette 'Options for Controlling PKNCA' for a current list of
options (vignette("Options-for-Controlling-PKNCA", package="PKNCA")
).
If...
returns the current options.
returns NULL
the current value of that option is returned as a scalar
the current values of those options are returned as a list
Other PKNCA calculation and summary settings:
PKNCA.choose.option()
,
PKNCA.set.summary()
PKNCA.options() PKNCA.options(default=TRUE) PKNCA.options("auc.method") PKNCA.options(name="auc.method") PKNCA.options(auc.method="lin up/log down", min.hl.points=3)
PKNCA.options() PKNCA.options(default=TRUE) PKNCA.options("auc.method") PKNCA.options(name="auc.method") PKNCA.options(auc.method="lin up/log down", min.hl.points=3)
Describe a PKNCA.options option by name.
PKNCA.options.describe(name)
PKNCA.options.describe(name)
name |
The option name requested. |
A character string of the description.
Define how NCA parameters are summarized.
PKNCA.set.summary( name, description, point, spread, rounding = list(signif = 3), reset = FALSE )
PKNCA.set.summary( name, description, point, spread, rounding = list(signif = 3), reset = FALSE )
name |
The parameter name or a vector of parameter names. It must have
already been defined (see |
description |
A single-line description of the summary |
point |
The function to calculate the point estimate for the summary.
The function will be called as |
spread |
Optional. The function to calculate the spread (or
variability). The function will be called as |
rounding |
Instructions for how to round the value of point and spread. It may either be a list or a function. If it is a list, then it must have a single entry with a name of either "signif" or "round" and a value of the digits to round. If a function, it is expected to return a scalar number or character string with the correct results for an input of either a scalar or a two-long vector. |
reset |
Reset all the summary instructions |
All current summary settings (invisibly)
Other PKNCA calculation and summary settings:
PKNCA.choose.option()
,
PKNCA.options()
## Not run: PKNCA.set.summary( name="half.life", description="arithmetic mean and standard deviation", point=business.mean, spread=business.sd, rounding=list(signif=3) ) ## End(Not run)
## Not run: PKNCA.set.summary( name="half.life", description="arithmetic mean and standard deviation", point=business.mean, spread=business.sd, rounding=list(signif=3) ) ## End(Not run)
Create a PKNCAconc object
PKNCAconc(data, ...) ## Default S3 method: PKNCAconc(data, ...) ## S3 method for class 'tbl_df' PKNCAconc(data, ...) ## S3 method for class 'data.frame' PKNCAconc( data, formula, subject, time.nominal, exclude = NULL, duration, volume, exclude_half.life, include_half.life, sparse = FALSE, ... )
PKNCAconc(data, ...) ## Default S3 method: PKNCAconc(data, ...) ## S3 method for class 'tbl_df' PKNCAconc(data, ...) ## S3 method for class 'data.frame' PKNCAconc( data, formula, subject, time.nominal, exclude = NULL, duration, volume, exclude_half.life, include_half.life, sparse = FALSE, ... )
data |
A data frame with concentration (or amount for urine/feces),
time, and the groups defined in |
... |
Ignored. |
formula |
The formula defining the |
subject |
The column indicating the subject number. If not provided,
this defaults to the beginning of the inner groups: For example with
|
time.nominal |
(optional) The name of the nominal time column (if the
main time variable is actual time. The |
exclude |
(optional) The name of a column with concentrations to exclude
from calculations and summarization. If given, the column should have
values of |
duration |
(optional) The duration of collection as is typically used for concentration measurements in urine or feces. |
volume |
(optional) The volume (or mass) of collection as is typically used for urine or feces measurements. |
exclude_half.life , include_half.life
|
A character scalar for the column name in the dataset of the points to exclude from the half-life calculation (still using normal curve-stripping selection rules for the other points) or to include for the half-life (using specifically those points and bypassing automatic curve-stripping point selection). See the "Half-Life Calculation" vignette for more details on the use of these arguments. |
sparse |
Are the concentration-time data sparse PK (commonly used in small nonclinical species or with terminal or difficult sampling) or dense PK (commonly used in clinical studies or larger nonclinical species)? |
A PKNCAconc object that can be used for automated NCA.
Other PKNCA objects:
PKNCAdata()
,
PKNCAdose()
,
PKNCAresults()
PKNCAdata()
combines PKNCAconc
and PKNCAdose
objects and adds in the
intervals for PK calculations.
PKNCAdata(data.conc, data.dose, ...) ## S3 method for class 'PKNCAconc' PKNCAdata(data.conc, data.dose, ...) ## S3 method for class 'PKNCAdose' PKNCAdata(data.conc, data.dose, ...) ## Default S3 method: PKNCAdata( data.conc, data.dose, ..., formula.conc, formula.dose, impute = NA_character_, intervals, units, options = list() )
PKNCAdata(data.conc, data.dose, ...) ## S3 method for class 'PKNCAconc' PKNCAdata(data.conc, data.dose, ...) ## S3 method for class 'PKNCAdose' PKNCAdata(data.conc, data.dose, ...) ## Default S3 method: PKNCAdata( data.conc, data.dose, ..., formula.conc, formula.dose, impute = NA_character_, intervals, units, options = list() )
data.conc |
Concentration data as a |
data.dose |
Dosing data as a |
... |
arguments passed to |
formula.conc |
Formula for making a |
formula.dose |
Formula for making a |
impute |
Methods for imputation. |
intervals |
A data frame with the AUC interval specifications as defined
in |
units |
A data.frame of unit assignments and conversions as created by
|
options |
List of changes to the default PKNCA options (see
|
If data.dose
is not given or is NA
, then the intervals
must be
given. At least one of data.dose
and intervals
must be given.
A PKNCAdata object with concentration, dose, interval, and calculation options stored (note that PKNCAdata objects can also have results after a NCA calculations are done to the data).
choose.auc.intervals()
, pk.nca()
, pknca_units_table()
Other PKNCA objects:
PKNCAconc()
,
PKNCAdose()
,
PKNCAresults()
Create a PKNCAdose object
PKNCAdose(data, ...) ## Default S3 method: PKNCAdose(data, ...) ## S3 method for class 'tbl_df' PKNCAdose(data, ...) ## S3 method for class 'data.frame' PKNCAdose( data, formula, route, rate, duration, time.nominal, exclude = NULL, ... )
PKNCAdose(data, ...) ## Default S3 method: PKNCAdose(data, ...) ## S3 method for class 'tbl_df' PKNCAdose(data, ...) ## S3 method for class 'data.frame' PKNCAdose( data, formula, route, rate, duration, time.nominal, exclude = NULL, ... )
data |
A data frame with time and the groups defined in |
... |
Ignored. |
formula |
The formula defining the |
route |
Define the route of administration. The value may be either a
column name from the |
rate , duration
|
(optional) for |
time.nominal |
(optional) The name of the nominal time column (if the
main time variable is actual time. The |
exclude |
(optional) The name of a column with concentrations to exclude
from calculations and summarization. If given, the column should have
values of |
The formula
for a PKNCAdose
object can be
given three ways: one-sided (missing left side), one-sided (missing
right side), or two-sided. Each of the three ways can be given
with or without groups. When given one-sided missing the left
side, the left side can either be omitted or can be given as a
period (.
): ~time|treatment+subject
and
.~time|treatment+subject
are identical, and dose-related NCA
parameters will all be reported as not calculable (for example,
clearance). When given one-sided missing the right side, the right
side must be specified as a period (.
):
dose~.|treatment+subject
, and only a single row may be given
per group. When the right side is missing, PKNCA assumes that the
same dose is given in every interval. When given as a two-sided
formula
A PKNCAconc object that can be used for automated NCA.
Other PKNCA objects:
PKNCAconc()
,
PKNCAdata()
,
PKNCAresults()
This function should not be run directly. The object is created for summarization.
PKNCAresults(result, data, exclude = NULL)
PKNCAresults(result, data, exclude = NULL)
result |
a data frame with NCA calculation results and groups. Each row is one interval and each column is a group name or the name of an NCA parameter. |
data |
The PKNCAdata used to generate the result |
exclude |
(optional) The name of a column with concentrations to exclude
from calculations and summarization. If given, the column should have
values of |
A PKNCAresults object with each of the above within.
Other PKNCA objects:
PKNCAconc()
,
PKNCAdata()
,
PKNCAdose()
Print and/or summarize a PKNCAconc or PKNCAdose object.
## S3 method for class 'PKNCAconc' print(x, n = 6, summarize = FALSE, ...) ## S3 method for class 'PKNCAconc' summary(object, n = 0, summarize = TRUE, ...) ## S3 method for class 'PKNCAdose' print(x, n = 6, summarize = FALSE, ...) ## S3 method for class 'PKNCAdose' summary(object, n = 0, summarize = TRUE, ...)
## S3 method for class 'PKNCAconc' print(x, n = 6, summarize = FALSE, ...) ## S3 method for class 'PKNCAconc' summary(object, n = 0, summarize = TRUE, ...) ## S3 method for class 'PKNCAdose' print(x, n = 6, summarize = FALSE, ...) ## S3 method for class 'PKNCAdose' summary(object, n = 0, summarize = TRUE, ...)
x |
The object to print |
n |
The number of rows of data to show (see
|
summarize |
Summarize the nested number of groups |
... |
Arguments passed to |
object |
The object to summarize |
Print a PKNCAdata object
## S3 method for class 'PKNCAdata' print(x, ...)
## S3 method for class 'PKNCAdata' print(x, ...)
x |
The object to print |
... |
Arguments passed on to |
Print the summary of a provenance object
## S3 method for class 'provenance' print(x, ...)
## S3 method for class 'provenance' print(x, ...)
x |
The object to be printed |
... |
Ignored |
invisible text of the printed information
Print the results summary
## S3 method for class 'summary_PKNCAresults' print(x, ...)
## S3 method for class 'summary_PKNCAresults' print(x, ...)
x |
A summary_PKNCAresults object |
... |
passed to print.data.frame ( |
x
invisibly
During the summarization of PKNCAresults, do the rounding of values based on the instructions given.
roundingSummarize(x, name)
roundingSummarize(x, name)
x |
The values to summarize |
name |
The NCA parameter name (matching a parameter name in
|
A string of the rounded value
Round a value to a defined number of digits printing out trailing zeros, if applicable.
roundString(x, digits = 0, sci_range = Inf, sci_sep = "e", si_range)
roundString(x, digits = 0, sci_range = Inf, sci_sep = "e", si_range)
x |
The number to round |
digits |
integer indicating the number of decimal places |
sci_range |
See help for |
sci_sep |
The separator to use for scientific notation strings (typically this will be either "e" or "x10^" for computer- or human-readable output). |
si_range |
Deprecated, please use |
Values that are not standard numbers like Inf
, NA
, and
NaN
are returned as "Inf"
, "NA"
, and NaN
.
A string with the value
Takes in two objects, the PKNCAdata object and the proposed intervals. It will then check that the intervals are valid, given the data object. If the intervals are valid, it will set them in the object. It will return the data object with the intervals set.
set_intervals(data, intervals)
set_intervals(data, intervals)
data |
PKNCAdata object |
intervals |
Proposed intervals |
The data object with the intervals set.
Add an attribute to an object where the attribute is added as a name to the names of the object.
setAttributeColumn( object, attr_name, col_or_value, col_name, default_value, stop_if_default, warn_if_default, message_if_default )
setAttributeColumn( object, attr_name, col_or_value, col_name, default_value, stop_if_default, warn_if_default, message_if_default )
object |
The object to set the attribute column on. |
attr_name |
The attribute name to set |
col_or_value |
If this exists as a column in the data, it is used as the
|
col_name |
The name of the column within the dataset to use (if missing,
uses |
default_value |
The value to fill in the column if the column does not
exist (the column is filled with |
stop_if_default , warn_if_default , message_if_default
|
A character string
to provide as an error, a warning, or a message to the user if the
|
The object with the attribute column added to the data.
Set the duration of dosing or measurement
## S3 method for class 'PKNCAconc' setDuration(object, duration, ...) setDuration(object, ...) ## S3 method for class 'PKNCAdose' setDuration(object, duration, rate, dose, ...)
## S3 method for class 'PKNCAconc' setDuration(object, duration, ...) setDuration(object, ...) ## S3 method for class 'PKNCAdose' setDuration(object, duration, rate, dose, ...)
object |
An object to set a duration on |
duration |
The value to set for the duration or the name of the column in the data to use for the duration. |
... |
Arguments passed to another setDuration function |
rate |
(for PKNCAdose objects only) The rate of infusion |
dose |
(for PKNCAdose objects only) The dose amount |
The object with duration set
This function adds the exclude column to an object. To change the
exclude value, use the exclude()
function.
setExcludeColumn(object, exclude = NULL, dataname = "data")
setExcludeColumn(object, exclude = NULL, dataname = "data")
object |
The object to set the exclude column on. |
exclude |
The column name to set as the exclude value. |
dataname |
The name of the data.frame within the object to add the exclude column to. |
The object with an exclude column and attribute
Set the dosing route
setRoute(object, ...) ## S3 method for class 'PKNCAdose' setRoute(object, route, ...)
setRoute(object, ...) ## S3 method for class 'PKNCAdose' setRoute(object, route, ...)
object |
A PKNCAdose object |
... |
Arguments passed to another setRoute function |
route |
A character string indicating one of the following: the column from the data which indicates the route of administration, a scalar indicating the route of administration for all subjects, or a vector indicating the route of administration for each dose in the dataset. |
The object with an updated route
Round a value to a defined number of significant digits printing out trailing zeros, if applicable.
signifString(x, ...) ## S3 method for class 'data.frame' signifString(x, ...) ## Default S3 method: signifString(x, digits = 6, sci_range = 6, sci_sep = "e", si_range, ...)
signifString(x, ...) ## S3 method for class 'data.frame' signifString(x, ...) ## Default S3 method: signifString(x, digits = 6, sci_range = 6, sci_sep = "e", si_range, ...)
x |
The number to round |
... |
Arguments passed to methods. |
digits |
integer indicating the number of significant digits |
sci_range |
integer (or |
sci_sep |
The separator to use for scientific notation strings (typically this will be either "e" or "x10^" for computer- or human-readable output). |
si_range |
Deprecated, please use |
Values that are not standard numbers like Inf
, NA
, and
NaN
are returned as "Inf"
, "NA"
, and NaN
.
A string with the value
Columns are always to the right of columns that they depend on.
## S3 method for class 'interval.cols' sort()
## S3 method for class 'interval.cols' sort()
The weight is used as the parameter in
pk.calc.sparse_auc()
sparse_auc_weight_linear(sparse_pk)
sparse_auc_weight_linear(sparse_pk)
sparse_pk |
A sparse_pk object from |
Where:
is the weight at time i
and
are the changes between time i-1 and i or i and i+1 (zero outside of the time range)
is the time at time i
A numeric vector of weights for sparse AUC calculations the same
length as sparse_pk
Other Sparse Methods:
as_sparse_pk()
,
pk.calc.sparse_auc()
,
sparse_mean()
Choices for the method of calculation (the argument sparse_mean_method
)
are:
sparse_mean( sparse_pk, sparse_mean_method = c("arithmetic mean, <=50% BLQ", "arithmetic mean") )
sparse_mean( sparse_pk, sparse_mean_method = c("arithmetic mean, <=50% BLQ", "arithmetic mean") )
sparse_pk |
A sparse_pk object from |
sparse_mean_method |
The method used to calculate the sparse mean (see details) |
Arithmetic mean (ignoring number of BLQ samples)
If >= 50% of the measurements are BLQ, zero. Otherwise, the arithmetic mean of all samples (including the BLQ as zero).
A vector the same length as sparse_pk
with the mean concentration
at each of those times.
Other Sparse Methods:
as_sparse_pk()
,
pk.calc.sparse_auc()
,
sparse_auc_weight_linear()
Set or get a sparse_pk object attribute
sparse_pk_attribute(sparse_pk, ...)
sparse_pk_attribute(sparse_pk, ...)
sparse_pk |
A sparse_pk object from |
... |
Either a character string (to get that value) or a named vector
the same length as |
Either the attribute value or an updated sparse_pk
object
Extract the mean concentration-time profile as a data.frame
sparse_to_dense_pk(sparse_pk)
sparse_to_dense_pk(sparse_pk)
sparse_pk |
A sparse_pk object from |
A data.frame with names of "conc" and "time"
Summarize a PKNCAdata object showing important details about the concentration, dosing, and interval information.
## S3 method for class 'PKNCAdata' summary(object, ...)
## S3 method for class 'PKNCAdata' summary(object, ...)
object |
The PKNCAdata object to summarize. |
... |
arguments passed on to |
Summarize PKNCA results
## S3 method for class 'PKNCAresults' summary( object, ..., drop_group = object$data$conc$columns$subject, drop_param = character(), summarize_n = NA, not_requested = ".", not_calculated = "NC", drop.group = deprecated(), summarize.n.per.group = deprecated(), not.requested.string = deprecated(), not.calculated.string = deprecated(), pretty_names = NULL )
## S3 method for class 'PKNCAresults' summary( object, ..., drop_group = object$data$conc$columns$subject, drop_param = character(), summarize_n = NA, not_requested = ".", not_calculated = "NC", drop.group = deprecated(), summarize.n.per.group = deprecated(), not.requested.string = deprecated(), not.calculated.string = deprecated(), pretty_names = NULL )
object |
The results to summarize |
... |
Ignored. |
drop_group |
Which group(s) should be dropped from the formula? |
drop_param |
Which parameters should be excluded from the summary? |
summarize_n |
Should a column for |
not_requested |
A character string to use when a parameter summary was not requested for a parameter within an interval. |
not_calculated |
A character string to use when a parameter summary was
requested, but the point estimate AND spread calculations (if applicable)
returned |
drop.group , summarize.n.per.group , not.requested.string , not.calculated.string
|
Deprecated use |
pretty_names |
Should pretty names (easier to understand in a report) be
used? |
Excluded results will not be included in the summary.
A data frame of NCA parameter results summarized according to the summarization settings.
PKNCA.set.summary()
, print.summary_PKNCAresults()
conc_obj <- PKNCAconc(as.data.frame(datasets::Theoph), conc ~ Time | Subject) d_dose <- unique(datasets::Theoph[ datasets::Theoph$Time == 0, c("Dose", "Time", "Subject") ]) dose_obj <- PKNCAdose(d_dose, Dose ~ Time | Subject) data_obj_automatic <- PKNCAdata(conc_obj, dose_obj) results_obj_automatic <- pk.nca(data_obj_automatic) # To get standard results run summary summary(results_obj_automatic) # To enable numeric conversion and extraction, do not give a spread function # and subsequently run as.numeric on the result columns. PKNCA.set.summary( name = c("auclast", "cmax", "half.life", "aucinf.obs"), point = business.geomean, description = "geometric mean" ) PKNCA.set.summary( name = c("tmax"), point = business.median, description = "median" ) summary(results_obj_automatic, not_requested = "NA")
conc_obj <- PKNCAconc(as.data.frame(datasets::Theoph), conc ~ Time | Subject) d_dose <- unique(datasets::Theoph[ datasets::Theoph$Time == 0, c("Dose", "Time", "Subject") ]) dose_obj <- PKNCAdose(d_dose, Dose ~ Time | Subject) data_obj_automatic <- PKNCAdata(conc_obj, dose_obj) results_obj_automatic <- pk.nca(data_obj_automatic) # To get standard results run summary summary(results_obj_automatic) # To enable numeric conversion and extraction, do not give a spread function # and subsequently run as.numeric on the result columns. PKNCA.set.summary( name = c("auclast", "cmax", "half.life", "aucinf.obs"), point = business.geomean, description = "geometric mean" ) PKNCA.set.summary( name = c("tmax"), point = business.median, description = "median" ) summary(results_obj_automatic, not_requested = "NA")
Compute noncompartmental superposition for repeated dosing
superposition(conc, ...) ## S3 method for class 'PKNCAconc' superposition(conc, ...) ## S3 method for class 'numeric' superposition( conc, time, dose.input = NULL, tau, dose.times = 0, dose.amount, n.tau = Inf, options = list(), lambda.z, clast.pred = FALSE, tlast, additional.times = numeric(), check.blq = TRUE, method = NULL, auc.type = "AUCinf", steady.state.tol = 0.001, ... )
superposition(conc, ...) ## S3 method for class 'PKNCAconc' superposition(conc, ...) ## S3 method for class 'numeric' superposition( conc, time, dose.input = NULL, tau, dose.times = 0, dose.amount, n.tau = Inf, options = list(), lambda.z, clast.pred = FALSE, tlast, additional.times = numeric(), check.blq = TRUE, method = NULL, auc.type = "AUCinf", steady.state.tol = 0.001, ... )
conc |
Measured concentrations |
... |
Additional arguments passed to the |
time |
Time of the measurement of the concentrations |
dose.input |
The dose given to generate the |
tau |
The dosing interval |
dose.times |
The time of dosing within the dosing interval. The
|
dose.amount |
The doses given for the output. Linear proportionality
will be used from the input to output if they are not equal. The length of
dose.amount must be either 1 or matching the length of |
n.tau |
The number of tau dosing intervals to simulate or |
options |
List of changes to the default PKNCA options (see
|
lambda.z |
The elimination rate (in units of inverse time) for extrapolation |
clast.pred |
To use predicted as opposed to observed Clast, either give the value for clast.pred here or set it to true (for automatic calculation from the half-life). |
tlast |
The time of last observed concentration above the limit of quantification. This is calculated if not provided. |
additional.times |
Times to include in the final outputs in addition to
the standard times (see details). All |
check.blq |
Must the first concentration measurement be below the limit of quantification? |
method |
The method for integration (one of 'lin up/log down', 'lin-log', or 'linear') |
auc.type |
The type of AUC to compute. Choices are 'AUCinf', 'AUClast', and 'AUCall'. |
steady.state.tol |
The tolerance for assessing if steady-state has been achieved (between 0 and 1, exclusive). |
The returned superposition times will include all of the following
times: 0 (zero), dose.times
, time modulo tau
(shifting time
for each
dose time as well), additional.times
, and tau
.
A data frame with columns named "conc" and "time".
Times relative to an event (typically dosing)
time_calc(time_event, time_obs, units = NULL)
time_calc(time_event, time_obs, units = NULL)
time_event |
A vector of times for events |
time_obs |
A vector of times for observations |
units |
Passed to |
A data.frame with columns for:
The index of time_event
that is the last one before time_obs
or NA
if none are before.
The index of time_event
that is the first one after time_obs
or NA
if none are after.
The minimum time that the current time_obs
is before a time_event
, 0 if at least one time_obs == time_event
.
The minimum time that the current time_obs
is after a time_event
, 0 if at least one time_obs == time_event
.
The time after the first event (may be negative or positive).
time_after
and time_before
are calculated if they are at the same time as
a dose, they equal zero, and otherwise, they are calculated relative to the
dose number in the event_number_*
columns.
A helper function to generate the formula and starting values for the parameters in monoexponential models.
tss.monoexponential.generate.formula(data)
tss.monoexponential.generate.formula(data)
data |
The data used for the model |
a list with elements for each of the variables
Equation 7.vii in Nedelman and Jia, 1998 is used for this calculation:
var_sparse_auc(sparse_pk)
var_sparse_auc(sparse_pk)
sparse_pk |
A sparse_pk object from |
The degrees of freedom are calculated as described in equation 6 of the same paper.
Nedelman JR, Jia X. An extension of Satterthwaite’s approximation applied to pharmacokinetics. Journal of Biopharmaceutical Statistics. 1998;8(2):317-328. doi:10.1080/10543409808835241