02 Mar 15:47

Immutable

v0.1.0

d022e0d

v0.1.0 Latest

Latest

pnanolocz v0.1.0 — Initial Public PyPi Release

This release marks the first public version of pnanolocz, the Python implementation of the NanoLocz AFM/HS‑AFM levelling and analysis library, to be released on PyPi.
It includes a full package rename, modernised source layout, updated documentation, refreshed metadata, and new GitHub issue templates.

What's changed?

Package Rename & Restructure

Renamed the project from pnanolocz_lib → pnanolocz.
Moved all source code to a src/pnanolocz/ layout.
Updated all imports, module paths, entry points, and tests.
Updated coverage, mypy, Ruff, and isort configs to match the new structure.
Updated version file target for setuptools_scm.

Packaging & Metadata Improvements

Updated pyproject.toml:
- renamed the distribution to pnanolocz
- added Issues and Changelog URLs
- updated playnano filter entry points
- corrected author information
Updated CITATION.cff (fixed email + metadata cleanup).
Added full CHANGELOG.md following Keep a Changelog conventions.

Documentation Overhaul

Rewrote the README:
- updated install instructions (pip install pnanolocz)
- updated import paths
- updated module documentation
- refreshed examples and code blocks
- added CI / coverage / license badges
Updated module references in docstrings (pnanolocz.level, pnanolocz.level_auto, etc.).

Repository Improvements

GitHub Issue Templates

Added modern GitHub issue forms:

Bug Report
Feature Request

CI & Tests

Updated coverage configuration to --cov=pnanolocz.
Updated all test imports to use the new package name.
Ensured all core modules import correctly after the rename.

Housekeeping

Updated .gitignore.
Corrected duplicate dist/ entries.
Cleaned up outdated references to pnanolocz_lib.

No Algorithm Changes in v0.1.0

This release contains no functional or numerical changes to levelling, thresholding, automated routines, or region‑weighted methods.
All algorithmic updates remain in previous versions (0.0.3, 0.0.4).

v0.1.0 is a structural and packaging milestone to prepare the project for PyPI publication.

Summary

This release:

finalises the rename to pnanolocz,
modernises the project layout,
updates all imports, metadata, and documentation,
adds issue templates and citation metadata,
and prepares the library for PyPI distribution.

This is the foundation for all future development and public releases.

Release Notes — v0.0.3

MATLAB‑aligned masks & auto routines; Python 3.11+ required
Date: 2026‑01‑14

This release moves the Python NanoLocz library from “functionally similar” to algorithmically aligned with the MATLAB reference, with a strong focus on mask semantics, numerical parity, and automated routines. It clarifies public contracts, reduces hidden numerical drift, and makes validation and extension easier.

Highlights

Unified mask semantics across thresholding and leveling: boolean exclusion masks (True = excluded / masked), with consistent NaN‑outside fitting semantics.
Numerical parity with MATLAB: 1‑based indices; population standard deviation (ddof=0) for polyfit(..., mu) alignment; explicit stage gating and fallbacks.
Automated routines completed: multi-plane-edges & multi-plane-otsu implemented; anisotropy‑gated med_line preconditioning; MATLAB‑style gauss1 histogram fitting for adaptive bounds.
API cleanup: new public apply_thresholder(...); consistent contracts across level, level_weighted, thresholder, level_auto.
Build/CI: Python 3.11+ required; test 3.11/3.12/3.13; pin scikit-image>=0.26,<0.27; refined pre‑commit hooks.
Docs & citation: CITATION.cff; expanded docstrings; README/Notebook updated.

Breaking Changes

Minimum Python: now 3.11 (3.10 dropped).
Thresholding API & mask polarity:
- Use apply_thresholder(img, method, limits=None, invert=False).
- Returns a boolean exclusion mask (True = excluded, False = valid), replacing NaN‑style masks and prior mixed polarity.
Leveling inputs expect exclusion masks:
- Public leveling functions convert the provided exclusion mask to an internal validity mask and fit with NaN‑outside semantics.
Behavioral alignment tweaks:
- level_line only runs the column stage when polyy > 0.
- med_line interprets polyx as a gain when polyx > 0 (else 1.0), matching MATLAB.

New & Improved

1) Mask Semantics (All Modules)

Thresholders now return exclusion masks (consistent with MATLAB NaN regions).
Shared helper _validity_mask converts public exclusion masks to internal validity masks for fitting.
Fitting uses NaN‑outside semantics: excluded pixels are omitted in summaries/fits but preserved in outputs.

2) Core Leveling Parity (`level.py`)

Polynomial fitting uses 1‑based indices and population std (ddof=0) to mirror MATLAB polyfit(..., mu).
Reworked methods: plane, line, med_line, med_line_y, smed_line, mean_plane, log_y.
- Fit only over valid pixels; explicit low‑sample fallbacks; preserve excluded pixels.
- Documented MATLAB stage gating (e.g., column stage in line when polyy > 0) and med/mean behaviors.
get_background(...) now guarantees: background = input − leveled under the same semantics.

3) Automated Routines (`level_auto.py`)

Implemented: multi-plane-edges, multi-plane-otsu; restored missing plane→histogram passes.
Anisotropy‑gated preconditioning: injects a one‑off med_line after specific triggers (e.g., post plane(1,1)), matching MATLAB’s adaptive flow.
MATLAB‑style Gaussian histogram fitting (gauss1 via curve_fit) for adaptive bounds: gauss_fit, gauss_peaks, gauss_holes.
Note: adaptive bounds are computed per frame rather than globally across the stack (documented deviation).

4) Thresholding (`thresholder.py`)

New dispatcher: apply_thresholder (returns boolean exclusion masks).
Clarified and expanded methods:
- Intensity/segmentation: selection, histogram, otsu.
- Edge masks: auto edges, hist edges, otsu edges.
- Skeletonized edges: hist skel, otsu skel.
- Specialized: line_step (PELT change‑point), adaptive (Sobel + morphology + inclusive gating).

5) Region‑Weighted Leveling (`level_weighted.py`)

Regions computed from validity using 8‑connectivity; min area = floor(1% of H×W) (MATLAB rule).
Weighted aggregation uses a 2% weight threshold (weights ≤2% zeroed; not renormalized), matching MATLAB convention.
Evaluation on 1‑based coordinate grids for numerical alignment.
Expanded docstrings; clearer behavior/edge‑case notes.

6) Documentation, Examples & Citation

Added CITATION.cff for proper software citation.
README: requirements (Python 3.11+), quickstart using apply_thresholder and apply_level_weighted, routine summaries, links, citations.
Notebook: refreshed workflow examples and narrative using the new API.

7) Build, Tooling & CI

Python 3.11+; CI tests 3.11/3.12/3.13.
Pin: scikit-image>=0.26,<0.27 for stability.
Pre‑commit: --show-diff-on-failure; refined exclude patterns (docs, notebooks, tests/resources, etc.).
Tooling targets set to py311 (Black, Ruff, Mypy).

8) Tests & Resources

New tests/conftest.py with an NPZ loader fixture.
Added AFM resource data under tests/resources/ for future tests.

Migration Guide

A) Thresholding

Before

from pnanolocz_lib.thresholder import thresholder
mask = thresholder(img, method="otsu")         # NaN/ambiguous polarity

After

from pnanolocz_lib.thresholder import apply_thresholder
mask_excl = apply_thresholder(img, method="otsu")  # bool, True = excluded
valid = ~mask_excl

B) Leveling with Masks

Before (weighted leveling with assumed validity mask)

leveled = apply_level_weighted(img, 1, 1, method="line", mask=valid_mask)

After (exclusion mask expected)

leveled = apply_level_weighted(img, 1, 1, method="line", mask=mask_excl)

C) Automated Routines

from pnanolocz_lib.level_auto import apply_level_auto
out = apply_level_auto(stack, routine="multi-plane-otsu")

D) Environment / CI

Ensure Python 3.11+ locally & in CI.
If using GitHub Actions, fetch tags for setuptools-scm during build:

- uses: actions/checkout@v4
  with:
    fetch-depth: 0

Assets 2

Releases: derollins/Python-Nanolocz-Library