cdisc¶

CDISC map of the parameters: PKPARMCD codes, PKUNIT spellings and the PP domain.

A submission does not carry the variable names of an analysis package: every parameter of the PP domain (and of the ADaM ADPP dataset derived from it) is named by a code of the CDISC controlled terminology, PKPARMCD, and its unit by a value of PKUNIT. This module holds the crosswalk from the variables pkpdutils reports to those codes and writes the domain.

The codes are read from pkpdutils/data/pkparmcd.csv, which was extracted from the tab-delimited NCI EVS package of the CDISC SDTM controlled terminology (codelist C85839, "PK Parameters Code"); the header of the file names the source, the date and the checksum of the package it was taken from. Nothing is transcribed by hand, and a variable the terminology has no code for maps to None and is left out of the domain with a warning. Several codes that are commonly assumed do not exist (CLSTP for the predicted last concentration, CMAXSS and CMINSS for the steady state peak and trough, ACCIND, PTROUGH, AEAMT, FE): the steady state peak and trough are CMAX and CMIN with PPSCAT = "STEADY STATE", the accumulation index is AILAMZ and the peak trough ratio PTROUGHR.

from pkpdutils.cdisc import to_pp

pp = to_pp(result, subject_dim="individual")

pkunit ¶

pkunit(unit)

The PKUNIT spelling of a unit of a result.

The exact submission value of PKUNIT when the table knows the unit, otherwise the same unit written in the CDISC symbols of PKUNIT_SYMBOLS in the order pint spells it (milligram / liter becomes mg/L, which the terminology does not have, since it spells mass concentrations per milliliter; ParameterResult.to_units converts such a result to a unit the terminology spells). A dimensionless unit is the empty string, a unit which is not a unit of the registry is passed through unchanged.

Parameters:

Name	Type	Description	Default
`unit`	`str`	the unit string of a variable of a result, e.g. `"hour * nanogram / milliliter"`.	required

Returns:

Type	Description
`str`	The `PKUNIT` submission value.

pkparmcd ¶

pkparmcd(variable, route=None)

The PKPARMCD code of a variable of a result.

Parameters:

Name	Type	Description	Default
`variable`	`str`	name of the variable, e.g. `"auc_inf_obs"` or `"mrt"`.	required
`route`	`Route \| str \| None`	the route of administration, for a variable whose code depends on it (`mrt`); `None` when it is not known.	`None`

Returns:

Type	Description
`str \| None`	The code, or `None` when the terminology has none for the variable or
`str \| None`	when the code needs a route which was not given.

to_pp ¶

to_pp(
    result,
    *,
    subject_dim,
    usubjid=None,
    spec="SDTM",
    studyid=None,
    route=None,
    ppspec=None,
    digits=6,
)

Lay a result out as the CDISC PP domain, one row per subject and parameter.

Every parameter of the result which the terminology has a code for (pkparmcd) becomes one row per sample: PPTESTCD the code, PPTEST its CDISC name, PPORRES the value as it was reported and PPORRESU its unit in the PKUNIT spelling (pkunit), PPSTRESN and PPSTRESU the same value as a number. PPCAT is the substance the analysis was run on and PPSPEC the specimen; PPSEQ numbers the rows of a subject from 1.

PPSCAT tells a single dose parameter from a steady state one, and the analysis of the sample decides it: every parameter of a sample which was analysed over its dosing intervals (more than one dose, or NCAOptions.tau, _steady_state_samples) describes the steady state, since its peak, its exposure and its clearance are computed from the last dose on; a variable of STEADY_STATE_VARIABLES is STEADY STATE whatever the sample, which is what tells the steady state peak and trough from a single dose one (both are CMAX and CMIN, there is no CMAXSS). PPRFTDTC, the reference date-time of the analysis, is empty: the analysis works on elapsed times and never sees a date.

A parameter without a code is left out and named in a warning. The variables which CDISC defines as a percentage while the package reports a fraction (PERCENT_VARIABLES) are multiplied by 100 and carry the unit %. A sample whose parameter is NaN (a parameter of the other route or of the other dosing path) gets no row. The uncertainty and summary variables of a parameter, the per-interval point variables and the status variables are not part of the domain.

The substance and the route are read from the coordinates substance and route of the result when it carries them (a batch of several analytes or of several routes) and from its attributes otherwise; route names the route of a result which carries neither and is needed for the mean residence time, whose code depends on it.

Parameters:

Name	Type	Description	Default
`result`	`ParameterResult`	the result, e.g. of `pkpdutils.nca.nca`	required

Other Parameters:

Name	Type	Description
`subject_dim`	`str`	the sample dimension whose labels are the subjects
`usubjid`	`Mapping[Any, str] \| Sequence[str] \| None`	the `USUBJID` of every subject, a mapping from the label of the subject or a sequence in the order of the dimension; the label itself by default
`spec`	`Literal['SDTM', 'ADaM']`	`"SDTM"` writes the `PP` domain, `"ADaM"` adds the analysis variables `PARAMCD`, `PARAM`, `AVAL` and `AVALU` of an `ADPP` dataset and leaves the `DOMAIN` column out
`studyid`	`str \| None`	the `STUDYID` of the study, left out when it is not given
`route`	`Route \| str \| None`	route of administration, when the result names none itself
`ppspec`	`str \| None`	the specimen, `"PLASMA"` by default and `"URINE"` for the variables of a urinary excretion analysis (`URINE_VARIABLES`); the `tissue` of the analysed batch when it names one
`digits`	`int`	significant digits of the character result `PPORRES`; the numeric `PPSTRESN` carries the value itself

Returns:

Type	Description
`DataFrame`	The domain, one row per subject and parameter.

Raises:

Type	Description
`ValueError`	if `subject_dim` is not a sample dimension of the result.

write_pp ¶

write_pp(result, path, **options)

Write a result as the PP domain into a csv file.

Parameters:

Name	Type	Description	Default
`result`	`ParameterResult`	the result	required
`path`	`str \| Path`	the file to write	required
`**options`	`Any`	the keyword arguments of `to_pp` (`subject_dim` is required)	`{}`

Returns:

Type	Description
`DataFrame`	The domain that was written.