Command-line tool

clop

Group command.

Usage

clop [OPTIONS] COMMAND [ARGS]...

Options

--version

Show the version and exit.

eq1

Model Kd dependence on pH.

Usage

clop eq1 [OPTIONS] KD1 PKA PH

Arguments

KD1

Required argument

PKA

Required argument

PH

Required argument

fit-titration

Fit Titration group command.

Usage

fit-titration [OPTIONS] COMMAND [ARGS]...

Options

--version

Show the version and exit.

-v, --verbose

Verbosity of messages.

-o, --out <out>

Output folder.

--is-ph, --no-is-ph

Concentrations are pH.

Default:

True

glob

Update old glob fit of multiple datasets.

Usage

fit-titration glob [OPTIONS] FILE

Options

-b, --boot <boot>

Number of booting iterations.

--weight, --no-weight

Use residue weights.

Default:

True

Arguments

FILE

Required argument

spec

Update old svd or band fit of titration spectra.

Usage

fit-titration spec [OPTIONS] CSV_F NOTE_F

Options

-b, --band <band>

Integration interval from <1> to <2>

Arguments

CSV_F

Required argument

NOTE_F

Required argument

ppr

Parse Plate Reader ppr group command.

Usage

ppr [OPTIONS] COMMAND [ARGS]...

Options

--version

Show the version and exit.

-v, --verbose

Increase verbosity: -v for INFO, -vv for DEBUG. Default is WARNING.

-q, --quiet

Silence terminal output; show only ERROR messages.

-o, --out <out>

Output folder.

enspire

Save spectra as csv tables from EnSpire xls file.

Usage

ppr enspire [OPTIONS] CSV_F [NOTE_F]

Options

-b <bands>

Label and band interval (format: LABEL LOWER UPPER)

--method <method>

How spectra become one number per well. band averages named windows (anionic 480-495, neutral 395-410, emission 500-520) and lets them share K; svd projects whole spectra on their first principal component, as this command always did. Neither is uniformly more precise – on replicate rows of one plate they trade places – but band keeps plateaus in measured units, cross-checks its bands against each other, and names a readout that has stopped titrating. global (prototype) fits every wavelength of the excitation scan with one K, the two species spectra solved linearly and a per-well amplitude, with a jackknife error; it writes <stem>_K_global.csv and <stem>_species.pdf. both runs band and svd; all runs band, svd and global. vanthoff fits every temperature of the note at once, tied by pKa(T) = dH/(2.303 R T) - dS/(2.303 R): the bands of all temperatures share one thermodynamic pair while plateaus stay free per band and temperature; pH plates fit pKa(T) (linear in 1/T), ligand plates pKd(T) - so Kd is exponential in 1/T and reported in the x units; needs at least two temperatures and writes <stem>_K_vanthoff.csv and <stem>_K_vanthoff.pdf (curves with the joint model, and the constant vs 1/T). mcr resolves each temperature’s spectra into non-negative closed concentration profiles and species spectra by alternating least squares (–components species; default 2), then fits Henderson-Hasselbalch (pH plates) or Langmuir (ligand plates) to the tracking component; it writes <stem>_K_mcr.csv, <stem>_mcr_spectra.csv and <stem>_mcr.pdf. bayes puts a seeded PyMC/NUTS posterior on the same corrected band readouts as band, combining the excitation and emission scans into one shared K, and reports the median and 94 % HDI (hdi03/hdi97, r_hat, ess_bulk) in <stem>_K_bayes.csv and <stem>_K_bayes.pdf: the successor of the legacy svd+emcee HDI - same Bayesian interval, stable readout, reproducible seed.

Default:

'band'

Options:

band | svd | both | global | vanthoff | mcr | bayes | all

--buffer, --no-buffer

For –method band: subtract the buffer well of the same plate column. A row sitting at the instrument’s floor is treated as buffer even when the note names it after the mutant.

Default:

True

--screen <screen>

Point screen for –method band, as method:threshold:min_keep. ‘studentized’ takes a family-wise alpha and a Bonferroni-corrected Student-t cutoff; ‘mad’ takes a robust z. Pass ‘none’ to fit every point.

Default:

'studentized:0.05:5'

--min-rho <min_rho>

For –method band: smallest |Spearman rho| between a band and the titrant, taken within each replicate row, for that band to carry K. A flat band has no K to give.

Default:

0.8

--band-name <band_names>

Bands allowed into the shared K; repeatable. Default is the two direct readouts (exc_anionic + em_exc420); exc_neutral and em_exc278 are reported but not fitted by default.

Options:

exc_anionic | exc_neutral | em_exc420 | em_exc278

--scan <scans>

Scans –method global or mcr takes whole; repeatable. Default is the excitation scan only: on the 25-plate readout sweep, adding the 420 nm emission scan whole widened the between-session spread (see clophfit/prenspire/spectral.py), so all-scans is offered for comparison, not as the default.

Options:

exc_anionic | exc_neutral | em_exc420 | em_exc278

--seed <seed>

NUTS seed for –method bayes; fixes the posterior draws so the 94 % HDI is reproducible run to run.

Default:

0

--draws <draws>

Posterior draws per chain for –method bayes (tuning is half of that).

Default:

2000

--chains <chains>

MCMC chains for –method bayes. A fixed –seed stays reproducible whether the chains run sequentially or in parallel.

Default:

2

--cores <cores>

CPU cores for –method bayes chain parallelism. Unset runs the chains in parallel (PyMC default, capped at the core count); 1 runs them sequentially.

--target-accept <target_accept>

NUTS target acceptance for –method bayes, in (0, 1). Unset keeps the sampler default; higher (e.g. 0.9) trades step size for better mixing.

--x-sigma <x_sigma>

For –method bayes: prior SD (pH) on each well’s true axis value - x_true ~ N(note pH, sigma), per well. The note’s pH is an instrument reading, not an exact level, so a latent axis is a defensible option: ‘auto’ pools the note’s replicate-row spread per index column (A04/B04/C04 are the same nominal target) into the sigma, a number (e.g. 0.15) fixes it. Default: the axis is fixed at the note values.

--components <components>

Species to resolve for –method mcr. Ask for 3 where –method global reports a high sv_ratio: a third non-negative component that keeps absorbing signal is evidence against the two-state model, not a fix for a bad plate.

Default:

2

Arguments

CSV_F

Required argument

NOTE_F

Optional argument

enspire-batch

Fit every folder under ROOT holding an EnSpire csv beside its *_note.csv.

One row per fit lands in enspire_batch_K.csv and one per folder that could not be paired or fitted in enspire_batch_failures.csv: a folder that fails is part of the result, not a silent gap.

Usage

ppr enspire-batch [OPTIONS] ROOT

Options

--buffer, --no-buffer

Subtract the buffer well of the same plate column.

Default:

True

--screen <screen>

Point screen as method:threshold:min_keep; ‘none’ fits every point.

Default:

'studentized:0.05:5'

--min-rho <min_rho>

Smallest |Spearman rho| for a band to carry K.

Default:

0.8

Arguments

ROOT

Required argument

tecan

Convert a list of Tecan-exported excel files into titrations.

LIST_FILE : Path to file containing Tecan files and concentration values.

Saves titrations as .dat files and fits all wells using 2 labels. The function produces:

• K plot

• csv tables for all labelblocks and global fittings.

Buffer is always subtracted if scheme indicates buffer well positions.

Usage

ppr tecan [OPTIONS] LIST_FILE

Options

--cl <cl>

Cl stock concentration (mM) of added aliquots.

--bg

Subtract buffer signal (from scheme.txt). Implied by –bg-adj.

--bg-adj

Heuristically adjust negative buffer values (implies –bg).

--bg-mth <bg_mth>

Buffer calculation method.

Default:

'mean'

Options:

mean | median | fit | meansd | mediansd

--nrm

Normalize using label metadata.

--raw-dir <raw_dir>

Folder holding the Tecan .xls files, when they are not next to LIST_FILE.

--label <label>

Fit only these measurement labels (repeatable), e.g. –label 2 for the 485 nm excitation channel alone. A plate carries 400 nm as label 1 and 485 nm as label 2; the 400 nm channel turns over at the acidic end, which one pKa cannot describe, and on this campaign’s controls including it costs accuracy against the bench pK (median |error| 0.089 against 0.055 pH) and replicate agreement (0.225 against 0.195). Unset fits every label, as before.

--sch <sch>

Path to plate scheme file (buffers and controls).

--add <add>

Path to additions file (initial volume + additions); enables dilution correction.

--all

Export all bg/dil/nrm data combinations.

--lim <lim>

x-axis range MIN MAX for K plots.

-t, --title <title>

Title for plots.

--fit, --no-fit

Perform fitting.

Default:

True

--png, --no-png

Export PNG files.

Default:

True

--fit-method <fit_method>

Global fit method: lm (standard LS), huber (robust Huber loss), irls (iterative reweighting), odr (orthogonal distance regression, x-aware).

Default:

'huber'

Options:

lm | huber | irls | odr

--fit-noise <fit_noise>

Weights for the per-well global fit (–fit-method lm or huber). fixed uses y_err as built. gain weights by floor^2 + gain*yhat with alpha 0: every well is fitted, the dof-corrected residuals of all wells are pooled into one gain per label, and the wells are refitted until it settles; floor-gain calibrates the floor too. Writes noise_single_history.csv.

Default:

'fixed'

Options:

fixed | gain | floor-gain

--outlier <outlier>

Outlier removal spec, e.g. ‘mad:3.5:4’ (method:threshold:min_keep).

--mcmc <mcmc>

MCMC sampling: None, single, single-refit (robust screening pass then refit), multi (all wells jointly, control K shared per group).

Default:

'None'

Options:

None | single | single-refit | multi

--nuts-sampler <nuts_sampler>

NUTS backend: default (pytensor/CPU), blackjax/numpyro (JAX/CPU), nutpie (Rust/CPU).

Default:

'default'

Options:

default | blackjax | numpyro | nutpie

--mcmc-samples <mcmc_samples>

Number of posterior draws per chain (tune = samples // 2).

Default:

2000

--noise-alpha <noise_alpha>

Proportional noise coefficient per label. Adds proportional term to y_err variance. Obtain from MCMC multi-noise shared_noise_params.csv.

--noise-gain <noise_gain>

Poisson gain per label. Replaces hardcoded gain=1 in shot-noise term. Obtain from MCMC multi-noise shared_noise_params.csv.

--noise-floor <noise_floor>

Read-noise floor per label, overriding the measured bg_read_noise. Reaches y_err, the FGLS/NNLS calibration and the –mcmc-noise structured floor alike. Use it to apply a floor pooled across plates rather than one estimated from a single plate’s three to six buffer wells.

--noise-floor-ref-gain <noise_floor_ref_gain>

Reader Gain each –noise-floor was quoted at, per label. The floor is then scaled to this plate’s own Gain by 10**((gain-ref)/34.1), so one calibration serves plates read at different settings. Pass 0 to leave a label’s floor unscaled, which is right where no Gain dependence was measured.

--mcmc-noise <mcmc_noise>

Observation-noise family for –mcmc single-refit and multi. ye_mag scales y_err by a learned multiplier; structured builds floor+gain*y+(alpha*y)^2 with floors from bg_noise and gain/alpha from –noise-gain/–noise-alpha.

Default:

'ye_mag'

Options:

ye_mag | structured

--noise-mode <noise_mode>

For –mcmc-noise structured, how a hint is treated: centered (a prior the posterior may leave) or fixed (pinned). It governs the floor, which is always hinted because it comes from the measured buffer noise, and any –noise-gain/–noise-alpha supplied. Gain and alpha given no value stay free, so –noise-mode fixed on its own means a pinned floor with both signal-dependent terms learned.

Default:

'centered'

Options:

centered | fixed

--noise-floor-mode <noise_floor_mode>

Override –noise-mode for floor alone. One mode for all three cannot separate the terms: pinning alpha at zero also pins the floor, so sigma cannot rescale and the run measures that instead of the term it meant to isolate.

Options:

centered | fixed

--noise-gain-mode <noise_gain_mode>

Override –noise-mode for gain alone. One mode for all three cannot separate the terms: pinning alpha at zero also pins the floor, so sigma cannot rescale and the run measures that instead of the term it meant to isolate.

Options:

centered | fixed

--noise-alpha-mode <noise_alpha_mode>

Override –noise-mode for alpha alone. One mode for all three cannot separate the terms: pinning alpha at zero also pins the floor, so sigma cannot rescale and the run measures that instead of the term it meant to isolate.

Options:

centered | fixed

--noise-ye-mag, --no-noise-ye-mag

For –mcmc-noise structured: also learn a ye_mag multiplier on sigma, per label (or per well with –per-well-ye-mags). A structured model otherwise has no overall multiplier, so a supplied floor/gain sets the level as well as the shape; this separates the two.

Default:

False

--per-well-ye-mags, --no-per-well-ye-mags

For –mcmc multi: scale y_err per well rather than per label. Unset lets the library resolve it from the noise family, which couples the two.

--ye-mag-parameterization <ye_mag_parameterization>

For –mcmc multi with per-well ye_mags: independent per label (centered), a shared well factor with per-label deviations (hierarchical), a per-label level plus one shared well factor (separable), or that plus a per-label pH axis on the noise (separable_step).

Default:

'centered'

Options:

centered | hierarchical | separable | separable_step

--plate-fit <plate_fit>

Also fit the whole plate in one classical least-squares problem, with the noise scale profiled per label across the plate and each control group pooled onto one K. Writes plate_{method}_K.csv. Minutes rather than hours, and as accurate against known pKs as the sampler.

Options:

lm | odr

--plate-noise <plate_noise>

How –plate-fit weights the points K is fitted to, with or without –plate-screen-z. fixed uses y_err as built (bg_noise floor plus any –noise-gain/–noise-alpha). calibrated estimates gain and alpha per label from the fit’s own residuals and refits under them; it describes the residuals better and fits K worse, so it is not the default. gain weights by floor^2 + gain*yhat with alpha 0, the floor held and the gain calibrated from the dof-corrected residuals between refits until it settles; floor-gain calibrates the floor too. Both write plate_lm_noise_history.csv.

Default:

'fixed'

Options:

fixed | calibrated | gain | floor-gain

--plate-screen-noise <plate_screen_noise>

The ruler –plate-screen-z judges points on. calibrated fits gain and alpha to the screening pass’s own residuals so bright and dim points are judged alike; fixed judges on y_err as built. Separate from –plate-noise, which sets the weights K is then fitted with.

Default:

'calibrated'

Options:

calibrated | fixed

--plate-screen-z <plate_screen_z>

For –plate-fit: drop points whose |z| exceeds this and refit. The ruler is –plate-screen-noise (calibrated by default, so a dim point and a bright one are judged on the same scale); the refit uses –plate-noise’s weights. 3.0 is the value measured to help; 2.5 is harmful.

--plate-screen-frac <plate_screen_frac>

For –plate-fit: also drop 400 nm points whose |y-yhat|/yhat exceeds this, sparing any the 485 nm channel moves with. A z-score fails at both ends of a titration – sigma tracks the signal while model error tracks the curve – so a 5% miss at the dim end reads as 3.6 sigma while a 36% miss at the bright end reads as 2.7. 0.12 is where reviewer calls separate; unset leaves the z-screen alone.

--mcmc-robust, --no-mcmc-robust

Use a robust likelihood for –mcmc instead of a Normal. Student-t nu=3 was the best-calibrated arm on this campaign’s plates.

Default:

False

--mcmc-robust-likelihood <mcmc_robust_likelihood>

Which robust likelihood –mcmc-robust selects: a heavy-tailed student_t, or a Normal/outlier contamination mixture that models the outliers rather than down-weighting them.

Default:

'student_t'

Options:

student_t | mixture

--student-t-nu <student_t_nu>

Student-t degrees of freedom for –mcmc-robust. Lower is heavier-tailed; pass 0 to infer nu (support above 2).

Default:

3.0

--mcmc-x-start-between-learn

For –mcmc-x-error per_well: estimate how far apart the wells’ pH axes sit (x_start_between) instead of pinning it, with –mcmc-x-start-between as the prior scale. A well’s pH offset shifts its K, so pinning that scale asserts how far two wells’ K may sit apart.

--ctr-sigma-w <ctr_sigma_w>

For –mcmc multi on a pH titration: let each control replicate keep its own K a learned distance from its group’s, with this prior SD (pH) on that distance (K_sigma_w). Between –ctr-shared-k, which asserts the replicates agree exactly, and –ctr-free-k, which says nothing about the group; ~0.08 is what the plates show. Unset leaves the model as it was.

--acid-scale

pH titrations: give each well a free factor on its most acidic step, shared by both labels, in the global lm/huber fit and in –mcmc multi. Both channels lose emission at the last acid addition by a mutant-dependent amount (the 400 nm ‘turnover’); the factor frees that step’s brightness but keeps its label ratio, which still informs K. On the 11 final library plates it improved bench accuracy over the plain fit and over dropping the step (arslanbaeva’s scripts/score_acid_loss.py).

--ctr-free-k, --ctr-shared-k

For –mcmc multi and –plate-fit: fit every well its own K rather than pooling each control group onto a shared one. Pooling buys no accuracy at the construct level and narrows the stated interval, and library wells have no group to pool with.

Default:

False

--mcmc-x-error <mcmc_x_error>

Latent pH axis for –mcmc multi. deterministic is one pipetting walk shared by every well; per_well gives each well its own walk, with step SDs from the measured pH errors (read noise plus accumulated pipetting). pH is measured in a few wells and their spread grows along the titration, so only per_well carries an unmeasured well’s pH uncertainty into its K.

Default:

'deterministic'

Options:

deterministic | per_well

--mcmc-x-start-between <mcmc_x_start_between>

For –mcmc-x-error per_well: prior SD of each well’s pH offset at the first step. It passes straight into K’s interval, so set it to the measured well-to-well spread at the first step. Unset keeps the library default.

--mcmc-tune <mcmc_tune>

Tuning draws per chain for –mcmc. Default is mcmc-samples // 2.

--mcmc-target-accept <mcmc_target_accept>

NUTS target acceptance for –mcmc. Default is latent-x aware.

--mcmc-chains <mcmc_chains>

Number of NUTS chains for –mcmc. Unset keeps the sampler default (4).

--mcmc-seed <mcmc_seed>

Random seed for –mcmc, making the draws reproducible. Unset leaves sampling nondeterministic.

--print-spec

Print the resolved analysis specification and its signature, then exit. Two runs with the same signature fit the same model, whatever flags were typed.

--dry-run

Validate inputs without processing data.

--detect-bad, --no-detect-bad

Run bad-well detection: discard unusable wells before fitting, writing discarded_wells.txt, and record everything atypical in atypical_wells.csv beside it.

Default:

True

--max-k-se <max_k_se>

With –detect-bad, a pKa whose standard error exceeds this (pH) is undetermined: left off the K plot, marked on its figure, listed in discarded_wells.txt. Every ffit*.csv carries an ‘undetermined’ column regardless. Chloride ignores it: a Kd is undetermined when its SE exceeds it, and ‘does not bind’ (a no_binding column, listed and left off the plot likewise) when its 94% lower bound is above the highest concentration titrated.

Default:

0.3

--mask-outliers, --no-mask-outliers

Mask geometric point outliers before fitting.

Default:

False

--outlier-threshold <outlier_threshold>

Threshold for geometric point outlier scoring (0-1).

Default:

0.2

Arguments

LIST_FILE

Required argument

note_to_csv

Convert a tab-separated data file into a CSV file.

Usage

note_to_csv [OPTIONS] NOTE

Options

-o, --output <output>

Output CSV file.

-l, --labels <labels>

Labels to be appended.

-t, --temp <temp>

Temperature to be appended.

Arguments

NOTE

Required argument