Metadata-Version: 2.4
Name: sklearn-genetic-opt
Version: 0.16.0
Summary: Cross-validated hyperparameter search and feature selection for scikit-learn with interchangeable optimizers
Author-email: Rodrigo Arenas <rodrigo.arenas456@gmail.com>
License-Expression: MIT
Project-URL: Documentation, https://sklearngeneticopt.rodrigo-arenas.com/
Project-URL: Source Code, https://github.com/rodrigo-arenas/Sklearn-genetic-opt
Project-URL: Bug Tracker, https://github.com/rodrigo-arenas/Sklearn-genetic-opt/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Python: >=3.12
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: scikit-learn>=1.5.0; python_version < "3.15"
Requires-Dist: numpy>=1.26.0; python_version < "3.15"
Requires-Dist: pandas>=1.3.0; python_version < "3.15"
Requires-Dist: scikit-learn>=1.9.1; python_version >= "3.15"
Requires-Dist: numpy>=2.5.2; python_version >= "3.15"
Requires-Dist: pandas>=3.0.6; python_version >= "3.15"
Requires-Dist: scipy>=1.18.1; python_version >= "3.15"
Requires-Dist: deap>=1.4.4
Requires-Dist: tqdm>=4.60.0
Provides-Extra: nevergrad
Requires-Dist: nevergrad<2,>=1.0.12; extra == "nevergrad"
Provides-Extra: cmaes
Requires-Dist: cmaes<0.14,>=0.13.1; extra == "cmaes"
Provides-Extra: pymoo
Requires-Dist: pymoo<0.7,>=0.6.2; extra == "pymoo"
Provides-Extra: scipy
Requires-Dist: scipy>=1.15; extra == "scipy"
Provides-Extra: plot
Requires-Dist: seaborn>=0.13.2; extra == "plot"
Provides-Extra: mlflow
Requires-Dist: mlflow>=3.14.0; extra == "mlflow"
Provides-Extra: test
Requires-Dist: pytest>=9.1.0; extra == "test"
Requires-Dist: pytest-cov>=7.1.0; extra == "test"
Requires-Dist: pytest-order>=1.5.0; extra == "test"
Provides-Extra: docs
Requires-Dist: seaborn>=0.13.2; extra == "docs"
Requires-Dist: scipy>=1.11.0; extra == "docs"
Requires-Dist: mlflow>=3.14.0; extra == "docs"
Provides-Extra: build
Requires-Dist: build>=1.3.0; extra == "build"
Requires-Dist: twine>=6.2.0; extra == "build"
Provides-Extra: lint
Requires-Dist: black>=26.5.1; extra == "lint"
Provides-Extra: benchmark
Requires-Dist: nevergrad<2,>=1.0.12; extra == "benchmark"
Requires-Dist: cmaes<0.14,>=0.13.1; extra == "benchmark"
Requires-Dist: pymoo<0.7,>=0.6.2; extra == "benchmark"
Requires-Dist: scipy>=1.15; extra == "benchmark"
Requires-Dist: optuna>=4.0.0; extra == "benchmark"
Provides-Extra: all
Requires-Dist: nevergrad<2,>=1.0.12; extra == "all"
Requires-Dist: cmaes<0.14,>=0.13.1; extra == "all"
Requires-Dist: pymoo<0.7,>=0.6.2; extra == "all"
Requires-Dist: scipy>=1.15; extra == "all"
Requires-Dist: seaborn>=0.13.2; extra == "all"
Requires-Dist: mlflow>=3.14.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=9.1.0; extra == "dev"
Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
Requires-Dist: pytest-order>=1.5.0; extra == "dev"
Requires-Dist: seaborn>=0.13.2; extra == "dev"
Requires-Dist: scipy>=1.15; extra == "dev"
Requires-Dist: mlflow>=3.14.0; extra == "dev"
Requires-Dist: build>=1.3.0; extra == "dev"
Requires-Dist: twine>=6.2.0; extra == "dev"
Requires-Dist: black>=26.5.1; extra == "dev"
Requires-Dist: optuna>=4.0.0; extra == "dev"
Dynamic: license-file

sklearn-genetic-opt
===================

.. image:: https://raw.githubusercontent.com/rodrigo-arenas/Sklearn-genetic-opt/master/docs-vitepress/public/brand/readme-banner-1280x320.png
   :alt: sklearn-genetic-opt
   :width: 760
   :target: https://sklearngeneticopt.rodrigo-arenas.com/

|release| |tests| |license|

**Tune a scikit-learn estimator or find a smaller set of features.**
Give the search a model, a scorer and a budget. It evaluates candidates with
cross-validation, refits the winner and lets you call ``predict`` on new data.
Use it when the combinations of parameters or columns would make an exhaustive
search too expensive.

`Stable documentation`_ · `Backend tutorial`_ · `Benchmarks`_ · `Plot gallery`_

Run your first search
---------------------

Install the published package on Python 3.12 or newer:

.. code-block:: bash

   python -m pip install sklearn-genetic-opt

How deep should a decision tree grow? Search integer depths and two split
criteria on the training set. Compare the winning cross-validation score with
balanced accuracy on data the search never saw.

.. code-block:: python

   from sklearn.datasets import load_breast_cancer
   from sklearn.metrics import balanced_accuracy_score
   from sklearn.model_selection import train_test_split
   from sklearn.tree import DecisionTreeClassifier
   from sklearn_genetic import GASearchCV
   from sklearn_genetic.space import Categorical, Integer

   X, y = load_breast_cancer(return_X_y=True)
   X_train, X_test, y_train, y_test = train_test_split(
       X, y, stratify=y, test_size=0.25, random_state=7
   )
   tree = DecisionTreeClassifier(random_state=7)
   settings = dict(cv=3, scoring="balanced_accuracy", population_size=8,
                   generations=3, random_state=7, n_jobs=1, verbose=False)

   search = GASearchCV(
       tree,
       param_grid={"max_depth": Integer(2, 12), "criterion": Categorical(["gini", "entropy"])},
       **settings,
   ).fit(X_train, y_train)

   print(search.best_params_, search.best_score_)
   print(balanced_accuracy_score(y_test, search.predict(X_test)))

Which columns does the tree need?
---------------------------------

Reuse the model, folds and budget with ``GAFeatureSelectionCV``. Set an upper
limit of eight columns. The fitted selector applies its mask during prediction.

.. code-block:: python

   from sklearn_genetic import GAFeatureSelectionCV

   selector = GAFeatureSelectionCV(tree, max_features=8, **settings).fit(X_train, y_train)
   print(selector.get_support(indices=True))
   print(balanced_accuracy_score(y_test, selector.predict(X_test)))

Choose an optimizer
-------------------

Version 0.16.0 includes DEAP by default and supports four optional engines.
Install the extra for the engine you want. For example, to use pymoo:

.. code-block:: bash

   python -m pip install "sklearn-genetic-opt[pymoo]==0.16.0"

Change one parameter on either estimator to run the same experiment with a
different engine. Cloning keeps the earlier result available for comparison.

.. code-block:: python

   from sklearn.base import clone

   alternative = clone(selector).set_params(optimizer_backend="pymoo")
   alternative.fit(X_train, y_train)
   print(alternative.get_support(indices=True), alternative.fit_stats_["cross_validate_calls"])

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Backend
     - What it brings to the search
   * - ``deap``
     - Included by default. Choose genetic operators, adaptive schedules and local search.
   * - ``scipy``
     - Differential evolution for bounded spaces. It can stop early when the population converges.
   * - ``nevergrad``
     - OnePlusOne adjusts its mutations as candidates succeed or fail. TwoPointsDE is also available.
   * - ``cmaes``
     - CatCMA with Margin learns how numeric variables vary together and adapts category probabilities.
   * - ``pymoo``
     - Uses type-specific operators for mixed parameters and a binary genetic algorithm for feature masks.

Each optional engine has a pip extra with the same name. All five support
live plotting, early stopping and resuming from a completed generation.
The `engine reference`_ lists supported domains, controls and checkpoint
requirements. To integrate another optimizer, see the `plugin protocol`_.

How do they compare? Across five held-out splits, pymoo had the lowest mean
RMSE on both synthetic linear-regression feature-selection tasks. DEAP had
the lowest mean RMSE when tuning a tree on Friedman #1. The `benchmarks`_
compare nine workloads at matched counts of actual CV calls and include
overhead, raw measurements and commands to reproduce the runs.

Inspect a fitted search
-----------------------

Use ``cv_results_`` for individual candidates and ``history`` for progress by
generation. This example from the `digits walkthrough`_ shows how a neural
network search progressed and which candidates finished near the top.

.. image:: https://raw.githubusercontent.com/rodrigo-arenas/Sklearn-genetic-opt/master/docs-vitepress/public/images/basic_usage_mlp_search_overview.png
   :alt: Digits search dashboard with fitness by generation, population diversity, optimizer events and top candidate scores
   :width: 720
   :target: https://sklearngeneticopt.rodrigo-arenas.com/versions/0.16/guide/basic-usage

Go further
----------

* **Build a search** with the `GASearchCV`_, `GAFeatureSelectionCV`_ and `search space`_ references.
* **Track a long run** with the `checkpoint recipe`_, `plot gallery`_ and `backend tutorial`_.
* **Work on the project** with the `contributor guide`_ and `release notes`_.

Cite sklearn-genetic-opt
------------------------

If you use the library in research, cite the version used in your experiment.
For version 0.16.0, cite Rodrigo Arenas (2026), *sklearn-genetic-opt*
(version 0.16.0) [Computer software]. The `software citation`_ contains the
machine-readable metadata. For BibTeX, use:

.. code-block:: bibtex

   @software{arenas2026sklearn_genetic_opt,
     author  = {Arenas, Rodrigo},
     title   = {{sklearn-genetic-opt}},
     year    = {2026},
     version = {0.16.0},
     url     = {https://pypi.org/project/sklearn-genetic-opt/0.16.0/}
   }

.. |release| image:: https://img.shields.io/pypi/v/sklearn-genetic-opt
   :alt: Latest release on PyPI
   :target: https://pypi.org/project/sklearn-genetic-opt/
.. |tests| image:: https://github.com/rodrigo-arenas/Sklearn-genetic-opt/actions/workflows/ci-tests.yml/badge.svg?branch=master
   :alt: Continuous integration on master
   :target: https://github.com/rodrigo-arenas/Sklearn-genetic-opt/actions/workflows/ci-tests.yml
.. |license| image:: https://img.shields.io/badge/license-MIT-blue
   :alt: MIT license
   :target: https://github.com/rodrigo-arenas/Sklearn-genetic-opt/blob/master/LICENSE

.. _stable documentation: https://sklearngeneticopt.rodrigo-arenas.com/stable/
.. _backend tutorial: https://sklearngeneticopt.rodrigo-arenas.com/versions/0.16/tutorials/optimizer-backends
.. _benchmarks: https://sklearngeneticopt.rodrigo-arenas.com/versions/0.16/benchmarks/optimizer-catalog
.. _engine reference: https://sklearngeneticopt.rodrigo-arenas.com/versions/0.16/api/optimizer-backends
.. _plugin protocol: https://sklearngeneticopt.rodrigo-arenas.com/versions/0.16/api/algorithms#optimizer-plugins
.. _digits walkthrough: https://sklearngeneticopt.rodrigo-arenas.com/versions/0.16/guide/basic-usage
.. _GASearchCV: https://sklearngeneticopt.rodrigo-arenas.com/versions/0.16/api/gasearchcv
.. _GAFeatureSelectionCV: https://sklearngeneticopt.rodrigo-arenas.com/versions/0.16/api/gafeatureselectioncv
.. _search space: https://sklearngeneticopt.rodrigo-arenas.com/versions/0.16/api/space
.. _checkpoint recipe: https://sklearngeneticopt.rodrigo-arenas.com/versions/0.16/recipes/advanced/checkpointing
.. _plot gallery: https://sklearngeneticopt.rodrigo-arenas.com/versions/0.16/examples/plotting-gallery
.. _contributor guide: https://github.com/rodrigo-arenas/Sklearn-genetic-opt/blob/master/CONTRIBUTING.md
.. _release notes: https://sklearngeneticopt.rodrigo-arenas.com/versions/0.16/release-notes
.. _software citation: https://github.com/rodrigo-arenas/Sklearn-genetic-opt/blob/0.16.0/CITATION.cff
