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.
- consilience-0.1.0/LICENSE +21 -0
- consilience-0.1.0/LICENSE-DATA +17 -0
- consilience-0.1.0/PKG-INFO +470 -0
- consilience-0.1.0/README.md +428 -0
- consilience-0.1.0/pyproject.toml +62 -0
- consilience-0.1.0/setup.cfg +4 -0
- consilience-0.1.0/src/consilience/__init__.py +29 -0
- consilience-0.1.0/src/consilience/__main__.py +5 -0
- consilience-0.1.0/src/consilience/agent.py +140 -0
- consilience-0.1.0/src/consilience/api.py +32 -0
- consilience-0.1.0/src/consilience/check.py +400 -0
- consilience-0.1.0/src/consilience/cli.py +360 -0
- consilience-0.1.0/src/consilience/compare.py +595 -0
- consilience-0.1.0/src/consilience/data/examples/measurement_a.json +13 -0
- consilience-0.1.0/src/consilience/data/examples/measurement_b.json +13 -0
- consilience-0.1.0/src/consilience/data/examples/measurement_c.json +12 -0
- consilience-0.1.0/src/consilience/data/examples/measurement_d.json +11 -0
- consilience-0.1.0/src/consilience/data/examples/measurement_e.json +12 -0
- consilience-0.1.0/src/consilience/data/examples/readings.csv +23 -0
- consilience-0.1.0/src/consilience/data/examples/readings_rules.yaml +45 -0
- consilience-0.1.0/src/consilience/data/packs/electrochemistry.yaml +86 -0
- consilience-0.1.0/src/consilience/export/__init__.py +1 -0
- consilience-0.1.0/src/consilience/export/nanopub.py +589 -0
- consilience-0.1.0/src/consilience/export/spec.py +527 -0
- consilience-0.1.0/src/consilience/export/vocab.py +126 -0
- consilience-0.1.0/src/consilience/hashing.py +20 -0
- consilience-0.1.0/src/consilience/nanopub_cli.py +162 -0
- consilience-0.1.0/src/consilience/receipts.py +226 -0
- consilience-0.1.0/src/consilience/rules.py +408 -0
- consilience-0.1.0/src/consilience/units.py +262 -0
- consilience-0.1.0/src/consilience/verify.py +186 -0
- consilience-0.1.0/src/consilience.egg-info/PKG-INFO +470 -0
- consilience-0.1.0/src/consilience.egg-info/SOURCES.txt +44 -0
- consilience-0.1.0/src/consilience.egg-info/dependency_links.txt +1 -0
- consilience-0.1.0/src/consilience.egg-info/entry_points.txt +2 -0
- consilience-0.1.0/src/consilience.egg-info/requires.txt +24 -0
- consilience-0.1.0/src/consilience.egg-info/top_level.txt +1 -0
- consilience-0.1.0/tests/test_check.py +275 -0
- consilience-0.1.0/tests/test_compare.py +311 -0
- consilience-0.1.0/tests/test_mapping.py +179 -0
- consilience-0.1.0/tests/test_no_keys.py +101 -0
- consilience-0.1.0/tests/test_receipts.py +113 -0
- consilience-0.1.0/tests/test_theories.py +184 -0
- consilience-0.1.0/tests/test_trig.py +138 -0
- consilience-0.1.0/tests/test_units.py +188 -0
- 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).
|