AAPred.score_to_group

static AAPred.score_to_group(scores, thresholds, labels, *, score_range='percent')[source]

Map prediction scores to an ordered categorical of named confidence groups.

A stateless classifier that turns continuous scores into human-readable, ordered bands (e.g. "low" < "medium" < "high"): thresholds delimit the bands and labels names them from the lowest to the highest scores. Each threshold is an inclusive lower bound, so a score equal to a threshold falls in the band above it (right-open bands [t_{i-1}, t_i)); a score below the first threshold takes the first label and a score at or above the last threshold the last label. This is the single source of truth for the band boundaries also used by AAPredPlot.predict_group() (band=True), so a table, a filter, and the plotted colouring always agree.

Added in version 1.1.0.

Parameters:

  • scores (array-like, shape (n_samples,)) – Per-sample prediction scores to classify. A pd.Series keeps its index; NaN scores are preserved as missing (unassigned) groups.

  • thresholds (list of int or float) – Band boundaries in strictly increasing order, each an inclusive lower bound. n thresholds define n + 1 bands and must lie within the score_range bounds.

  • labels (list of str) – One name per band, ordered from the lowest-score band to the highest; length must be len(thresholds) + 1 and the names must be unique. Sets the category order of the returned series.

  • score_range (str, default="percent") – Numeric range the scores and thresholds live on: 'percent' ([0, 100]) or 'proba' ([0, 1]). Thresholds outside the range raise, which rejects silently mixing probabilities and percentages.

Returns:

group – Ordered categorical (pd.Categorical, ordered=True) row-aligned with scores (index preserved), whose categories are labels in the given low-to-high order. NaN input scores map to missing values.

Return type:

pd.Series

See also

Examples

AAPred.score_to_group() is a stateless helper that maps continuous prediction scores to an ordered categorical of named confidence bands. thresholds delimit the bands and labels names them from the lowest to the highest scores; each threshold is an inclusive lower bound, so a score equal to a threshold falls in the band above it. It is the single source of truth for the same bands drawn by :meth:AAPredPlot.predict_group (band=True), so a table and its plot always agree.

import aaanalysis as aa
aa.options["verbose"] = False  # Disable verbosity

# DOM_GSEC example dataset + its feature set (see [Breimann25]_)
df_seq = aa.load_dataset(name="DOM_GSEC")
labels = df_seq["label"].to_list()
df_feat = aa.load_features(name="DOM_GSEC").head(20)

# Build the CPP feature matrix and cross-validated out-of-fold scores
sf = aa.SequenceFeature()
df_parts = sf.get_df_parts(df_seq=df_seq)
X = sf.feature_matrix(features=df_feat["feature"], df_parts=df_parts)
aap = aa.AAPred(models=["rf", "extra_trees"], random_state=42)
df_pred = aap.predict_oof(X, labels)

Pass the scores together with thresholds and one more labels name than thresholds. Here percent scores (0-100) are split into three bands; the returned series is row-aligned with the scores and its categories keep the low-to-high order:

scores = df_pred["score"] * 100  # percent scale
groups = aa.AAPred.score_to_group(scores, thresholds=[50, 80], labels=["low", "medium", "high"])
df_groups = df_seq[["entry"]].assign(score=scores.round(1).values, group=groups.values)
aa.display_df(df_groups, n_rows=10, show_shape=True)

DataFrame shape: (126, 3)
  entry score group
1 P05067 80.000000 high
2 P14925 87.000000 high
3 P70180 89.500000 high
4 Q03157 93.500000 high
5 Q06481 98.500000 high
6 P35613 87.000000 high
7 P35070 7.500000 low
8 P09803 94.000000 high
9 P19022 96.000000 high
10 P16070 82.500000 high

score_range selects the numeric scale that thresholds must lie within: 'percent' ([0, 100], the default) or 'proba' ([0, 1]). Thresholds outside the range raise, so probabilities and percentages can’t be silently mixed. Scoring the raw [0, 1] probabilities on the 'proba' scale gives the same banding:

groups_proba = aa.AAPred.score_to_group(df_pred["score"], thresholds=[0.5, 0.8],
                                        labels=["low", "medium", "high"], score_range="proba")
df_counts = groups_proba.value_counts(sort=False).rename_axis("group").reset_index(name="n_proteins")
aa.display_df(df_counts, n_rows=10, show_shape=True)

DataFrame shape: (3, 2)
  group n_proteins
1 low 61
2 medium 35
3 high 30