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.

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, is_ph)	Build titrations from grouped Tecanfiles and corresponding concentrations or pH values.
`TitrationAnalysis`(tecanfiles, conc, is_ph)	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.

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:

__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}.

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.

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.

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, is_ph)#

Build titrations from grouped Tecanfiles and corresponding concentrations or pH values.

Parameters:

tecanfiles (list[Tecanfile]) – Tecanfiles to be grouped.
conc (ArrayF) – Concentration or pH values.
is_ph (bool) – Indicate if x values represent pH (default is False).

Attributes:

`tecanfiles`
`conc`
`is_ph`
`additions`	List of initial volume followed by additions.
`data`	Buffer subtracted and corrected for dilution data.
`data_nrm`	Buffer subtracted, corrected for dilution and normalized data.
`scheme`	Scheme for known samples like {'buffer', ['H12', 'H01'], 'ctrl'...}.

Methods:

`fromlistfile`(list_file, is_ph)	Build Titration from a list[.pH\|.Cl] file.
`load_additions`(additions_file)	Load additions from file.
`load_scheme`(schemefile)	Load scheme from file.
`export_data`(out_folder)	Export dat files [x,y1,..,yN] from labelblocksgroups.

tecanfiles: list[Tecanfile]#

conc: ndarray[Any, dtype[float64]]#

is_ph: bool#

classmethod fromlistfile(list_file, is_ph)#

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

Parameters:

list_file (Path | str) – File path to the listfile ([fpath conc]).
is_ph (bool) – Indicate if x values represent pH.

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) –

property data: list[dict[str, list[float]] | None] | None#: Buffer subtracted and corrected for dilution data.

property data_nrm: list[dict[str, list[float]]] | None#: Buffer subtracted, corrected for dilution and normalized data.

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

load_scheme(schemefile)#

Load scheme from file. Set buffer_wells.

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

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, is_ph)#

Perform analysis of a titration.

Raises:

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

Parameters:

tecanfiles (list[Tecanfile]) –
conc (ArrayF) –
is_ph (bool) –

Classes:

FitKwargs([ini, fin, weight])

Represent arguments for fit method.

Attributes:

`keys_unk`	A list of wells containing samples that are neither buffer nor CTR samples.
`fitdata`	Data used for fitting.
`fitdata_params`	Get the datafit parameters.
`fitkws`	Get the arguments for fitting.
`results`	Result dataframes.
`result_dfs`	Result dataframes.

Methods:

`fromlistfile`(list_file, is_ph)	Build TitrationAnalysis from a list[.pH\|.Cl] file.
`fit`()	Fit titrations.
`plot_k`(lb, hue_column[, xlim, title])	Plot K values as stripplot.
`plot_all_wells`(lb, path)	Plot all wells into a pdf.
`plot_ebar`(lb, y, yerr[, x, xerr, xmin, ...])	Plot SA vs.
`print_fitting`(lb)	Print fitting parameters for the whole plate.
`plot_buffer`([title])	Plot buffers of all labelblocksgroups.
`export_png`(lb, path)	Export png like lb1/ lb2/ lb1_lb2/.

class FitKwargs(ini=0, fin=None, weight=True)#

Represent arguments for fit method.

Attributes:

`ini`
`fin`
`weight`

Parameters:

ini (int) –
fin (int | None) –
weight (bool) –

ini: int = 0#

fin: Optional[int] = None#

weight: bool = True#

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

classmethod fromlistfile(list_file, is_ph)#

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

Return type:

TitrationAnalysis

Parameters:

list_file (Path | str) –
is_ph (bool) –

property fitdata: Sequence[dict[str, list[float]] | None]#: Data used for fitting.

property fitdata_params: dict[str, bool]#: Get the datafit parameters.

tecanfiles: list[Tecanfile]#

conc: ArrayF#

is_ph: bool#

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

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

property fitkws: FitKwargs#: Get the arguments for fitting.

property results: list[dict[str, FitResult]]#: Result dataframes.

property result_dfs: list[DataFrame]#: Result dataframes.

fit()#

Fit titrations.

The fitting process uses the initial point (ini), the final point (fin), and weighting (weight) parameters defined in the FitKwargs instance (accessible through self.fitkws).

To perform a fit, you would first define the fit parameters and then call the fit method: titan.fitkws = TitrationAnalysis.FitKwargs(ini=0, fin=None, weight=True)

Returns:: A list of dictionaries with fitting results.
Return type:: list[dict[str, FitResult]]

Notes

This method is less general and is designed for two label blocks.

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

Plot K values as stripplot.

Parameters:

lb (int) – Labelblock index.
hue_column (str) – Column in fitresults_df used for color-coding data points in the stripplot.
xlim (tuple[float, float], optional) – Range.
title (str, optional) – To name the plot.

Returns:

The figure.

Return type:

plt.figure

plot_all_wells(lb, path)#

Plot all wells into a pdf.

Return type:

None

Parameters:

lb (int) –
path (str | Path) –

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

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

Return type:

figure

Parameters:

lb (int) –
y (str) –
yerr (str) –
x (str) –
xerr (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) –

export_png(lb, path)#

Export png like lb1/ lb2/ lb1_lb2/.

Return type:

None

Parameters:

lb (int) –
path (str | Path) –

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:

ArrayF

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:: ArrayF

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, 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']]