API#

TUCAVOC#

Calculation of chromatography amount fraction and uncertainties.

This package aims at processing data for calculating the uncertainty of the measurements.

Note

TUCAVOC python code uses concentration instead of amount fraction. As one single small word is easier most of the function use the abbreviation conc.

Utilities#

Different utility functions to use with TUCAVOC.

reading output files with python#

tucavoc.read_concs(file: PathLike) → DataFrame#

Read the concentration of substances from a TUCAVOC file.

Concentration files are usually the output of the calculations.

Return concs_df:

The pandas.DataFrame with the concentrations. This is a dataframe with the metadata columns first and then each substance concentration in one column.

tucavoc.read_output(file: PathLike) → DataFrame#

Read an output file from TUCAVOC.

Concentration files are usually the output of the calculations.

Return concs_df:

The pandas.DataFrame with the concnetrations. This is a dataframe with 2-Levels columns. The first level of the column is the substance and the second is the variable corresponding to that substance. For example to access the concentration of methane you can do : df[(‘methane’, ‘conc’)]. The metadata common to all substances is acessed using a ‘-’ instead of the substance name: df[(‘-’, ‘type’)] .

tucavoc.read_gcwerks(file_path: str | Path) → DataFrame#

Read the input file from gcwerks, adding a datetime column.

Calculations#

tucavoc.calculations.main(df_calc: DataFrame, df_subs: DataFrame, uncertainties: list[tucavoc.abstract_uncertainty.Uncertainty] = [], blanks_in_df_subs: bool = False, calib_type='std', blank_type='blank', ignore_n_first_blanks: int = 0, zero_min: bool = True, debug: bool = False, calibration_sustances: list[str] = [], interpolate: bool = True) → tuple[pandas.core.frame.DataFrame, pandas.core.frame.DataFrame]#

Main calculations.

Parameters:

  • df_calc – The dataframe containing the area of the substances for which we want to calculate the concentration.

  • df_subs – The dataframe containing information on each substances. size: substances * parameters the parameters required are the name of the parameters in the documentation. see Glossary .

  • uncertainties – A list of uncertainties to calculate. One can choose which one they want.

  • blanks_in_df_subs – Whether the blank area to use is a constant from df_subs. See blank_conc_preset , that should then be present in the df_subs .

  • calib_type – The name in the ‘type’ column of df_calc that corresponds to the calibration runs.

  • blank_type – The name in the ‘type’ column of df_calc that corresponds to the blank runs.

  • ignore_n_first_blanks – The number of blanks runs to ignore at the start of a set of blank runs.

  • zero_min – Whether zero should be used as a min value in case negative are calculated (clipping).

  • debug – Whether to add debug information to the dfs.

  • calibration_sustances – The list of substances to use in the calibration to calculate the CRF. If not given, all substances will be used.

  • interpolate – Whether to interpolate the calibration and blank data.

TUCAVOC content#

This section describes objects that represent tucavoc content.

Parameters#

Parameters represent variables that are used in tucavoc calculations. They are all described in the Glossary .

Here are classes that represents possible types of parameters.

class tucavoc.abstract_uncertainty.Parameter(name: str, val: float | str | bool | None, full_name: str | None = None, explanation: str = '', unit: str = '-', tex_name: texstr = '', selectable: Selection = Selection.GLOBAL, type: Type | None = None)#

Base class for tucavoc parameters.

Contains different attributes that are need by all the parameters. They are compatible with the widget and with the docs, allowing for easy additions of new parameters.

Parameters:

  • name – Name of the parameter.

  • val – Value of the parameter.

Used only for documentation purposes or for the widget:

Parameters:

  • full_name – Full name of the parameter.

  • explanation – Explanation of the parameter.

  • unit – Unit of the parameter.

  • tex_name – Name of the parameter in latex.

  • selectable – Whether parameter is selectable for one substance or for all.

  • type – (Python) Type of the parameter.

class tucavoc.abstract_uncertainty.FloatParamter(name: str, val: float, full_name: str | None = None, explanation: str = '', unit: str = '-', tex_name: ~tucavoc.tex.texstr = '', selectable: ~tucavoc.abstract_uncertainty.Selection = Selection.GLOBAL, type: ~typing.Type = <class 'float'>, min_val: float = 0, max_val: float = 1000000000.0, decimals: int = 6)#

A parameter that is a float.

Parameters:

  • min_val – Minimum value of the parameter.

  • max_val – Maximum value of the parameter.

  • decimals – Number of decimals to display.

class tucavoc.abstract_uncertainty.BoolParameter(name: str, val: bool, full_name: str | None = None, explanation: str = '', unit: str = '-', tex_name: ~tucavoc.tex.texstr = '', selectable: ~tucavoc.abstract_uncertainty.Selection = Selection.GLOBAL, type: ~typing.Type = <class 'bool'>)#

A parameter that is a boolean.

The value is either True or False.

class tucavoc.abstract_uncertainty.CalculatedVariable(name: str, val: None = None, full_name: str | None = None, explanation: str = '', unit: str = '-', tex_name: tex.texstr = '', selectable: Selection = Selection.GLOBAL, type: Type | None = None, equations: list[Equation] = <factory>)#

A variable that is calculated from other variables.

Parameters:

  • val – Value of the variable.

  • equations – List of equations that are used to calculate the variable. (only used for documentation purposes)

Uncertainties#

class tucavoc.abstract_uncertainty.Uncertainty#

An abstract class for the uncertainties calculated by TUCAVOC.

The attributes of this class are used to generate the documentation.

Only calculate() needs to be implemented in each subclass, and is used to calculate the uncertainty during the execution in tucavoc.calculations.main() .

Parameters:

  • name – Name of the uncertainty.

  • param_name – Name of the uncertainty when in a funciton parameter.

  • name_camel_case – Name of the uncertainty in camel case.

  • latex_name – Name of the uncertainty in latex.

  • title_name – Name of the uncertainty in the title.

  • title_char – Character to use to underline the title. Used for specifying the title level.

  • short_explanation – A short explanation text for what this uncertainty. This is shown in the glossary.

  • explanation – An explanation text for what this uncertainty is about.

  • color – A color corresponding to this uncertainty value (used for plotting).

  • parameters – A list of the name of the attributes that should be selectable by the user.

  • parameters_dict – Mapps the name of the param to the paramter.

abstract calculate(*args, **kwargs) → ndarray#

Calculate the uncertainty.

This should return the value for all the samples in pmol/mol.

Equations#

Equations are only used for documentation purposes.

class tucavoc.equations.Equation(full_name: str, latex_equation: texstr, output_variable: CalculatedVariable, variables: list[tucavoc.abstract_uncertainty.Parameter], derivation: texstr | None = None)#

An equation used to calculate a variable.

During building of the documentation, the equations are saved in a rst file, and is then automatically added to an equation glossary.

See file conf.py in the docs folder.

Parameters:

  • full_name – Full name of the equation.

  • latex_equation – LaTeX equation.

  • output_variable – Variable calculated by the equation.

  • variables – Variables used in the equation.

  • name – Name of the equation (lowercase, no spaces).

  • derivation – LaTeX equations for the derivation of the equation.

Additional Data#

class tucavoc.additional_data.AdditionalData(settings: QSettings | None = None)#

Represent an additonal data in tucavoc.

Parameters:

  • settings – Settings to use for the additional data. Some additional data might need to save user settings if some parameters can be selected.

  • widget – Qt Widget to be displayed in the main widget.

get_data(time_serie: Series) → DataFrame#

Get the additional data for the requested times.

This method must be implemented when creating a new type of additional data.

Parameters:

time_serie – Times for which the additional data should be returned.

Returns:

Dataframe with the additional data. Can be many columns, but they have to provide a value for each time in the time_serie.