clophfit.prtecan#

Parse Tecan files and fit files that are grouped into titrations.

A ‘titration’ in this context is defined within a list.pH or list.cl file. These files describe the properties and parameters of the titration experiment.

The command-line interface ‘prtecan’ is used to construct 96 distinct titrations and export the results to .txt files. This allows for further analysis or visualization of the titration data.

In cases where two label blocks exist in the Tecan files, the module performs a ‘global fitting’ operation. Global fitting is a method used in data analysis to best fit a model to multiple data sets simultaneously, under the assumption that some underlying parameters are shared between the data sets.

Please consult the documentation for each function in this module for more detailed information on their operation and use.

Exceptions:

FitFirstError()

Error when plotting before fitting.

Classes:

`Labelblock`(_lines[, path])	Parse a label block.
`LabelblocksGroup`(labelblocks[, allequal])	Group labelblocks with compatible metadata.
`Metadata`(value[, unit])	Represents the value of a metadata dictionary.
`PlateScheme`([file])	Define buffer, ctrl and unk wells, and ctrl names.
`Tecanfile`(path)	Parse a Tecan .xls file.
`TecanfilesGroup`(tecanfiles)	Group of Tecanfiles containing at least one common Labelblock.
`Titration`(tecanfiles, conc)	TecanfileGroup + concentrations.
`TitrationAnalysis`(tecanfiles, conc)	Perform analysis of a titration.

Functions:

`calculate_conc`(additions, conc_stock[, conc_ini])	Calculate concentration values.
`dilution_correction`(additions)	Apply dilution correction.
`extract_metadata`(lines)	Extract metadata into both Tecanfile and Labelblock.
`lookup_listoflines`(csvl[, pattern, col])	Lookup line numbers (row index) where given pattern occurs.
`merge_md`(mds)	Merge a list of metadata dict if the key value is the same in the list.
`read_xls`(path)	Read first sheet of an xls file.
`strip_lines`(lines)	Remove empty fields/cells from lines read from a csv file.

exception clophfit.prtecan.FitFirstError#

Error when plotting before fitting.

Return type:: None

class clophfit.prtecan.Labelblock(_lines, path=None)#

Parse a label block.

Parameters:

_lines (list[list[str | int | float]]) – Lines to create this Labelblock.
path (Path, optional) – Path to the containing file, if it exists.

Raises:

Exception – When data do not correspond to a complete 96-well plate.

Warns:

Warning – When it replaces “OVER” with np.nan for saturated values.

Attributes:

`path`
`metadata`	Metadata specific for this Labelblock.
`data`	The 96 data values as {'well_name', value}.
`buffer`	Background value to be subtracted before dilution correction.
`buffer_norm`	Background value to be subtracted before dilution correction.
`buffer_sd`	Get standard deviation of buffer_wells values.
`buffer_norm_sd`	Get standard deviation of normalized buffer_wells values.
`data_norm`	Normalize data by number of flashes, integration time and gain.
`data_buffersubtracted`	Buffer subtracted data.
`data_buffersubtracted_norm`	Normalize buffer-subtracted data.

Methods:

`on_buffer_wells_set`(value)	Update related attributes upon setting 'buffer_wells' in Labelblock class.
`__almost_eq__`(other)	Two labelblocks are almost equal when they could be merged after normalization.

path: Path | None = None#

metadata: dict[str, Metadata]#: Metadata specific for this Labelblock.

data: dict[str, float]#: The 96 data values as {‘well_name’, value}.

on_buffer_wells_set(value)#

Update related attributes upon setting ‘buffer_wells’ in Labelblock class.

Parameters:: value (list[str]) – The new value of ‘buffer_wells’
Return type:: None

property buffer: float | None#: Background value to be subtracted before dilution correction.

property buffer_norm: float | None#: Background value to be subtracted before dilution correction.

property buffer_sd: float | None#: Get standard deviation of buffer_wells values.

property buffer_norm_sd: float | None#: Get standard deviation of normalized buffer_wells values.

property data_norm: dict[str, float]#: Normalize data by number of flashes, integration time and gain.

property data_buffersubtracted: dict[str, float]#: Buffer subtracted data.

property data_buffersubtracted_norm: dict[str, float]#: Normalize buffer-subtracted data.

__almost_eq__(other)#

Two labelblocks are almost equal when they could be merged after normalization.

Return type:: bool
Parameters:: other (Labelblock) –

class clophfit.prtecan.LabelblocksGroup(labelblocks, allequal=False)#

Group labelblocks with compatible metadata.

data_norm always exist.

Parameters:

labelblocks (list[Labelblock]) – Labelblocks to be grouped.
allequal (bool) – True if labelblocks already tested equal.

Raises:

Exception – When labelblocks are neither equal nor almost equal.

Attributes:

`labelblocks`
`allequal`
`metadata`	Metadata shared by all labelblocks.
`data`	Return None or data.
`data_norm`	Normalize data by number of flashes, integration time and gain.
`data_buffersubtracted`	Buffer subtracted data.
`data_buffersubtracted_norm`	Buffer subtracted data.

Methods:

on_buffer_wells_set(value)

Update related attributes upon setting 'buffer_wells' in Labelblock class.

labelblocks: list[Labelblock]#

allequal: bool = False#

metadata: dict[str, Metadata]#: Metadata shared by all labelblocks.

property data: dict[str, list[float]] | None#: Return None or data.

property data_norm: dict[str, list[float]]#: Normalize data by number of flashes, integration time and gain.

on_buffer_wells_set(value)#

Update related attributes upon setting ‘buffer_wells’ in Labelblock class.

Parameters:: value (list[str]) – The new value of ‘buffer_wells’
Return type:: None

property data_buffersubtracted: dict[str, list[float]] | None#: Buffer subtracted data.

property data_buffersubtracted_norm: dict[str, list[float]]#: Buffer subtracted data.

class clophfit.prtecan.Metadata(value, unit=None)#

Represents the value of a metadata dictionary.

Parameters:

value (int | str | float | None) – The value for the dictionary key.
unit (Sequence[str | float | int] | None, optional) – The first element represents the unit, while the following elements are only listed.

Attributes:

`value`
`unit`

value: UnionType[int, str, float, None]#

unit: Optional[Sequence[str | float | int]] = None#

class clophfit.prtecan.PlateScheme(file=None)#

Define buffer, ctrl and unk wells, and ctrl names.

Parameters:: file (Path) – File path to the scheme file [<well Id, sample name>].

Attributes:

`file`
`buffer`	List of buffer wells.
`ctrl`	List of CTR wells.
`names`	A dictionary mapping sample names to their associated list of wells.

file: Optional[Path] = None#

property buffer: list[str]#: List of buffer wells.

property ctrl: list[str]#: List of CTR wells.

property names: dict[str, set[str]]#: A dictionary mapping sample names to their associated list of wells.

class clophfit.prtecan.Tecanfile(path)#

Parse a Tecan .xls file.

Parameters:

path (Path) – Path to .xls file.

Raises:

FileNotFoundError – When path does not exist.
Exception – When no Labelblock is found.

Attributes:

`path`
`metadata`	General metadata for Tecanfile, like Date and Shaking Duration.
`labelblocks`	All labelblocks contained in this file.

path: Path#

metadata: dict[str, Metadata]#: General metadata for Tecanfile, like Date and Shaking Duration.

labelblocks: list[Labelblock]#: All labelblocks contained in this file.

class clophfit.prtecan.TecanfilesGroup(tecanfiles)#

Group of Tecanfiles containing at least one common Labelblock.

Parameters:: tecanfiles (list[Tecanfile]) – List of Tecanfiles.
Raises:: Exception – When all Labelblocks are not at least almost equal.
Warns:: Warning – The Tecanfiles listed in tecanfiles are expected to contain the “same” list (of length N) of Labelblocks. Normally, N labelblocksgroups will be created. However, if not all Tecanfiles contain the same number of Labelblocks that can be merged (‘equal’ mergeable) in the same order, then a warning will be raised. In this case, a number M < N of groups can be built.

Attributes:

`tecanfiles`
`labelblocksgroups`	Each group contains its own data like a titration.
`metadata`	Metadata shared by all tecanfiles.

tecanfiles: list[Tecanfile]#

labelblocksgroups: list[LabelblocksGroup]#: Each group contains its own data like a titration. ??

metadata: dict[str, Metadata]#: Metadata shared by all tecanfiles.

class clophfit.prtecan.Titration(tecanfiles, conc)#

TecanfileGroup + concentrations.

Parameters:

tecanfiles (list[Tecanfile]) – Tecanfiles to be grouped.
conc (Sequence[float]) – Concentration or pH values.

Attributes:

`tecanfiles`
`conc`
`additions`	List of initial volume followed by additions.
`data_dilutioncorrected`	Buffer subtracted data.
`data_dilutioncorrected_norm`	Buffer subtracted data.

Methods:

`fromlistfile`(list_file)	Build Titration from a list[.pH\|.Cl] file.
`load_additions`(additions_file)	Load additions from file.
`on_buffer_wells_set`(value)	Update related attributes upon setting 'buffer_wells' in Labelblock class.
`export_data`(out_folder)	Export dat files [x,y1,..,yN] from labelblocksgroups.

tecanfiles: list[Tecanfile]#

conc: Sequence[float]#

classmethod fromlistfile(list_file)#

Build Titration from a list[.pH|.Cl] file.

Parameters:: list_file (Path | str) – File path to the listfile ([fpath conc]).
Return type:: Titration

property additions: list[float] | None#: List of initial volume followed by additions.

load_additions(additions_file)#

Load additions from file.

Return type:: None
Parameters:: additions_file (Path) –

on_buffer_wells_set(value)#

Update related attributes upon setting ‘buffer_wells’ in Labelblock class.

Parameters:: value (list[str]) – The new value of ‘buffer_wells’
Return type:: None

property data_dilutioncorrected: list[dict[str, list[float]] | None] | None#: Buffer subtracted data.

property data_dilutioncorrected_norm: list[dict[str, list[float]]] | None#: Buffer subtracted data.

export_data(out_folder)#

Export dat files [x,y1,..,yN] from labelblocksgroups.

Remember that a Titration has at least 1 normalized Lbg dataset dat_nrm.

dat: [d1, None] | [d1, d2] dat_bg: [{}, None] | [d1, None] | [{}, {}] | [d1, d2] dat_bg_dil: [{}, None] | [d1, None] | [{}, {}] | [d1, d2] dat_nrm: [d1,d2] dat_bg_nrm: [{}, {}] | [d1, d2] dat_bg_dil_nrm: [{}, {}] | [d1, d2]

Parameters:: out_folder (Path) – Path to output folder.
Return type:: None

labelblocksgroups: list[LabelblocksGroup]#: Each group contains its own data like a titration. ??

metadata: dict[str, Metadata]#: Metadata shared by all tecanfiles.

class clophfit.prtecan.TitrationAnalysis(tecanfiles, conc)#

Perform analysis of a titration.

Raises:

ValueError – For unexpected file format, e.g. header names.

Parameters:

tecanfiles (list[clophfit.prtecan.prtecan.Tecanfile]) –
conc (Sequence[float]) –

Attributes:

`fittings`	List of result dataframes.
`fz`	Function used in the fitting.
`keys_unk`	A list of wells containing samples that are neither buffer nor CTR samples.
`scheme`	Scheme for known samples like {'buffer', ['H12', 'H01'], 'ctrl'...}.

Methods:

`fromlistfile`(list_file)	Build TitrationAnalysis from a list[.pH\|.Cl] file.
`load_scheme`(schemefile)	Load scheme from file.
`fit`(kind[, ini, fin, no_weight, tval, nrm, ...])	Fit titrations.
`plot_k`(lb[, xlim, title])	Plot K values as stripplot.
`plot_well`(key)	Plot global fitting using 2 labelblocks.
`plot_all_wells`(path)	Plot all wells into a pdf.
`plot_ebar`(lb[, x, y, xerr, yerr, xmin, ...])	Plot SA vs.
`print_fitting`(lb)	Print fitting parameters for the whole plate.
`plot_buffer`([title])	Plot buffers of all labelblocksgroups.

fittings: list[DataFrame]#: List of result dataframes.

fz: Callable[[float, Union[ndarray[Any, dtype[float64]], Sequence[float]], ndarray[Any, dtype[float64]]], ndarray[Any, dtype[float64]]]#: Function used in the fitting.

keys_unk: list[str]#: A list of wells containing samples that are neither buffer nor CTR samples.

classmethod fromlistfile(list_file)#

Build TitrationAnalysis from a list[.pH|.Cl] file.

Parameters:: list_file (Path | str) – File path to the listfile ([fpath conc]).
Return type:: TitrationAnalysis

property scheme: PlateScheme#: Scheme for known samples like {‘buffer’, [‘H12’, ‘H01’], ‘ctrl’…}.

tecanfiles: list[Tecanfile]#

conc: Sequence[float]#

labelblocksgroups: list[LabelblocksGroup]#: Each group contains its own data like a titration. ??

metadata: dict[str, Metadata]#: Metadata shared by all tecanfiles.

load_scheme(schemefile)#

Load scheme from file. Set buffer_wells.

Return type:: None
Parameters:: schemefile (Path) –

fit(kind, ini=0, fin=None, no_weight=False, tval=0.95, nrm=False, bg=False, dil=False)#

Fit titrations.

Here is less general. It is for 2 labelblocks.

Parameters:

kind (str) – Titration type {‘pH’|’Cl’}
ini (int) – Initial point (default: 0).
fin (int, optional) – Final point (default: None).
no_weight (bool) – Do not use residues from single Labelblock fit as weight for global fitting.
tval (float) – Only for tval different from default=0.95 for the confint calculation.
nrm (bool) – Data normalization flag (default=False).
bg (bool) – Buffer subtraction flag (default=False).
dil (bool) – Dilution correction flag (default=False).

Return type:

None

Notes

Create (: list) 3 fitting tables into self.fittings.

plot_k(lb, xlim=None, title=None)#

Plot K values as stripplot.

Parameters:

lb (int) – Labelblock index.
xlim (tuple[float, float], optional) – Range.
title (str, optional) – To name the plot.

Returns:

The figure.

Return type:

plt.figure

Raises:

FitFirstError – When no fitting results are yet available.

plot_well(key)#

Plot global fitting using 2 labelblocks.

Here is less general. It is for 2 labelblocks.

Parameters:: key (str) – Well position as dictionary key like “A01”.
Returns:: Pointer to mpl.figure.
Return type:: plt.figure
Raises:: FitFirstError – When no fitting results are yet available.

plot_all_wells(path)#

Plot all wells into a pdf.

Parameters:: path (Path) – Where the pdf file is saved.
Raises:: FitFirstError – When no fitting results are yet available.
Return type:: None

plot_ebar(lb, x='K', y='SA', xerr='sK', yerr='sSA', xmin=None, ymin=None, xmax=None, title=None)#

Plot SA vs. K with errorbar for the whole plate.

Return type:

figure

Parameters:

lb (int) –
x (str) –
y (str) –
xerr (str) –
yerr (str) –
xmin (float | None) –
ymin (float | None) –
xmax (float | None) –
title (str | None) –

print_fitting(lb)#

Print fitting parameters for the whole plate.

Return type:: None
Parameters:: lb (int) –

plot_buffer(title=None)#

Plot buffers of all labelblocksgroups.

Return type:: figure
Parameters:: title (str | None) –

clophfit.prtecan.calculate_conc(additions, conc_stock, conc_ini=0.0)#

Calculate concentration values.

additions[0]=vol_ini; Stock concentration is a parameter.

Parameters:

additions (Sequence[float]) – Initial volume and all subsequent additions.
conc_stock (float) – Concentration of the stock used for additions.
conc_ini (float) – Initial concentration (default=0).

Returns:

Concentrations as vector.

Return type:

np.ndarray

clophfit.prtecan.dilution_correction(additions)#

Apply dilution correction.

Parameters:: additions (list[float]) – List of initial volume (index=0) followed by all additions.
Returns:: Dilution correction vector.
Return type:: NDArray[float]

clophfit.prtecan.extract_metadata(lines)#

Extract metadata into both Tecanfile and Labelblock.

From a list of stripped lines takes the first field as the key of the metadata dictionary, remaining fields goes into a list of values with the exception of Label ([str]) and Temperature ([float]).

Parameters:: lines (list_of_lines) – Lines that are a list of fields, typically from a csv/xls file.
Returns:: Metadata for Tecanfile or Labelblock.
Return type:: dict[str, str | list[str | int | float]]

Examples

>>> lines = [['Shaking (Linear) Amplitude:', '', '', '', 2, 'mm', '', '', '', '', '']]
>>> extract_metadata(lines)
{'Shaking (Linear) Amplitude:': Metadata(value=2, unit=['mm'])}

>>> lines = [['', 'Temperature: 26 °C', '', '', '', '', '', '', '', '', '']]
>>> extract_metadata(lines)
{'Temperature': Metadata(value=26.0, unit=['°C'])}

>>> lines = [['Excitation Wavelength', '', '', '', 400, 'nm', '', '', '', '', '']]
>>> extract_metadata(lines)
{'Excitation Wavelength': Metadata(value=400, unit=['nm'])}

>>> lines = [['Label: Label1', '', '', '', '', '', '', '', '', '', '', '', '']]
>>> extract_metadata(lines)
{'Label': Metadata(value='Label1', unit=None)}

>>> lines = [['Mode', '', '', '', 'Fluorescence Top Reading', '', '', '', '', '']]
>>> extract_metadata(lines)['Mode'].value
'Fluorescence Top Reading'

clophfit.prtecan.lookup_listoflines(csvl, pattern='Label: Label', col=0)#

Lookup line numbers (row index) where given pattern occurs.

Parameters:

csvl (list_of_lines) – Lines of a csv/xls file.
pattern (str) – Pattern to be searched (default=”Label: Label”).
col (int) – Column to search (default=0).

Returns:

Row/line index for all occurrences of pattern. Empty list for no occurrences.

Return type:

list[int]

clophfit.prtecan.merge_md(mds)#

Merge a list of metadata dict if the key value is the same in the list.

Return type:: dict[str, Metadata]
Parameters:: mds (list[dict[str, clophfit.prtecan.prtecan.Metadata]]) –

clophfit.prtecan.read_xls(path)#

Read first sheet of an xls file.

Parameters:: path (Path) – Path to .xls file.
Returns:: Lines.
Return type:: list_of_lines

clophfit.prtecan.strip_lines(lines)#

Remove empty fields/cells from lines read from a csv file.

Parameters:: lines (list_of_lines) – Lines that are a list of fields, typically from a csv/xls file.
Returns:: Lines removed from blank cells.
Return type:: list_of_lines

Examples

>>> lines = [['Shaking (Linear) Amplitude:', '', '', '', 2, 'mm', '', '', '', '', '']]
>>> strip_lines(lines)
[['Shaking (Linear) Amplitude:', 2, 'mm']]