Skip to content

Feature Selection API Reference

The kreview.selection module scores features and applies the selection strategies — mRMR, hybrid union, and the GrootCV/Leshy family from arfs that became the multimodal default in #96. It also owns build_binary_target, the single definition of which label tiers form the positive and negative classes.

For conceptual explanations, see:

kreview.selection

Shared feature scoring and selection library (mRMR / hybrid-union).

Docs: https://msk-access.github.io/kreview/selection.html.md

__all__ = ['log', 'MODEL_LABELS', 'POSITIVE_LABELS', 'build_binary_target', 'score_features', 'select_features'] module-attribute

Feature scoring and selection for kreview.

Provides shared functions used by both kreview run (monolithic) and kreview select (standalone CLI) to ensure identical feature selection logic across all execution modes.

Two public functions:

  • :func:score_features — compute univariate AUC, mutual information, and statistical tests (KW, Cohen's d) for every numeric feature column.
  • :func:select_features — apply mRMR (default) or hybrid-union selection with a zero-variance guard.

build_binary_target(df, label_col='label')

Filter to modelable samples and build a binary target vector.

Keeps only samples whose label is in the canonical 5-tier model set (True ctDNA+, Possible ctDNA+, Healthy Normal, Possible ctDNA-/−). Returns a binary target: 1 for positives, 0 for negatives.

Parameters:

Name Type Description Default
df DataFrame

DataFrame with a label column.

 required
label_col str

Name of the label column.

 'label'

Returns:

Type Description
DataFrame

(model_df, y) where model_df contains only samples with
ndarray

labels in MODEL_LABELS and y is a binary numpy array.

Raises:

Type Description
ValueError

If fewer than 20 samples remain or only one class is present (models cannot train).

score_features(matrix_df, *, label_col='label', cv_folds=5, compute_auc=True, random_state=42)

Score every numeric feature by statistical tests, univariate AUC, and MI.

Computes per-feature:

  • Statistical tests via :func:evaluate_feature: Kruskal-Wallis, Cohen's d, group medians, etc.
  • Univariate AUC (optional): Cross-validated logistic regression AUC per feature.
  • Mutual information: Quantifies non-linear dependency between feature and binary target.

Parameters:

Name Type Description Default
matrix_df DataFrame

DataFrame from kreview extract containing LABEL_META_COLS metadata columns and numeric feature columns.

 required
label_col str

Name of the label column (default "label").

 'label'
cv_folds int

Number of folds for univariate AUC cross-validation.

 5
compute_auc bool

If False, skip univariate AUC (selection degrades to MI-only).

 True

Returns:

Type Description
DataFrame

DataFrame with one row per feature and columns including
DataFrame

feature_column, univariate_auc, mutual_info, plus all
DataFrame

columns from :func:evaluate_feature.

Raises:

Type Description
ValueError

If no numeric feature columns found, or insufficient samples for scoring.

select_features(matrix_df, eval_stats, *, top_percentile=50.0, impute_strategy='median', label_col='label', strategy='mrmr')

Apply feature selection and return a filtered matrix.

Strategies: - 'mrmr': Minimum Redundancy Maximum Relevance (redundancy-aware) - 'hybrid_union': Top N% AUC ∪ Top N% MI (legacy)

Selection algorithm (mRMR):

  1. Compute n_keep = max(1, n_features × top_percentile / 100).
  2. Impute NaNs using impute_strategy.
  3. Apply mRMR to select top n_keep features.
  4. Variance guard: drop zero-variance features.
  5. Return the matrix with only LABEL_META_COLS + selected features.

Selection algorithm (hybrid_union):

  1. Compute n_keep = max(1, n_features × top_percentile / 100).
  2. Take top n_keep features by univariate_auc (if present).
  3. Take top n_keep features by mutual_info (if present).
  4. Union both sets — captures linear (AUC) and non-linear (MI) signal.
  5. Variance guard: impute + drop zero-variance features.
  6. Return the matrix with only LABEL_META_COLS + selected features.

Parameters:

Name Type Description Default
matrix_df DataFrame

Full matrix DataFrame from kreview extract.

 required
eval_stats DataFrame

Feature scoring DataFrame from :func:score_features.

 required
top_percentile float

Top N% per metric to keep (default 50).

 50.0
impute_strategy str

Strategy for NaN imputation before variance check.

 'median'
label_col str

Name of the label column.

 'label'
strategy str

Feature selection strategy ('mrmr' or 'hybrid_union').

 'mrmr'

Returns:

Type Description
DataFrame

Tuple of (selected_matrix_df, selection_qc_dict):
dict
  • selected_matrix_df: DataFrame with metadata + selected features.
tuple[DataFrame, dict]
  • selection_qc_dict: Audit trail with counts and method metadata.

Raises:

Type Description
ValueError

If all features are constant after selection (nothing to model).