SequenceFeature.get_labels_quantile

static SequenceFeature.get_labels_quantile(targets, q=0.5, label_test=1, label_ref=0)

Convert a continuous target into a binary label array by a single quantile threshold.

Splits samples at the q-quantile of targets: samples at or above the cut become the test group and the remainder the reference group. No samples are dropped, so the result is directly usable as the labels argument of CPP.run() / CPP.run_num(), enabling regression-style tasks (e.g. thermostability, binding affinity) within the binary CPP framework. For a fixed positive set with stepwise-lowered negative cuts, use get_labels_tiered().

Added in version 1.1.0.

Parameters:

• targets (array-like, shape (n_samples,)) – Continuous target values for samples.

• q (float, default=0.5) – Quantile in the open interval (0, 1) defining the split threshold (0.5 splits at the median).

• label_test (int, default=1) – Value assigned to samples at or above the threshold.

• label_ref (int, default=0) – Value assigned to samples below the threshold.

Returns:

labels – Binary label array.

Return type:

np.ndarray, shape (n_samples,)

Notes

• Targets are converted to float64. Raises ValueError up front if the split would yield only one class (constant targets, or a cut leaving one side empty), instead of failing later inside CPP.run().

• Complexity: O(n_samples log n_samples) from the quantile, negligible beside CPP runtime.

See also

• aaanalysis.CPP: consumes the returned binary label array via CPP.run().

• get_labels_tiered(): fixed positive set vs stepwise-lowered negative cuts.

Examples

get_labels_quantile discretizes a continuous target into a binary label array at a single quantile cut (default median): samples at or above the cut are the test group. This bridges regression-style targets (thermostability, binding affinity) into the binary CPP framework:

import numpy as np
import aaanalysis as aa

targets = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]
aa.SequenceFeature.get_labels_quantile(targets, q=0.5)

array([0, 0, 0, 1, 1, 1])

Use the labels directly with CPP.run:

df_seq = aa.load_dataset(name="DOM_GSEC", n=8)
sf = aa.SequenceFeature()
df_parts = sf.get_df_parts(df_seq=df_seq)

labels = aa.SequenceFeature.get_labels_quantile(np.linspace(0, 1, len(df_parts)), q=0.5)
aa.CPP(df_parts=df_parts).run(labels=labels, n_filter=4)[["feature", "abs_auc"]].head()

1. CPP creates 580140 features for 16 samples
1.1 Assigning scale values to parts
   |.........................| 100.0%
1.2 Streaming pre-filter stats (mask in stream)
   |.........................| 100.0%
2. CPP pre-filters 29007 features (5.0%) with highest 'abs_mean_dif' and 'max_std_test' <= 0.2 (kept=517501 of 580140)
3. CPP filtering algorithm
4. CPP returns df of 4 unique features with general information and statistics

	feature	abs_auc
0	TMD-Pattern(C,4,8)-NAKH900112	0.5
1	TMD_C_JMD_C-Pattern(N,4,8)-NAKH900112	0.5
2	TMD-Pattern(C,4,8)-AURR980114	0.5
3	TMD_C_JMD_C-Pattern(N,4,8)-AURR980114	0.5

What can go wrong? A constant target (or a cut that leaves one side empty) yields a single class and is rejected up front:

try:
    aa.SequenceFeature.get_labels_quantile([5.0, 5.0, 5.0], q=0.5)
except ValueError as e:
    print("ValueError:", e)

ValueError: 'targets' produce a single class at q=0.5 (all values equal, or the cut leaves one side empty); adjust 'q' or 'targets'.

Further parameters. label_test / label_ref set the integer values assigned to the at-or-above-cut (test) and below-cut (reference) groups:

labels_q = aa.SequenceFeature.get_labels_quantile([1.0, 2.0, 3.0, 4.0], q=0.5,
                                                  label_test=1, label_ref=0)
print(labels_q)

[0 0 1 1]