0.3.3

Human-in-the-loop active-learning cell classifier for QuPath 0.7.

This release fixes the findings of a review of the machine-learning code (#65–#72). Most changes are fixes. Some change results, so read Changes to results before comparing with 0.3.2 runs.

Changes to results

• Early stopping no longer uses the validation cells it reports on (#71). The number of boosting rounds is now chosen on cells from the training 80% only:

  • below 2,000 labelled cells, by 5-fold cross-validation;
  • above that, on a 10% inner split.

  The loss is class-weighted so small classes count. Auto-tune also uses only the training 80% when Train/val metrics is ticked. The final model is still trained on all labelled cells. Round counts can differ from 0.3.2; accuracy is about the same.

• Macro F1 averages only the classes present in the set (#71). A class with no validation cells is shown as not in this set instead of counting as 0. This applies to Training Metrics and to Auto-tune's scoring.

• Random Forest confidence is the fraction of trees voting for the class (#69). Before, confidences were pulled towards equal values: a forest whose trees all agreed could show under 10%. Random Forest's predicted class can change for borderline cells.

• Images missing a measurement the classifier was trained on are skipped (#70). Before, the missing measurement was read as 0 for every cell. Now these images are not classified and their labels are not used for training. A dialog after training lists them.

• Composite classification and Feature Importance apply batch-correction gains (#70), as training and prediction already did.

Fixed

• Binary and multi-class predictions overwrote each other (#66). Binary predictions are now saved per marker in celltune/binary-image-predictions/<marker>/. Entering or leaving binary mode loads the right set.
• Saved predictions from an older model were used (#66, #68). Review sampling, image switching, Project Prediction Summary and the agreement matrix now skip predictions made with a different class list.
• Training Metrics counted synthetic cells as training cells (#65). The header now gives real labelled-cell counts, plus the row count after balancing.
• Imported ground truth with merged classes (X-mergedInto(Y)) trained as a separate class (#66).
• Deleted classes came back through labels on other images (#66).
• Review re-sampled cells you had just labelled (#66).
• Old metrics were kept when the metrics step failed (#66).
• Training refused to start with fewer than 10 labels on the open image, even with pooling on (#67). Labels on other images now count.
• Manual Label Mode ignored cells already selected when it opened (#67).
• Class Control lists were out of date until Refresh (#68). A merge that matches no labels now shows a warning.
• XGBoost + XGBoost and LightGBM + LightGBM gave identical models and an empty review queue (#69). These pairs are now refused.
• LightGBM native memory grew with every retrain (#69, #70).
• A failed training run could leave the old model with the new class list (#69).

New warnings

• Batch correction changed since training (#70). The setting was toggled, or the gains were re-fitted. Prediction continues with the current setting.
• Classes with fewer than 6 labelled cells when SMOTE or ADASYN is selected (#71). Shown before training starts.

Upgrading

• Install: remove the old qupath-extension-sp-classify-*-all.jar from the QuPath extensions folder, add this one, and restart QuPath.
• Binary mode: run Apply to which images... once per marker, so other images get binary predictions in the new folder.
• Retrain to get the new early stopping and an up-to-date Training Metrics report. Reports saved by 0.3.2 are marked as possibly optimistic.
• Classifiers saved before 0.3.3 have no batch-correction record, so no correction warning is shown for them until they are retrained.

Documentation: README, user guide and the docs site are updated for all of the above (#72).

0.3.2

Human-in-the-loop active-learning cell classifier for QuPath 0.7.

Highlights since 0.3.1

New: Channel Mapping editor (#61)

Extensions → SP Classify → Channel Mapping (Review Display)..., or Edit channel mapping… in the Review Mode window.

• Choose rather than type. Pick which channels review mode shows for each class: classes come from the project and channels from the open image, so nothing is typed by hand.
• Status per class. Shows whether each class's channels match the open image exactly, approximately (✓ ≈ ~ ! ✗), or not at all.
• Tools: Preview, Pin matches, CSV import/export, and Scan project channels for projects whose images have different panels.
• No limit on channels per class.
• Persistence. The mapping is saved in the project and survives restarts. Each project keeps its own.
• Old CSVs still work. Existing marker-table CSVs import as before.

Fixed

• Auto channel switching picked the wrong channels. For example, CD3 also showed CD31. Matching now uses the image's own channel names (#61).
• Switching projects carried the previous project's channel mapping into the new one (#61).
• Marker-table CSVs saved by Excel (UTF-8) failed to load, and quoted fields containing commas were split wrongly (#61).
• Model labels ignored Random Forest. The confusion matrix, review buttons and Training Metrics always said XGBoost / LightGBM. They now show the model types you selected (#63).
• Scatter plot ignored a changed Clustering Normalisation. Reopening the plot now offers to rebuild it, and New clustering session uses the current settings (#63).
• Scatter plot applied batch correction only in the all-cells Leiden run. With Use batch-corrected values on, it is now applied in every scope and to every assign and write (#63).
• Filter Cells by Size & Circularity could filter on nucleus area. It used the first measurement containing "area". You now choose the area and circularity measurements; the whole-cell ones are pre-selected (#63).

Documentation (#62)

• User guide and documentation site rewritten in plain language, with exact defaults and UI labels.
• Statements that did not match the software are corrected. Examples: auto-prune runs on raw values, the review batch default is 200, and Open Selected Image discards unsaved changes.
• Documentation: https://mikemcka.github.io/qupath-extension-sp-classify/

Install

1. Download qupath-extension-sp-classify-0.3.2-all.jar below.
2. Delete any older qupath-extension-sp-classify-*-all.jar (and any qupath-extension-celltune-*-all.jar) from your QuPath extensions folder. Only one SP Classify JAR should be present.
3. Drag the JAR onto QuPath, or copy it into the extensions folder, then restart QuPath fully.

Requires QuPath 0.7.0+ (Java 25). Existing projects load unchanged. The channel mapping is stored in the same marker-table.json file. Older versions of the extension can still read it, but they ignore the exact channels.

0.3.1

Human-in-the-loop active-learning cell classifier for QuPath 0.7.

Highlights since 0.3.0

• Renamed CellTune → SP Classify. Menu is now Extensions ▸ SP Classify; the package/artifact/module were renamed. Existing project state (<project>/celltune/) and QuPath preferences are preserved, so existing projects keep loading.
• Fix: auto channel-switching during review (reported as "sometimes doesn't work"):
  • Predicted cell type → marker lookup is now case/spacing/punctuation-insensitive (the main cause of silent no-ops).
  • Channel matching is exact-preferred, so marker CD3 no longer also lights up CD31/CD34.
  • When no channel matches, the viewer is left unchanged instead of blanked.
• Citations: point to the published CellTune paper (Nature Methods, doi:10.1038/s41592-026-03162-2); new in-app How to Cite dialog.
• New online documentation site: https://mikemcka.github.io/qupath-extension-sp-classify/

Install

1. Download qupath-extension-sp-classify-0.3.1-all.jar below.
2. Delete any older qupath-extension-celltune-*-all.jar and qupath-extension-sp-classify-*-all.jar from your QuPath extensions folder (only one should be present).
3. Drag the JAR onto QuPath (or copy it into the extensions folder) and restart QuPath fully.

Requires QuPath 0.7.0+ (Java 25).

0.3.0

Highlights

• UniFORM batch correction (#51) — fit per-image per-channel gains and stream them into clustering and ML training/inference (no corrected columns written; correction is in-memory and re-fittable). Batch Normalisation dialog + QC window under the CellTune menu.
• Annotation-name sampling for clustering (#52) — restrict a cohort clustering run to cells whose centroid falls inside annotations matching given name/class keywords; combines with the class filter.

Install

Download qupath-extension-celltune-0.3.0-all.jar below and drop it in your QuPath extensions folder (delete any older CellTune jar first), then restart QuPath.

🤖 Generated with Claude Code

0.2.7

CellTune 0.2.7

Usability fixes for the clustering/heatmap views, plus a CPU-only cleanup (PR #47).

Fixed

• Cellular-neighborhood enrichment heatmap no longer disappears. The heatmap window is now independent of the Neighbourhood Analysis dialog, and reopening it keeps your toggles (show values / merge rows / diversity swatch), typed CN names, and window position.
• The cell scatter plot / clustering window remembers its results. Closing and reopening it from the menu restores your clusters, scope and fit without re-clustering — including whole-project Leiden with kNN assignment. Use the new New clustering session button (next to Re-sample) to deliberately start over with a different marker set or scope.
• Marker and cluster heatmaps are easier to read. The assign-clusters z-score heatmap is gamma-stretched so faint blue (low) values no longer wash out to white, and the scatter "colour by marker" view now scales to the 2nd–98th percentile (plus a gamma boost) so a few bright cells no longer flatten everyone else into one colour.

Changed

• CPU-only build cleanup. Removed the leftover GPU device-reporting and probe scaffolding (this build ships no GPU kernels), which also removes the alarming [LightGBM] GPU Tree Learner was not enabled log line. Training behaviour is unchanged.

Install

Download qupath-extension-celltune-0.2.7-all.jar below. Delete any older CellTune JAR from your QuPath extensions folder first, drop this one in, and restart QuPath fully.

0.2.6

CellTune 0.2.6

Auto-tune was scoring itself on data it had already seen (PR #45).

Fixed

• Auto-tune picked the wrong settings when data balancing was on. Balancing ran across the whole dataset before cross-validation split it, so the synthetic cells SMOTE invents — each one a blend of two real cells — ended up in the slice being scored while the cells they were built from were in the slice being trained on. The search was marking its own homework. The damage was not just an inflated score: settings that memorise hardest win that kind of test, so those were the ones handed to your model. Balancing now happens inside each fold, and the cells a run is scored against are always real ones.
• Auto-tune spent about half its LightGBM trials on identical models. Tree depth stops changing a LightGBM model once its leaf limit takes over, which happens at depth 5 — so trials at depths 6 through 12 were re-testing the same thing. The search now stops where the limit bites.
• A very rare class could quietly drag the reported score down. With more folds than a class has labelled cells, some folds had none of it to learn from and then got marked on it anyway. The fold count now adapts and the training log says when it does.

Changed

• Auto-tune is faster. The cross-validation folds are built once per run instead of once per trial.
• Trials and CV folds are now settable next to the auto-tune checkbox. They were fixed at 20 × 5 = 200 model fits per run, which is hours on a wide panel with no way to ask for less.
• Auto-tune also searches column sampling (how many markers each tree may look at) alongside depth, learning rate and row sampling. On a wide panel this moves accuracy at least as much as depth does.

Note

Only auto-tune behaviour changes. A run with auto-tune switched off — the default — produces the identical model it did in 0.2.5; this is pinned by tests. If you have used auto-tune before, expect its reported trial scores to be lower than you are used to and closer to the Training Metrics report: that gap was the bug.

Install

Download qupath-extension-celltune-0.2.6-all.jar below. Delete any older qupath-extension-celltune-*-all.jar from your QuPath extensions/ folder first, drop this one in, and restart QuPath fully.

Built against QuPath 0.7 / JDK 25.

0.2.5

CellTune 0.2.5

One fix: the project-combined intensity heatmap now reads the open image live (PR #44).

Fixed

• The combined heatmap could show phenotypes you had already replaced. All Images (Project Combined) read every project image from disk, including the one you had open. Classifications applied to the open image stay in memory until QuPath saves it — training and composite classification write the other project images to disk but leave the open one to QuPath — so the pooled view showed whatever classifier last wrote that image's .qpdata. In practice, an old composite run's Marker+ / Marker- rows kept appearing alongside the current phenotypes, while the same image viewed on its own showed the correct classes. The open image is now always pooled from its live hierarchy, so the two views cannot disagree.

Note

This fixes the heatmap reading stale state. It does not clean up images that already carry old classes on disk — if other images in your project still show leftover phenotype rows when you select them individually, re-run classification with those images ticked in Apply to which images… and save.

Install

Download qupath-extension-celltune-0.2.5-all.jar below. Delete any older qupath-extension-celltune-*-all.jar from your QuPath extensions/ folder first, drop this one in, and restart QuPath fully.

Built against QuPath 0.7 / JDK 25.

0.2.4

CellTune 0.2.4

Much faster training, and a fix that makes Model 2 noticeably better (PR #43).

Faster

• Training is substantially faster. Class balancing (SMOTE / Tomek) was the biggest cost in a run and is now a rounding error — on a 35-class, 1,886-feature panel it went from dominating the run to 1.5% of it.
• The metrics step no longer retrains a model it already had. Worth about 4 minutes on the same run.
• Removed a pointless GPU check that ran a full training pass on every run before giving up. Training is CPU-only; the bundled models have no GPU support.

New

• Training log file. Every run is saved to <project>/celltune/logs/, including when a run crashes. It records every setting used and ends with a breakdown of where the time went, so a slow run can be diagnosed rather than guessed at.
• Out-of-memory handling. A warning before training starts if memory looks tight, and a proper error naming the step that failed instead of a progress window that hangs forever.
• CPU threads setting — limit how much of the machine training uses, so you can keep working while it runs.
• Train/val metrics tick-box — untick to skip the Training Metrics report and train roughly a third faster.
• Rounds default raised from 200 to 500. With early stopping on (the default) this is a limit rather than a target, so models still stop when they stop improving.
• Workers renamed to Images at once, to distinguish it from the new CPU threads setting.

Fixed

• Auto-tune was tuning the wrong thing. It scored candidate settings on a model configured differently from the one it then built, so its recommendations were unreliable.
• Auto-tune ignored the CPU threads limit and could ask for five times the machine at once.
• Auto-tune threw away the early-stopping result and searched for a round count it had already measured.
• Failed cross-validation runs now say so instead of being reported as poor scores.
• Batch-apply progress no longer looks like it dropped an image (Saved (13/13) rather than 13/14).
• Fixed a memory leak during auto-tuning.

Install

Download qupath-extension-celltune-0.2.4-all.jar below. Delete any older qupath-extension-celltune-*-all.jar from your QuPath extensions/ folder first, drop this one in, and restart QuPath fully.

Built against QuPath 0.7 / JDK 25.

0.2.3

CellTune 0.2.3

Review-mode & cellular-neighborhood usability, plus Project Prediction Summary fixes (PR #42).

Updates

• Review mode: new "Auto-adjust brightness/contrast of shown channels" tick-box (off by default). Auto channel-switching now changes only channel visibility unless you opt in, so your own brightness/contrast is preserved.
• Cellular Neighborhoods: the kNN control now reads total window size (cells) and defaults to 10 (the paper's 10-cell window), instead of the raw neighbour count. Default behaviour is unchanged — 10 cells = 9 neighbours + the centre cell.

Fixes

• Project Prediction Summary: composition metric now returns the true Jensen–Shannon distance (was the divergence); this affects composition-outlier flags and ranking.
• Project Prediction Summary: Anomaly column now shows 3 decimals (sorting unchanged).
• Docs: flag-reason names in the user guide corrected to match what the table shows (COMPOSITION_OUTLIER, HIGH_DISAGREEMENT); review-mode and cellular-neighborhood sections updated.

Install

Download qupath-extension-celltune-0.2.3-all.jar below. Delete any older qupath-extension-celltune-*-all.jar from your QuPath extensions/ folder first, drop this one in, and restart QuPath fully.

Built against QuPath 0.7 / JDK 25.

v0.2.2

Maintenance update: fix cellular-neighbourhood overlay colours invisible on QuPath's black background, plus documentation updates.