Skip to content

Python MATLAB Feature Parity for IFCB v4 Features

Jump to bottom
John Walsh edited this page Jun 9, 2026 · 3 revisions

Python/MATLAB Feature Parity for IFCB v4 Features

Status

As of May 2026, the Python ifcb-features v4 pipeline has near-complete parity with the MATLAB v4 feature pipeline.

The blob generation pipeline is identical. Feature differences are now limited to a very small number of floating-point-level differences, primary in Biovolume, SurfaceArea, and their summed equivalents.

Scope

This page describes parity between:

  • Python: ifcb-features
  • MATLAB: ifcb-analysis, branch match-python
  • Output version: v4
  • Python output:
    • *_features_v4.csv
    • *_blobs_v4.zip
  • MATLAB outputs:
    • *_fea_v4.csv
    • *_blobs_v4.zip

Note that this is parity with the MATLAB v4 feature pipeline, not the older MATLAB v2 feature pipeline.

Changes

The main sources of Python/MATLAB mismatch were removed by making ambiguous operations explicit and deterministic.

Blob Segmentation

The k-means segmentation path was updated to avoid implementation-dependent floating-point behavior.

Key changes:

  • Use deterministic 1D k-means behavior.
  • Match MATLAB/Python cluster initialization and empty-cluster behavior.
  • Use explicit single-precision accumulation semantics.

Result: blob masks now match exactly.

Orientation and Rotation

Small differences in regionprops orientation caused nearest-neighbor rotation to choose different pixels at half-pixel boundaries.

The fix was to make orientation and crop rotation explicit:

  • Compute orientation from image moments directly in both languages.
  • Use deterministic nearest-neighbor crop rotation.
  • Avoid relying on MATLAB imrotate black-box edge behavior.

Result: blob rotation behavior now matches between Python and MATLAB.

Biovolume / Surface Area

Biovolume and surface area are computed by two paths: - Solid of revolution, for simpler compact blobs.

  • Distance-map volume, for more complex blobs.

The distance-map path was aligned by making distance transform and summation behavior more explicit. Remaining feature differences are now small and isolated.

Large Sample Validation

A large validation sample was used to compare MATLAB v4 outputs against Python v4 outputs after the parity fixes.

Bins compared: 210

Total ROIs compared: 970712

Blob comparison result:

Bins compared: 210

Total common files: 970712

Total differing files: 0

This means every common ROI blob PNG in the 210-bin sample matched exactly between MATLAB and Python.

Feature comparison result:

Common bins: 210

Rows compared: 970712

Rows with any numeric feature diff > 0: 117 (0.012053%)

Rows with any numeric feature diff > 1e-6: 93 (0.0095806%)

Rows with any numeric feature diff > 1e-5: 89 (0.00916853%)

Rows with any numeric feature diff > 0.001: 11 (0.00113319%)

Largest remaining feature differences:

Biovolume max abs diff: 11.2574

summedBiovolume max abs diff: 11.2574

SurfaceArea max abs diff: 13.5493

summedSurfaceArea max abs diff: 16.0489

Orientation max abs diff: 1e-08

Biovolume differences were further classified by method:

SOR vs SOR: 2 ROIs

distmap vs distmap: 80 ROIs

method mismatch: 0 ROIs

The two largest Biovolume differences were both solid-of-revolution cases:

D20251103T180413_IFCB127_08745 abs diff 11.257374

D20231027T143426_IFCB102_00420 abs diff 7.330383

The remaining Biovolume differences were distance-map cases and were much smaller, starting around 0.0156.

Clone this wiki locally