GrandQC-QuPath

The group’s own QuPath wrapper around the published GrandQC artefact-detection models — not a copy of them — and the folder that shows how the umbrella’s submodule wiring is broken.

Purpose

GrandQC is a published quality-control system for whole-slide images: two-stage tissue segmentation followed by multi-class artefact detection (tissue folds, air bubbles, pen marks, dark spots, foreign objects, out-of-focus regions), released with models on Zenodo alongside a Nature Communications 2024 paper (doi 10.1038/s41467-024-54769-y). This repository is the group’s integration of it into QuPath, so that artefact masks land where annotation actually happens rather than in a separate Python session.

Provenance, checked rather than assumed: the remote is sbalci/GrandQC-QuPath, six commits, last pushed 2025-11-01, private, not a fork. The root-level code is the group’s own, which py_scripts/grandqc_original_processor.py says of itself — “direct adaptation of original repository code”. A complete copy of the upstream cpath-ukk/grandqc tree does sit under documentation/, but it is gitignored and never reached GitHub, so this is own integration code plus a local reference copy, not a vendored repository. Same shape as spider-qupath, unlike the reference collections elsewhere in Digital Pathology Drafts.

The README declares CC BY-NC-SA 4.0, matching upstream.

Data used

No cohort in version control, and the image-file hygiene is genuinely good: .gitignore excludes /data, /classifiers, output/, *.svs* and *.pth, so the ~545-file QuPath project, the model weights and every derived thumbnail stay local. Verified against git ls-files — only 91 files are tracked, and no thumbnail or overlay image is among them.

But project.qpproj and project.qpproj.backup are both tracked, and both carry slide identifiers. Each contains 33 accession-shaped tokens across two distinct values, alongside 19 properly anonymised ANON… tokens — so the project is inconsistently de-identified: part of the cohort was pseudonymised and part was not, in one committed file.

This matters more than the raw count suggests, because it is the group’s own rule being broken in the group’s own repository. QuPath Tooling states plainly that .qpproj files for cohorts containing patient identifiers must not be committed and stay on the Memorial share. It is also the second recorded instance of exactly this, after the teaching repository noted under Known gap 8 in the wiki index — and it repeats that instance’s detail that the fix is two files, not one, because the .backup carries the identical content. A .gitignore covering *.qpproj* would close it.

An earlier draft of this page recorded the de-identification here as “done correctly” on the strength of the .gitignore alone. That was wrong: the ignore rules cover the images and miss the project file, which is the one place the identifiers actually live. Corrected 2026-07-27.

One smaller point in the same family: .gitignore excludes a specific result thumbnail by filename, and that filename is a slide identifier — so the identifier is written into a tracked file in the course of keeping the image out. The tracked per-slide statistics report is cleaner than it could have been: it lists bare scanner-assigned slide numbers with no accession-format strings at all.

Methods

Wrapper and orchestration rather than modelling: 32 Python scripts, 13 QuPath scripts, 18 batch/shell launchers, a grandqc_config.json, and an unusually large documentation folder (~110 files). The launcher scripts and a dedicated .venv_GrandQC indicate the integration problem here was mostly environment management — getting the upstream model’s dependency stack to run reliably beside QuPath on Windows — rather than algorithm work.

The performance figure in the README is the upstream paper’s, not a local measurement. The stated tissue-segmentation Dice of 0.957 appears only in the README; nothing in the scripts computes a Dice score. That is the same pattern already recorded on spider-qupath, where published vendor accuracies were carried over as though they described local behaviour, and it is worth naming as a recurring habit across these drafts rather than a one-off. The figure is almost certainly correct for the data GrandQC was evaluated on; what is missing, here as there, is any measurement on Memorial material.

Current state / open questions

Paused at the same date the umbrella itself stopped, 2025-11-01.

• This folder is the clearest symptom of the umbrella’s submodule problem. .gitmodules declares GrandQC-QuPath as a submodule, but no gitlink exists in the index, so it shows as an untracked directory and a git clone --recursive of the umbrella does not fetch it at all. Anyone reconstructing the drafts tree on another machine silently gets no GrandQC. The fix belongs on Digital Pathology Drafts, not here.

• The open question is the one the wrapper cannot answer: does GrandQC’s artefact vocabulary match what actually goes wrong in this laboratory? Pen marks and air bubbles are universal; the frequency and appearance of folds and out-of-focus regions depend on the microtomy, mounting and scanner in use. An agreement check against a pathologist’s own artefact calls on a small local set is what would turn this from an installed tool into a validated one, and it is a smaller piece of work than the environment plumbing already done.

  Largely answered on 2026-07-31, and the answer is no — see GrandQC Quality Study, which ran exactly this check on 502 slides and was sitting in a separate MemorialPath repository the whole time. 70% of the quality problems the laboratory records have no GrandQC class at all, because nine of the technicians’ thirteen criteria are microtomy and mounting geometry (off-centre, oblique, torn, overflowing, detached) rather than properties of the scanned image. Chance-corrected agreement is κ = 0.10. Two caveats keep this from closing the question outright: the raters were technicians, not pathologists — a different rater class with a different threshold, which is what was asked for here — and the form is a preparation-quality instrument rather than a diagnostic-adequacy one. So the artefact vocabulary is confirmed narrower than the laboratory’s notion of a bad slide, while the original pathologist-facing version of the question stands. [unverified]

  This also settles the sentence above about the README’s Dice 0.957 being upstream’s rather than a local measurement: local measurement now exists, in the other repository, and it is an agreement statistic rather than a segmentation one.

• Whether QC should run before or after tissue detection in the group’s pipeline has not been decided — stepbystep tunes a tissue threshold independently, and the two have never been run in sequence. [unverified]

Naming hazard, added 2026-07-31 — read this before comparing any “GrandQC” number. This repository is the real thing: it runs the published artefact-detection models. imagebank also ships two files carrying the GrandQC name — cli/GrandQC/GrandQC.py and grandqc_integration.py — and neither contains any GrandQC at all. Their container installs no deep-learning framework and loads no weights; they compute Laplacian variance, mean grey level and a fixed intensity threshold, while the plugin manifest advertises “GrandQC Quality Assessment” and claims it was “Built with GrandQC library”. So a quality figure described as “the GrandQC result” may have come from a segmentation network or from a blur heuristic, and nothing in either output records which. If a number is being compared against this repository’s or against GrandQC Quality Study’s, establish which tool produced it first.

There is a third instance in the same repository, found 2026-08-01 and different in kind: Dockerfile.complex carries the comments “Install GrandQC for quality control” and “GrandQC is a digital pathology quality assessment tool” directly above a pip install of OpenCV, pandas and openpyxl. Not a mis-named tool this time — a build step that says it installs GrandQC and does not.

The obvious fix — rename them — is not the ten-minute job it looks like, and the reasons are written up under Current state on imagebank. Read that before starting: the name is also a CLI dispatch key wired across four files, and grandqc_analysis is the key under which QC results are already stored in slide metadata, read back in two places behind unguarded .get() calls. A find-and-replace silently drops existing QC results from the Excel export and the PDF report rather than failing. As of 2026-08-01 the rename is deliberately not done, so the hazard above is live and this wiki is the only thing warning about it.

Related: WSI Quality Control — the method this implements; GrandQC is the strongest published option in that space and this is the group’s route to it. Related: imagebank — carries two differently-implemented tools under this repository’s name; the reason the paragraph above exists. Related: spider-qupath — the same wrapper-around-published-models shape, and the same habit of quoting upstream accuracy figures locally. Related: stepbystep — the other tissue-detection route here; the two overlap and have never been compared. Related: Digital Pathology Drafts — the umbrella that declares this as a submodule without registering it.

Derived from: repository read 2026-07-27 — README.md, .gitignore, grandqc_config.json, directory inventory of py_scripts/, scripts/, bash_scripts/, documentation/; git remote, git log, git ls-files for provenance, currency and what is actually tracked; gh repo view for visibility; upstream paper and Zenodo links as cited in the README.