Publish 2026_W32_Cosmos_guiltless-orange-mallard

README.md

@@ -25,14 +25,18 @@ feature release `2026_W32`.
 
 ```python
 import pandas as pd
-from ephysatlas.regionclassifier import RegionClassifier
+from ephysatlas import load_pretrained
 
-clf = RegionClassifier.from_pretrained("int-brain-lab/ea-decoder-channel-xgboost", revision="2026_W32")
+model = load_pretrained("int-brain-lab/ea-decoder-channel-xgboost", revision="2026_W32")
 df = pd.read_parquet("example/features_sample.parquet")   # or your own features
-out = clf.predict(df)
+out = model.predict(df)
 print(out[["predicted_acronym", "prediction_probability", "fold_agreement"]].head())
 ```
 
+`load_pretrained` is the entry point for every ephysatlas model, whatever its family — it reads
+`ephysatlas_model.json` and returns the right wrapper. Use it rather than importing a concrete
+class, so your code keeps working as the package evolves.
+
 `predict` returns one row per input channel, indexed identically to the input:
 `predicted_acronym`, its Allen `predicted_atlas_id`, the fold-averaged
 `prediction_probability`, a `fold_agreement` column (fraction of the 5 folds voting
@@ -51,7 +55,7 @@ carries histology-derived `acronym` / `atlas_id` columns, and predictions must n
   as loaded by `ephysatlas.data.read_features_from_disk`. Units are baked into that table by
   the pipeline (RMS features in dB, `spike_count` in log2), so feeding raw features, or
   features from a vintage whose units differ, produces confident nonsense. Run
-  `clf.selftest()` to confirm your install reproduces the shipped output before trusting it.
+  `model.selftest()` to confirm your install reproduces the shipped output before trusting it.
 
 ## Performance
 
@@ -70,11 +74,15 @@ insertion appears in training. See `confusion_matrix.png`.
 
 ## Reproducibility
 
+**Pin the revision.** `revision="2026_W32"` is an immutable tag. Omitting `revision` resolves
+to `main`, which tracks whichever model is currently recommended and *will* change when a new
+feature vintage is published — fine for a first look, not for anything you publish or re-run.
+
 `ephysatlas_model.json` records the training-time `environment` (xgboost, scikit-learn, numpy,
 ephysatlas, python) and `random_seed`. Verify your install reproduces the shipped output:
 
 ```python
-clf.selftest()
+model.selftest()
 ```
 
 Note `scikit-learn<1.9` is required (1.9 broke `OneToOneFeatureMixin.get_feature_names_out`,