Skip to content

units

Units of the package.

One pint registry per process, ureg, is shared by every timecourse, result and quantity of the package; quantities of different registries cannot be combined, which is why nothing creates a registry of its own. Numerics run on plain arrays in the units of the input, pint is used at the boundaries: parsing unit strings, deriving the units of results and converting volumes and clearances to their conventional units.

The helpers which take a unit string and answer a question about it (parse_unit, check_dose_unit, is_per_bodyweight) are cached: pint parsing is not cheap, the same handful of unit strings is parsed for every timecourse, dose and parameter, and units are immutable, so the answer of a string never changes within a process.

from pkpdutils.units import Q_, ureg

dose = Q_(100, "mg")
time = Q_([0, 1, 2], "hr")

short_unit 

short_unit(unit)

A unit in the short symbols of pint, mg/l for milligram / liter.

The analyses derive their units with pint and store its canonical long form (milligram / liter, hour * milligram / liter) in the units attributes of a result, which is too long for a table header or an axis label. A string in that long form is written in the short symbols of the registry (the ~P format of pint); a string the user spelled themselves (hr, ng/ml, anything which is not the canonical form of the unit it names) is kept as it is, so that a table or a figure carries the unit as the data carries it. A dimensionless or empty unit gives the empty string, and a string 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.

 required

Returns:

Type Description
str

The short unit, empty for a dimensionless or empty unit.

parse_unit cached 

parse_unit(unit)

Parse a unit string with the registry of the package.

The empty string is rejected: pint parses it as dimensionless, but an empty unit string then composes into the unit expressions of the derived parameters as "()", so a dimensionless quantity (a pharmacodynamic score, a ratio) is spelled "dimensionless".

The result is cached per unit string (CACHE_SIZE): parsing is the most frequent pint call of the package (every timecourse, every dose, every parameter of a result) and a pint.Unit is immutable, so every caller of the same string can share one object.

Parameters:

Name Type Description Default
unit str

unit string, e.g. "ng/ml" or "hr"

 required

Returns:

Type Description
Unit

The unit.

Raises:

Type Description
ValueError

if the string is empty or is not a unit of the registry.

unit_str 

unit_str(unit)

Canonical string of a unit, e.g. "nanogram / milliliter" for "ng/ml".

Parameters:

Name Type Description Default
unit Unit | str

a unit or a unit string.

 required

Returns:

Type Description
str

The canonical string of the unit.

check_dose_unit cached 

check_dose_unit(unit)

Check that a unit is a dose unit.

A dose is an amount of substance, as mass (mg), as substance (mmol) or as activity (IU, for insulin, heparin, vaccines and enzyme replacement), or such an amount per body weight (mg/kg, µmol/kg, IU/kg).

The check is cached per unit string (CACHE_SIZE); a unit which fails it raises on every call, as functools.lru_cache does not cache exceptions.

Parameters:

Name Type Description Default
unit str

unit string of the dose

 required

Raises:

Type Description
ValueError

if the unit has another dimensionality.

is_per_bodyweight cached 

is_per_bodyweight(unit)

Check whether a dose unit is an amount per body weight.

The answer is cached per unit string (CACHE_SIZE).

Parameters:

Name Type Description Default
unit str

unit string of the dose, e.g. "mg/kg".

 required

Returns:

Type Description
bool

True if the unit is an amount per body weight, e.g. "mg/kg",
bool

"µmol/kg" or "IU/kg".

normalize_volume 

normalize_volume(q)

Convert a volume to liter and a volume per body weight to liter/kilogram.

Anything else is returned unchanged.

Parameters:

Name Type Description Default
q Quantity

quantity to normalize.

 required

Returns:

Type Description
Quantity

The quantity converted to liter or liter / kilogram, or q unchanged.

normalize_clearance 

normalize_clearance(q)

Convert a clearance to liter/hour and one per body weight to liter/hour/kilogram.

Anything else is returned unchanged.

Parameters:

Name Type Description Default
q Quantity

quantity to normalize.

 required

Returns:

Type Description
Quantity

The quantity converted to liter / hour or liter / hour / kilogram,
Quantity

or q unchanged.