regionclassifier.RegionClassifier

regionclassifier.RegionClassifier(path_model, index=None)

A trained region classifier, ready to predict on a features DataFrame.

Wraps the fold models and the ephysatlas_model.json manifest so that a caller needs neither iblatlas to read the output nor prior knowledge of the feature list.

Example: >>> clf = RegionClassifier.from_pretrained(‘int-brain-lab/ea-decoder-channel-xgboost’) >>> out = clf.predict(df_features) >>> out.head()

Attributes: path_model (Path): Local model directory. index (dict): Contents of ephysatlas_model.json (the publication manifest). config (dict): The manifest’s task-specific config block – class ids, acronyms, region map and accuracy. inputs (dict): The manifest’s inputs block – row identity and feature list.

Methods

Name	Description
from_pretrained	Fetch a model by id and return a ready-to-use classifier.
predict	Predict a brain region per channel.
selftest	Reproduce the shipped golden predictions, if the model ships an example.

from_pretrained

regionclassifier.RegionClassifier.from_pretrained(
    model_id,
    revision=None,
    cache_dir=None,
)

Fetch a model by id and return a ready-to-use classifier.

Args: model_id (str): Hugging Face org/repo. revision (str, optional): Hugging Face branch/tag to pin. cache_dir (Path, optional): Download location.

Returns: RegionClassifier: Classifier backed by the downloaded directory.

predict

regionclassifier.RegionClassifier.predict(
    df,
    denoise=False,
    estimator='ensemble',
)

Predict a brain region per channel.

Args: df (pd.DataFrame): Features, indexed by (pid, channel). Must contain every column listed in the manifest’s features. denoise (bool, optional): Apply :func:ephysatlas.features.denoise_dataframe first. Leave False if df already holds denoised features. estimator (str, optional): Which weights to use.

    * ``"ensemble"`` (default) -- average the per-fold models. Slightly better
      calibrated, and the only mode that yields a meaningful ``fold_agreement``.
    * ``"global"`` -- the single model trained on all channels. One fifth of the
      inference cost; ``fold_agreement`` comes back as NaN because no folds were
      consulted.

    The two disagree on a small fraction of channels, so do not mix them within
    one analysis.

Returns: pd.DataFrame: Indexed like df, with columns predicted_acronym, predicted_atlas_id, prediction_probability (fold-averaged probability of the winning class), fold_agreement (fraction of folds voting for the winner), and one p_<acronym> column per class holding the fold-averaged probability.

The prediction columns are deliberately namespaced: both the channel feature
table and the cluster table already carry histology-derived ``acronym`` and
``atlas_id`` columns, so bare names would collide on ``df.join(out)`` and would
silently overwrite ground truth on assignment.

Raises: KeyError: If any required feature column is absent, naming the missing ones. ValueError: If the manifest’s inputs.features no longer matches its recorded order digest, i.e. the published feature list has been edited or reordered.

selftest

regionclassifier.RegionClassifier.selftest(rtol=1e-05)

Reproduce the shipped golden predictions, if the model ships an example.

Converts silent numerical drift (changed transforms, an incompatible xgboost, a reordered class vector) into one explicit failure.

Args: rtol (float, optional): Relative tolerance on the probability comparison.

Returns: bool: True when the recomputed predictions match the shipped ones.

Raises: FileNotFoundError: If the model does not ship example/ files. AssertionError: If the predictions differ.