Ts Lib Parsy Components #

Version #

v0.2.3

Table of Contents #

Summary#

This library stores commonly used Parsy parser components, so they can easily be imported and used in Task Scripts.

Base Parsers#

The ts_lib_parsy_components.base module provides pre-built numeric parser instances that can be used directly or composed into larger parsers.

This module contains 4 parsers:

  • float_ - Matches float strings (e.g. "123.45", "-7")

  • int_ - Matches integer strings (e.g. "42", "-3")

  • scientific - Matches scientific notation strings (e.g. "1.23e6", "-1.5E-3")

  • scientific_or_float - Matches either scientific notation or plain floats

These are parser instances (not classes or functions), so they are used directly with .parse() or composed into larger parsers with Parsy operators. scientific_or_float is also the default value_parser used by ValueUnitParser.

These parsers can be used as follows:

from ts_lib_parsy_components.base import scientific_or_float

# Parse a float string
print(scientific_or_float.parse("123.45"))
# Output: 123.45

# Parse a scientific notation string
print(scientific_or_float.parse("1.23e6"))
# Output: 1.23e6

Plate Reader Parsers#

The ts_lib_parsy_components.plate_reader module provides parsers for plate reader well names (e.g. "A1", "AA01").

This module contains 4 parsers:

  • single_letter_well_name - Matches a single letter (case-insensitive) followed by 1-2 digits (e.g. "A1", "b02")

  • two_letter_well_name - Matches two uppercase letters followed by 1-2 digits (e.g. "AA1", "AB02")

  • well_name - Matches either a single-letter or two-letter well name

  • well_position - Parses a well name into a WellPosition object with .row and .column attributes

WellPosition is provided by task_script_utils.plate_reader. Row and column numbers are 1-indexed, with two-letter rows continuing from Z (e.g. "AA1" maps to row 27, column 1).

These parsers can be used as follows:

from ts_lib_parsy_components.plate_reader import well_position

# Parse a single-letter well name
print(well_position.parse("A1"))
# Output: WellPosition(row=1, column=1)

# Parse a two-letter well name
print(well_position.parse("AA1"))
# Output: WellPosition(row=27, column=1)

ValueUnitParser#

The ValueUnitParser class can be used to parse value-unit strings to the RawValueUnit IDS object.

This class contains 3 methods:

  • ValueUnitParser.value - Returns a Parsy parser to parse a value string, with a default unit

  • ValueUnitParser.value_unit - Returns a Parsy parser to parse a value-unit string, with a required raw unit

  • ValueUnitParser.value_optional_unit - Returns a Parsy parser to parse a value-unit string, following the default behavior of the above two methods.

These parsers use the ts_lib_units.UnitParser class to parse raw unit strings to TetraScience standard unit strings. A UnitParser instance must be passed to the ValueUnitParser constructor.

By default the ValueUnitParser parsers assume:

  • The value can be either a float or in scientific notation.

  • The unit follows the value string, separated by spaces, and enclosed in optional parenthesis or square brackets.

  • When the unit is missing, Unit.ARBITRARY_UNIT is the default unit

The above behavior can be changed by supplying a value_parser, raw_unit_parser or default_unit when instantiating ValueUnitParser.

Additionally, the default behavior of the ValueUnitParser.value_unit and ValueUnitParser.value methods can be overwritten by passing the raw_unit and unit arguments respectively. For more details, see the method docstrings.

These methods can be used as follows:

from ts_lib_units import CONCENTRATION_MAPPING, UnitParser
from ts_lib_parsy_components.value_unit import ValueUnitParser

# The string to parse
raw_string = "1.23 (mg/ml), 1.23e6, 1.23 (RandomUnit), 1.23 [AnotherUnit]"

# Initialize a UnitParser instance to parse the raw unit strings
unit_parser = UnitParser(mappings=CONCENTRATION_MAPPING)

# Initialize a ValueUnitParser instance to parse the value-unit strings
value_unit_parser = ValueUnitParser(unit_parser=unit_parser)

# Create a Parsy parser to parse the raw string
parser = (value_unit_parser.value_optional_unit() << regex(r"[ ,]*")).many()
results = parser.parse(raw_string)

# Check for unmapped units
print(unit_parser.unmapped_units)
# Output:
# {'RandomUnit', 'AnotherUnit'}

# Check results
print(results)
# Output:
# [
#   RawValueUnit(value=1.23, unit="MilligramPerMilliliter", raw_value="1.23 (mg/ml)"),
#   RawValueUnit(value=1230000.0, unit="ArbitraryUnit", raw_value="1.23e6"),
#   RawValueUnit(value=1.23, unit="RandomUnit", raw_value="1.23 (RandomUnit)"),
#   RawValueUnit(value=1.23, unit="AnotherUnit", raw_value="1.23 [AnotherUnit]"),
# ]

Changelog#

v0.2.3#

  • Add LICENSE

v0.2.2#

  • Add documentation for ts_lib_parsy_components.base module (float_, int_, scientific, scientific_or_float)

  • Add documentation for ts_lib_parsy_components.plate_reader module (single_letter_well_name, two_letter_well_name, well_name, well_position)

v0.2.1#

  • Update ValueUnitParser.value_unit method to take an optional argument raw_unit which is a string of the raw unit to store with the raw value, instead of parsing the raw unit from the stream.

  • Update ValueUnitParser.value method to take an optional argument unit which is a Unit used to override the default unit.

v0.2.0#

  • Add ts_lib_parsy_components.plate_reader module to store common plate-reader parsers

    • Add parsers for plate-reader well names like A1, A01, a01, etc.

  • Update ValueUnitParser to take an optional argument float_converter which is a function used to convert the value string to a float or None (defaults to task_script_utils.parse.to_float).

v0.1.1#

  • Update the default unit parser to support the % character

v0.1.0#

  • Initial version