deep-lamella-masking

UNet release candidate model card

This card describes the selected checkpoint for the planned v0.9 release. The package is still version 0.8; release-tag metrics and clean-room inference are pending. The checkpoint is distributed at Jonwagner/deep-lamella-masking. Checkpoint verification was performed on 2026-09-06; the release preparation is merged into software commit 50b208b315a0a1ddc70c25ed58e34de3a7d48fa8.

Intended use

Segment lamellae in cryo-electron tomography volumes and optionally fit two boundary planes to produce a slab mask. Inputs are raw MRC tomograms or manifest-selected preprocessed Zarr volumes. Outputs include probabilities, slab masks, geometry, and quality-control reports. Flagged fits can be inspected and corrected with dlm review.

Checkpoint and architecture

The artifact is a metadata export of best-epoch=1339-val/dice=0.969.ckpt from four_arch_20260512_222124/train_20260512_222124_unet_bs8. The handover records that all 63 state-dict tensors match the source. Its v1 source did not record architecture kwargs: these were inferred from registry defaults during export and verified by rebuilding the model and loading the weights. They are not a contemporaneous training record. CPU model rebuild, weight loading, and the exported file hash were rechecked on 2026-09-06.

Preprocessing and prediction

The checkpoint owns patch size and target pixel size. Raw MRC inputs are resampled and normalized to zero mean and unit variance. Canonical Zarr inputs follow the same normalized, rescaled, unpadded model-input contract; training storage padding is removed. Resampling uses the version-1 align_corners=True convention. Spatial metadata must be valid; supplying a volume with unknown pixel size does not establish this contract.

The current prediction configuration uses 50% patch overlap and Gaussian blending. Plane fitting uses component gating and coverage targeting; its defaults and selection history are documented in post-processing provenance. Thickness is the median of a footprint-scoped spatial map, with within-volume IQR.

With the selected artifact placed in models/, inspect and predict using:

uv run dlm inspect-checkpoint models/unet_best_20260512_valdice0.969_v2.ckpt
uv run dlm predict \
  --input-dir /path/to/unseen_tomograms \
  --output-dir prediction_results \
  --checkpoint models/unet_best_20260512_valdice0.969_v2.ckpt \
  inference.device_ids=[0]
uv run dlm review prediction_results --flagged-only

Download the checkpoint from the public Hugging Face repository, pinned to the verified artifact revision:

uv run dlm download-weights --model unet \
  --repo-id Jonwagner/deep-lamella-masking \
  --revision 0fe6cacd88623ab0521c4aca8ce2b55ea0f8982d

This prints the cached checkpoint path to pass to --checkpoint. The command requests the schema-v2 filename above. The Hub repository includes its SHA-256 in SHA256SUMS. On 2026-09-06, the default CLI downloaded this revision without account authentication into a fresh cache; the file matched the SHA-256 above and passed checkpoint inspection. This verifies distribution, not the pending clean-machine raw-tomogram inference run.

Data and evaluation

The retained experiment provenance identifies manifest_80_10_10.json with 1,752 training, 218 validation, and 228 test volumes. Dataset descriptions, the distributable manifest location/hash still need owner confirmation. dataset_6 stays in validation and test under the existing split assignments; see the dataset note. These counts are historical provenance, not a fresh audit of the release data.

The checkpoint filename's 0.969 is the rounded training-run validation selection metric. It is not a release-tag whole-volume slab Dice score. The historical canonical post-processing experiments reported test mean slab Dice of 0.9614; see the experiment provenance for its scope and accounting. Earlier padded-frame results are not comparable to canonical unpadded inference.

The current test split influenced method selection. Its results must not be presented as an unbiased generalization estimate. Re-deriving the final trim and coverage settings on training data does not undo the earlier use of test data. An untouched split is deferred until an unbiased claim is needed (N17).

External-tomogram evidence is qualitative unless annotations and quantitative evaluation are supplied. Training reproducibility is statistical; bit-for-bit equivalence is not promised.

Known limitations

• Boundary planes can be offset from the segmented body even when mutually parallel. Wedge-shaped or poorly fitted surfaces can also produce inaccurate slab masks.
• QC flags are heuristics. Their historical poor-fit detection sample was small, and an unflagged result is not proof of correctness. See QC policy.
• Historical canonical runs had one validation and three test input failures caused by absent pixel-size metadata. Release evaluation must count failures explicitly.
• dataset_6 reference masks deliberately exclude particles denatured at the air–water interface (data-owner explanation). The owner considers the predicted lamella masks geometrically appropriate, but they do not necessarily reproduce that particle-selection boundary. Keep the low-scoring examples and their metrics; 3dmod comparisons remain pending and will illustrate this difference rather than replace quantitative evaluation.

Publication record still to complete

Record the release tag and clean Git SHA, package version, final checkpoint hash, resolved training/inference configs, manifest hash and split counts, Python/Torch/CUDA/ driver/GPU tuple, and verification date against the exact published artifacts. The software is MIT licensed, copyright Jonathan Wagner, with the laboratory and funding acknowledgements supplied by the owner. Authors are Jonathan Wagner ([email protected]) and Hippoly Ritter; Hippoly's contact details and contribution statement remain an active placeholder. The owner has approved shipping concise benchmark code and compact results; full public reproduction also requires the data and annotations to be deposited on EMPIAR or a similar archive. Track completion in the release checklist.