SEM Analysis Pipeline

sem-analysis-pipeline is a framework for calibrated, auditable analysis of scanning electron micrographs. The repository has a deliberately generic name so independently validated capabilities can be added over time.

Current capability

Version 0.1.0 provides one frozen workflow: paired-acquisition external- aggregate aspect ratio. It segments one external two-dimensional aggregate silhouette per image, automatically abstains when image evidence is inadequate, and requires agreement between two images of the same physical field.

The endpoint is the major-to-minor axis ratio of the second-moment equivalent ellipse. It is not an isolated-crystal measurement and does not estimate three-dimensional sphericity.

No human-drawn or human-corrected boundary is used by this workflow.

Install

Python 3.11 or newer is required.

python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

Run

Prepare an explicit image manifest and validated profile declaration, then run:

sem analyze aspect-ratio examples/image_manifest.csv \
  --config examples/analysis.toml \
  --output results/example

The command refuses to overwrite an existing result directory. It writes:

• image_results.csv: every image, automatic disposition, diagnostics, and image-level aspect ratio;
• field_results.csv: paired-field disposition and accepted primary endpoint;
• summary.json: descriptive statistics across accepted physical fields;
• masks/: exact binary silhouettes, including empty masks for abstentions;
• overlays/: source images with the selected outline;
• foreground_scores/: the operational pixel-intensity maps used by the segmentation procedure; and
• run_manifest.json: resolved profile, claim boundary, and SHA-256 hashes of declared inputs and generated outputs.

See the manifest contract, scientific scope, validation record, capability roadmap, and release-quality gates.

Capability maturity

Capability	Status
Paired-field external-aggregate aspect ratio	Stable v0.1.0; synthetic challenge independently reproduced
Additional size, shape, roughness, texture, or particle-level endpoints	Not implemented

The full blinded challenge corpus and scorer are attached to the v0.1.0 release. Independent public-only reproduction of the frozen validation archive and reported synthetic metrics is documented in the validation record. Future capabilities must have an explicit endpoint, sampling unit, abstention policy, known-truth validation, example data, and tests before being described as validated. A generic repository name does not imply that every conceivable SEM measurement is currently supported.

Development checks

pytest
ruff check .
python -m build
python -m twine check dist/*
python scripts/check_public_release_boundary.py

License

MIT. See LICENSE.

Citation

For results produced with v0.1.0, cite:

Brunaugh, A. (2026). SEM Analysis Pipeline (Version v0.1.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.21845096