labqc 0.4.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.
labqc/__init__.py ADDED
@@ -0,0 +1,6 @@
1
+ """Calculations for laboratory quality work: uncertainty, validation, PT, IQC, emissions."""
2
+
3
+ from . import control_charts, emissions, proficiency, uncertainty, validation
4
+
5
+ __all__ = ["control_charts", "emissions", "proficiency", "uncertainty", "validation"]
6
+ __version__ = "0.4.0"
@@ -0,0 +1,215 @@
1
+ """Internal quality control: Shewhart limits and Westgard multirules.
2
+
3
+ Rules are evaluated on z = (x - target) / sd for one control material:
4
+
5
+ 1_2s warning one result beyond 2 SD
6
+ 1_3s reject one result beyond 3 SD (random error)
7
+ 2_2s reject two consecutive results beyond 2 SD on the same side (systematic)
8
+ R_4s reject consecutive results differ by more than 4 SD, one above +2 SD and
9
+ one below -2 SD (random error)
10
+ 4_1s reject four consecutive results beyond 1 SD on the same side (systematic)
11
+ 10_x reject ten consecutive results on the same side of the target (systematic)
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ from collections.abc import Mapping, Sequence
17
+ from dataclasses import dataclass
18
+
19
+ import numpy as np
20
+ import pandas as pd
21
+
22
+ REJECT_RULES = ("1_3s", "2_2s", "R_4s", "4_1s", "10_x")
23
+
24
+
25
+ @dataclass(frozen=True)
26
+ class Limits:
27
+ centre: float
28
+ sd: float
29
+
30
+ def line(self, n_sd: float) -> float:
31
+ return self.centre + n_sd * self.sd
32
+
33
+
34
+ def limits_from_data(values: Sequence[float], method: str = "sd") -> Limits:
35
+ """Estimate the centre line and SD from a baseline run.
36
+
37
+ method "sd" uses the sample standard deviation; "moving_range" uses the
38
+ average moving range / 1.128, which is less inflated by drifts.
39
+ """
40
+ x = np.asarray(values, dtype=float)
41
+ if method == "moving_range":
42
+ sd = float(np.mean(np.abs(np.diff(x))) / 1.128)
43
+ elif method == "sd":
44
+ sd = float(x.std(ddof=1))
45
+ else:
46
+ raise ValueError("method must be 'sd' or 'moving_range'")
47
+ return Limits(float(x.mean()), sd)
48
+
49
+
50
+ def _run_same_side(z: np.ndarray, threshold: float, length: int) -> np.ndarray:
51
+ """True where the last `length` points are all beyond `threshold` on one side."""
52
+ hit = np.zeros(z.size, dtype=bool)
53
+ for i in range(length - 1, z.size):
54
+ w = z[i - length + 1 : i + 1]
55
+ if (w > threshold).all() or (w < -threshold).all():
56
+ hit[i] = True
57
+ return hit
58
+
59
+
60
+ def westgard(values: Sequence[float], limits: Limits) -> pd.DataFrame:
61
+ """Flag each result with the Westgard rules it violates.
62
+
63
+ Returns a table with the value, its z-score, one boolean column per rule,
64
+ and a status: "accept", "warning" (1_2s only) or "reject".
65
+ """
66
+ x = np.asarray(values, dtype=float)
67
+ z = (x - limits.centre) / limits.sd
68
+ prev = np.concatenate([[np.nan], z[:-1]])
69
+ rules = {
70
+ "1_2s": np.abs(z) > 2,
71
+ "1_3s": np.abs(z) > 3,
72
+ "2_2s": _run_same_side(z, 2, 2),
73
+ "R_4s": ((z > 2) & (prev < -2)) | ((z < -2) & (prev > 2)),
74
+ "4_1s": _run_same_side(z, 1, 4),
75
+ "10_x": _run_same_side(z, 0, 10),
76
+ }
77
+ out = pd.DataFrame({"value": x, "z": z.round(3), **rules})
78
+ reject = out[list(REJECT_RULES)].any(axis=1)
79
+ out["status"] = np.where(reject, "reject", np.where(out["1_2s"], "warning", "accept"))
80
+ return out
81
+
82
+
83
+ def _same_side(window: np.ndarray, threshold: float) -> bool:
84
+ return bool(window.size) and bool((window > threshold).all() or (window < -threshold).all())
85
+
86
+
87
+ def westgard_levels(
88
+ values: Mapping[str, Sequence[float]], limits: Mapping[str, Limits]
89
+ ) -> pd.DataFrame:
90
+ """Westgard multirules across two or three control materials run together.
91
+
92
+ `values` maps each control level (e.g. "low", "high") to its results,
93
+ one per run; `limits` gives each level its own centre and SD. Rules use
94
+ z-scores, so levels with different concentrations can be compared.
95
+
96
+ Two levels: 1_3s, 2_2s (both levels in one run, or one level in two
97
+ runs), R_4s (one level above +2 SD and the other below -2 SD in one run),
98
+ 4_1s (two runs x two levels, or one level over four runs), 10_x (five
99
+ runs x two levels, or one level over ten runs).
100
+
101
+ Three levels: 1_3s, 2of3_2s (two of the three in one run beyond 2 SD on
102
+ the same side), R_4s, 3_1s (all three in one run, or one level over three
103
+ runs), 12_x (four runs x three levels, or one level over twelve runs).
104
+
105
+ Returns one row per run: z per level, one boolean column per rule and a
106
+ status ("accept", "warning" for 1_2s only, or "reject"), like `westgard`.
107
+ """
108
+ names = list(values)
109
+ if len(names) not in (2, 3):
110
+ raise ValueError("westgard_levels needs two or three control levels")
111
+ if set(limits) != set(names):
112
+ raise ValueError("limits must have one entry per control level")
113
+ lengths = {len(values[n]) for n in names}
114
+ if len(lengths) != 1:
115
+ raise ValueError("every level needs one result per run")
116
+ z = np.column_stack(
117
+ [(np.asarray(values[n], dtype=float) - limits[n].centre) / limits[n].sd for n in names]
118
+ )
119
+ runs, levels = z.shape
120
+
121
+ def across(threshold: float, count: int) -> np.ndarray:
122
+ """`count` consecutive results beyond threshold on one side, across levels
123
+ (the last count / levels runs together) or within one level over runs."""
124
+ span = count // levels
125
+ hit = np.zeros(runs, dtype=bool)
126
+ for i in range(runs):
127
+ if i + 1 >= span and _same_side(z[i + 1 - span : i + 1].ravel(), threshold):
128
+ hit[i] = True
129
+ elif i + 1 >= count and any(
130
+ _same_side(z[i + 1 - count : i + 1, j], threshold) for j in range(levels)
131
+ ):
132
+ hit[i] = True
133
+ return hit
134
+
135
+ rules: dict[str, np.ndarray] = {
136
+ "1_2s": (np.abs(z) > 2).any(axis=1),
137
+ "1_3s": (np.abs(z) > 3).any(axis=1),
138
+ }
139
+ if levels == 2:
140
+ rules["2_2s"] = across(2, 2)
141
+ else:
142
+ rules["2of3_2s"] = ((z > 2).sum(axis=1) >= 2) | ((z < -2).sum(axis=1) >= 2)
143
+ rules["R_4s"] = (z.max(axis=1) > 2) & (z.min(axis=1) < -2)
144
+ if levels == 2:
145
+ rules["4_1s"] = across(1, 4)
146
+ rules["10_x"] = across(0, 10)
147
+ else:
148
+ rules["3_1s"] = across(1, 3)
149
+ rules["12_x"] = across(0, 12)
150
+
151
+ out = pd.DataFrame({f"z_{n}": z[:, j].round(3) for j, n in enumerate(names)})
152
+ for rule, hit in rules.items():
153
+ out[rule] = hit
154
+ reject = out[[r for r in rules if r != "1_2s"]].any(axis=1)
155
+ out["status"] = np.where(reject, "reject", np.where(out["1_2s"], "warning", "accept"))
156
+ return out
157
+
158
+
159
+ def cusum(
160
+ values: Sequence[float], target: float, sd: float, k: float = 0.5, h: float = 5.0
161
+ ) -> pd.DataFrame:
162
+ """Tabular CUSUM in SD units (Montgomery, Introduction to Statistical Quality Control).
163
+
164
+ C+_i = max(0, z_i - k + C+_{i-1}) and C-_i = max(0, -z_i - k + C-_{i-1}),
165
+ with z = (x - target) / sd. A signal when either exceeds h. k = 0.5 and
166
+ h = 5 detect a 1 SD shift quickly; smaller shifts than Westgard catches.
167
+
168
+ Columns: value, z, c_plus, c_minus, signal_high, signal_low, signal.
169
+ """
170
+ x = np.asarray(values, dtype=float)
171
+ z = (x - target) / sd
172
+ c_plus = np.zeros(x.size)
173
+ c_minus = np.zeros(x.size)
174
+ up = down = 0.0
175
+ for i, zi in enumerate(z):
176
+ up = max(0.0, zi - k + up)
177
+ down = max(0.0, -zi - k + down)
178
+ c_plus[i], c_minus[i] = up, down
179
+ out = pd.DataFrame(
180
+ {
181
+ "value": x,
182
+ "z": z,
183
+ "c_plus": c_plus,
184
+ "c_minus": c_minus,
185
+ "signal_high": c_plus > h,
186
+ "signal_low": c_minus > h,
187
+ }
188
+ )
189
+ out["signal"] = out["signal_high"] | out["signal_low"]
190
+ return out
191
+
192
+
193
+ def ewma(
194
+ values: Sequence[float], target: float, sd: float, lam: float = 0.2, L: float = 3.0
195
+ ) -> pd.DataFrame:
196
+ """EWMA chart (Montgomery, Introduction to Statistical Quality Control).
197
+
198
+ ewma_i = lam * x_i + (1 - lam) * ewma_{i-1}, starting at the target, with
199
+ exact limits target +/- L * sd * sqrt(lam / (2 - lam) * (1 - (1 - lam)^(2i))).
200
+
201
+ Columns: value, ewma, lcl, ucl, signal.
202
+ """
203
+ if not 0 < lam <= 1:
204
+ raise ValueError("lam must be in (0, 1]")
205
+ x = np.asarray(values, dtype=float)
206
+ smoothed = np.zeros(x.size)
207
+ prev = target
208
+ for i, xi in enumerate(x):
209
+ prev = lam * xi + (1 - lam) * prev
210
+ smoothed[i] = prev
211
+ i = np.arange(1, x.size + 1)
212
+ width = L * sd * np.sqrt(lam / (2 - lam) * (1 - (1 - lam) ** (2 * i)))
213
+ out = pd.DataFrame({"value": x, "ewma": smoothed, "lcl": target - width, "ucl": target + width})
214
+ out["signal"] = (out["ewma"] > out["ucl"]) | (out["ewma"] < out["lcl"])
215
+ return out
labqc/emissions.py ADDED
@@ -0,0 +1,99 @@
1
+ """Flue-gas emission conversions for combustion testing.
2
+
3
+ Concentrations from a gas analyser are usually in ppm (by volume) at the
4
+ measured oxygen level. Emission limits, for example in EN 303-5 for
5
+ solid-fuel boilers, are stated in mg/m3 of dry flue gas at standard
6
+ conditions (273.15 K, 101.325 kPa) and a reference oxygen level (10% O2 for
7
+ EN 303-5).
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from .uncertainty import Component, Result, propagate
13
+
14
+ O2_AIR = 20.9 # % O2 in dry air, as used in EN and ISO stack-emission standards
15
+ MOLAR_VOLUME_STP = 22.414 # L/mol at 273.15 K and 101.325 kPa
16
+
17
+ MOLAR_MASS = { # g/mol
18
+ "CO": 28.010,
19
+ "NO": 30.006,
20
+ "NO2": 46.006, # NOx is conventionally reported as NO2
21
+ "SO2": 64.066,
22
+ "CO2": 44.009,
23
+ "CH4": 16.043,
24
+ "C3H8": 44.097, # OGC is often reported as propane equivalent
25
+ }
26
+
27
+
28
+ def ppm_to_mg_m3(ppm: float, gas: str) -> float:
29
+ """ppm by volume to mg/m3 at 273.15 K and 101.325 kPa."""
30
+ return ppm * MOLAR_MASS[gas] / MOLAR_VOLUME_STP
31
+
32
+
33
+ def mg_m3_to_ppm(mg_m3: float, gas: str) -> float:
34
+ return mg_m3 * MOLAR_VOLUME_STP / MOLAR_MASS[gas]
35
+
36
+
37
+ def to_reference_o2(concentration: float, o2_measured: float, o2_ref: float = 10.0) -> float:
38
+ """Correct a dry concentration to a reference oxygen level.
39
+
40
+ C_ref = C_meas * (20.9 - O2_ref) / (20.9 - O2_meas)
41
+ """
42
+ if not 0 <= o2_measured < O2_AIR:
43
+ raise ValueError("measured O2 must be between 0 and 20.9 %")
44
+ return concentration * (O2_AIR - o2_ref) / (O2_AIR - o2_measured)
45
+
46
+
47
+ def wet_to_dry(concentration_wet: float, water_vol_fraction: float) -> float:
48
+ """Convert a wet-basis concentration to dry basis."""
49
+ if not 0 <= water_vol_fraction < 1:
50
+ raise ValueError("water fraction must be in [0, 1)")
51
+ return concentration_wet / (1 - water_vol_fraction)
52
+
53
+
54
+ def to_temperature_pressure(concentration: float, t_c: float, p_kpa: float) -> float:
55
+ """Convert mg/m3 measured at t_c (degC) and p_kpa to standard conditions."""
56
+ return concentration * (273.15 + t_c) / 273.15 * 101.325 / p_kpa
57
+
58
+
59
+ def register_gas(name: str, molar_mass: float, overwrite: bool = False) -> None:
60
+ """Add a gas to MOLAR_MASS (g/mol) so the ppm <-> mg/m3 conversions accept it.
61
+
62
+ Refuses to change a gas already in the table unless overwrite=True.
63
+ """
64
+ if not name:
65
+ raise ValueError("gas name must not be empty")
66
+ if not molar_mass > 0:
67
+ raise ValueError("molar mass must be positive")
68
+ if name in MOLAR_MASS and not overwrite and MOLAR_MASS[name] != molar_mass:
69
+ raise ValueError(f"{name} is already registered ({MOLAR_MASS[name]} g/mol)")
70
+ MOLAR_MASS[name] = float(molar_mass)
71
+
72
+
73
+ def corrected_uncertainty(
74
+ concentration: float,
75
+ u_concentration: float,
76
+ o2_measured: float,
77
+ u_o2: float,
78
+ o2_ref: float = 10.0,
79
+ coverage: float = 0.95,
80
+ k: float | None = None,
81
+ ) -> tuple[float, Result]:
82
+ """Uncertainty of a concentration corrected to reference O2 (GUM first order).
83
+
84
+ Propagates the standard uncertainties of the measured concentration and
85
+ of the measured O2 through to_reference_o2 with
86
+ labqc.uncertainty.propagate. Returns (C_ref, Result); the Result table
87
+ shows which of the two dominates. The O2 term grows quickly as O2_meas
88
+ approaches 20.9 %, because the correction factor's denominator shrinks.
89
+ """
90
+ return propagate(
91
+ lambda c, o2: to_reference_o2(c, o2, o2_ref),
92
+ {"c": concentration, "o2": o2_measured},
93
+ {
94
+ "c": Component("Concentration", u_concentration),
95
+ "o2": Component("Measured O2", u_o2),
96
+ },
97
+ coverage=coverage,
98
+ k=k,
99
+ )
labqc/proficiency.py ADDED
@@ -0,0 +1,94 @@
1
+ """Proficiency-testing performance statistics (ISO 13528:2022, ISO/IEC 17043).
2
+
3
+ z = (x - x_pt) / sigma_pt
4
+ zeta = (x - x_pt) / sqrt(u_x^2 + u_pt^2)
5
+ E_n = (x - x_pt) / sqrt(U_x^2 + U_pt^2) (expanded uncertainties)
6
+
7
+ z and zeta: |score| <= 2 satisfactory, 2 < |score| < 3 questionable,
8
+ |score| >= 3 unsatisfactory. E_n: |E_n| <= 1 satisfactory, otherwise not.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import math
14
+
15
+ import numpy as np
16
+ import pandas as pd
17
+
18
+
19
+ def z_score(x: float, assigned: float, sigma_pt: float) -> float:
20
+ return (x - assigned) / sigma_pt
21
+
22
+
23
+ def zeta_score(x: float, assigned: float, u_x: float, u_assigned: float) -> float:
24
+ return (x - assigned) / math.sqrt(u_x**2 + u_assigned**2)
25
+
26
+
27
+ def en_number(x: float, assigned: float, U_x: float, U_assigned: float) -> float:
28
+ return (x - assigned) / math.sqrt(U_x**2 + U_assigned**2)
29
+
30
+
31
+ def classify(score: float, kind: str = "z") -> str:
32
+ """Interpret a score. kind is "z" (also for zeta) or "en"."""
33
+ s = round(abs(score), 9) # avoid floating-point noise at the 2 and 3 boundaries
34
+ if kind == "en":
35
+ return "satisfactory" if s <= 1 else "unsatisfactory"
36
+ if s <= 2:
37
+ return "satisfactory"
38
+ return "questionable" if s < 3 else "unsatisfactory"
39
+
40
+
41
+ def robust_mean_sd(values, tol: float = 1e-6, max_iter: int = 100) -> tuple[float, float]:
42
+ """Algorithm A from ISO 13528 Annex C: robust mean and standard deviation.
43
+
44
+ Useful when the assigned value is the consensus of participants.
45
+ """
46
+ x = np.asarray(values, dtype=float)
47
+ mean = float(np.median(x))
48
+ sd = 1.483 * float(np.median(np.abs(x - mean)))
49
+ for _ in range(max_iter):
50
+ delta = 1.5 * sd
51
+ clipped = np.clip(x, mean - delta, mean + delta)
52
+ new_mean = float(clipped.mean())
53
+ new_sd = 1.134 * float(clipped.std(ddof=1))
54
+ if abs(new_mean - mean) < tol and abs(new_sd - sd) < tol:
55
+ return new_mean, new_sd
56
+ mean, sd = new_mean, new_sd
57
+ return mean, sd
58
+
59
+
60
+ def pt_history(df: pd.DataFrame, date_col: str = "date", z_col: str = "z") -> pd.DataFrame:
61
+ """Review z-scores across PT rounds, one row per round, oldest first.
62
+
63
+ Control-chart rules applied to a laboratory's z-scores over time:
64
+
65
+ two_beyond_2 |z| > 2 in this round and the one before (any side): a
66
+ repeated questionable result needs action even though each
67
+ round alone is only questionable.
68
+ trend_9 nine rounds in a row on the same side of zero (Nelson's
69
+ rule 2): a persistent bias, even when every score is small.
70
+
71
+ Columns: date, z, classification (as `classify`), the two flags, and
72
+ action (True if either flag or the round itself is unsatisfactory).
73
+ """
74
+ data = df[[date_col, z_col]].dropna().sort_values(date_col).reset_index(drop=True)
75
+ z = data[z_col].to_numpy(dtype=float)
76
+ beyond = np.abs(z) > 2
77
+ two = beyond & np.concatenate([[False], beyond[:-1]])
78
+ trend = np.zeros(z.size, dtype=bool)
79
+ for i in range(8, z.size):
80
+ window = z[i - 8 : i + 1]
81
+ trend[i] = bool((window > 0).all() or (window < 0).all())
82
+ out = pd.DataFrame(
83
+ {
84
+ "date": data[date_col],
85
+ "z": z,
86
+ "classification": [classify(v) for v in z],
87
+ "two_beyond_2": two,
88
+ "trend_9": trend,
89
+ }
90
+ )
91
+ out["action"] = (
92
+ out["two_beyond_2"] | out["trend_9"] | (out["classification"] == "unsatisfactory")
93
+ )
94
+ return out
labqc/py.typed ADDED
File without changes