Metadata-Version: 2.5
Name: featureranker
Version: 3.0.3
Summary: Feature ranking ensemble using L1 paths, random forests, XGBoost, ANOVA F-scores, and mutual information
Project-URL: Repository, https://github.com/lhallee/featureranker
Project-URL: Documentation, https://github.com/lhallee/featureranker/tree/main/docs
Project-URL: Issues, https://github.com/lhallee/featureranker/issues
Project-URL: Changelog, https://github.com/lhallee/featureranker/releases
Author-email: Logan Hallee <lhallee99@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ensemble,feature-ranking,feature-selection,machine-learning,sklearn
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: datasets>=2.19
Requires-Dist: joblib>=1.3
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.1
Requires-Dist: scikit-learn>=1.8
Requires-Dist: scipy>=1.11
Requires-Dist: seaborn>=0.13
Requires-Dist: xgboost>=2.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# featureranker

[![Tests](https://github.com/lhallee/featureranker/actions/workflows/tests.yml/badge.svg)](https://github.com/lhallee/featureranker/actions/workflows/tests.yml)
[![PyPI](https://img.shields.io/pypi/v/featureranker)](https://pypi.org/project/featureranker/)

Ensemble feature ranking for any numeric feature matrix: tabular datasets,
transformer embeddings, pooled hidden states, engineered features. Five
methods rank every feature, a typed result object holds the evidence, and
weighted rank voting produces one consensus ordering, for classification and
regression. Unnamed matrices work directly: pass a numpy array and features
get stable generated IDs.

Featured in:

- [Machine learning classifiers predict key genomic and evolutionary traits across the kingdoms of life](https://www.nature.com/articles/s41598-023-28965-7) (Nature Scientific Reports, 2023)
- [cdsBERT - Extending Protein Language Models with Codon Awareness](https://www.biorxiv.org/content/10.1101/2023.09.15.558027v1.abstract) (bioRxiv, 2023)

## Installation

```bash
pip install featureranker
```

Requires Python >= 3.11.

## Quick start

```python
from sklearn.datasets import load_breast_cancer
from featureranker import feature_ranking, voting, plot_rankings, plot_after_vote

cancer = load_breast_cancer(as_frame=True)
result = feature_ranking(cancer.data, cancer.target, task="classification")

vote_table = voting(result)                # ["feature", "score"], best first
plot_rankings(result, top_n=15)            # per-method ranks as a dot plot
plot_after_vote(vote_table, top_n=15)      # consensus scores
```

`feature_ranking` returns a `RankingResult` with per-method ranking tables,
rank and score matrices, diagnostics, and save/load. Results are
deterministic for a given `random_state` at any `n_jobs`.

## Hugging Face datasets

Pass a Hub path, name the label column, list what to exclude; the rest
become features. Categorical columns one-hot expand into named sub-features
(`sex-Female`, `workclass-Private`) by default.

```python
from featureranker import feature_ranking, get_hf_data

X, y = get_hf_data(
    "scikit-learn/adult-census-income",
    target="income",
    columns_to_drop=["fnlwgt"],
)
result = feature_ranking(X, y, task="classification")
```

## One score from the best features

`fit_convex` finds the optimal convex combination of the top consensus
features: weights >= 0 that sum to one, so each weight is that feature's
share of a single interpretable scoring function.

```python
fit = result.fit_convex(X, y, top_n=10)
fit.table()               # ["feature", "weight"], largest first
scores = fit.predict(X)   # rank rows by the combined score
```

## Ranking methods

| Key | Method | Score |
|-----|--------|-------|
| `rf` | Random forest | Impurity importance from a halving-search-tuned forest |
| `xg` | XGBoost | Gain importance from a halving-search-tuned booster |
| `mi` | Mutual information | kNN-estimated dependency with the target |
| `f_test` | ANOVA F-test | Between/within variance ratio |
| `l1` | L1 regularization path | Entry point on the lasso / L1 logistic path |

## Examples and the selection-vs-reduction study

20 datasets (transformer embeddings, classical NLP feature spaces, pixels,
molecules, sensors) each run the same ablation: every ranking method and
the ensemble vote as selectors against PCA, ICA, random projection, kernel
PCA, Isomap, UMAP, and t-SNE at matched budgets, scored by linear, kNN,
and SVM probes. Findings: [the research report](docs/examples/report.md).
Per-dataset pages live in [docs/examples/](docs/examples/), regenerated by
the scripts in [examples/](examples/); the
[ModernBERT sentiment deep dive](docs/examples/modernbert_sentiment.md)
walks the methodology on unnamed transformer dimensions.

![Feature ranks by method on breast cancer](docs/images/breast_cancer_rankings.png)

## Documentation

| Topic | Page |
|---|---|
| Install and first run | [docs/quickstart.md](docs/quickstart.md) |
| The math behind each method and the voting schemes | [docs/algorithms.md](docs/algorithms.md) |
| Speed, the n_jobs core budget, determinism | [docs/performance.md](docs/performance.md) |
| Every signature and exception | [docs/api.md](docs/api.md) |
| Upgrading from v2 | [docs/migration_v2_to_v3.md](docs/migration_v2_to_v3.md) |
| Development and releases | [docs/contributing.md](docs/contributing.md) |

The [example notebook](example_usage.ipynb) walks through classification and
regression end to end.

## Development

```bash
git clone https://github.com/lhallee/featureranker.git
cd featureranker
pip install -e ".[dev]"
pytest
```

## Citation

```bibtex
@article{Hallee2023,
  title = {Machine learning classifiers predict key genomic and evolutionary traits across the kingdoms of life},
  volume = {13},
  ISSN = {2045-2322},
  url = {http://dx.doi.org/10.1038/s41598-023-28965-7},
  DOI = {10.1038/s41598-023-28965-7},
  number = {1},
  journal = {Scientific Reports},
  publisher = {Springer Science and Business Media LLC},
  author = {Hallee, Logan and Khomtchouk, Bohdan B.},
  year = {2023},
  month = feb
}
```

```bibtex
@article{Hallee2023cds,
  title = {cdsBERT - Extending Protein Language Models with Codon Awareness},
  url = {http://dx.doi.org/10.1101/2023.09.15.558027},
  DOI = {10.1101/2023.09.15.558027},
  publisher = {Cold Spring Harbor Laboratory},
  author = {Hallee, Logan and Rafailidis, Nikolaos and Gleghorn, Jason P.},
  year = {2023},
  month = sep
}
```

## License

MIT
