HistoAnalyzer Pre-release

Pre-release: This version is intended for technical testing, workflow validation, and research evaluation. It is not yet recommended for production or clinical use.

DOI

Zenodo DOI: 10.5281/zenodo.21456469

https://doi.org/10.5281/zenodo.21456469

HistoAnalyzer is a cross-platform desktop application for reproducible analysis of H-DAB histology images. This initial pre-release combines tissue detection, anthracosis exclusion, DAB-positive area quantification, nuclei segmentation, exploratory nucleus classification, spatial graph construction, and tissue-region visualization in a single workflow.

Highlights

• Automated tissue detection using the bundled QuPath-derived tissue classifier
• Anthracosis detection and configurable dilation
• Generation of a clean-tissue compartment for downstream measurements
• DAB-positive and DAB-negative area quantification
• GeoJSON export for the main analysis stages
• InstanSeg brightfield nuclei segmentation
• Automatic watershed fallback when InstanSeg is unavailable
• Per-nucleus morphology, hematoxylin, texture, and spatial feature extraction
• Exploratory nucleus classification with class probabilities and uncertainty
• Color-coded nucleus-class overlays
• Nucleus neighborhood graph generation
• Exploratory tissue-region inference from local nucleus composition
• CSV, GeoJSON, GraphML, PNG, and JSON exports
• Windows, macOS, and Linux build workflows

Analysis workflow

Input H-DAB image
→ Tissue detection
→ Anthracosis detection
→ Anthracosis dilation
→ CleanTissue generation
→ DAB-positive/negative classification
→ Nuclei segmentation
→ Per-nucleus feature extraction
→ Exploratory nucleus classification
→ Nucleus graph construction
→ Tissue-region inference
→ CSV / GeoJSON / GraphML / PNG export

Nucleus classes

The current exploratory classifier supports:

• Small lymphocyte
• Plasma cell
• Neutrophil
• Macrophage
• Fibroblast/myofibroblast
• Endothelial cell
• Normal pneumocyte/bronchial epithelial cell
• Tumour epithelial cell
• Uncertain

Each nucleus includes:

• predicted class
• candidate class
• top-class probability
• second-class probability
• entropy-based uncertainty
• margin-based uncertainty
• complete per-class probability vector

Class-color visualization

Each nucleus is displayed using a consistent class color:

Class	Display color
Small lymphocyte	Blue
Plasma cell	Purple
Neutrophil	Cyan
Macrophage	Orange
Fibroblast/myofibroblast	Green
Endothelial cell	Yellow
Normal epithelial cell	Pink
Tumour epithelial cell	Red
Uncertain	Gray

The exact palette is exported as:

nuclei_class_palette.csv

Main outputs

01_Tissue.geojson
02_Anthracosis_raw.geojson
02b_Anthracosis_dilated.geojson
03_CleanTissue.geojson
04a_Positive.geojson
04b_Negative.geojson

nuclei_validation_summary.csv
nuclei_validation_montage.png
nuclei_validation_overlay.png
nuclei_validation_instances.png

nuclei_classification.csv
nuclei_classification.geojson
nuclei_class_summary.csv
nuclei_class_palette.csv
nuclei_class_overlay.png
nuclei_class_uncertainty_overlay.png
nuclei_class_legend.png

nuclei_graph.graphml
nuclei_graph_overlay.png

tissue_region_features.csv
tissue_regions.geojson
tissue_region_overlay.png

nuclei_classification_manifest.json

Installation notes

Windows installer

Run:

HistoAnalyzer-Windows-x64-Setup.exe

Installing a newer build into the same default folder should update the existing installation.

Windows portable build

Extract the ZIP completely before launching the application:

HistoAnalyzer-Windows-x64-PORTABLE-EXTRACT-FIRST.zip

Do not run the executable directly from inside the compressed archive.

InstanSeg model

The brightfield_nuclei model is not redistributed with the application. It is downloaded during first use and stored in the user-writable HistoAnalyzer model cache.

An internet connection may therefore be required during the first InstanSeg run.

Important scientific limitations

Nucleus classification is exploratory

The bundled nucleus classifier is currently based on morphology, hematoxylin appearance, texture, and local spatial context. It has not yet been trained and validated as a clinically calibrated multiclass model.

The output probabilities should be interpreted as compatibility scores rather than diagnostic probabilities.

For robust biological interpretation, future releases should use pathologist-annotated training data and independent validation.

Similar classes may overlap

H-DAB nuclear morphology alone may not reliably distinguish:

• plasma cells from small lymphocytes
• endothelial cells from spindle stromal cells
• macrophages from some tumour cells
• normal epithelial cells from malignant epithelial cells
• tumour subtypes without tissue-context supervision

Low-confidence cases should remain assigned to Uncertain.

Pixel size matters

Physical nuclear dimensions depend on image resolution. When metadata are unavailable, HistoAnalyzer may use a fallback pixel size.

For quantitative work, provide the true image resolution using the pixel-size setting.

Tissue-region inference is experimental

Graph-derived regions such as tumour-rich, stroma-rich, immune-rich, vascular-rich, mixed, and uncertain are exploratory summaries of local nuclear composition. They are not equivalent to a validated histopathology compartment model.

Known issues

• OneDrive or antivirus software may temporarily lock intermediate files and prevent automatic cleanup of _work_masks_run_* folders.
• Dense nucleus graphs can appear visually crowded in highly cellular samples.
• Images without valid resolution metadata require manual pixel-size configuration.
• The first InstanSeg run may take longer while the model is downloaded and initialized.
• Very large images may require substantial RAM and processing time.
• Compartment-specific Tumour/Stroma/Other outputs require a separately trained compartment model.
• The current nucleus classifier may produce low-confidence mixed predictions on complex tissue.

Recommended use for this pre-release

This version is suitable for:

• testing the end-to-end workflow
• validating segmentation quality
• reviewing exported measurements
• identifying failure cases
• preparing nucleus annotations
• evaluating class colors and uncertainty visualization
• refining graph and tissue-region parameters
• collecting feedback before model training and formal validation

It should not be used for:

• clinical diagnosis
• patient-level decision making
• unreviewed quantitative conclusions
• validated cell-type counts without manual quality control

Feedback requested

Useful feedback for this pre-release includes:

• image formats that fail to load
• incorrect pixel-size handling
• InstanSeg model-download or cache errors
• nucleus over-segmentation or under-segmentation
• nuclei incorrectly removed by the CleanTissue filter
• misleading class assignments
• confusing uncertainty visualization
• overly dense graph connections
• tissue-region windows extending outside valid tissue
• missing or malformed CSV, GeoJSON, GraphML, or PNG outputs

When reporting an issue, include:

Operating system
HistoAnalyzer version
Input image format
Image dimensions
Pixel size
Selected mode
Relevant log output
Failure traceback, when generated
Example result image

Citation

Please cite this release as:

Rodríguez-Rojas J. HistoAnalyzer: Cross-platform H-DAB histology analysis.
Version 0.1. Zenodo. 2026.
https://doi.org/10.5281/zenodo.21456469

BibTeX:

@software{rodriguez_rojas_histoanalyzer_2026,
  author    = {Rodríguez-Rojas, José},
  title     = {HistoAnalyzer: Cross-platform H-DAB histology analysis},
  version   = {0.1},
  year      = {2026},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.21456469},
  url       = {https://doi.org/10.5281/zenodo.21456469}
}

Pre-release status

This release is published as v0.1 pre-release to support early testing and scientific feedback before the first stable release.

Do not cite this version as a validated clinical or diagnostic system.