unitty.utils module

Created on Thu May 7 10:54:00 2020

@author: Reuben

The utils module contains helper functions to allow users to quickly process input or output data, automatically converting between units as required.

unitty.utils.add_unit(s, unit_str)

Append a unit string within square brackets to a string

Parameters:
  • s (str) – A string without units (e.g. ‘widget.length’).
  • unit_str (str) – The unit string to attach (e.g. ‘mm’)
Returns:

A string with units appneded in square brackets (e.g. ‘widget.length [mm]’)
Return type:

str
unitty.utils.make_qty(s, val)

Make a Quantity from a unit-containing string and a value

Parameters:
  • s (str) – A string with units at the end in square brackets (e.g. ‘widget.length [mm]’).
  • val (int, float, arraylike) – A value in the units indicated within the string, s.
Returns:

The Quantity specified by the value and units. The Quantity will have a reference set by the body of the string (e.g. ‘widget.length’).
Return type:

Quantity
unitty.utils.split_qty(q, name=None)

Split a Quantity into a string with units appended and a value

Parameters:
  • q (Quantity) – The quantity
  • name (str) – [Optional] The name to use for the string. If omitted, the name will default to the reference set in the Quantity.
Returns:

A string with units suffixed in square brackets, and the value in those units. The units are selected through the currently active system, either automatically, or by those specified through reference quantity types.
Return type:

tuple
unitty.utils.split_str(s)

Split out units from a string suffixed with units in square brackets

Parameters:s (str) – A string with units at the end in square brackets (e.g. ‘widget.length [mm]’).
Returns:The string with it’s units stripped (e.g. ‘widget.length’), and the unit string (e.g. ‘mm’).
Return type:tuple

Examples:

split_str('length ['mm'])
# ('length', 'mm')

split_str('a long string with spaces [W/m2]')
# ('a long string with spaces', 'W/m2')
unitty.utils.str_to_unit(s)

Return the unit within square brackets in a string

Parameters:s (str) – A string with units at the end in square brackets (e.g. ‘widget.length [mm]’).
Returns:The Unit instance corresponding to the string. If it is not already defined, unitty will attempt to derive it from the string.
Return type:Unit
unitty.utils.transform_df(df)

Transform a pandas dataframe into the current unit system

Parameters:df (DataFrame) – A pandas dataframe. Column names with units should have them within square brackets at the end of each name.
Returns:A dataframe in which the column units have been changed into the current unit system and the table values have been changed into those new units.
Return type:DataFrame
unitty.utils.transform_dict(dct)

Transform a dictionary of values into the current unit system

Parameters:dct (dict) – Each key should be a name with units suffixed in square brackets (e.g. ‘widget.length [mm]’). Each key should be the magnitude of the quantity expressed in those units.
Returns:A transformed dictionary, in which the keys have units in the current unit system and the values are automatically converted to match those units. Keys without unit information, or ones in which a conversion error arises, are returned unchanged.
Return type:dct (dict)
unitty.utils.transform_list_of_dicts(lst)

Transform a list of dictionaries into the current unit system

Parameters:lst (list) – A list of dictionaries as for the transform_dict() function.
Returns:A list of dictionaries, where each is the output of the transform_dict() function.
Return type:list
unitty.utils.transform_pair(s, val)

Transform a string-value pair into the current unit system

Parameters:
  • s (str) – A string with units at the end in square brackets (e.g. ‘widget.length [ft]’).
  • val (int, float, arraylike) – The value in those units.
Returns:

A string with units in the current unit system (e.g. ‘widget.length [m]’, plus the value expressed in those units.
Return type:

tuple