Hifuku: Morphometric Analysis of Sural Nerve Biopsies

Hifuku, meaning 'sural' or 'saphenous' in Japanese, is an open-source machine learning-based software designed for Whole slide Morphometric Analysis in human sural nerve biopsies.

Installation

Clone the Hifuku GitHub repository:

git clone https://github.com/onnonuro/hifuku.git

Tutorial with Google Colab

Google Colab is the easiest way to try out Hifuku with GPU support, especially for clinicians and pathologists who are unfamiliar with programming or do not have a local Python environment.

To get started:

1. Download tutorial.ipynb: Download tutorial.ipynb.

2. Upload tutorial.ipynb to your Google Drive: Upload the file to your Google Drive.

3. Open tutorial.ipynb with Google Colab: Sign in Google Colab and open tutorial.ipynb with it. It detects Colab automatically and mounts Drive / clones the repo / installs dependencies for you; run its cells top to bottom.

4. Run Hifuku: Follow the instructions in the Jupyter Notebook tutorial.

   *You need a google account and sign in to Google colab.

Full analysis walkthrough (tutorial.ipynb)

tutorial.ipynb is a one-stop walkthrough: run hifuku.main(), QC the results, and produce the full set of summary plots and statistics, in one continuous flow.

It covers, in order: running the pipeline, fascicle-level QC (excluding mis-segmented fascicles), fiber-level QC including optional human review, visualization (histograms/scatter plots), Gaussian-mixture small/large fiber classification, the g-ratio slope, per-fascicle spatial analysis (nearest-neighbor distance, KDE entropy), and combining cross sections.

The pipeline itself is one call — there is no command-line interface, so run it from a notebook or a script:

import hifuku

hifuku.main(
    root='.',                          # used to locate weights/ (downloaded on first run)
    path='data/slide.jpg',             # input image
    is_wsi=True,                       # whole-slide (multi-fascicle) vs. single-fascicle crop
    scale=0.273,                       # µm per pixel
    save_dir='results/slide',          # every output file goes here
    fib_det_th=0.5,                    # fiber-detection score threshold (optional)
    fiber_qc_thresholds=None,          # optional per-column QC ranges, see below
)

Fiber-level QC: hifuku.main() flags each detected fiber with a valid column (data_fib.csv) based on whether its myelin/axon contours were segmentable and shape-plausible; data_nerve.csv/data_fas.csv counts and densities are computed from valid fibers only, but no fiber row is ever silently dropped from data_fib.csv.

• Excluding fibers by parameter: pass fiber_qc_thresholds to main(), e.g. fiber_qc_thresholds={'diameter_out': (0, 25)}, to additionally exclude fibers outside a given range for any column in data_fib.csv. Off by default.

• Visual QC beyond the first 100 fibers: each run now saves paginated fibers_NN.jpg (100 fibers per page, covering every detected fiber) instead of a single image silently truncated to the first 100.

• g-ratio slope in the result tables: data_nerve.csv now includes g_ratio_slope, g_ratio_intercept, g_ratio_r2, and g_ratio_n (a linear fit of g-ratio vs. diameter over valid fibers), so this no longer needs to be read off a plot.

• Combining fascicles from different cross sections: hifuku.summarize_fibers(df, total_area=...) recomputes the same fiber count / density / g-ratio slope from any fiber table, so multiple data_fib.csv files (e.g. from separate cross-section images of the same case) can be concatenated and summarized together with their combined total_area.

• Human review of individual fibers: rule-based thresholds only ever produce candidates, so the final call can be a person's — and it is made on the crop images themselves, in a file browser. main() writes one crop per detected fiber (fiber_00000.jpg = row 0 of data_fib.csv) and sorts them into three directories:

  fiber_crops/                   the fibers the rules kept: these are what count
  fiber_crops_exclude/           the fibers the rules excluded
  fiber_crops_exclude_by_human/  empty; this is where you put the ones you reject
  

  A fiber counts if, and only if, its crop is still in fiber_crops/. So reviewing is just re-sorting: drag a crop into fiber_crops_exclude_by_human/ to exclude that fiber (deleting it works too, but moving keeps the audit trail), or drag one back out of fiber_crops_exclude/ to rescue it. hifuku.apply_human_review(save_dir) then reads that sorting back into a fiber table carrying all three verdicts side by side — rule_valid (what the rules decided), human_valid (True for each fiber whose crop is still in fiber_crops/) and valid (the final say, which follows human_valid) — ready to filter on human_valid and pass into summarize_fibers(). Re-running main() on the same output directory regenerates and re-sorts the crops, so finish a review before re-running the pipeline.

• A readable run report: main() now prints what it is doing and what it found — image size and device, fascicles detected, fibers detected per fascicle, exactly which QC rule excluded how many fibers, the resulting counts/density/g-ratio slope, and the list of files written.

Dependencies

Hifuku was tested in the following Google Clolab environment on November 21, 2023.

Python (3.10.12), torch (2.1.0+cu118), torchvision (0.16.0+cu118), torchmetrics (1.2.0), pytorch-lightning (2.1.2), segmentation-models-pytorch (0.3.3), timm (0.9.2), opencv-python (4.8.0.76), albumentations (1.3.1)

tutorial.ipynb's classification and spatial-analysis sections additionally need scikit-learn, scipy, and joblib — all pre-installed in Colab, and listed in requirements.txt for local environments.

Citation

Ono D et al. Automated Whole slide morphometrics of sural nerve biopsy using machine learning Neuropathol Appl Neurobiol. 2024;50:e12967. doi:10.1111/nan.12967