Skip to content

units

ngtools.units

Tools to convert between units.

Functions:

Name Description
split_unit

Split prefix and unit
convert_unit

Convert a value between units
normalize_unit

Convert to prefixless SI unit
unit_to_scale

Return the scale of a arbitrary unit with respect to its SI equivalent
as_ome_unit

Find OME version of a unit
as_nifti_unit

Find NIfTI version of a unit
as_neuroglancer_unit

Find Neuroglancer version of a unit (= short SI)

Attributes:

Name Type Description
UnitDomain

Type hint for unit domains, i.e., Literal["space", "time", "all"]
OME_UNITS dict[UnitDomain, list[str]]

Dictionary where values are lists of valid OME units.
NIFTI_UNITS dict[UnitDomain, list[str]]

Dictionary where values are lists of valid NIfTI units.
SI_UNITS_SHORT dict[UnitDomain, list[str]]

Dictionary where values are lists of valid Neuroglancer (short SI) units.
SI_UNITS_LONG dict[UnitDomain, list[str]]

Dictionary where values are lists of valid SI (long) units.
SI_PREFIX_SHORT2LONG dict[str, str]

Dictionary that maps short forms of SI prefixes to long forms
SI_PREFIX_LONG2SHORT dict[str, str]

Dictionary that maps long forms of SI prefixes to short forms
SI_PREFIX_EXPONENT dict[str, float]

Dictionary that maps short forms of SI prefixes to their exponent value
UNIT_SHORT2LONG dict[UnitDomain, dict[str, str]]

Dictionary where values are dictionaries that map short forms of a unit to long forms
UNIT_LONG2SHORT dict[UnitDomain, dict[str, str]]

Dictionary where values are dictionaries that map long forms of a unit to short forms

UNIT_SHORT2LONG module-attribute 

UNIT_SHORT2LONG = {}

Mapping from short name to long name (per domain).

UNIT_LONG2SHORT module-attribute 

UNIT_LONG2SHORT = {}

Mapping from long name to short name (per domain).

UNIT_SCALE module-attribute 

UNIT_SCALE = {}

Mapping from short name to scale (per domain).

SI_UNITS_SHORT module-attribute 

SI_UNITS_SHORT = {}

List of short SI units (per category).

SI_UNITS_LONG module-attribute 

SI_UNITS_LONG = {}

List of long SI units (per domain).

split_unit 

split_unit(unit)

Split prefix and unit.

Parameters:

Name Type Description Default
unit [sequence of] str
required

Returns:

Name Type Description
prefix [sequence of] str
unit [sequence of] str

same_unit_kind 

same_unit_kind(src, dst)

Check whether two units are of the same kind.

convert_unit 

convert_unit(value, src, dst)

Convert a value between different units.

Parameters:

Name Type Description Default
value float or ArrayLike

Value to convert

 required
src str

Source unit

 required
dst str

Destination unit

 required

Returns:

Name Type Description
value float or array

Converted value

normalize_unit 

normalize_unit(value, unit)

Normalize a unit (i.e., convert to prefixless SI unit).

Parameters:

Name Type Description Default
value float or ArrayLike

Value to convert

 required
unit str

Source unit

 required

Returns:

Name Type Description
value float or array

Converted value

ensure_list 

ensure_list(x, n=None, **kwargs)

Ensure that x is a list.

Arrays are converted to nested lists, whereas scalars are insereted into a list of length 1.

Parameters:

Name Type Description Default
x object

Input value(s)

 required
n int

Target length of the list. If the input is longer, it gets cropped. Otherwise, it gets padded with the default value.

 None
default any

Value to use to pad the list. If not provided, use last value in the list.

 required

Returns:

Name Type Description
x list

as_short_unit 

as_short_unit(unit)

Return the shortest representation for this unit.

Parameters:

Name Type Description Default
unit str

Any unit.

 required

Returns:

Name Type Description
unit str

An short unit.

Raises:

Type Description
ValueError

If the input unit is unknown.

as_long_unit 

as_long_unit(unit)

Return the long representation for this unit.

Parameters:

Name Type Description Default
unit str

Any unit.

 required

Returns:

Name Type Description
unit str

An long unit.

Raises:

Type Description
ValueError

If the input unit is unknown.

as_neuroglancer_unit 

as_neuroglancer_unit(unit)

Return the Neuroglancer representation of a unit.

Parameters:

Name Type Description Default
unit str

Any unit.

 required

Returns:

Name Type Description
unit str

An OME-compatible unit.

Raises:

Type Description
ValueError

If the input unit does not have an exactly equivalent representation in OME.

as_ome_unit 

as_ome_unit(unit)

Return the OME-compatible representation of a unit.

Parameters:

Name Type Description Default
unit str

Any unit

 required

Returns:

Name Type Description
unit str

An OME-compatible unit

Raises:

Type Description
ValueError

If the input unit does not have an exactly equivalent representation in OME.

as_nifti_unit 

as_nifti_unit(unit)

Return the NIfTI-compatible representation of a unit.

Parameters:

Name Type Description Default
unit str

Any unit

 required

Returns:

Name Type Description
unit str

A NIfTI-compatible unit. If the unit does not have a NIfTI representation, the NIfTI type "unknown" is returned.

unit_to_scale 

unit_to_scale(unit)

Return the scale of a arbitrary unit with respect to its SI equivalent.

Parameters:

Name Type Description Default
unit str

Any unit

 required

Returns:

Name Type Description
scale float

The corresponding SI scale

Raises:

Type Description
ValueError

If the unit does not have a SI equivalent.