helpers: helper functions for the transform package

Code author: Peter Kraus, Ueli Sauter

dgpost.utils.helpers.element_from_formula(f, el)

Given a chemical formula f, returns the number of atoms of element el in that formula.

Return type

int

dgpost.utils.helpers.default_element(f)

Given a formula f, return the default element for calculating conversion. The priority list is ["C", "O", "H"].

Return type

str

dgpost.utils.helpers.name_to_chem(name)
Return type

str

dgpost.utils.helpers.columns_to_smiles(**kwargs)

Creates a dictionary with a SMILES representation of all chemicals present among the keys in the kwargs, storing the returned chemicals.ChemicalMetadata as well as the full name within args.

Parameters

kwargs (dict[str, dict[str, Any]]) – A dict containing dict[str, Any] values. The str keys of the inner dicts are parsed to SMILES.

Returns

smiles – A new dict[str, dict] containing the SMILES of all prefixed chemicals as str keys, and the metadata and column specification as the dict values.

Return type

dict

dgpost.utils.helpers.electrons_from_smiles(smiles, ions=None)
Return type

float

dgpost.utils.helpers.pQ(df, col, unit=None)

Unit-aware dataframe accessor function.

Given a dataframe in df and a column name in col, the function looks through the units stored in df.attrs["units"] and returns a unit-annotated pint.Quantity containing the column data. Alternatively, the data in df[col] can be annotated by the provided unit.

Note

If df.attrs has no units, or col is not in df.attrs["units"], the returned pint.Quantity is dimensionless.

Parameters

  • df (DataFrame) – A pd.DataFrame, optionally annotated with units in df.attrs.

  • col (Union[str, tuple[str]]) – The str name of the column to be loaded from the df.

  • unit (Optional[str]) – Optional override for units.

Returns

Quantity – Unit-aware ping.Quantity object containing the data from df[col].

Return type

pint.Quantity

dgpost.utils.helpers.separate_data(data, unit=None)

Separates the data into values, errors and units

Parameters

  • data (Quantity) – A pint.Quantity object containing the data points. Can be either float or uc.ufloat.

  • unit (Optional[str]) – When specified, converts the data to this unit.

Returns

Converted nominal values and errors, and the original unit of the data.

Return type

(values, errors, old_unit)

dgpost.utils.helpers.load_data(*cols)

Decorator factory for data loading.

Creates a decorator that will load the columns specified in cols and calls the wrapped function func as appropriate. The func has to accept pint.Quantity objects, return a dict[str, pint.Quantity], and handle an optional parameter "output" which prefixes (or assigns) the output data in the returned dict appropriately.

The argument of the decorator is a list[tuple], with each element being a are tuple[str, str, type]. The first field in this tuple is the str name of the argument of the decorated func, the second str field denotes the default units for that argument (or None for a unitless quantity), and the type field allows the use of the decorator with functions that expect list of points in the argument (such as trace-processing functions) or dict of pint.Quantity objects (such as functions operating on chemical compositions).

The decorator handles the following cases:

  • the decorated func is launched directly, either with kwargs or with a mixture of args and kwargs:

    • the args are assigned into kwargs using their position in the args and cols array as provided to the decorator

    • all elements in kwargs that match the argument names in the cols list provided to the decorator are converted to pint.Quantity objects, assigning the default units using the data from the cols list, unless they are a pint.Quantity already.

  • decorated func is launched with a pd.DataFrame as the args and other parameters in kwargs:

    • the data for the arguments listed in cols is sourced from the columns of the pd.DataFrame, using the provided str arguments to find the appropriate columns

    • if pd.Index is provided as the data type, and no column name is provided by the user, the index of the pd.DataFrame is passed into the called function

    • data from unit-aware pd.DataFrame objects is loaded using the pQ() accessor accordingly

    • data from unit-naive pd.DataFrame objects are coerced into pint.Quantity objects using the default units as specified in the cols list

Parameters

cols (tuple[str, str, type]) – A list[tuple[str, str, type]] containing the column names used to call the func.

Returns

loading – A wrapped version of the decorated func.

Return type

Callable

dgpost.utils.helpers.combine_tables(a, b)

Combine two pd.DataFrames into a new pd.DataFrame.

Assumes the pd.DataFrames contain a pd.MultiIndex. Automatically pads the pd.MultiIndex to match the higher number of levels, if necessary. Merges units.

Return type

DataFrame

dgpost.utils.helpers.arrow_to_multiindex(df, warn=True)

Convert the provided pd.DataFrame to a dgpost-compatible format.

  • converts tables with pd.Index into pd.MultiIndex,

  • converts ->-separated namespaces into pd.MultiIndex,

  • processes units into nested dicts.

Return type

DataFrame

dgpost.utils.helpers.keys_in_df(key, df)

Find all columns in the provided pd.DataFrame that match key.

Returns a set of all columns in the df which are matched by key. Assumes the provided pd.DataFrame contains a pd.MultiIndex.

Return type

set[tuple]

dgpost.utils.helpers.key_to_tuple(key)

Convert a provided key to a tuple for use with pd.DataFrames containing a pd.MultiIndex.

Return type

tuple

dgpost.utils.helpers.get_units(key, df)

Given a key corresponding to a column in the df, return the units. The provided key can be both a str for df with pd.Index, or any other Sequence for a df with pd.MultiIndex.

Return type

Optional[str]

dgpost.utils.helpers.set_units(key, unit, target)

Set the units of key to unit in the target object, which can be either a dict or a pd.DataFrame. See also get_units().

Return type

None