consilience 0.1.0__tar.gz

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.
Files changed (46) hide show
  1. consilience-0.1.0/LICENSE +21 -0
  2. consilience-0.1.0/LICENSE-DATA +17 -0
  3. consilience-0.1.0/PKG-INFO +470 -0
  4. consilience-0.1.0/README.md +428 -0
  5. consilience-0.1.0/pyproject.toml +62 -0
  6. consilience-0.1.0/setup.cfg +4 -0
  7. consilience-0.1.0/src/consilience/__init__.py +29 -0
  8. consilience-0.1.0/src/consilience/__main__.py +5 -0
  9. consilience-0.1.0/src/consilience/agent.py +140 -0
  10. consilience-0.1.0/src/consilience/api.py +32 -0
  11. consilience-0.1.0/src/consilience/check.py +400 -0
  12. consilience-0.1.0/src/consilience/cli.py +360 -0
  13. consilience-0.1.0/src/consilience/compare.py +595 -0
  14. consilience-0.1.0/src/consilience/data/examples/measurement_a.json +13 -0
  15. consilience-0.1.0/src/consilience/data/examples/measurement_b.json +13 -0
  16. consilience-0.1.0/src/consilience/data/examples/measurement_c.json +12 -0
  17. consilience-0.1.0/src/consilience/data/examples/measurement_d.json +11 -0
  18. consilience-0.1.0/src/consilience/data/examples/measurement_e.json +12 -0
  19. consilience-0.1.0/src/consilience/data/examples/readings.csv +23 -0
  20. consilience-0.1.0/src/consilience/data/examples/readings_rules.yaml +45 -0
  21. consilience-0.1.0/src/consilience/data/packs/electrochemistry.yaml +86 -0
  22. consilience-0.1.0/src/consilience/export/__init__.py +1 -0
  23. consilience-0.1.0/src/consilience/export/nanopub.py +589 -0
  24. consilience-0.1.0/src/consilience/export/spec.py +527 -0
  25. consilience-0.1.0/src/consilience/export/vocab.py +126 -0
  26. consilience-0.1.0/src/consilience/hashing.py +20 -0
  27. consilience-0.1.0/src/consilience/nanopub_cli.py +162 -0
  28. consilience-0.1.0/src/consilience/receipts.py +226 -0
  29. consilience-0.1.0/src/consilience/rules.py +408 -0
  30. consilience-0.1.0/src/consilience/units.py +262 -0
  31. consilience-0.1.0/src/consilience/verify.py +186 -0
  32. consilience-0.1.0/src/consilience.egg-info/PKG-INFO +470 -0
  33. consilience-0.1.0/src/consilience.egg-info/SOURCES.txt +44 -0
  34. consilience-0.1.0/src/consilience.egg-info/dependency_links.txt +1 -0
  35. consilience-0.1.0/src/consilience.egg-info/entry_points.txt +2 -0
  36. consilience-0.1.0/src/consilience.egg-info/requires.txt +24 -0
  37. consilience-0.1.0/src/consilience.egg-info/top_level.txt +1 -0
  38. consilience-0.1.0/tests/test_check.py +275 -0
  39. consilience-0.1.0/tests/test_compare.py +311 -0
  40. consilience-0.1.0/tests/test_mapping.py +179 -0
  41. consilience-0.1.0/tests/test_no_keys.py +101 -0
  42. consilience-0.1.0/tests/test_receipts.py +113 -0
  43. consilience-0.1.0/tests/test_theories.py +184 -0
  44. consilience-0.1.0/tests/test_trig.py +138 -0
  45. consilience-0.1.0/tests/test_units.py +188 -0
  46. consilience-0.1.0/tests/test_verify_cli.py +163 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Anuja Khatri
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,17 @@
1
+ Creative Commons Attribution 4.0 International (CC BY 4.0)
2
+
3
+ Copyright (c) 2026 Anuja Khatri
4
+
5
+ Data, records, rule packs, vocabularies and other non-code material in this
6
+ repository are licensed under the Creative Commons Attribution 4.0
7
+ International License.
8
+
9
+ You are free to share and adapt this material for any purpose, including
10
+ commercially, provided you give appropriate credit, provide a link to the
11
+ license, and indicate if changes were made.
12
+
13
+ License deed: https://creativecommons.org/licenses/by/4.0/
14
+ Legal code: https://creativecommons.org/licenses/by/4.0/legalcode
15
+
16
+ The code in this repository is licensed separately under the MIT License;
17
+ see LICENSE.
@@ -0,0 +1,470 @@
1
+ Metadata-Version: 2.4
2
+ Name: consilience
3
+ Version: 0.1.0
4
+ Summary: Compare two measurements with units and conditions, and check a table against written limits. Refuses what it cannot read; every result has a receipt you can re-run.
5
+ Author: Anuja Khatri
6
+ License-Expression: MIT AND CC-BY-4.0
7
+ Project-URL: Homepage, https://github.com/Anuja-Khatri/consilience-core
8
+ Project-URL: Source, https://github.com/Anuja-Khatri/consilience-core
9
+ Project-URL: Issues, https://github.com/Anuja-Khatri/consilience-core/issues
10
+ Project-URL: Changelog, https://github.com/Anuja-Khatri/consilience-core/blob/v0.1.0/CHANGELOG.md
11
+ Keywords: measurement,units,comparison,data quality,validation,reproducibility,electrochemistry,receipts
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Topic :: Scientific/Engineering
22
+ Requires-Python: >=3.10
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ License-File: LICENSE-DATA
26
+ Requires-Dist: pint>=0.23
27
+ Requires-Dist: pyyaml>=6
28
+ Provides-Extra: nanopub
29
+ Requires-Dist: nanopub<3,>=2.2.2; python_version >= "3.12" and extra == "nanopub"
30
+ Requires-Dist: rdflib>=7.0; python_version >= "3.12" and extra == "nanopub"
31
+ Provides-Extra: test
32
+ Requires-Dist: pytest>=8; extra == "test"
33
+ Requires-Dist: nanopub<3,>=2.2.2; python_version >= "3.12" and extra == "test"
34
+ Requires-Dist: rdflib>=7.0; python_version >= "3.12" and extra == "test"
35
+ Provides-Extra: dev
36
+ Requires-Dist: pytest>=8; extra == "dev"
37
+ Requires-Dist: nanopub<3,>=2.2.2; python_version >= "3.12" and extra == "dev"
38
+ Requires-Dist: rdflib>=7.0; python_version >= "3.12" and extra == "dev"
39
+ Requires-Dist: build; extra == "dev"
40
+ Requires-Dist: twine; extra == "dev"
41
+ Dynamic: license-file
42
+
43
+ # consilience
44
+
45
+ Compare two measurements with their units and conditions, and check a table of data
46
+ against written limits. When something cannot be read exactly, `consilience` says so and
47
+ names the reason instead of guessing. Every result comes with a receipt that anyone can
48
+ re-run to confirm it.
49
+
50
+ - `consilience compare a.json b.json` answers: do these two measurements agree, and are
51
+ they even comparable? It converts units, applies your tolerances, and checks that the
52
+ measurement conditions match.
53
+ - `consilience check data.csv --rules rules.yaml` lists every row that breaks a rule (a
54
+ value above its own recorded limit, a value outside physical bounds), and every cell it
55
+ could not read.
56
+ - `consilience verify receipt.json` re-runs either result and confirms its hash.
57
+
58
+ Verdicts come from plain, deterministic code. No AI model is called anywhere in this
59
+ package.
60
+
61
+ **Who it is for:** anyone who compares numbers from different labs, papers or runs, or
62
+ who receives tables of measurements and wants to know which rows to distrust before
63
+ using them: researchers, data stewards, people building automated or AI-assisted analysis
64
+ who want a check that refuses rather than guesses.
65
+
66
+ ## Install
67
+
68
+ Needs Python 3.10 or newer.
69
+
70
+ ```
71
+ pip install consilience
72
+ ```
73
+
74
+ This installs the command `consilience` and two dependencies (pint for units, PyYAML for
75
+ rule files).
76
+
77
+ ## Five-minute quickstart: compare
78
+
79
+ Write the made-up example files into a new folder and go there:
80
+
81
+ ```console
82
+ $ consilience examples try
83
+ wrote try/measurement_a.json
84
+ wrote try/measurement_b.json
85
+ wrote try/measurement_c.json
86
+ wrote try/measurement_d.json
87
+ wrote try/measurement_e.json
88
+ wrote try/readings.csv
89
+ wrote try/readings_rules.yaml
90
+ wrote try/electrochemistry.yaml
91
+ These examples are MADE UP for trying the tool; they are not real data.
92
+ $ cd try
93
+ ```
94
+
95
+ A measurement file holds a value, a unit, an optional uncertainty and the conditions it
96
+ was measured under. `measurement_a.json`:
97
+
98
+ ```json
99
+ {
100
+ "note": "MADE-UP EXAMPLE for the consilience quickstart. Not a real measurement.",
101
+ "label": "Example lab A, overpotential at 10 mA/cm^2",
102
+ "value": 0.320,
103
+ "unit": "V",
104
+ "uncertainty": "4 mV",
105
+ "conditions": {
106
+ "electrolyte": {"identity": "H2SO4", "concentration": "0.5 mol/L"},
107
+ "current_density": {"value": 10, "unit": "mA/cm^2", "normalization": "geometric"},
108
+ "temperature": "25 degC",
109
+ "ir_correction": true
110
+ }
111
+ }
112
+ ```
113
+
114
+ `measurement_b.json` reports 331 mV ± 3 mV under the same conditions, written
115
+ differently ("sulfuric acid", "500 mmol/L", "0.01 A/cm^2", "298.15 K"). Compare them with
116
+ the bundled electrochemistry pack, which knows which conditions matter:
117
+
118
+ ```console
119
+ $ consilience compare measurement_a.json measurement_b.json --pack electrochemistry
120
+ verdict: disagree
121
+ a: 0.32 V ± 0.004 V (as given: 0.32 V ± 4 mV) [Example lab A, overpotential at 10 mA/cm^2]
122
+ b: 0.331 V ± 0.003 V (as given: 331 mV ± 3 mV) [Example lab B, overpotential at 10 mA/cm^2]
123
+ difference: 0.011 V
124
+ tolerance: 0 V (larger of --abs-tol and --rel-tol x the larger value)
125
+ floor: 0.004 V (largest of --floor and the two uncertainties)
126
+ conditions: checked with pack electrochemistry (electrochemistry-v1): electrolyte, current_density, temperature, ir_correction
127
+ pack hash: cbf7aea81b7f7eb070538e6049b2b2bd4ebcb00ae409c9ecfde9737d3ef1f97c
128
+ receipt: sha256 ...
129
+ $ echo $?
130
+ 1
131
+ ```
132
+
133
+ The units were converted and the conditions matched, so the two values could be
134
+ compared; they differ by 11 mV, more than either stated uncertainty. If you know that
135
+ labs typically spread by 13 mV on this measurement, say so with `--floor`:
136
+
137
+ ```console
138
+ $ consilience compare measurement_a.json measurement_b.json --pack electrochemistry --floor "13 mV"
139
+ verdict: within_floor
140
+ a: 0.32 V ± 0.004 V (as given: 0.32 V ± 4 mV) [Example lab A, overpotential at 10 mA/cm^2]
141
+ b: 0.331 V ± 0.003 V (as given: 331 mV ± 3 mV) [Example lab B, overpotential at 10 mA/cm^2]
142
+ difference: 0.011 V
143
+ tolerance: 0 V (larger of --abs-tol and --rel-tol x the larger value)
144
+ floor: 0.013 V (largest of --floor and the two uncertainties)
145
+ conditions: checked with pack electrochemistry (electrochemistry-v1): electrolyte, current_density, temperature, ir_correction
146
+ pack hash: cbf7aea81b7f7eb070538e6049b2b2bd4ebcb00ae409c9ecfde9737d3ef1f97c
147
+ receipt: sha256 ...
148
+ $ echo $?
149
+ 0
150
+ ```
151
+
152
+ (The 13 mV here is an example number, not a measured spread.)
153
+
154
+ Measurement C was taken at 100 mA/cm^2 instead of 10, so it is refused, and the rule that
155
+ refused it is named:
156
+
157
+ ```console
158
+ $ consilience compare measurement_a.json measurement_c.json --pack electrochemistry
159
+ verdict: not_comparable(current_density)
160
+ a: 0.32 V ± 0.004 V (as given: 0.32 V ± 4 mV) [Example lab A, overpotential at 10 mA/cm^2]
161
+ b: 0.41 V [Example lab C, overpotential at 100 mA/cm^2]
162
+ not_comparable current_density ({"normalization": "geometric", "unit": "mA/cm^2", "value": 10} vs {"normalization": "geometric", "unit": "mA/cm^2", "value": 100})
163
+ rule EC2: Overpotentials are comparable only at the same current density and the same normalisation (geometric or ECSA).
164
+ conditions: checked with pack electrochemistry (electrochemistry-v1): electrolyte, current_density, temperature, ir_correction
165
+ pack hash: cbf7aea81b7f7eb070538e6049b2b2bd4ebcb00ae409c9ecfde9737d3ef1f97c
166
+ receipt: sha256 ...
167
+ $ echo $?
168
+ 2
169
+ ```
170
+
171
+ Measurement D does not say its temperature, so the comparison is refused rather than
172
+ assumed:
173
+
174
+ ```console
175
+ $ consilience compare measurement_a.json measurement_d.json --pack electrochemistry
176
+ verdict: not_stated(temperature)
177
+ a: 0.32 V ± 0.004 V (as given: 0.32 V ± 4 mV) [Example lab A, overpotential at 10 mA/cm^2]
178
+ b: 0.318 V [Example lab D, temperature not reported]
179
+ not_stated temperature (not stated on b)
180
+ rule EC3: Measurements are comparable only at the same temperature; room_temperature matches room_temperature only, never a number.
181
+ conditions: checked with pack electrochemistry (electrochemistry-v1): electrolyte, current_density, temperature, ir_correction
182
+ pack hash: cbf7aea81b7f7eb070538e6049b2b2bd4ebcb00ae409c9ecfde9737d3ef1f97c
183
+ receipt: sha256 ...
184
+ $ echo $?
185
+ 2
186
+ ```
187
+
188
+ Measurement E writes its value as `"0,32"`. A comma can be a decimal point or a
189
+ thousands separator, so it is refused:
190
+
191
+ ```console
192
+ $ consilience compare measurement_a.json measurement_e.json --pack electrochemistry
193
+ verdict: unparseable(b.value: ambiguous_separator)
194
+ a: 0.32 V ± 0.004 V (as given: 0.32 V ± 4 mV) [Example lab A, overpotential at 10 mA/cm^2]
195
+ b: 0,32 V [Example lab E, value written as 0,32]
196
+ unparseable b.value: ambiguous_separator (a comma may be a decimal or a thousands separator)
197
+ conditions: checked with pack electrochemistry (electrochemistry-v1): electrolyte, current_density, temperature, ir_correction
198
+ pack hash: cbf7aea81b7f7eb070538e6049b2b2bd4ebcb00ae409c9ecfde9737d3ef1f97c
199
+ receipt: sha256 ...
200
+ $ echo $?
201
+ 3
202
+ ```
203
+
204
+ Without a pack, every condition on either side must match exactly, so the different
205
+ spelling of the electrolyte is enough to refuse. That is what a pack is for:
206
+
207
+ ```console
208
+ $ consilience compare measurement_a.json measurement_b.json
209
+ verdict: not_comparable(electrolyte.identity)
210
+ a: 0.32 V ± 0.004 V (as given: 0.32 V ± 4 mV) [Example lab A, overpotential at 10 mA/cm^2]
211
+ b: 0.331 V ± 0.003 V (as given: 331 mV ± 3 mV) [Example lab B, overpotential at 10 mA/cm^2]
212
+ not_comparable electrolyte.identity ("H2SO4" vs "sulfuric acid")
213
+ conditions: no pack: every condition on either side must match (current_density, electrolyte, ir_correction, temperature)
214
+ receipt: sha256 ...
215
+ $ echo $?
216
+ 2
217
+ ```
218
+
219
+ Save a receipt and re-run it:
220
+
221
+ ```console
222
+ $ consilience compare measurement_a.json measurement_b.json --pack electrochemistry --abs-tol "15 mV" --receipt compare-receipt.json
223
+ verdict: agree
224
+ a: 0.32 V ± 0.004 V (as given: 0.32 V ± 4 mV) [Example lab A, overpotential at 10 mA/cm^2]
225
+ b: 0.331 V ± 0.003 V (as given: 331 mV ± 3 mV) [Example lab B, overpotential at 10 mA/cm^2]
226
+ difference: 0.011 V
227
+ tolerance: 0.015 V (larger of --abs-tol and --rel-tol x the larger value)
228
+ floor: 0.004 V (largest of --floor and the two uncertainties)
229
+ conditions: checked with pack electrochemistry (electrochemistry-v1): electrolyte, current_density, temperature, ir_correction
230
+ pack hash: cbf7aea81b7f7eb070538e6049b2b2bd4ebcb00ae409c9ecfde9737d3ef1f97c
231
+ receipt: sha256 ...
232
+ wrote: compare-receipt.json
233
+ $ consilience verify compare-receipt.json
234
+ ok: compare-receipt.json (compare)
235
+ ok receipt hash: matches its contents
236
+ ok rule hash: electrochemistry (electrochemistry-v1) matches
237
+ ok re-run: same result
238
+ recorded sha256 ...
239
+ $ echo $?
240
+ 0
241
+ ```
242
+
243
+ Add `--json` to any `compare` or `check` to get the full result as JSON (the same content
244
+ as the receipt).
245
+
246
+ ## Five-minute quickstart: check a table
247
+
248
+ `readings.csv` is a small made-up table of bench readings. Each row has a reading, the
249
+ unit of that reading, the limit recorded for it, a temperature and a humidity. Some rows
250
+ are wrong on purpose. `readings_rules.yaml` holds three rules:
251
+
252
+ - **R1** (limit): a reading must not exceed its own recorded limit by more than 0.02 V;
253
+ - **R2** (bound): no temperature below absolute zero (`min: 0 K`);
254
+ - **R3** (bound): relative humidity between 0 and 100 percent.
255
+
256
+ ```console
257
+ $ consilience check readings.csv --rules readings_rules.yaml --html report.html --receipt check-receipt.json
258
+ data: readings.csv (20 rows; sha256 ce1f95d5ff15ebab30b57e7d37d1e3793d88c2bbedc0e8f42f59d3a6f1d2e84f)
259
+ rules: example-bench-readings-v1 (readings_rules.yaml)
260
+ rule hash: b6a64e8fab26a07da5ca9fbcc0c50a3460781ba722f224bd0a27221fb80bbcff
261
+ violations: 5
262
+ line 7 S-004 R1 reading 2.71 V > limit_v 2.5 V + margin 0.02 V row receipt f6ebb38ff21a
263
+ line 10 S-007 R2 temperature_c -280 degC < min -273.15 degC row receipt bda89ad69f3a
264
+ line 14 S-011 R1 reading 850 mV > limit_v 800 mV + margin 20 mV row receipt 511d51f9d275
265
+ line 18 S-015 R3 humidity_pct 104 percent > max 100 percent row receipt be633f7a4560
266
+ line 21 S-018 R3 humidity_pct -3 percent < min 0 percent row receipt 3a7f9477333a
267
+ could not read: 2 cells (not checked; nothing was guessed)
268
+ line 12 S-009 limit_v "n/a": not_a_number (needed by R1)
269
+ line 16 S-013 temperature_c "21,5": ambiguous_separator (needed by R2)
270
+ skipped empty: 0
271
+ result: exit 3: some cells could not be read, so the check is incomplete
272
+ receipt: sha256 ...
273
+ wrote: report.html
274
+ wrote: check-receipt.json
275
+ $ echo $?
276
+ 3
277
+ $ consilience verify check-receipt.json
278
+ ok: check-receipt.json (check)
279
+ ok receipt hash: matches its contents
280
+ ok rule hash: example-bench-readings (example-bench-readings-v1) matches
281
+ ok data hash: readings.csv matches
282
+ ok re-run: same result
283
+ recorded sha256 ...
284
+ $ echo $?
285
+ 0
286
+ ```
287
+
288
+ Row S-011 was recorded in mV; it was converted before comparing with its limit in V. The
289
+ two cells that could not be read are listed and counted, not skipped: fix them and run
290
+ the check again. Open `report.html` in a browser for the same report as a page. The
291
+ full report, including every violating row's receipt, is in `check-receipt.json`.
292
+
293
+ ## Python
294
+
295
+ The same four functions, from Python:
296
+
297
+ ```python
298
+ from consilience import check, compare, load_rules, verify
299
+
300
+ r = compare("measurement_a.json", "measurement_b.json", pack="electrochemistry")
301
+ print(r.verdict, r.exit_code) # disagree 1
302
+ print(round(r.difference, 6), r.unit) # 0.011 V
303
+
304
+ c = check("readings.csv", "readings_rules.yaml")
305
+ print(c.summary["violations"], c.summary["unparseable_cells"]) # 5 2
306
+ print([v["id"] for v in c.violations]) # ['S-004', 'S-007', 'S-011', 'S-015', 'S-018']
307
+
308
+ print(verify(r.receipt).ok) # True
309
+ print(load_rules("electrochemistry").version) # electrochemistry-v1
310
+ ```
311
+
312
+ Run it from the `try` folder. Inputs can be file paths or dicts. Problems with the inputs
313
+ themselves (a missing file, an unknown field, a bad option) raise `InputError`; a bad rule
314
+ file raises `RuleFileError`. Anything that can be read but not compared is a verdict, not
315
+ an exception. `c.to_html()` gives the HTML report.
316
+
317
+ ## What the verdicts mean
318
+
319
+ | Verdict | Meaning | Exit code |
320
+ |---|---|---|
321
+ | `agree` | The difference is within the tolerance: the larger of `--abs-tol` and `--rel-tol` times the larger value (both 0 by default, so equal after unit conversion). | 0 |
322
+ | `within_floor` | Not within the tolerance, but within the floor: the largest of `--floor` and the two stated uncertainties. A difference this small is not evidence of disagreement. | 0 |
323
+ | `disagree` | The difference is larger than both. | 1 |
324
+ | `not_comparable(<what>)` | A condition differs (`not_comparable(temperature)`), or the two values measure different things (`not_comparable(unit)`: millivolts against milliamps). | 2 |
325
+ | `not_stated(<what>)` | A value, unit or condition is missing on one or both sides, so the comparison cannot be made. | 2 |
326
+ | `unparseable(<what>: <why>)` | Something could not be read exactly. The reason is named, e.g. `ambiguous_separator`, `non_finite`, `unknown_unit`. | 3 |
327
+
328
+ When there are several problems, all are listed and the verdict is the first by rank:
329
+ `unparseable`, then `not_comparable`, then `not_stated`. Differences smaller than one
330
+ part in 10^9 of the values are treated as rounding from unit conversion.
331
+
332
+ Exit codes of `check`: 0 no violations and every needed cell read; 1 violations; 3 some
333
+ cells could not be read (the check is incomplete; the violations it did find are still
334
+ listed). `verify`: 0 the re-run reproduces the receipt, 1 it does not. Every command: 64
335
+ for a usage or input error (missing file, unknown field, unreadable rule file).
336
+
337
+ ## What is refused, and why
338
+
339
+ Numbers are read by a fixed grammar (a sign, digits, one decimal point, an optional
340
+ exponent), never evaluated as arithmetic. These are refused with a named reason:
341
+
342
+ | Input | Reason | Why |
343
+ |---|---|---|
344
+ | `"1 200"` | `space_separated_digits` | one number or two? |
345
+ | `"3,14"`, `"1,200"` | `ambiguous_separator` | decimal comma or thousands separator? |
346
+ | `"1.2.3"` | `second_decimal_point` | not a number |
347
+ | `"nan"`, `"inf"`, `NaN`, `1e400` | `non_finite` | not a measurement |
348
+ | `"(1,234)"` | `parenthesised_number` | accounting negative? |
349
+ | `"5-10"`, `"1/2"` | `malformed_number` | a range or arithmetic, not a value |
350
+ | `"1 h 30 min"` | `compound_quantity` | more than one number |
351
+ | `"5M"`, `"5k"` | `ambiguous_scale_suffix` | molar or million? |
352
+ | `"25 C"` | `ambiguous_unit` | Celsius or coulomb? Write `degC`. |
353
+ | `"10 mA/cm2"` | `unit_contains_number` | write `cm^2` |
354
+ | `"5 banana"` | `unknown_unit` | |
355
+ | empty | `empty` / `missing_unit` | |
356
+
357
+ Units are [pint](https://pint.readthedocs.io/) unit names, and case matters (`m` is
358
+ metre, `M` is molar, `K` is kelvin). Write `degC` for Celsius and `dimensionless` for a
359
+ pure number. `%` and `percent` work, so `90 %` equals `0.9`.
360
+
361
+ ## Conditions and domain packs
362
+
363
+ **Without a pack**, every condition present on either side must be present on both and
364
+ equal: text exactly (case and spelling count, because `Co` is cobalt and `CO` is carbon
365
+ monoxide), numbers exactly, quantities after unit conversion, nested objects key by key.
366
+ A condition present on only one side gives `not_stated(<condition>)`. A value of `null`
367
+ or `"unstated"` is treated as not stated.
368
+
369
+ **With a pack** (`--pack electrochemistry` or `--pack my_pack.yaml`), only the conditions
370
+ the pack names are checked, by the pack's rules; other conditions are listed as "not
371
+ checked". A pack can say that some spellings mean the same thing, that a quantity must
372
+ match within a tolerance, that a word like `room_temperature` matches only itself, and
373
+ that a part such as `normalization` must also match.
374
+
375
+ The bundled **electrochemistry** pack (`electrochemistry-v1`) checks electrolyte identity
376
+ and concentration, current density and its normalisation, temperature, and iR correction.
377
+ Each rule has a plain-English line, a rationale and a source. List bundled packs with
378
+ `consilience packs`. `consilience examples` writes a copy, `electrochemistry.yaml`, that
379
+ you can edit.
380
+
381
+ ## Writing rules
382
+
383
+ Both kinds of rule file are YAML with a `kind`, a `name`, a `version`, and a
384
+ `plain_english` line for the file and for every rule. A check rule file:
385
+
386
+ ```yaml
387
+ kind: check-rules
388
+ name: my-rules
389
+ version: my-rules-v1
390
+ plain_english: What these rules are for.
391
+ id_column: sample_id # optional: labels rows in the report
392
+ columns: # every column a rule reads, with its unit
393
+ reading: {unit_column: reading_unit} # each row says its own unit
394
+ limit_v: {unit: V} # one unit for the whole column
395
+ temperature_c: {unit: degC}
396
+ rules:
397
+ - id: R1
398
+ kind: limit # value against another column of the same row
399
+ column: reading
400
+ limit_column: limit_v
401
+ must_be: at_most # or at_least
402
+ margin: 0.02 V
403
+ plain_english: A reading must not exceed its own recorded limit by more than 0.02 V.
404
+ - id: R2
405
+ kind: bound # value against fixed bounds
406
+ column: temperature_c
407
+ min: 0 K
408
+ plain_english: No temperature is below absolute zero.
409
+ ```
410
+
411
+ Unknown keys are refused, so a misspelt key is an error rather than silently ignored.
412
+ The full format for both kinds (and options such as `if_empty`, `if_limit_empty`,
413
+ `value_offset`, exclusive bounds, and every pack predicate) is in
414
+ [docs/RULES.md](https://github.com/Anuja-Khatri/consilience-core/blob/v0.1.0/docs/RULES.md).
415
+
416
+ ## Receipts
417
+
418
+ A receipt is a JSON file holding the inputs (for `check`, the data file's path and
419
+ SHA-256), the options, the complete rule file used, the consilience and pint versions,
420
+ and the result, plus a SHA-256 over all of that. `consilience verify` checks the hash,
421
+ checks the data file still has the same SHA-256, re-runs the comparison or check, and
422
+ confirms the fresh result hashes the same. For a check receipt it looks for the data file
423
+ where it was, then beside the receipt; `--data` tells it where the file is now. A
424
+ violation's row receipt is `sha256` over `{"rules_sha256", "rule", "line", "cells"}` in
425
+ canonical JSON (the rule file's hash, the rule id, the line number and the row as text).
426
+
427
+ ## What it does not do
428
+
429
+ - **It does not read prose.** It does not find numbers or conditions in papers, reports
430
+ or model output. You give it structured files.
431
+ - **It checks only the conditions you give it.** If a condition that matters is missing
432
+ from both files, and no pack names it, nothing will notice.
433
+ - **The electrochemistry pack covers one field**, and only the four conditions it names.
434
+ For other fields, write a pack; without one, every condition must match exactly.
435
+ - **The example data is made up.** It shows how the tool works; it describes no real
436
+ instrument, sample or experiment. The 13 mV floor in the quickstart is an example too.
437
+ - **It does not know whether your rules are right.** A check reports rows that break the
438
+ rules you wrote, nothing more.
439
+ - **There is no hosted service.** `compare`, `check` and `verify` run on your computer
440
+ and send nothing anywhere.
441
+ - It reads CSV only (UTF-8, comma-separated, a header row).
442
+
443
+ ## Also in this package: nanopublication export
444
+
445
+ From a source checkout, the package can also export Consilience records as
446
+ nanopublications (signed, citable RDF statements) to the Knowledge Pixels test registry.
447
+ This needs `pip install "consilience[nanopub]"` (Python 3.12 or newer, which the
448
+ nanopub library requires) and is described in
449
+ [docs/NANOPUB.md](https://github.com/Anuja-Khatri/consilience-core/blob/v0.1.0/docs/NANOPUB.md)
450
+ and [PILOT.md](https://github.com/Anuja-Khatri/consilience-core/blob/v0.1.0/PILOT.md).
451
+
452
+ ## Develop
453
+
454
+ ```
455
+ git clone -b v0.1.0 https://github.com/Anuja-Khatri/consilience-core.git
456
+ cd consilience-core
457
+ python -m venv .venv && . .venv/bin/activate
458
+ pip install -e ".[test]"
459
+ python -m pytest -q
460
+ bash scripts/check_release.sh # build, install the wheel in a clean venv, run this README
461
+ ```
462
+
463
+ ## Licence and provenance
464
+
465
+ Code: MIT ([LICENSE](https://github.com/Anuja-Khatri/consilience-core/blob/v0.1.0/LICENSE)).
466
+ Rule packs, examples, records and vocabulary: CC BY 4.0
467
+ ([LICENSE-DATA](https://github.com/Anuja-Khatri/consilience-core/blob/v0.1.0/LICENSE-DATA)).
468
+ What was adapted from other Consilience repositories, and from which commit, is in
469
+ [PROVENANCE.md](https://github.com/Anuja-Khatri/consilience-core/blob/v0.1.0/PROVENANCE.md).
470
+ Changes: [CHANGELOG.md](https://github.com/Anuja-Khatri/consilience-core/blob/v0.1.0/CHANGELOG.md).