┌────────────────────────────────────────────────────────┐
│  FEATRANKER  [ FEATURE RANKING TERMINAL ]              │
├────────────────────────────────────────────────────────┤
│  > MODEL ARRAY ............... 40 UNITS      [ OK ]    │
│  > SEPARATE EVAL SET ......... REQUIRED      [ OK ]    │
│  > DUMMY BASELINE GATE ....... ARMED         [ OK ]    │
│  > RANK CONSENSUS ............ ONLINE        [ OK ]    │
├────────────────────────────────────────────────────────┤
│  READY._                                               │
└────────────────────────────────────────────────────────┘

FeatRanker trains a set of estimators on explicit training data, measures permutation importance on separate evaluation data, and combines each model's ranking into a single consensus. It is built for ML workflows where leakage control, semantic feature groups, and model failures must stay visible.

▍ Why FeatRanker?

Ships with 40 built-in models (22 classification, 18 regression), or bring your own scikit-learn estimators and pipelines.

▍ 01 · Install

pip install featranker

Requires Python ≥ 3.10. Optional extras: featranker[xgboost], [lightgbm], [catboost], or [all].

▍ 02 · Quick start

The caller owns splitting and preprocessing. Fit on training data, then rank on a separate evaluation set. This example runs as is:

from sklearn.datasets import load_diabetes
from sklearn.model_selection import train_test_split

from featranker import FeatureRanker

data = load_diabetes()
X_train, X_eval, y_train, y_eval = train_test_split(
    data.data, data.target, test_size=0.3, random_state=0
)

ranker = FeatureRanker(task="reg", group="tree")
ranker.fit(X_train, y_train, feature_names=list(data.feature_names))

report = ranker.rank_features(
    X_eval,
    y_eval,
    scoring="neg_mean_absolute_error",
    feature_groups={"serum": ["s1", "s2", "s3", "s4", "s5", "s6"]},
    random_state=42,
)

for row in report["consensus"]:
    print(f"{row['feature_group']:>6}  median rank {row['median_rank']:.1f}  ({row['n_models']} models)")

 serum  median rank 1.0  (7 models)
   bmi  median rank 2.0  (7 models)
    bp  median rank 3.0  (7 models)
   sex  median rank 4.0  (7 models)
   age  median rank 5.0  (7 models)

Output shown with the xgboost and catboost extras installed; a core-only install has fewer tree models, so n_models is lower. The six blood-serum columns are ranked as one group. The decision tree scored worse than the dummy baseline, so it stays in the report without a vote. See Reading the report for what to do next.

Or from the command line:

featranker --task reg --train-data train.csv --eval-data eval.csv \
  --target target --scoring neg_mean_absolute_error --output report.json

▍ 03 · How it works

fit()            train every model + a dummy baseline on the training data
rank_features()  score every model on the evaluation data
                 shuffle each feature group n_repeats times, measure the score drop
                 rank the groups within each model
                 models that beat the dummy vote  ->  median / mean rank consensus

For each model, a feature group's importance is how much that model's score drops when the group is shuffled:

importance = model_score - model_score_after_shuffling

Every model uses the same scorer. In the report, the unshuffled score is each model's evaluation_score; baseline_score is the dummy's score, used only for the vote.

Built-in linear models are wrapped in a StandardScaler pipeline fit on training data only; tree models and your own models are used as given.

▍ 04 · Docs

Upgrading from 0.3? The preparation-file workflow was removed in 0.4.0; see the release notes.

▍ Scope

FeatRanker intentionally does not do cross-validation, imputation, feature encoding, automatic feature selection, or SHAP-style attribution. The one target change it makes is encoding classification labels to 0..n_classes-1 internally (see Usage). Results depend on the evaluation sample, scorer, estimators, correlated predictors, and permutation design.

▍ Development

git clone https://github.com/CountZero-Error/Featranker.git
cd Featranker
pip install -e '.[test]'
python -m pytest -q

▍ License

Released under the MIT License.