PA-NF — Paired-Acquisition Neural Factorization
PA-NF is a paired-acquisition representation-learning model that separates
frozen pathology features into biological and acquisition branches under
scanner-paired supervision. This repository is the trained model artifact; its
supported result is a bounded, dataset- and comparator-specific structured-
separation result, not evidence of pure factors, complete scanner invariance,
clinical utility, or deployment readiness.
The separate
MatthewVaishnav/paired-acquisition-factorization-evidence
repository contains registered metrics, analyses, manifests, and negative
results. This model repository contains the trained PA-NF family and the
preprocessing state required to use it.
Method summary
The release object is the complete registered pathoalign_dep20 family from the
SCORPION capacity-matched campaign: five slide-blocked folds × seeds 801–805 =
25 fixed-final-epoch checkpoints. The campaign had no model-selection rule and
records checkpoint_selection: none; fixed final epoch only. No checkpoint is
called “best,” and published test results must not be used to rank the 25
instances post hoc.
Architecture
Each PyTorch checkpoint contains a 1,550,026-parameter ScorpionProjection with:
- a 768 → 512 → 256 biological projection;
- a 768 → 512 → 64 acquisition projection;
- a 320 → 512 → 768 joint reconstruction decoder;
- five-class scanner heads on both branches;
- the registered contrastive, reconstruction, variance, covariance, scanner-
adversarial, acquisition-scanner, scanner-dependence, and cross-covariance
objectives.
The exact architecture is distributed as scorpion_pathoalign.py. Biological
and acquisition latent dimensions are 256 and 64; the hidden dimension is 512.
Intended use
- reproduce the registered SCORPION PA-NF projections with a matching fold and
seed;
- audit checkpoint-to-campaign provenance and state-dict identity;
- study paired-acquisition representation behavior on frozen features under a
prespecified research protocol;
- apply all 25 co-equal family members, or choose a fold/seed by a rule specified
independently of the published test outcomes.
Out-of-scope use
Do not use this release for diagnosis, treatment, patient care, clinical or
regulatory decisions, production deployment, or claims of universal scanner
harmonization. Do not select a checkpoint using the registered held-out test
results. The model does not accept raw pathology images.
Training data
The registered campaign used SCORPION v1: 2,400 spatially aligned H&E patches
from 480 regions on 48 original slides, each acquired on five scanners. Folds
are blocked by original slide. Each fold's preprocessing statistics were fit on
all non-test slides in that registered fold.
Inputs were frozen facebook/dinov2-base 768-D features at immutable Hub
revision f9e44c814b77203eaa57a6bdbbd535f21ede1415. The DINOv2 feature archive,
SCORPION images, and image paths are not redistributed here.
Evaluation
On the registered SCORPION structured-separation objective, the full model's
primary scanner-suppression contrast against the equal-capacity two-branch
no-scanner-objectives control was:
full - capacity-matched no-scanner-objectives = -0.3108333333
with fold-aware 95% interval
[-0.3346122449, -0.2857872340]. Average same-region retrieval and worst-pair
retrieval were preserved within their registered noninferiority margins, while
the acquisition branch retained strong scanner information.
This is distinct from the corrected canine fixed five-category estimand, where
the neural feature-space representations did not establish an additional
improvement over the strongest simple scanner-removal baselines. The SCORPION
result does not establish universal superiority; the canine result does not
erase the registered SCORPION controlled advantage.
Supported claims
The release supports partial structured separation under the tested paired-
acquisition protocol and a controlled comparative advantage over the registered
equal-capacity two-branch neural control on the SCORPION objective. It supports
reduced linear scanner recoverability in the tissue-oriented branch, preserved
registered same-region retrieval noninferiority, and retained scanner
information in the acquisition branch.
Unsupported claims
This release does not establish pure biological factors, complete scanner
invariance, complete disentanglement, information-theoretic independence,
universal superiority, diagnostic improvement, clinical utility, patient
benefit, deployment readiness, or regulatory readiness.
Limitations
The model was trained on one small scanner-paired dataset and one frozen feature
contract. Its outputs depend on the exact DINOv2 representation and fold-specific
standardization. Scanner labels were used during training for the scanner
objectives, but are not required by the forward pass at inference. Broader human-
tissue, site, device, backbone, and task validation is not supplied by these
checkpoints.
Provenance
- training source commit:
0adea50f1ef22865969109f1834a3c175e3f8b43;
- model definition:
src/models/scorpion_pathoalign.py at SHA256
528b653459bbdb759c5ca414cf434cf0ad54fba1ef6cbc98e6968c235a3c799f;
- campaign config hash:
59ba04450adf738aa2983dc40ecb4ff09ffa495f13d43c56edde5ec57707a2e1;
- evidence dataset revision:
a9853bd32e3b446a97608002f7e5ea12f68f88e1;
- source repository:
https://github.com/matthewvaishnav/computational-pathology-research.
model-manifest.json binds every fold, seed, run ID, checkpoint SHA256, source
cell-manifest SHA256, preprocessing SHA256, config, and state-dict validation.
checksums.sha256 covers the complete released folder. The immutable model Hub
revision is recorded only after upload, redownload, and checksum verification.
Citation
Please cite the repository
CITATION.cff, the PA-NF foundations manuscript, the
SCORPION dataset, and
DINOv2. The evidence repository carries the
registered result and analysis provenance.
License
The PA-NF model release, including the 25 released checkpoints and the
researcher-authored release-specific source/inference code distributed with the
model package, is licensed under the Apache License 2.0. See the bundled
LICENSE file. The Hugging Face model card therefore uses license: apache-2.0.
The frozen facebook/dinov2-base feature archive and SCORPION source images are
not redistributed in this model repository. Those third-party artifacts retain
their own upstream terms; this release does not relicense them.
Reproducibility
The checkpoint alone is not sufficient. Use the matching
preprocessing/fold_X_standardization.npz, which contains 1 × 768 float32
mean and std arrays fit on that fold's non-test slides.
1from pathlib import Path
2import numpy as np
3
4from inference import load_panf, project_features
5
6root = Path(".")
7# Example coordinate only; fold 0 / seed 801 is not designated as the best model.
8model, mean, std, identity = load_panf(root, fold=0, seed=801)
9raw_dinov2_features = np.load("my_compatible_features.npy")
10outputs = project_features(model, raw_dinov2_features, mean, std)
11biological = outputs["biological"] # [n, 256]
12acquisition = outputs["acquisition"] # [n, 64]
Before use, verify the package and all 25 checkpoint contents:
1python tools/huggingface/panf_model_bundle.py verify --bundle build/huggingface/paired-acquisition-neural-factorization
2python tools/huggingface/release.py verify-local build/huggingface/paired-acquisition-neural-factorization
Scanner labels are required to reproduce the registered training objectives;
they are not inputs to the trained projection at inference.
