clophfit.fitting.plotting#

Provide utilities for creating various types of plots used in this project.

Primary functions encompassed are:

plot_spectra: Develops a plot for spectral data. Each line is colored based on a designated colormap. plot_autovectors: Plots the autovectors. plot_autovalues: Plots the singular values from SVD. plot_fit: Plots residuals for each dataset with uncertainty. plot_pca: Plots the first two principal components. plot_spectra_distributed: Plots spectra from titration distributing on the figure top. plot_emcee: Plots emcee result. plot_emcee_k_on_ax: Plots emcee result for a specific parameter on an axis. distribute_axes: Positions axes evenly along the horizontal axis of the figure.

The module uses several dependencies such as ArviZ, numpy, pandas, seaborn, lmfit, matplotlib, and uncertainties. Moreover, it includes a range of internal project modules and a specific color map for PCA components and LM fit.

Helper Functions:

_apply_common_plot_style: Applies grid style, title, and labels to a plot. _create_spectra_canvas: Creates figure and axes for spectra plot.

Classes:

PlotParameters: Parameters for plotting, depending on whether the data is pH or Cl.

Classes#

PlotParameters

Parameters for plotting, depending on whether the data is pH or Cl.

Functions#

`distribute_axes`(fig, num_axes)	Position axes evenly along the horizontal axis of the figure.
`plot_autovalues`(ax, s)	Plot the singular values from SVD.
`plot_autovectors`(ax, wl, u)	Plot autovectors.
`plot_pca`(ax, v, conc, pp)	Plot the first two principal components.
`plot_spectra`(ax, spectra, pp)	Plot spectra.
`plot_spectra_distributed`(fig, titration, pp[, dbands])	Plot spectra from titration distributing on the top of the figure top.
`plot_qc_mean_vs_std`(trace[, results, ...])	Plot standard deviation versus mean of inferred sigma for quality control.
`plot_emcee`(flatchain)	Plot emcee result.
`plot_emcee_k_on_ax`(ax, res_emcee[, p_name])	Plot emcee result.
`plot_fit`(ax, ds, params[, nboot, pp])	Plot fitted curves and data points with uncertainty on a given Axes.
`plot_fit_gemini`(ax, ds, params[, nboot, pp])	Plot fitted curves and data points on a given axis.
`print_emcee`(result_emcee)	Print maximum likelihood estimation (MLE) results from an emcee fitting.
`extract_sigma_df`(trace[, results])	Extract heteroscedastic sigma summaries from a PyMC trace.
`plot_qc_span_vs_center`(data[, center, ...])	Plot signal span versus center for quality control of titration wells.
`qc_flag_bad_wells`(…)	Flag low-quality wells from span-vs-amplitude QC, without plotting.
`qc_flag_bad_wells_titration`(…)	Robust QC bad-well detection from a Titration (buffers + controls handled).
`plot_qc_span_vs_center_titration`(tit[, center, ...])	Plot signal span versus center for quality control using a Titration object.

Module Contents#

class clophfit.fitting.plotting.PlotParameters#: Parameters for plotting, depending on whether the data is pH or Cl.

clophfit.fitting.plotting.distribute_axes(fig, num_axes)#

Position axes evenly along the horizontal axis of the figure.

Parameters:

fig (Figure) – The Figure object on which the Axes objects are drawn.
num_axes (int) – The number of Axes objects to position.

Returns:

A list of positioned Axes objects.

Return type:

list[Axes]

clophfit.fitting.plotting.plot_autovalues(ax, s)#

Plot the singular values from SVD.

Parameters:

ax (Axes) – The mpl.axes.axes on which to plot the singular values.
s (ArrayF) – The singular values from the SVD.

Return type:

None

clophfit.fitting.plotting.plot_autovectors(ax, wl, u)#

Plot autovectors.

Parameters:

ax (Axes) – The mpl.axes.Axes object to which the plot should be added.
wl (pd.Index[int]) – The index of spectra data frame.
u (ArrayF) – The left singular vectors obtained from SVD.

Return type:

None

clophfit.fitting.plotting.plot_pca(ax, v, conc, pp)#

Plot the first two principal components.

Parameters:

ax (Axes) – The mpl.axes.Axes object to which the plot should be added.
v (ArrayF) – The matrix containing the principal components.
conc (ArrayF) – The concentrations used for the titration.
pp (PlotParameters) – The PlotParameters object containing plot parameters.

Return type:

None

clophfit.fitting.plotting.plot_spectra(ax, spectra, pp)#

Plot spectra.

Parameters:

ax (Axes) – The Mpl.Axes.Axes object to which the plot should be added.
spectra (pd.DataFrame) – The DataFrame containing spectral data.
pp (PlotParameters) – The PlotParameters object containing plot parameters.

Return type:

None

clophfit.fitting.plotting.plot_spectra_distributed(fig, titration, pp, dbands=None)#

Plot spectra from titration distributing on the top of the figure top.

Parameters:

fig (matplotlib.figure.Figure)
titration (dict[str, pandas.DataFrame])
pp (PlotParameters)
dbands (dict[str, tuple[int, int]] | None)

Return type:

None

clophfit.fitting.plotting.plot_qc_mean_vs_std(trace, results=None, figsize_per_label=(5, 4), annotate_wells=None, z_threshold=3.0, bg_noise=None, bg_multiplier=4.0)#

Plot standard deviation versus mean of inferred sigma for quality control.

Identifies “dead” or flat-line wells (e.g. caused by pipetting errors or missing fluorophore) which typically exhibit both low mean and low span (max - min) for the inferred standard deviation (sigma_obs) across titration steps.

Parameters:

trace (xr.DataTree | MultiFitResult) – The PyMC inference trace containing sigma_obs deterministic nodes, or the multi-well result wrapper returned by fit_binding_pymc_multi.
results (Mapping[str, FitResult] | None, optional) – The dictionary of well results to derive fallback sigma values.
figsize_per_label (tuple[float, float], optional) – Figure size allocated for each spectral band (label). Default is (5, 4).
annotate_wells (list[str] | None, optional) – A list of specific well IDs to annotate on the plot (e.g., [“B03”, “C05”]). If None, no explicit labels are drawn.
z_threshold (float) – Z-score threshold for identifying outliers.
bg_noise (Mapping[str, float] | None, optional) – Background noise dictionary.
bg_multiplier (float) – Multiplier for background noise.

Returns:

The generated QC matplotlib figure.

Return type:

Figure

clophfit.fitting.plotting.plot_emcee(flatchain)#

Plot emcee result.

Parameters:: flatchain (pandas.DataFrame)
Return type:: matplotlib.figure.Figure

clophfit.fitting.plotting.plot_emcee_k_on_ax(ax, res_emcee, p_name='K')#

Plot emcee result.

Parameters:

ax (matplotlib.axes.Axes)
res_emcee (lmfit.minimizer.MinimizerResult)
p_name (str)

Return type:

None

clophfit.fitting.plotting.plot_fit(ax, ds, params, nboot=0, pp=None)#

Plot fitted curves and data points with uncertainty on a given Axes.

Parameters:

ax (Axes) – The matplotlib axis to plot on.
ds (Dataset) – The dataset containing the data points.
params (Parameters) – The fitted parameters from lmfit.
nboot (int) – Number of bootstrap samples to generate confidence bands.
pp (PlotParameters | None) – Plotting parameters for consistent styling.

Return type:

None

clophfit.fitting.plotting.plot_fit_gemini(ax, ds, params, nboot=0, pp=None)#

Plot fitted curves and data points on a given axis.

Parameters:

ax (axes.Axes) – The matplotlib axis to plot on.
ds (Dataset) – The dataset containing the data points.
params (Parameters) – The fitted parameters from lmfit.
nboot (int) – Number of bootstrap samples to generate confidence bands.
pp (PlotParameters | None) – Plotting parameters for consistent styling.

Return type:

None

clophfit.fitting.plotting.print_emcee(result_emcee)#

Print maximum likelihood estimation (MLE) results from an emcee fitting.

Parameters:: result_emcee (lmfit.minimizer.MinimizerResult)
Return type:: None

clophfit.fitting.plotting.extract_sigma_df(trace, results=None)#

Extract heteroscedastic sigma summaries from a PyMC trace.

Parameters:

trace (xarray.DataTree | clophfit.fitting.data_structures.MultiFitResult)
results (collections.abc.Mapping[str, clophfit.fitting.data_structures.FitResult] | None)

Return type:

pandas.DataFrame

clophfit.fitting.plotting.plot_qc_span_vs_center(data, center='mean', figsize_per_label=(5, 4), z_threshold=3.0, bg_noise=None, bg_multiplier=4.0, loglog=False, annotate_wells=None, span_q=None, ctrl_wells=None)#

Plot signal span versus center for quality control of titration wells.

Identifies dead or flat wells (e.g. caused by pipetting errors or missing fluorophore) which show low dynamic range relative to their signal center.

Parameters:

data (Mapping[str, Mapping[str, ArrayF]]) – Raw or normalised data keyed by label, then by well name.
center (str | float) – X-axis amplitude per well: "mean", "max", or a quantile in (0, 1) of |signal| (e.g. 0.9, more robust than "max").
figsize_per_label (tuple[float, float]) – Figure size allocated per spectral label.
z_threshold (float) – Z-score threshold for trendline-based outlier detection.
bg_noise (Mapping[str, float | ArrayF] | Mapping[int, float | ArrayF] | None) – Background noise reference per label (string or integer keys). Used to draw a bg_multiplier * bg_noise reference line.
bg_multiplier (float) – Multiplier applied to bg_noise for the low-signal reference.
loglog (bool) – If True, use log-log axes.
annotate_wells (list[str] | None) – Well IDs to annotate even if not flagged as outliers (e.g. to overlay wells flagged by another detector for comparison).
span_q (tuple[float, float] | None) – None uses max - min for the y-axis span; a (lo, hi) pair uses the robust inter-quantile range quantile(hi) - quantile(lo).
ctrl_wells (list[str] | None) – Control wells: excluded from the trendline fit and the z-score flagging (good data with different span-vs-signal statistics) but still subject to the background floor. Good controls are drawn distinctly for reference; controls below the floor appear as background outliers.

Returns:

The generated QC matplotlib figure.

Return type:

Figure

clophfit.fitting.plotting.qc_flag_bad_wells(data: collections.abc.Mapping[str, collections.abc.Mapping[str, clophfit.clophfit_types.ArrayF]], *, center: str | float = ..., span_q: tuple[float, float] | None = ..., z_threshold: float = ..., bg_noise: collections.abc.Mapping[str, float | clophfit.clophfit_types.ArrayF] | collections.abc.Mapping[int, float | clophfit.clophfit_types.ArrayF] | None = ..., bg_multiplier: float = ..., ctrl_wells: collections.abc.Iterable[str] = ..., combine: None = ...) → dict[str, list[str]]#

Flag low-quality wells from span-vs-amplitude QC, without plotting.

A robust, non-mutating alternative to clophfit.prtecan.Titration.detect_and_discard_bad_wells(): fits a Theil-Sen trend of span versus a robust amplitude (quantile center) and applies a background floor. Returns, per label, the wells that are trend outliers or fall below bg_multiplier * bg_noise. The companion plot_qc_span_vs_center() highlights exactly these wells.

Parameters:

data (Mapping[str, Mapping[str, ArrayF]]) – Per-label, per-well signal arrays (exclude buffer wells beforehand).
center (str | float) – Amplitude measure; a quantile such as 0.9 is robust to spikes.
span_q (tuple[float, float] | None) – Robust inter-quantile span (lo, hi), or None for max - min.
z_threshold (float) – Robust z-score threshold for trend-outlier flagging.
bg_noise (Mapping[str, float | ArrayF] | Mapping[int, float | ArrayF] | None) – Background reference per label for the low-signal floor.
bg_multiplier (float) – Multiplier on bg_noise for the floor.
ctrl_wells (Iterable[str]) – Control wells: excluded from the trend fit and the z-score flagging (good data with different span-vs-signal statistics), but still subject to the background floor.
combine (Literal["intersection", "union"] | None) – None returns the per-label dict. "intersection" returns one sorted list of wells flagged in every label (conservative); "union" returns wells flagged in any label.

Returns:

Per-label flagged wells, or a single combined list when combine is set.

Return type:

dict[str, list[str]] | list[str]

clophfit.fitting.plotting.qc_flag_bad_wells_titration(tit: object, *, center: str | float = ..., span_q: tuple[float, float] | None = ..., z_threshold: float = ..., bg_multiplier: float = ..., combine: None = ...) → dict[str, list[str]]#

Robust QC bad-well detection from a Titration (buffers + controls handled).

Non-mutating alternative to clophfit.prtecan.Titration.detect_and_discard_bad_wells(); see qc_flag_bad_wells(). Buffer wells are dropped and control wells (tit.scheme.ctrl) are excluded from the trend fit and the z-score flagging, but a control below the background floor is still flagged. Pass combine="intersection" for one set of wells flagged in every label. Does not touch tit.scheme.

clophfit.fitting.plotting.plot_qc_span_vs_center_titration(tit, center=0.9, figsize_per_label=(5, 4), z_threshold=3.0, bg_multiplier=4.0, loglog=False, annotate_wells=None, span_q=(0.1, 0.9))#

Plot signal span versus center for quality control using a Titration object.

Convenience wrapper around plot_qc_span_vs_center() that extracts data and background noise from a Titration, excludes buffer wells, and defaults to the robust q90 amplitude and inter-quantile span. Pass annotate_wells=tit.scheme.discard to overlay another detector’s verdict for comparison.

Parameters:

tit (object) – The titration object.
center (str | float) – Amplitude measure forwarded to plot_qc_span_vs_center() (default 0.9 quantile).
figsize_per_label (tuple[float, float]) – Figure size per spectral label.
z_threshold (float) – Z-score threshold for trendline outlier detection.
bg_multiplier (float) – Multiplier applied to the background noise reference.
loglog (bool) – If True, use log-log axes.
annotate_wells (list[str] | None) – Well IDs to annotate even if not flagged.
span_q (tuple[float, float] | None) – Robust span quantiles (lo, hi) (default (0.1, 0.9)), or None for max - min.

Returns:

The generated QC matplotlib figure.

Return type:

Figure