Note
Go to the end to download the full example code.
Wet-lab: an assay with a nominal factor#
Design an enzyme-activity assay whose buffer type is nominal, scored with the QQ-aware maxproqq.
An enzyme-activity assay is being optimised in a wet lab across four factors: pH, incubation temperature, buffer type, and substrate concentration. Buffer type is a nominal (unordered categorical) factor, which changes how the design must be scored. A held-out validation set is reserved so the fitted response can be checked on unseen conditions.
Because the space contains a nominal factor, the design is scored with
maxproqq. A QQ-type criterion handles the mix of numeric and
categorical factors correctly; a purely numeric criterion (phi_p,
MaxPro, …) would treat the buffer labels as if they had a numeric
distance, which is meaningless for unordered categories and would
distort the design.
Parameters#
pH (5.0-9.0, continuous, 0.1 steps): the physiological range over which the enzyme is active, at the precision a pH meter can be set to.
temperature (25-45 degC, 5-degree steps): the assay incubator’s discrete temperature settings.
buffer (nominal: ‘phosphate’, ‘tris’, ‘acetate’): three common buffers with no intrinsic ordering.
substrate (integer, 1-10 mM): substrate concentration in whole millimolar steps.
What to look at#
summary()andquality_report(): the design covers the mixed factor space; the percentiles remain meaningful becausemaxproqqscores the numeric and nominal factors appropriately.The saved pairplot: the buffer panels should show all three levels visited, and the numeric factors should be evenly spread.
enzyme_design.csv: the run list for the bench.
Mergen features used#
A nominal factor alongside continuous / discrete / integer factors.
Per-parameter rounding on the continuous pH axis.
criteria='maxproqq'as the correct choice for a space containing a nominal factor.A validation hold-out via
set_design(n_validation=...).
Estimated runtime: a few seconds to a minute.
from mergen import ParameterSpace, Sampler
# 1. Define the mixed-factor assay space.
space = ParameterSpace({
'pH': ('continuous', 5.0, 9.0, {'resolution': 41, 'round': 1}),
'temperature': range(25, 46, 5), # 25, 30, ..., 45
'buffer': ('nominal', ['phosphate', 'tris', 'acetate']),
'substrate': ('integer', 1, 10), # mM
})
# 2. Build the design with maxproqq (correct for a nominal factor) and
# reserve a validation set for the assay.
sampler = Sampler(space)
sampler.set_design(n_samples=24, n_validation=6)
result = sampler.run(criteria='maxproqq')
# 3. Inspect and save the bench run list.
result.summary()
result.quality_report()
result.plot('pairplot', save=True)
result.to_csv('enzyme_design.csv')
[WARNING] n_samples (24) < recommended 10*n_parameters (40, Loeppky et al. 2009). Design quality may be reduced.
════════════════════════════════════════════════════════════
MERGEN — Space-filling Design
════════════════════════════════════════════════════════════
Parameters : 4
Candidates : 6,150
n_samples : 24 (prescribed_in=0, focus_in=0, optimised_slots=24)
Total design : 24
Validation : 6
Criterion : maxproqq
Algorithm(s) : sa
────────────────────────────────────────────────────────────
[MERGEN] Optimising (criterion=maxproqq, algorithm=sa)...
[SA] Restart 1/5
[SA] Tuning temperature...
[SA] Start log(score)=15.408 T=3.1388e+12 iters=2400 swappable=24 hybrid=0.50
iter 500/2400 T=4.607e+11 best log(score)=15.164
iter 1000/2400 T=6.762e+10 best log(score)=15.164
iter 1500/2400 T=9.926e+09 best log(score)=15.164
iter 2000/2400 T=1.457e+09 best log(score)=15.164
[SA] Done log(score)=15.164 (accepted=2162/2400, rate=90.1%)
[SA] Restart 1: new best log(score)=15.164
[SA] Restart 2/5
[SA] Tuning temperature...
[SA] Start log(score)=27.591 T=3.7693e+12 iters=2400 swappable=24 hybrid=0.50
iter 500/2400 T=5.533e+11 best log(score)=27.591
iter 1000/2400 T=8.121e+10 best log(score)=26.375
iter 1500/2400 T=1.192e+10 best log(score)=26.375
iter 2000/2400 T=1.750e+09 best log(score)=24.692
[SA] Done log(score)=24.692 (accepted=2182/2400, rate=90.9%)
[SA] Restart 3/5
[SA] Tuning temperature...
[SA] Start log(score)=31.573 T=3.2188e+12 iters=2400 swappable=24 hybrid=0.50
iter 500/2400 T=4.725e+11 best log(score)=26.516
iter 1000/2400 T=6.935e+10 best log(score)=22.577
iter 1500/2400 T=1.018e+10 best log(score)=22.577
iter 2000/2400 T=1.494e+09 best log(score)=15.401
[SA] Done log(score)=15.401 (accepted=2173/2400, rate=90.5%)
[SA] Restart 4/5
[SA] Tuning temperature...
[SA] Start log(score)=30.392 T=5.3897e+12 iters=2400 swappable=24 hybrid=0.50
iter 500/2400 T=7.911e+11 best log(score)=25.569
iter 1000/2400 T=1.161e+11 best log(score)=25.569
iter 1500/2400 T=1.704e+10 best log(score)=25.569
iter 2000/2400 T=2.502e+09 best log(score)=25.569
[SA] Done log(score)=25.569 (accepted=2180/2400, rate=90.8%)
[SA] Restart 5/5
[SA] Tuning temperature...
[SA] Start log(score)=29.433 T=3.6355e+12 iters=2400 swappable=24 hybrid=0.50
iter 500/2400 T=5.336e+11 best log(score)=25.930
iter 1000/2400 T=7.832e+10 best log(score)=25.930
iter 1500/2400 T=1.150e+10 best log(score)=25.930
iter 2000/2400 T=1.687e+09 best log(score)=25.930
[SA] Done log(score)=25.930 (accepted=2160/2400, rate=90.0%)
[MERGEN] sa done -- score=3.851e+06 (elapsed 16.6s)
────────────────────────────────────────────────────────────
MERGEN — Final Design
────────────────────────────────────────────────────────────
Prescribed (in) : 0
Prescribed (out) : 0
Focus (in) : 0
Focus (out) : 0
Optimised : 24
Total design : 24
Validation : 6
════════════════════════════════════════════════════════════
────────────────────────────────────────────────────
MERGEN Design Summary
────────────────────────────────────────────────────
Optimised : 24
Total design : 24
Validation : 6
────────────────────────────────────────────────────
Parameters : 4
Candidates : 6150
Criterion : maxproqq
Seed : 44
Algorithm : sa
────────────────────────────────────────────────────
[METRICS] Computing MC baseline (300 designs)...
[METRICS] MC baseline complete (300 designs).
════════════════════════════════════════════════════════════════════════
MERGEN Design Metrics (n=24, d=4)
════════════════════════════════════════════════════════════════════════
Metric Value Baseline Better when Rank
────────────────────────────────────────────────────────────────────────
Min distance 0.2550 0.1218 higher 97th pct
Minimax distance 1.1435 1.1512 lower 60th pct
Max |correlation| 0.2436 0.2600 lower 56th pct
2D projection CD2 0.0976 0.1535 lower 100th pct
CV distances 0.2770 0.2912 lower 84th pct
Mean distance 1.1117 1.0942 higher 68th pct
────────────────────────────────────────────────────────────────────────
Criterion scores
────────────────────────────────────────────────────────────────────────
MAXPROQQ 3.8505e+06 1.0762e+13 100th pct lower
────────────────────────────────────────────────────────────────────────
Baseline: 300 MC designs from feasible space | Rank = percentile among baseline designs
════════════════════════════════════════════════════════════════════════
Saved: outputs/pairplot_13.png
Saved: outputs/enzyme_design.csv (30 rows)
Total running time of the script: (0 minutes 19.313 seconds)