Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
802388e
First version: format, counting rule, chain, page, SPEC and migration…
mklarmann Nov 16, 2026
31a4f83
Located factors as a fixture; identical builds said as such; second m…
mklarmann Nov 16, 2026
a05f66b
Compare the severity of a shared case to 1e-12, not exactly
mklarmann Nov 16, 2026
5c19866
Step 0's moves are the residual, not a regression; a model author in …
mklarmann Nov 16, 2026
d6a7e0e
Hold counts against the listed items; noise beyond the floor; `may` b…
mklarmann Nov 16, 2026
0e1f5be
Located factors: water use and land use may move
mklarmann Nov 16, 2026
4b7e1c9
Fix the 17 findings of the second review (#3 to #19)
mklarmann Nov 16, 2026
a7142db
A frameless page for a site's own page, and the matrix of every item
mklarmann Nov 16, 2026
b8e5a55
chain.state leaves out identity entries whose value is None
mklarmann Nov 16, 2026
3c0a953
A matrix from a tables description; the header follows the loaded matrix
mklarmann Nov 16, 2026
d90f76e
The page's own sentences say the file's word for an item
mklarmann Nov 16, 2026
163d6b1
A file's own word for an indicator; steps from 1 without published re…
mklarmann Nov 17, 2026
20e7d1e
The grid reads like the trial dashboard: a ratio in every cell, furth…
mklarmann Nov 17, 2026
7274efd
A matrix page: chips choose the comparison, the grid first, the rest …
mklarmann Nov 17, 2026
97045e8
Review a step where it is chosen: its claim beside its effect, what i…
mklarmann Nov 17, 2026
752043b
SPEC: the line of the chosen step, the columns by what moved, the add…
mklarmann Nov 17, 2026
b1cd355
Distributions per indicator: a card each, under the matrix, as the tr…
mklarmann Nov 17, 2026
38d6767
Distributions: bar heights per card, or one scale for every card (A21)
mklarmann Nov 17, 2026
52bb73c
The review of PR 21: every verdict, no colour, missing is not still, …
mklarmann Nov 17, 2026
4ed348a
Percentiles in one precision: the fewest digits that keep every diffe…
mklarmann Nov 17, 2026
a217b5a
Merge pull request #21 from sentier-dev/page-review
mklarmann Nov 17, 2026
1f3fb2f
The page refuses a matrix that says other numbers of a listed item th…
mklarmann Nov 17, 2026
b04137e
Merge pull request #20 from sentier-dev/dashboard-page
mklarmann Nov 17, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 59 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
name: tests

on:
pull_request:
push:
branches: [main]

permissions:
contents: read

jobs:
python:
name: Python ${{ matrix.python }}
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
python: ["3.10", "3.11", "3.12", "3.13", "3.14"]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python }}
- name: Tests and doctests, from the source
run: python -m unittest discover -s tests -t . -v
- name: The example builds, checks and has a page
run: |
PYTHONPATH=src python -m sentier_diagnostics example --out build/example
PYTHONPATH=src python -m sentier_diagnostics check build/example/diagnostics.json build/example/p01-fix-1.json
PYTHONPATH=src python -m sentier_diagnostics check examples/diagnostics.json examples/p01-fix-1.json
PYTHONPATH=src python -m sentier_diagnostics summary examples/diagnostics.json

package:
name: The package, installed
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v6
- name: Build, install into a fresh environment, run from it
run: |
uv build --out-dir dist
uv venv --python 3.12 /tmp/installed
uv pip install --python /tmp/installed/bin/python dist/*.whl
/tmp/installed/bin/sentier-diagnostics --version
/tmp/installed/bin/sentier-diagnostics example --out /tmp/example
/tmp/installed/bin/sentier-diagnostics check /tmp/example/diagnostics.json
test -f /tmp/example/page/index.html
/tmp/installed/bin/python -m unittest discover -s tests -t .

page:
name: The page script
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "22"
- name: Acceptance cases against the script
run: node --test tests/js/page.test.js
6 changes: 6 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
build/
dist/
__pycache__/
*.egg-info/
.venv/
.claude/launch.json
31 changes: 31 additions & 0 deletions GLOSSARY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# Glossary

The words this repository uses, each in one line. [SPEC.md](SPEC.md) says the rest.

- **Item**: one thing that has results, such as a product or a dataset. Its file calls it by its own word (`item.one`).
- **Indicator**: one impact category, named by an exact id.
- **Reference unit**: the unit an item's result is per (kg, MJ, machine hour). Floors are kept apart per unit.
- **State**: one set of results. The first may be the published results; the others are builds.
- **Step**: from one state to the next, with its kind, claim, tolerance and noise.
- **Step 0**: the reproduction of the published results. The start, never the target. A chain that does not start from the published results has no step 0: its steps are numbered from 1.
- **Chain**: the states in order and the steps between them.
- **Pair**: one item in one indicator, before and after a step.
- **Class**: what a pair is, by one rule: agrees, within noise, differs, beyond 10x, zero reference, zero result, sign change, near zero, missing.
- **Moved**: a pair of class differs, beyond 10x, zero reference, zero result or sign change. Only these have a direction.
- **Direction**: up where the result after is larger as a signed number, down otherwise.
- **Band**: the direction and the factor between the two sizes of a pair that differs.
- **Floor**: the size below which a result counts as near zero; one per indicator and reference unit.
- **Tolerance**: how far two results may differ, relative to the larger, and still agree.
- **Noise**: how far two builds of one state differ, measured.
- **Size filter**: a reader's choice on the page that hides small changes. It changes no count.
- **Claim**: what a step says it moves; its **scope entries** say which indicators and items, which way, how far, and whether they **must** or **may** move.
- **Verdict**: how a pair of a step holds against the step's claim.
- **Attribution**: the split of an item's whole difference into the steps' differences.
- **Explanation**: text about a step, an indicator or an item, with its **origin** (person, code or model) and its **finding** (a reason, or none found). It changes no count.
- **Breakdown**: what one item's result is made of, before and after one step.
- **Tier**: whether a file lists items (`items`) or holds counts only (`counts`).
- **Audience**: whether a file's writer says it may be published (`public`) or not (`local`).
- **Listed items**: the items a file holds, the worst first, up to `listed`.
- **Matrix**: every item of a local file, listed or not, in a second file the page loads after it has drawn.
- **Body**: the page as one element a site holds in its own page; its style stays inside it.
- **Drawer**: the panel of one item, at the right of the page, opened from a row.
10 changes: 10 additions & 0 deletions MAINTAINERS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# Maintainers

| Role | Who |
|---|---|
| Maintainer | Manuel Klarmann |
| Second maintainer | Laurenz Bougan (GitHub: lbougan), named by Manuel Klarmann on 16 November 2026 |

The tool must be possible to run, review and release without any one person
([docs/runbook.md](docs/runbook.md)). Changes go through a pull request that someone other
than its author reviews and merges.
34 changes: 34 additions & 0 deletions NOTICE
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
sentier-diagnostics
Copyright (c) 2026 Départ de Sentier. MIT licence: see LICENSE.

Parts of this package are adapted from sentier-bafu
(https://github.com/sentier-dev/sentier-bafu): the classes of a pair of results, the
claims and verdicts, the bands and the floor of `scripts/runrecord/before_after.py` and
`scripts/runrecord/review.py`, and the drawing of a value in `site/assets/before-after.js`,
as they stood at commit 9460128 (the same at a6a8df5). They were rewritten for the format sentier-diagnostics/1;
no file was copied whole. Their notice:

MIT License

Copyright (c) 2026 sentier.dev

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Nothing is taken from the private repositories of the backtest dashboards. Their
defects are described in SPEC.md, in words, as acceptance cases.
63 changes: 51 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,59 @@
What changed, before and after, in the impact assessment results of a life cycle
inventory database, and why.

This repository will hold one open tool for the Sentier projects (sentier-bafu,
sentier-bafu-agribalyse, sentier-agribalyse and others): a file format for results
compared before and after a change, one rule for counting what moved, the attribution
of a difference to the steps that made it, and a static page that shows it.
One open tool for the Sentier projects (sentier-bafu, sentier-bafu-agribalyse,
sentier-agribalyse and others):

The published results of a database are checked once, at the start: a faithful import
reproduces them. Every later step (a fix, a contribution, a changed mapping) is compared
with the step before it and with what it claimed to move. The page shows the whole way
from the published results to the current build, and what no step explains.
- a file format, `sentier-diagnostics/1`, and a strict validator;
- one rule for counting what moved, with named classes for zeros, sign changes, near-zero
and missing results, so that nothing is blanked, zeroed or called agreement;
- a chain of steps from the published results to the current build, each held against
what it claimed to move, with the whole difference split between the steps (exactly, up
to the rounding the page shows) and what nothing explains named;
- a page that shows it: a frameless body a site holds in its own page, with a style
scoped to it that takes the site's tokens, or a page of its own with no build step, no
server and no network; a local file can carry a matrix of every item, which the page
loads after it has drawn.

No data is held here: no inventory, no characterisation factors, no results of a
licensed database. Scoring and the readers of each database stay in the projects that
use this tool.
The published results are checked once, at the start (step 0). Every later step is
compared with the step before it.

Status: being specified. Not ready for use.
No data is held here: no inventory, no characterisation factor, no result of a licensed
database. Scoring and the readers of each database stay in the projects that use this.

## Try it

```bash
PYTHONPATH=src python3 -m sentier_diagnostics example --out build/example
```

Then open `build/example/page/index.html`, or `build/example/local/page/index.html` for a
local file whose page loads the matrix of every item. The example is made up.

In a site's own page:

```python
from sentier_diagnostics import page

html = page.body(data, title=False) # one <div class="sentier-diagnostics">, the file inside
assets = page.assets() # diagnostics.js and diagnostics.css, to copy
```

Install it in a project, pinned to a tag:

```bash
uv add "sentier-diagnostics @ git+https://github.com/sentier-dev/sentier-diagnostics@v0.1.0"
```

Python 3.10 or later, standard library only.

## Read more

- [SPEC.md](SPEC.md): the questions, the format, the rule, the views, the acceptance cases.
- [docs/runbook.md](docs/runbook.md): tests, releases, reviews, for a maintainer alone.
- [docs/migration.md](docs/migration.md): how the existing dashboards move here and retire.
- [GLOSSARY.md](GLOSSARY.md), [MAINTAINERS.md](MAINTAINERS.md), [NOTICE](NOTICE).

Status: first version, under review. The tag `v0.1.0` does not exist yet.

Licence: MIT, see [LICENSE](LICENSE).
Loading
Loading