pratico-sensor 3.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
pratico3_cal.py ADDED
@@ -0,0 +1,362 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ PRATICO 3 - calibration (run over SSH or with keyboard + HDMI)
4
+ ==============================================================
5
+
6
+ python3 pratico3_cal.py # asks which analyte
7
+ python3 pratico3_cal.py -a N -r 3 # N-NO3, 3 replicates per level
8
+ python3 pratico3_cal.py -a P --levels 0,0.05,0.1,0.2,0.5,1
9
+ python3 pratico3_cal.py --simulate # no hardware (PC test)
10
+ python3 pratico3_cal.py --refit ~/PRATICO_3/calibration/cal_P_20261118-120223.csv --exclude 0.05
11
+ # fit again from saved readings, no measuring
12
+
13
+ Workflow
14
+ 1. Blank: distilled water, lid closed, Enter (or the OK button).
15
+ 2. Every level x replicate: kit-reacted standard in the cuvette, lid closed, Enter / OK.
16
+ If reaction_time_s > 0 in the config: add the reagent, press Enter / OK to start the
17
+ timer, insert the cuvette and close the lid; the reading is taken automatically when the
18
+ timer ends, exactly as in the field program. A level 0 is a reagent blank.
19
+ After each reading: Enter / OK = accept, r = redo, s = skip.
20
+ 3. Linear fit A = slope*C + intercept with every accepted reading. The table shows the
21
+ back-calculated concentration and recovery of every level; levels can be excluded and
22
+ included again before saving. Quality = recovery band and residual sd in mg/L (R2 shown,
23
+ but it is dominated by the highest standard).
24
+ 4. Save -> calibration/pratico3_cal.json (previous file kept with a date suffix) plus a CSV of
25
+ all readings and a text report in calibration/.
26
+
27
+ The field program is stopped while calibrating (systemctl --user stop pratico3) and restarted
28
+ at the end if it was running.
29
+ """
30
+ import argparse
31
+ import json
32
+ import os
33
+ import statistics
34
+ import subprocess
35
+ import sys
36
+ import time
37
+
38
+ import pratico3_core as core
39
+
40
+ LEVELS = {"N": [0.2, 0.5, 1, 2, 5, 10], "P": [0.02, 0.05, 0.1, 0.2, 0.5, 1]}
41
+ SIM_A = {"N": lambda c: 0.107 * c + 0.006, "P": lambda c: 0.66 * c + 0.009}
42
+
43
+
44
+ class UI:
45
+ """Console prompts that also accept the OK (= Enter) and MODE (= 'r') buttons."""
46
+
47
+ def __init__(self, hw, simulate):
48
+ self.hw = hw
49
+ self.interactive = (not simulate) and sys.stdin.isatty()
50
+
51
+ def ask(self, msg, lcd=None):
52
+ if lcd:
53
+ self.hw.show(*lcd)
54
+ if not self.interactive:
55
+ return input(msg).strip()
56
+ print(msg, end="", flush=True)
57
+ k = core.wait_key(self.hw, keyboard=True)
58
+ if k in ("ok", "mode", "mode_long"):
59
+ print({"ok": "[OK]", "mode": "[MODE]", "mode_long": "[MODE]"}[k])
60
+ return "" if k == "ok" else "r"
61
+ return k
62
+
63
+
64
+ def service(cmd):
65
+ try:
66
+ return subprocess.run(["systemctl", "--user", cmd, "pratico3.service"],
67
+ capture_output=True, text=True, timeout=20).returncode == 0
68
+ except Exception:
69
+ return False
70
+
71
+
72
+ def measure(ui, hw, cfg, blank=False):
73
+ """One reading (blank: blank_repeats cycles); retries on QC errors. None = skipped."""
74
+ while True:
75
+ try:
76
+ hw.show("Measuring...", "keep lid closed")
77
+ return core.measure_repeated(hw, cfg, cfg["blank_repeats"] if blank else 1)
78
+ except core.MeasureError as e:
79
+ if blank and str(e) == "Saturated" and cfg["autorange_on_blank"]:
80
+ g = core.autorange(hw, cfg)
81
+ print(f" blank saturated -> gain lowered to {g}x, measuring again")
82
+ continue
83
+ ans = ui.ask(f" [!] {e}. Check cuvette/lid. Enter = retry, s = skip: ",
84
+ (str(e)[:16], "OK=retry"))
85
+ if ans.lower() == "s":
86
+ return None
87
+
88
+
89
+ def fit(points):
90
+ """Least squares A = b*C + a. points: list of (C, A)."""
91
+ xs = [p[0] for p in points]
92
+ ys = [p[1] for p in points]
93
+ n = len(xs)
94
+ mx, my = statistics.fmean(xs), statistics.fmean(ys)
95
+ sxx = sum((x - mx) ** 2 for x in xs)
96
+ if n < 3 or sxx == 0:
97
+ return None
98
+ b = sum((x - mx) * (y - my) for x, y in zip(xs, ys)) / sxx
99
+ a = my - b * mx
100
+ ss_res = sum((y - (a + b * x)) ** 2 for x, y in zip(xs, ys))
101
+ ss_tot = sum((y - my) ** 2 for y in ys)
102
+ s_res = (ss_res / (n - 2)) ** 0.5
103
+ return dict(slope=b, intercept=a, r2=1 - ss_res / ss_tot if ss_tot else 0.0, s_res=s_res, n=n)
104
+
105
+
106
+ def summarize(an, readings, excluded, cfg):
107
+ pts = [(r["C"], r["A"]) for r in readings if r["C"] not in excluded]
108
+ f = fit(pts)
109
+ lines = []
110
+ lines.append(f"\n[{core.LABEL[an]}] {len(pts)} readings used"
111
+ + (f", excluded levels: {sorted(excluded)}" if excluded else ""))
112
+ if f is None:
113
+ lines.append(" not enough points for a fit (need >= 3 readings on >= 2 levels)")
114
+ return None, "\n".join(lines)
115
+ band = cfg["accept_recovery_pct"]
116
+ lines.append(f" {'level':>7} {'n':>2} {'A mean':>8} {'sd':>7} {'back-calc':>9} {'recovery':>9}")
117
+ worst = 0.0
118
+ for c in sorted({r["C"] for r in readings}):
119
+ a = [r["A"] for r in readings if r["C"] == c]
120
+ am = statistics.fmean(a)
121
+ sd = statistics.stdev(a) if len(a) > 1 else float("nan")
122
+ bc = (am - f["intercept"]) / f["slope"]
123
+ rec = bc / c * 100 if c > 0 else float("nan")
124
+ mark = " excluded" if c in excluded else ""
125
+ if c > 0 and c not in excluded:
126
+ worst = max(worst, abs(rec - 100))
127
+ if abs(rec - 100) > band:
128
+ mark = f" <-- outside +/-{band}%"
129
+ sd_txt = f"{sd:7.4f}" if len(a) > 1 else f"{'-':>7}"
130
+ lines.append(f" {c:7g} {len(a):2d} {am:8.4f} {sd_txt} {bc:9.4f} "
131
+ + (f"{rec:8.1f}%" if c > 0 else f"{'(blank)':>9}") + mark)
132
+ used = sorted({c for c, _ in pts})
133
+ lod, loq = 3.3 * f["s_res"] / f["slope"], 10 * f["s_res"] / f["slope"]
134
+ f.update(lod=lod, loq=loq, c_min=min(c for c in used if c > 0) if any(c > 0 for c in used) else 0,
135
+ c_max=max(used), worst_recovery_dev_pct=worst, levels=used, excluded=sorted(excluded))
136
+ lines.append(f" slope {f['slope']:.5f} AU per mg/L intercept {f['intercept']:+.5f} AU "
137
+ f"R2 {f['r2']:.5f}")
138
+ lines.append(f" residual sd {f['s_res'] * 1000:.2f} mAU = {f['s_res'] / f['slope']:.4f} mg/L "
139
+ f"LOD {lod:.4f} LOQ {loq:.4f} mg/L worst recovery {worst:.1f}% off")
140
+ if worst > band:
141
+ lines.append(f" [!] at least one level is outside +/-{band}% - re-measure or exclude it")
142
+ return f, "\n".join(lines)
143
+
144
+
145
+ def calibrate(ui, hw, cfg, an, levels, reps, simulate):
146
+ print(f"\n========== {core.LABEL[an]} ==========")
147
+ ui.ask("Insert the BLANK (distilled water), close the lid, press Enter / OK: ",
148
+ ("Blank: DI water", "lid closed, OK"))
149
+ hw.absorbance = 0.0
150
+ while True:
151
+ blank = measure(ui, hw, cfg, blank=True)
152
+ if blank is not None:
153
+ break
154
+ print(f" blank net {blank['net']:.1f} counts ({blank['mean'] / core.FULL_SCALE:.1%} FS), dark "
155
+ f"{blank['dark']:.1f}, gain {blank['gain']}x / {blank['integration_ms']} ms")
156
+ core.log_raw(cfg, "cal_blank", blank, {"analyte": an})
157
+ t_blank = hw.now()
158
+ rt = cfg["reaction_time_s"].get(an, 0)
159
+ readings = []
160
+ for c in levels:
161
+ r_i = 0
162
+ while r_i < reps:
163
+ tag = f"{core.LABEL[an]} {c:g} mg/L, replicate {r_i + 1}/{reps}"
164
+ if rt > 0:
165
+ ans = ui.ask(f"\n{tag}\n add the reagent, then Enter / OK to start the {rt} s timer "
166
+ f"(s = skip level): ", (f"{an} {c:g} add reag", "OK=start timer"))
167
+ if ans.lower() == "s":
168
+ break
169
+ print(f" timer running: insert the cuvette and close the lid; reading at {rt} s "
170
+ f"(MODE or s+Enter = read now)")
171
+ t_start = core.countdown(hw, rt, an, keyboard=ui.interactive)
172
+ else:
173
+ ans = ui.ask(f"\n{tag}\n insert the cuvette, close the lid, Enter / OK (s = skip level): ",
174
+ (f"{an} {c:g} mg/L r{r_i + 1}", "lid closed, OK"))
175
+ if ans.lower() == "s":
176
+ break
177
+ t_start = None
178
+ if simulate:
179
+ hw.absorbance = SIM_A[an](c)
180
+ m = measure(ui, hw, cfg)
181
+ if m is None:
182
+ continue
183
+ A = core.absorbance(m["net"], blank["net"])
184
+ react = None if t_start is None else round(m["t_mono"] - t_start, 1)
185
+ print(f" A = {A:.4f} ({A * 1000:.1f} mAU) net {m['net']:.1f} spread {m['spread']:.2%}"
186
+ + (f" reaction {react:.0f} s" if react is not None else ""))
187
+ ans = ui.ask(" Enter / OK = accept, r / MODE = redo, s = skip level: ",
188
+ (f"A={A:.4f}", "OK=acc MODE=redo"))
189
+ if ans.lower() == "r":
190
+ continue
191
+ if ans.lower() == "s":
192
+ break
193
+ rec = dict(analyte=an, C=c, rep=r_i + 1, A=A, sample_net=m["net"], blank_net=blank["net"],
194
+ dark=m["dark"], spread=m["spread"], reaction_s=react,
195
+ blank_age_s=round(hw.now() - t_blank), gain=m["gain"],
196
+ integration_ms=m["integration_ms"], time=time.strftime("%Y-%m-%d %H:%M:%S"))
197
+ readings.append(rec)
198
+ core.log_raw(cfg, "cal_standard", m, {"analyte": an, "C": c, "A": A, "reaction_s": react})
199
+ r_i += 1
200
+ excluded = set()
201
+ while True:
202
+ f, text = summarize(an, readings, excluded, cfg)
203
+ print(text)
204
+ ans = ui.ask("\nType a level to exclude / include it again, or Enter to continue: ")
205
+ if not ans:
206
+ break
207
+ try:
208
+ lv = float(ans)
209
+ except ValueError:
210
+ continue
211
+ match = [c for c in {r["C"] for r in readings} if abs(c - lv) < 1e-9]
212
+ if match:
213
+ excluded ^= {match[0]}
214
+ return f, text, readings, blank
215
+
216
+
217
+ def parse_levels(txt):
218
+ return {float(x) for x in txt.split(",") if x.strip()} if txt else set()
219
+
220
+
221
+ def refit(cfg, path, exclude):
222
+ """Fit again from a saved readings CSV (no measurement, no hardware needed)."""
223
+ import csv
224
+ with open(os.path.expanduser(path), newline="") as fh:
225
+ rows = list(csv.DictReader(fh))
226
+ if not rows:
227
+ sys.exit(f"no readings in {path}")
228
+ an = rows[0]["analyte"]
229
+ readings = [dict(r, C=float(r["C"]), A=float(r["A"])) for r in rows]
230
+ levels = {r["C"] for r in readings}
231
+ unknown = [x for x in exclude if not any(abs(x - c) < 1e-9 for c in levels)]
232
+ if unknown:
233
+ sys.exit(f"levels {unknown} are not in {path} (levels: {sorted(levels)})")
234
+ excluded = {c for c in levels if any(abs(x - c) < 1e-9 for x in exclude)}
235
+ print(f"Refit of {path} ({core.LABEL[an]}, {len(readings)} readings, measured {rows[-1]['time']})")
236
+ while True:
237
+ f, text = summarize(an, readings, excluded, cfg)
238
+ print(text)
239
+ if not sys.stdin.isatty():
240
+ break
241
+ ans = input("\nType a level to exclude / include it again, or Enter to continue: ").strip()
242
+ if not ans:
243
+ break
244
+ try:
245
+ lv = float(ans)
246
+ except ValueError:
247
+ continue
248
+ excluded ^= {c for c in levels if abs(c - lv) < 1e-9}
249
+ if f is None:
250
+ return
251
+ cal_dir = os.path.dirname(cfg["cal_file"])
252
+ os.makedirs(cal_dir, exist_ok=True)
253
+ stem = os.path.splitext(os.path.expanduser(path))[0]
254
+ ts = time.strftime("%Y%m%d-%H%M%S")
255
+ report = f"{os.path.basename(stem)}_refit_{ts}.txt"
256
+ with open(os.path.join(cal_dir, report), "w") as fh:
257
+ fh.write(f"PRATICO 3 calibration refit {ts} fw {core.VERSION} readings: "
258
+ f"{os.path.basename(path)}\n{text}\n")
259
+ print(f"\nreport saved: {os.path.join(cal_dir, report)}")
260
+ if input(f"Save this calibration for {core.LABEL[an]} as the active one? [y/N]: ").strip().lower() != "y":
261
+ print(" not saved (the previous calibration stays active)")
262
+ return
263
+ try:
264
+ cal = core.load_calibration(cfg["cal_file"])
265
+ except (OSError, ValueError):
266
+ cal = {}
267
+ r0 = rows[0]
268
+ cal[an] = dict(f, date=rows[-1]["time"][:16], refit=time.strftime("%Y-%m-%d %H:%M"),
269
+ gain=int(float(r0["gain"])), integration_ms=int(float(r0["integration_ms"])),
270
+ n_avg=cfg["n_avg"], reaction_time_s=cfg["reaction_time_s"].get(an, 0),
271
+ blank_net=float(r0["blank_net"]), fw=core.VERSION, report=report)
272
+ core.save_calibration(cfg["cal_file"], cal)
273
+ print(f" saved {cfg['cal_file']}")
274
+ if service("is-active"):
275
+ service("restart")
276
+ print(" field program restarted with the new calibration")
277
+
278
+
279
+ def main():
280
+ ap = argparse.ArgumentParser(description="PRATICO 3 calibration")
281
+ ap.add_argument("-a", "--analyte", choices=["N", "P", "B"], help="N, P or B (both)")
282
+ ap.add_argument("-r", "--replicates", type=int, default=1)
283
+ ap.add_argument("--levels", help="comma-separated mg/L, e.g. 0,0.5,1,2,5,10 (one analyte only)")
284
+ ap.add_argument("--simulate", action="store_true", help="no hardware")
285
+ ap.add_argument("--refit", metavar="CSV", help="fit again from a saved readings file "
286
+ "(calibration/cal_<analyte>_<date>.csv), without measuring")
287
+ ap.add_argument("--exclude", help="with --refit: levels to leave out, e.g. 0.05 or 0.02,0.05")
288
+ args = ap.parse_args()
289
+
290
+ cfg = core.load_config()
291
+ if args.refit:
292
+ refit(cfg, args.refit, parse_levels(args.exclude))
293
+ return
294
+ if args.simulate:
295
+ base = os.path.join(os.getcwd(), "sim_out")
296
+ cfg.update(cal_file=os.path.join(base, "calibration", "pratico3_cal.json"),
297
+ res_file=os.path.join(base, "results", "results.csv"), log_dir=os.path.join(base, "logs"))
298
+ was_running = (not args.simulate) and service("is-active")
299
+ if was_running:
300
+ print("Stopping the field program (pratico3.service) during calibration ...")
301
+ service("stop")
302
+ time.sleep(1)
303
+ hw = core.make_hw(cfg, simulate=args.simulate)
304
+ ui = UI(hw, args.simulate)
305
+ try:
306
+ print(f"PRATICO 3 calibration fw {core.VERSION} setting {hw.gain}x / {hw.integration_ms} ms "
307
+ f"n_avg {cfg['n_avg']} reaction time N {cfg['reaction_time_s'].get('N', 0)} s, "
308
+ f"P {cfg['reaction_time_s'].get('P', 0)} s")
309
+ which = args.analyte
310
+ while which not in ("N", "P", "B"):
311
+ which = ui.ask("Calibrate N (N-NO3), P (P-PO4) or B (both)? ").upper()
312
+ analytes = ["N", "P"] if which == "B" else [which]
313
+ try:
314
+ cal = core.load_calibration(cfg["cal_file"])
315
+ except (OSError, ValueError):
316
+ cal = {}
317
+ cal_dir = os.path.dirname(cfg["cal_file"])
318
+ os.makedirs(cal_dir, exist_ok=True)
319
+ for an in analytes:
320
+ levels = cfg.get("cal_levels", LEVELS).get(an, LEVELS[an])
321
+ if args.levels and len(analytes) == 1:
322
+ levels = [float(x) for x in args.levels.split(",") if x.strip()]
323
+ txt = ui.ask(f"\nLevels for {core.LABEL[an]} in mg/L [{','.join(f'{c:g}' for c in levels)}] "
324
+ f"(Enter = keep): ")
325
+ if txt and txt[0].isdigit():
326
+ levels = [float(x) for x in txt.split(",") if x.strip()]
327
+ f, text, readings, blank = calibrate(ui, hw, cfg, an, levels, max(1, args.replicates),
328
+ args.simulate)
329
+ ts = time.strftime("%Y%m%d-%H%M%S")
330
+ stem = os.path.join(cal_dir, f"cal_{an}_{ts}")
331
+ with open(stem + ".csv", "w") as fh:
332
+ keys = list(readings[0].keys()) if readings else []
333
+ fh.write(",".join(keys + ["excluded"]) + "\n")
334
+ for r in readings:
335
+ ex = f is not None and r["C"] in f.get("excluded", [])
336
+ fh.write(",".join("" if r[k] is None else str(r[k]) for k in keys) + f",{int(ex)}\n")
337
+ with open(stem + ".txt", "w") as fh:
338
+ fh.write(f"PRATICO 3 calibration {ts} fw {core.VERSION}\n{text}\n")
339
+ print(f"\nreadings saved: {stem}.csv / .txt")
340
+ if f is None:
341
+ continue
342
+ if ui.ask(f"Save this calibration for {core.LABEL[an]} as the active one? [y/N]: ").lower() != "y":
343
+ print(" not saved (the previous calibration stays active)")
344
+ continue
345
+ cal[an] = dict(f, date=time.strftime("%Y-%m-%d %H:%M"), gain=blank["gain"],
346
+ integration_ms=blank["integration_ms"], n_avg=cfg["n_avg"],
347
+ reaction_time_s=cfg["reaction_time_s"].get(an, 0), blank_net=blank["net"],
348
+ fw=core.VERSION, report=os.path.basename(stem) + ".txt")
349
+ core.save_calibration(cfg["cal_file"], cal)
350
+ print(f" saved {cfg['cal_file']}")
351
+ hw.show("Calibration done", "")
352
+ except (KeyboardInterrupt, EOFError):
353
+ print("\nInterrupted - nothing saved for the analyte in progress.")
354
+ finally:
355
+ hw.close()
356
+ if was_running:
357
+ print("Restarting the field program ...")
358
+ service("start")
359
+
360
+
361
+ if __name__ == "__main__":
362
+ main()