evo-gafs 0.1.0__tar.gz

evo_gafs-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: evo-gafs
+Version: 0.1.0
+Summary: Genetic Algorithm Feature Selector — a scikit-learn-compatible wrapper feature selector for tabular data (evo-suite)
+Author: Axel Skrauba
+License: MIT
+Project-URL: Repository, https://github.com/AxelSkrauba/evo-suite
+Project-URL: Documentation, https://github.com/AxelSkrauba/evo-suite/tree/main/packages/evo-gafs
+Project-URL: Bug Tracker, https://github.com/AxelSkrauba/evo-suite/issues
+Keywords: feature selection,genetic algorithm,DEAP,NSGA-II,machine learning,scikit-learn,wrapper method,evolutionary computation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=1.5
+Requires-Dist: scikit-learn>=1.6
+Requires-Dist: deap>=1.4
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.6; extra == "viz"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: matplotlib>=3.6; extra == "dev"
+
+# evo-gafs — Genetic Algorithm Feature Selector
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
+
+A **scikit-learn-compatible** wrapper feature selector for tabular data, powered
+by [DEAP](https://github.com/DEAP/deap). `evo-gafs` searches for the subset of
+features that maximises a cross-validated score of your model, and lets you
+explicitly trade raw performance for a smaller feature set — useful for edge
+deployment.
+
+Part of the [`evo-suite`](../../README.md) family (import name: `evo_gafs`).
+
+## Why evo-gafs?
+
+| Capability | evo-gafs |
+|------------|----------|
+| Single-objective **weighted** fitness with a configurable `alpha` (performance ↔ compression) | ✓ |
+| **Multi-objective** NSGA-II with an accessible Pareto front | ✓ |
+| **Repair operator** guaranteeing a minimum number of features | ✓ |
+| Evaluation **cache** to skip repeated genomes | ✓ |
+| Native scikit-learn `fit`/`transform`/`get_support`, usable in a `Pipeline` | ✓ |
+| Built-in multi-dataset `BenchmarkRunner` | ✓ |
+
+## Installation
+
+```bash
+pip install evo-gafs            # core
+pip install evo-gafs[viz]       # + matplotlib for the plotting helpers
+```
+
+## Quickstart
+
+```python
+from sklearn.datasets import load_breast_cancer
+from sklearn.tree import DecisionTreeClassifier
+from evo_gafs import GAFeatureSelector, GAConfig
+
+X, y = load_breast_cancer(return_X_y=True, as_frame=True)
+
+selector = GAFeatureSelector(
+    estimator=DecisionTreeClassifier(random_state=42),
+    config=GAConfig(population_size=30, n_generations=20, alpha=0.8, verbose=False),
+)
+selector.fit(X, y)
+
+print(selector.summary())
+X_reduced = selector.transform(X)
+print("Selected:", selector.get_support(indices=True))
+```
+
+### Multi-objective (Pareto front)
+
+```python
+config = GAConfig(mode="multiobjective", population_size=40, n_generations=30, verbose=False)
+selector = GAFeatureSelector(estimator=DecisionTreeClassifier(random_state=42), config=config)
+selector.fit(X, y)
+
+for point in selector.result_.pareto_front:
+    print(point["n_features"], point["cv_score"])
+```
+
+### In a scikit-learn pipeline
+
+```python
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import StandardScaler
+from sklearn.svm import SVC
+
+pipe = Pipeline([
+    ("scaler", StandardScaler()),
+    ("selector", GAFeatureSelector(estimator=DecisionTreeClassifier(), config=config)),
+    ("clf", SVC()),
+])
+pipe.fit(X, y)
+```
+
+## The `alpha` trade-off (single-objective)
+
+```
+fitness = alpha * cv_score + (1 - alpha) * compression
+compression = 1 - n_selected / n_total
+```
+
+- `alpha = 1.0` → pure wrapper (performance only)
+- `alpha ≈ 0.7` → balanced, good default for edge deployment
+
+## Citation
+
+```bibtex
+@software{evo_gafs,
+  author    = {Skrauba, Axel},
+  title     = {evo-gafs: Genetic Algorithm Feature Selector for tabular data},
+  year      = {2026},
+  version   = {0.1.0},
+  url       = {https://github.com/AxelSkrauba/evo-suite}
+}
+```
+
+## License
+
+[MIT](../../LICENSE)

evo_gafs-0.1.0/README.md

@@ -0,0 +1,101 @@
+# evo-gafs — Genetic Algorithm Feature Selector
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
+
+A **scikit-learn-compatible** wrapper feature selector for tabular data, powered
+by [DEAP](https://github.com/DEAP/deap). `evo-gafs` searches for the subset of
+features that maximises a cross-validated score of your model, and lets you
+explicitly trade raw performance for a smaller feature set — useful for edge
+deployment.
+
+Part of the [`evo-suite`](../../README.md) family (import name: `evo_gafs`).
+
+## Why evo-gafs?
+
+| Capability | evo-gafs |
+|------------|----------|
+| Single-objective **weighted** fitness with a configurable `alpha` (performance ↔ compression) | ✓ |
+| **Multi-objective** NSGA-II with an accessible Pareto front | ✓ |
+| **Repair operator** guaranteeing a minimum number of features | ✓ |
+| Evaluation **cache** to skip repeated genomes | ✓ |
+| Native scikit-learn `fit`/`transform`/`get_support`, usable in a `Pipeline` | ✓ |
+| Built-in multi-dataset `BenchmarkRunner` | ✓ |
+
+## Installation
+
+```bash
+pip install evo-gafs            # core
+pip install evo-gafs[viz]       # + matplotlib for the plotting helpers
+```
+
+## Quickstart
+
+```python
+from sklearn.datasets import load_breast_cancer
+from sklearn.tree import DecisionTreeClassifier
+from evo_gafs import GAFeatureSelector, GAConfig
+
+X, y = load_breast_cancer(return_X_y=True, as_frame=True)
+
+selector = GAFeatureSelector(
+    estimator=DecisionTreeClassifier(random_state=42),
+    config=GAConfig(population_size=30, n_generations=20, alpha=0.8, verbose=False),
+)
+selector.fit(X, y)
+
+print(selector.summary())
+X_reduced = selector.transform(X)
+print("Selected:", selector.get_support(indices=True))
+```
+
+### Multi-objective (Pareto front)
+
+```python
+config = GAConfig(mode="multiobjective", population_size=40, n_generations=30, verbose=False)
+selector = GAFeatureSelector(estimator=DecisionTreeClassifier(random_state=42), config=config)
+selector.fit(X, y)
+
+for point in selector.result_.pareto_front:
+    print(point["n_features"], point["cv_score"])
+```
+
+### In a scikit-learn pipeline
+
+```python
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import StandardScaler
+from sklearn.svm import SVC
+
+pipe = Pipeline([
+    ("scaler", StandardScaler()),
+    ("selector", GAFeatureSelector(estimator=DecisionTreeClassifier(), config=config)),
+    ("clf", SVC()),
+])
+pipe.fit(X, y)
+```
+
+## The `alpha` trade-off (single-objective)
+
+```
+fitness = alpha * cv_score + (1 - alpha) * compression
+compression = 1 - n_selected / n_total
+```
+
+- `alpha = 1.0` → pure wrapper (performance only)
+- `alpha ≈ 0.7` → balanced, good default for edge deployment
+
+## Citation
+
+```bibtex
+@software{evo_gafs,
+  author    = {Skrauba, Axel},
+  title     = {evo-gafs: Genetic Algorithm Feature Selector for tabular data},
+  year      = {2026},
+  version   = {0.1.0},
+  url       = {https://github.com/AxelSkrauba/evo-suite}
+}
+```
+
+## License
+
+[MIT](../../LICENSE)

evo_gafs-0.1.0/pyproject.toml

@@ -0,0 +1,97 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "evo-gafs"
+version = "0.1.0"
+description = "Genetic Algorithm Feature Selector — a scikit-learn-compatible wrapper feature selector for tabular data (evo-suite)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "Axel Skrauba" },
+]
+keywords = [
+    "feature selection",
+    "genetic algorithm",
+    "DEAP",
+    "NSGA-II",
+    "machine learning",
+    "scikit-learn",
+    "wrapper method",
+    "evolutionary computation",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "numpy>=1.24",
+    "pandas>=1.5",
+    "scikit-learn>=1.6",
+    "deap>=1.4",
+]
+
+[project.optional-dependencies]
+viz = ["matplotlib>=3.6"]
+dev = [
+    "pytest>=7.4",
+    "pytest-cov>=4.1",
+    "ruff>=0.6",
+    "mypy>=1.8",
+    "matplotlib>=3.6",
+]
+
+[project.urls]
+Repository = "https://github.com/AxelSkrauba/evo-suite"
+Documentation = "https://github.com/AxelSkrauba/evo-suite/tree/main/packages/evo-gafs"
+"Bug Tracker" = "https://github.com/AxelSkrauba/evo-suite/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+evo_gafs = ["py.typed"]
+
+# ── Tooling ──────────────────────────────────────────────────────────────────
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+]
+
+[tool.coverage.run]
+source = ["evo_gafs"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "C4", "SIM"]
+ignore = [
+    "E501",  # line length handled by formatter
+]
+
+[tool.mypy]
+python_version = "3.10"
+warn_unused_configs = true
+ignore_missing_imports = true
+check_untyped_defs = true

evo_gafs-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

evo_gafs-0.1.0/src/evo_gafs/__init__.py

@@ -0,0 +1,34 @@
+"""evo_gafs — Genetic Algorithm Feature Selector.
+
+A scikit-learn-compatible wrapper feature selector for tabular data, built on
+DEAP. Supports single-objective (weighted) and multi-objective (NSGA-II,
+Pareto front) selection for both classification and regression.
+
+Examples
+--------
+>>> from sklearn.tree import DecisionTreeClassifier
+>>> from evo_gafs import GAFeatureSelector, GAConfig
+>>> selector = GAFeatureSelector(
+...     estimator=DecisionTreeClassifier(random_state=0),
+...     config=GAConfig(population_size=20, n_generations=10, verbose=False),
+... )
+"""
+
+from evo_gafs.benchmark.runner import BenchmarkRunner
+from evo_gafs.core.config import EvolutionStats, GAConfig, SelectionResult
+from evo_gafs.core.evaluator import FitnessEvaluator
+from evo_gafs.core.selector import GAFeatureSelector
+from evo_gafs.visualization.plots import GAPlotter
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BenchmarkRunner",
+    "EvolutionStats",
+    "FitnessEvaluator",
+    "GAConfig",
+    "GAFeatureSelector",
+    "GAPlotter",
+    "SelectionResult",
+    "__version__",
+]

evo_gafs-0.1.0/src/evo_gafs/algorithms/__init__.py

@@ -0,0 +1,6 @@
+"""Evolutionary loops: single-objective GA and multi-objective NSGA-II."""
+
+from evo_gafs.algorithms.nsga2 import run_nsga2
+from evo_gafs.algorithms.single import run_single_objective
+
+__all__ = ["run_nsga2", "run_single_objective"]

evo_gafs-0.1.0/src/evo_gafs/algorithms/nsga2.py

@@ -0,0 +1,125 @@
+"""Multi-objective genetic algorithm: NSGA-II."""
+
+from __future__ import annotations
+
+import random
+import time
+from typing import Callable
+
+import numpy as np
+from deap import base, tools
+
+from evo_gafs.core.config import EvolutionStats, GAConfig
+
+Callback = Callable[[int, EvolutionStats, list], bool]
+
+
+def _n_features_of(individual: list[int]) -> int:
+    return int(sum(individual))
+
+
+def run_nsga2(
+    toolbox: base.Toolbox,
+    config: GAConfig,
+    callbacks: list[Callback] | None = None,
+) -> tuple[list, tools.Logbook, list[EvolutionStats]]:
+    """Run NSGA-II for two maximised objectives: ``cv_score`` and ``compression``.
+
+    NSGA-II is the canonical multi-objective evolutionary algorithm: it ranks
+    the population by Pareto dominance and crowding distance to preserve a
+    diverse front.
+
+    Notes
+    -----
+    ``selTournamentDCD`` requires the selection size to be a multiple of four.
+    We round the population size up to the next multiple of four and pad with
+    clones, then trim the offspring back to ``population_size``.
+
+    Parameters
+    ----------
+    toolbox : deap.base.Toolbox
+        Pre-configured toolbox (``select`` must be ``selNSGA2``).
+    config : GAConfig
+        Algorithm configuration.
+    callbacks : list of callable, optional
+        Functions ``f(gen, stats, population) -> bool``.
+
+    Returns
+    -------
+    population : list
+        Final population (carries the Pareto front).
+    logbook : deap.tools.Logbook
+        DEAP logbook of compiled statistics.
+    history : list of EvolutionStats
+        Per-generation statistics.
+    """
+    population = toolbox.population(n=config.population_size)
+    logbook = tools.Logbook()
+    history: list[EvolutionStats] = []
+
+    stats = tools.Statistics(lambda ind: ind.fitness.values[0])
+    stats.register("mean", np.mean)
+    stats.register("std", np.std)
+    stats.register("max", np.max)
+
+    for ind, fit in zip(population, map(toolbox.evaluate, population)):
+        ind.fitness.values = fit
+
+    # Assign initial crowding distance.
+    population = toolbox.select(population, len(population))
+
+    for gen in range(config.n_generations):
+        t_gen_start = time.time()
+
+        k_dcd = config.population_size
+        if k_dcd % 4 != 0:
+            k_dcd += 4 - (k_dcd % 4)
+        pop_for_dcd = population[:]
+        while len(pop_for_dcd) < k_dcd:
+            pop_for_dcd.append(toolbox.clone(random.choice(population)))
+
+        offspring = tools.selTournamentDCD(pop_for_dcd, k_dcd)[: config.population_size]
+        offspring = [toolbox.clone(ind) for ind in offspring]
+
+        for child1, child2 in zip(offspring[::2], offspring[1::2]):
+            if random.random() < config.crossover_prob:
+                toolbox.mate(child1, child2)
+                del child1.fitness.values
+                del child2.fitness.values
+
+        for mutant in offspring:
+            if random.random() < config.mutation_prob:
+                toolbox.mutate(mutant)
+                del mutant.fitness.values
+
+        invalid = [ind for ind in offspring if not ind.fitness.valid]
+        for ind, fit in zip(invalid, map(toolbox.evaluate, invalid)):
+            ind.fitness.values = fit
+
+        population[:] = toolbox.select(population + offspring, config.population_size)
+
+        fits_cv = [ind.fitness.values[0] for ind in population]
+        n_feats = [_n_features_of(ind) for ind in population]
+        best_ind = max(population, key=lambda ind: ind.fitness.values[0])
+
+        gen_stats = EvolutionStats(
+            generation=gen,
+            best_fitness=float(best_ind.fitness.values[0]),
+            mean_fitness=float(np.mean(fits_cv)),
+            std_fitness=float(np.std(fits_cv)),
+            best_n_features=_n_features_of(best_ind),
+            mean_n_features=float(np.mean(n_feats)),
+            elapsed_time=time.time() - t_gen_start,
+        )
+        history.append(gen_stats)
+        logbook.record(gen=gen, **stats.compile(population))
+
+        if config.verbose and (gen % 10 == 0 or gen == config.n_generations - 1):
+            print(repr(gen_stats))
+
+        if callbacks and any(cb(gen, gen_stats, population) for cb in callbacks):
+            if config.verbose:
+                print(f"  Stopped by callback at generation {gen}.")
+            break
+
+    return population, logbook, history

evo_gafs-0.1.0/src/evo_gafs/algorithms/single.py

@@ -0,0 +1,133 @@
+"""Single-objective genetic algorithm with elitism and early stopping."""
+
+from __future__ import annotations
+
+import random
+import time
+from typing import Callable
+
+import numpy as np
+from deap import base, tools
+
+from evo_gafs.core.config import EvolutionStats, GAConfig
+
+Callback = Callable[[int, EvolutionStats, list], bool]
+
+
+def _n_features_of(individual: list[int]) -> int:
+    return int(sum(individual))
+
+
+def run_single_objective(
+    toolbox: base.Toolbox,
+    config: GAConfig,
+    callbacks: list[Callback] | None = None,
+) -> tuple[list, tools.Logbook, list[EvolutionStats]]:
+    """Run the single-objective GA.
+
+    The loop applies tournament selection, uniform crossover, bit-flip mutation
+    and elitism (the best ``elite_size`` individuals survive unchanged). It
+    supports both configuration-driven early stopping and callback-driven
+    stopping (a callback returning ``True`` halts evolution).
+
+    Parameters
+    ----------
+    toolbox : deap.base.Toolbox
+        Pre-configured toolbox with ``population``, ``evaluate``, ``select``,
+        ``mate``, ``mutate`` and ``clone`` registered.
+    config : GAConfig
+        Algorithm configuration.
+    callbacks : list of callable, optional
+        Functions ``f(gen, stats, population) -> bool``.
+
+    Returns
+    -------
+    population : list
+        Final population.
+    logbook : deap.tools.Logbook
+        DEAP logbook of compiled statistics.
+    history : list of EvolutionStats
+        Per-generation statistics.
+    """
+    population = toolbox.population(n=config.population_size)
+    logbook = tools.Logbook()
+    history: list[EvolutionStats] = []
+
+    stats = tools.Statistics(lambda ind: ind.fitness.values[0])
+    stats.register("mean", np.mean)
+    stats.register("std", np.std)
+    stats.register("min", np.min)
+    stats.register("max", np.max)
+
+    for ind, fit in zip(population, map(toolbox.evaluate, population)):
+        ind.fitness.values = fit
+
+    best_fitness_history: list[float] = []
+    no_improve_count = 0
+
+    for gen in range(config.n_generations):
+        t_gen_start = time.time()
+
+        elites = [toolbox.clone(e) for e in tools.selBest(population, config.elite_size)]
+
+        offspring = [toolbox.clone(ind) for ind in toolbox.select(population, len(population))]
+
+        for child1, child2 in zip(offspring[::2], offspring[1::2]):
+            if random.random() < config.crossover_prob:
+                toolbox.mate(child1, child2)
+                del child1.fitness.values
+                del child2.fitness.values
+
+        for mutant in offspring:
+            if random.random() < config.mutation_prob:
+                toolbox.mutate(mutant)
+                del mutant.fitness.values
+
+        invalid = [ind for ind in offspring if not ind.fitness.valid]
+        for ind, fit in zip(invalid, map(toolbox.evaluate, invalid)):
+            ind.fitness.values = fit
+
+        # Re-insert elites in place of the worst offspring.
+        offspring.sort(key=lambda ind: ind.fitness.values[0])
+        for i, elite in enumerate(elites):
+            offspring[i] = elite
+        population[:] = offspring
+
+        fits = [ind.fitness.values[0] for ind in population]
+        n_feats = [_n_features_of(ind) for ind in population]
+        best_ind = tools.selBest(population, 1)[0]
+
+        gen_stats = EvolutionStats(
+            generation=gen,
+            best_fitness=float(max(fits)),
+            mean_fitness=float(np.mean(fits)),
+            std_fitness=float(np.std(fits)),
+            best_n_features=_n_features_of(best_ind),
+            mean_n_features=float(np.mean(n_feats)),
+            elapsed_time=time.time() - t_gen_start,
+        )
+        history.append(gen_stats)
+        logbook.record(gen=gen, **stats.compile(population))
+
+        if config.verbose and (gen % 10 == 0 or gen == config.n_generations - 1):
+            print(repr(gen_stats))
+
+        if callbacks and any(cb(gen, gen_stats, population) for cb in callbacks):
+            if config.verbose:
+                print(f"  Stopped by callback at generation {gen}.")
+            break
+
+        if config.early_stopping_rounds is not None:
+            best_fitness_history.append(float(max(fits)))
+            if len(best_fitness_history) > config.early_stopping_rounds:
+                window = best_fitness_history[-config.early_stopping_rounds :]
+                if max(window) - min(window) < config.early_stopping_tol:
+                    no_improve_count += 1
+                    if no_improve_count >= config.early_stopping_rounds:
+                        if config.verbose:
+                            print(f"  Early stopping at generation {gen}.")
+                        break
+                else:
+                    no_improve_count = 0
+
+    return population, logbook, history

evo_gafs-0.1.0/src/evo_gafs/benchmark/__init__.py

@@ -0,0 +1,5 @@
+"""Multi-dataset benchmarking utilities."""
+
+from evo_gafs.benchmark.runner import BenchmarkRunner
+
+__all__ = ["BenchmarkRunner"]