Ts Lib Units #

Version #

v0.4.2

Table of Contents #

Summary#

This library stores the TetraScience standard unit strings, so they can easily be imported and used in Task Scripts

Unit Usage#

The Unit enum is used to store the TetraScience standard unit strings. It can be used in Task Scripts instead of manually typing out the unit strings:

from ts_lib_units import Unit
from ts_ids_core.schema import ValueUnit

temperature = ValueUnit(value=20, unit=Unit.DEGREE_CELSIUS)
print(temperature.dict())

# Output:
# {'value': 20, 'unit': 'DegreeCelsius'}

UnitParser Usage#

The Unit Parser has three modes of use UnitParser.from_unit_type, UnitParser.from_custom_mapping, and UnitParser.from_unit_type_and_custom_mapping.

UnitParser.from_custom_mapping is used to create a UnitParser instance from a custom mapping dictionary (like in the versions pre v0.4.0).

from ts_lib_units import Unit, UnitParser

MY_MAPPING = {
    "ng": Unit.NANOGRAM,
}

unit_parser = UnitParser.from_custom_mapping(mapping=MY_MAPPING)

parsed_unit = unit_parser.parse("ng")
print("Parsed unit: ", parsed_unit)

UnitParser.from_unit_type is used to create a UnitParser instance from a unit type.

from ts_lib_units import Unit, UnitParser
from ts_lib_units.unit_types import UnitType

unit_parser = UnitParser.from_unit_type(unit_type=UnitType.MASS)

parsed_unit = unit_parser.parse("ng")
print("Parsed unit: ", parsed_unit)

UnitParser.from_unit_type_and_custom_mapping is used to create a UnitParser instance from a unit type and custom mapping. This method uses an argument strict_mode to determine how conflicts between your custom mapping and the default mapping should be handled. It defaults to True, which means that if there are any conflicts, a ValueError will be raised. If strict_mode is set to False, a warning will be logged instead, and the custom mapping will take precedence. Please be aware of this behavior when using this method.


from ts_lib_units import Unit, UnitParser
from ts_lib_units.unit_types import UnitType

MY_MAPPING = {
    "ng": Unit.NANOGRAM,
}

unit_parser = UnitParser.from_unit_type_and_custom_mapping(unit_type=UnitType.MASS,mapping=MY_MAPPING)

parsed_unit = unit_parser.parse("ng")
print("Parsed unit: ", parsed_unit)

Standard Mappings#

The Standard mappings (previously available in the library) can be recreated following the example below:


from ts_lib_units import Unit, UnitParser
from ts_lib_units.unit_types import UnitType


CONCENTRATION_MAPPING = UnitParser.from_unit_type(UnitType.CONCENTRATION).mapping

Unit Library#

All units are singular rather than plural, e.g. Meter as in 1 Meter rather than Meters as in 2 Meters. If the unit cannot be found in this library, request for it to be added. New units will be added following this approach:

  1. If the unit is in QUDT, or Allotrope QUDT-extended, the name in the URI will be used.

    • See the allotrope-qudt-merged.txt file for reference.

  2. Otherwise:

    1. Use Pascal case.

    2. Use Per for units divided by another unit.

    3. Simply concatenate units when it is one unit multiplied by another unit, e.g. VoltMeter.

    4. Do not capitalize after prefixes such as Milli or Micro.

Finding a QUDT URI for a New Unit#

When adding a new unit, use the semantic search tool to find the correct QUDT URI.

Step 1: Set up the vector database (first time only)

# Install search dependencies (optional group, not installed by default)
poetry install --with search

# Index the QUDT units (creates .qudt_vectordb/ directory)
poetry run index-qudt

To remove the search dependencies afterwards, recreate the venv without the group:

poetry env remove --all
poetry install

Step 2: Search for your unit

# Search by name, symbol, or description
poetry run search-qudt "milligrams per liter"
poetry run search-qudt "RLU"
poetry run search-qudt "concentration unit" --top 10

Example output:

1. URI: http://purl.allotrope.org/ontology/qudt-ext/unit#MilligramPerLiter
   Labels: Milligram per Liter
   Symbols: mg/L
   Similarity: 0.878

2. URI: http://qudt.org/vocab/unit/MilliGM-PER-L
   Labels: Milligram per Litre
   Symbols: mg/L
   Similarity: 0.827

Step 3: Choose the correct URI

  • Prefer Allotrope URIs (http://purl.allotrope.org/...) when available

  • Use QUDT URIs (http://qudt.org/...) if no Allotrope equivalent exists

  • If no match is found, the unit may not exist in QUDT - use qudt_uri=None

Step 4: Validate after adding

After adding a new unit, run the validation script:

poetry run validate-qudt-uris

Unit Conversion#

The convert_unit function can be used to convert a RawValueUnit or ValueUnit instance from one unit to another:

from ts_lib_units import convert_unit, Unit

previous = RawValueUnit(
  raw_value = "20 g/L",
  value = 20,
  unit = "GramPerLiter"
)

converted = convert_unit(previous, Unit.MILLIGRAM_PER_LITER)
print(converted)
# Output:
# ValueUnit(value=20000, unit='MilligramPerLiter')

Changelog#

v0.4.2 #

  • Add RelativeFluorescenceUnit

v0.4.1 #

  • Add Torque unit type

  • Add NewtonMeter

  • Add MicronewtonMeter

v0.4.0 #

  • Add from_unit_type,from_custom_mapping and from_unit_type_and_custom_mapping methods to UnitParser

  • Add _aliases and _unit_type attributes to TetraUnit

  • Add UnitType StrEnum to encode the different types of units

    • Add new unit type SI for SI units

  • Add available_units method to UnitParser

  • Add _get_aliases_by_type and _generate_default_mapping methods to Unit so UnitParser can generate default mappings and list available units by type

  • Update aliases in Unit class objects to use either known aliases from the mapping dictionaries or from the QUDT ontology

v0.3.16 #

  • Add Nanoliter

  • Add MeterPerSecond

v0.3.15 #

  • Add EndotoxinUnit

v0.3.14 #

  • Add EndotoxinUnitPerMicroliter

  • Add EndotoxinUnitPerLiter

  • Add EndotoxinUnitPerNanogram

  • Add EndotoxinUnitPerMicrogram

  • Add EndotoxinUnitPerGram

  • Add ENDOTOXIN_MAPPING

v0.3.13 #

  • Add EndotoxinUnitPerMilliliter

v0.3.12 #

  • Add LICENSE

v0.3.11 #

  • Add SquareMicrometer

v0.3.10 #

  • Add ImportError with helpful message to search_qudt.py and index_qudt_units.py when search dependencies are not installed

v0.3.9 #

  • Move chromadb, sentence-transformers, and rdflib into an optional search dependency group

  • Run poetry install --with search to install these dependencies when using the QUDT search/index tools

v0.3.8 #

  • Add QUDT vector database search tooling for finding unit URIs via semantic similarity

  • Expose CLI commands via poetry run: search-qudt, index-qudt, download-qudt, validate-qudt-uris

v0.3.7 #

  • Add InternationalUnitPerLiter for enzyme activity

v0.3.6 #

  • Add mmol/L mapping to MillimolePerLiter in CONCENTRATION_MAPPING

v0.3.5 #

  • Add Femtoliter, CountPerLiter, CountPerMicroliter, CountPerMilliliter, CountPerNanoliter

v0.3.4 #

  • Add KilocaloriePerMole, MoleFraction

v0.3.3 #

  • Add CubicCentimeterPerMole, GramPerLiterSolvent, GramPerLiterSolution, JoulePerMole, KiloJoulePerMole, SquareRootMegaPascal

v0.3.2 #

  • Add PerSecond, PascalSecond, MillipascalSecond

  • Deprecate Permittivity which is a quantity rather than a unit

  • Fix QUDT URIs for GramPerMilliliter, LiterPerMinute, Microvolt

v0.3.1 #

  • Fix MilliAbsorbanceUnit, MilliAbsorbanceUnitTimesMinute and MilliAbsorbanceUnitTimesMilliliter unit definitions

v0.3.0 #

  • Modify UnitParser.parse method:

    • Allow to map to None type

    • Map empty string, “”, to None as a rule

  • Add units AbsorbanceUnit, MilliAbsorbanceUnit, MilliAbsorbanceUnitTimesMinute, MilliAbsorbanceUnitTimesMilliliter, CentimeterPerHour, CycleNumber, and LiterPerHour

v0.2.1 #

  • Add units MillivoltPerPH and MilliVolt

v0.2.0 #

  • Update the unit library to also store the following for each unit:

    • The QUDT / Allotrope QUDT Extended URI.

    • The representation of the unit according to the pint library, which is used for unit conversion.

  • Update the following unit strings to improve consistency between unit strings compared to the Allotrope / QUDT standards:

    • CentiPoise to Centipoise

    • FemtoGram to Femtogram

    • MilliSiemen to Millisiemens

    • MilliSiemensPerCentimeter to MillisiemensPerCentimeter

    • OsmolePerLiter to OsmolesPerLiter

  • Add the unit PerMinute

  • Add convert_unit function to convert a RawValueUnit or ValueUnit instance from one unit to another, using the pint library.

v0.1.5 #

  • Add unit MilliSiemen, LiterPerSquareMeter, MilliSiemensPerCentimeter, LiterPerSquareMeterPerMinute, LiterPerSquareMeterPerHour, LiterPerSquareMeterPerHourPerPoundPerSquareInch

v0.1.4 #

  • Add unit MillimolePerLiter

v0.1.3 #

  • Add units MilliDegreeAngle, NanometerPerMinute

  • Add mapping for "NANOMETERS" -> "Nanometer", "msec" -> "MilliSecond", "ul" -> "Microliter"

v0.1.2 #

  • Add PERCENT_MAPPING

v0.1.1 #

  • Fix bug where Unit.NANOGRAM_PER_LITER mapped to “NanogramPerMilliliter”

v0.1.0 #

  • Initial version