Genetic Classifier
A Python library that trains a linear classifier with a genetic algorithm, written from scratch with NumPy.
Instead of using gradients (like logistic regression), the model evolves a population of solutions: the best ones reproduce, mutate and, generation after generation, the classification improves.
It works for:
- Binary classification (2 classes: 0 and 1)
- Ordinal classification (K ordered classes, e.g. bad < average < good)
How it works
Each chromosome is a list of numbers: one bias and one weight per feature. With them the model computes a score for each sample:
score = bias + weight₁·x₁ + weight₂·x₂ + ... + weightₙ·xₙ
- Binary: score ≥ 0 → class 1, score < 0 → class 0
- Ordinal: the score is split into ranges by the thresholds (cut points), and each range is a class
The fitness
The score of each chromosome (its fitness) is the product of the recall of each class:
fitness = recall(class 0) × recall(class 1) × ... × recall(class K-1)
If the model gets every sample of a class wrong, the fitness becomes 0. This forces the model to get every class right, not only the most common one, which is useful when the classes are imbalanced.
The algorithm cycle
1. create random population
│
▼
2. compute fitness ◄───────────────┐
│ │
▼ │
3. select two parents (roulette) │
│ │
▼ │
4. crossover (one cut point) │
│ │
▼ │
5. mutation │
│ │
▼ │
6. replace the worst with ─────────┘
the best offspring
The cycle stops when it reaches the target fitness or runs out of generations.
| Step | What it does |
|---|---|
| Creation | Creates chromosomes with random genes between -1 and 1 |
| Fitness | Gives each chromosome a score from 0 to 1 |
| Selection | Draws two parents by roulette: the higher the fitness, the higher the chance |
| Crossover | The child takes the beginning of one parent and the end of the other, from a random cut point |
| Mutation | Replaces some genes of each child with new random values |
| Update | The worst of the population leave and the best offspring come in (elitism) |
Installation
Requires Python 3.10+.
pip install genetic-classifier
Or straight from GitHub:
pip install git+https://github.com/FeAlmassy/Genetic-Classifier.git
For development
git clone https://github.com/FeAlmassy/Genetic-Classifier.git
cd Genetic-Classifier
python -m venv venv_ag
source venv_ag/bin/activate # on Windows: venv_ag\Scripts\activate
pip install -e . # editable mode: code changes apply right away
Quick start
Binary
from genetic_classifier import train, predict, evaluate, read_excel, train_test_split
X, y = read_excel("examples/example_1_binary/binary_data_1.xlsx")
X_train, X_test, y_train, y_test = train_test_split(X, y, seed=0)
model = train(X_train, y_train, seed=0) # learns from the training set only
y_pred = predict(model, X_test) # classifies data the model has never seen
results = evaluate(y_test, y_pred) # prints accuracy, fitness, recall and confusion matrix
The default values of
trainalready give good results in most cases. Only tune the parameters if you need to.
The functions of each step (create_chromosomes, binary_fitness, select_parents_roulette, one_point_crossover, mutate, update_population) can also be used on their own, imported from their modules (e.g. from genetic_classifier.mutation import mutate).
Ordinal (several classes)
The classes must be numbers from 0 to K-1, ordered from lowest to highest. For K classes, pass K-1 thresholds in increasing order:
import numpy as np
thresholds = np.array([-1.5, -0.5, 0.5, 1.5]) # 4 cuts -> 5 classes
model = train(X, y, thresholds=thresholds, n_generations=2000)
y_pred = predict(model, X_new)
train parameters
| Parameter | Default | Description |
|---|---|---|
X |
— | array (n_samples, n_features) with the data |
y |
— | vector with the class of each sample |
n_chromosomes |
30 |
population size |
n_mutated_genes |
2 |
how many genes change in each child |
n_offspring |
16 |
how many children per generation |
n_replacements |
None |
how many of the worst in the population are swapped for the best children (at most the smaller of n_chromosomes and n_offspring). None = half of n_offspring |
n_generations |
1000 |
maximum number of generations |
target_fitness |
1.0 |
stops when the best fitness reaches this value (1.0 = runs every generation unless it gets everything right) |
thresholds |
None |
None = binary; array with K-1 cuts = ordinal |
gene_min |
-1.0 |
smallest gene value in the initial population |
gene_max |
1.0 |
largest gene value in the initial population |
seed |
None |
random seed for reproducibility (None = different every run) |
verbose |
True |
prints the best fitness and accuracy of every generation |
train returns a dictionary with chromosome (the best one found), fitness, accuracy (fraction right on the training data), generation (where it stopped), thresholds and history (lists best, mean and accuracy with the evolution per generation).
Tuning the parameters
The defaults work well in most cases. If you need to tune them, keep in mind that the parameters affect each other:
- Renewal rate =
n_replacements÷n_chromosomes: fraction of the population replaced every generation (default: 8 ÷ 30 ≈ 27%). Too low makes evolution slow; close to 100% the whole population becomes children of the same couple and loses diversity. That is why increasing only the population usually makes things worse: increase the replacements too, or leave it asNone. n_offspring×n_replacements: only the best children enter the population. With more children than replacements, the worst children are discarded.n_mutated_genes× number of features: what matters is the fraction of the chromosome that changes. With few features, use1; with many,2or3.- Cost ≈
n_generations× (n_chromosomes+n_offspring) × n_samples. - Explore × refine: a large population and more mutation search for new solutions; high renewal and little mutation improve the ones already found.
To find out whether more generations would help, look at the end of model["history"]["best"]: if the fitness is still going up, the model has not finished.
Data format
The spreadsheet (.xlsx or .csv) must follow this layout:
| Lessons | X1 | X2 | ... | Xn | CLASS |
|---|---|---|---|---|---|
| Y001 | 1 | 0 | ... | 1 | 1 |
| Y002 | 0 | 1 | ... | 0 | 0 |
- First column: sample identifier (ignored)
- Middle columns: features
- Last column: class
To classify new data, which has no class column, use has_labels=False. In that case the function returns only X:
X_new = read_excel("new_data.xlsx", has_labels=False)
y_pred = predict(model, X_new)
A ready-made template is in examples/template/template.xlsx.
Examples and results
| Notebook | Dataset | Classes | Test accuracy* |
|---|---|---|---|
binary_example.ipynb |
binary_data_1.xlsx (539 samples, 18 features) |
2 | 87% |
multiclass_example.ipynb |
multiclass_data.xlsx (261 samples, 30 features) |
5 | 79% |
mushroom_classification.ipynb |
mushroom_data.xlsx (8124 samples, 117 features) |
2 | 100% |
heart_disease_classification.ipynb |
heart_data.xlsx (917 samples, 21 features) |
2 | 85% |
diabetes_classification.ipynb |
diabetes_data.xlsx (40000 samples, 21 features) |
3 | 58%† |
* Trained on 80% of the data and tested on the remaining 20%, which the model never saw, always with seed 0.
† Prediabetes is very rare in this dataset, so the accuracy alone is misleading: the notebook shows the recall of each class.
The binary notebook shows one generation step by step, calling each function in the order of the algorithm. The multiclass one shows how to choose the order of the classes when it is not known.
Project structure
Genetic-Classifier/
├── src/
│ └── genetic_classifier/
│ ├── __init__.py # public API: train, predict, evaluate, confusion_matrix, read_excel, read_csv, train_test_split
│ ├── core.py # main loop (train) and prediction (predict)
│ ├── evaluation.py # model evaluation (evaluate) and confusion matrix
│ ├── creation.py # 1. initial population
│ ├── fitness.py # 2. binary and ordinal fitness, roulette proportions
│ ├── selection.py # 3. roulette selection
│ ├── crossover.py # 4. one-point crossover
│ ├── mutation.py # 5. mutation
│ ├── update.py # 6. replacing the worst with the best offspring
│ ├── reading.py # reading .xlsx and .csv files
│ └── split.py # train/test split (stratified)
├── docs/ # how the algorithm works, with math and examples (Markdown and LaTeX)
├── examples/ # example notebooks and datasets
├── tests/ # automated tests (coming soon)
├── pyproject.toml # package configuration (name, version, dependencies)
├── LICENSE # MIT license
└── requirements.txt
Each step of the algorithm lives in its own module, so you can swap one piece (for example, try another selection method) without touching the others. Every function checks its parameters and gives clear error messages.
Changelog
3.0.0
- The whole library is now in English and is published on PyPI as
genetic-classifier(importgenetic_classifier). The Portuguese version stays available asalgoritmo-genetico2.0.0. - Every docstring follows the same format: what the function does, each parameter with its type, and what it returns with its type and a suggested variable name.
- The deprecated alias
rodarwas removed.
Migrating from algoritmo-genetico:
| 2.x (Portuguese) | 3.0 (English) |
|---|---|
treinar, prever, avaliar, matriz_confusao |
train, predict, evaluate, confusion_matrix |
ler_excel, ler_csv (tem_classe) |
read_excel, read_csv (has_labels) |
dividir_treino_teste (proporcao_treino, estratificar) |
train_test_split (train_size, stratify) |
qtd_cromossomos, qtd_genes_mutados, qtd_filhos, qtd_substituicoes |
n_chromosomes, n_mutated_genes, n_offspring, n_replacements |
geracoes, fitness_alvo, minimo, maximo |
n_generations, target_fitness, gene_min, gene_max |
y_real, y_previsto, nomes_classes |
y_true, y_pred, class_names |
keys cromossomo, acuracia, geracao, historico (melhor, medio) |
keys chromosome, accuracy, generation, history (best, mean) |
key matriz of avaliar |
key confusion_matrix of evaluate |
criar_cromossomos, fitness_binario, fitness_ordinal, fitness_percentual |
create_chromosomes, binary_fitness, ordinal_fitness, fitness_proportions |
selecionar_pais_roleta, cruzar_um_ponto, mutar, atualizar_populacao |
select_parents_roulette, one_point_crossover, mutate, update_population |
2.0.0
- New
evaluatefunction (avaliar), which prints and returns accuracy, fitness, recall per class and the confusion matrix. The matrix can also be obtained on its own withconfusion_matrix. read_excelandread_csvgot thehas_labelsparameter: withhas_labels=Falsethey read new data without the class column.- New checks: empty cells, text in the features and text classes in ordinal mode now raise clear error messages instead of silently giving wrong results.
- Training no longer creates offspring in the last generation, since they would never be compared with the best chromosome.
1.1.0
rodarwas renamed totreinar(nowtrain), pairing withprever(nowpredict).- New default values, which give much better results without tuning: 30 chromosomes, 2 mutated genes, 16 offspring, replacements = half of the offspring, 1000 generations and target fitness 1.0.
- Training converts
Xto float internally, which makes it up to ~6x faster when the data is integer (as read byread_csv).
License
Distributed under the MIT license: you can use, modify and redistribute it freely, as long as you keep the copyright notice.
Authors
Metadata
Release files for genetic-classifier 3.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| genetic_classifier-3.0.0.tar.gz | 4.2 MB | With provenance | Details for genetic_classifier-3.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| genetic_classifier-3.0.0-py3-none-any.whl | Python 3 | none | any | Details for genetic_classifier-3.0.0-py3-none-any.whl |
Total release size: 4.2 MB
Release files / genetic_classifier-3.0.0.tar.gz
| Download URL | genetic_classifier-3.0.0.tar.gz |
|---|---|
| Size | 4.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
58f31e995339f5bde7fecd4e78b0d5408f7901c5d08184f73a41028162a456b4
|
|
BLAKE2b-256 checksum How to use checksums |
ed198516d7269cefbce1a0db7d828c21b9e7828b3c5716673c84192e9bdf19a8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logRelease files / genetic_classifier-3.0.0-py3-none-any.whl
| Download URL | genetic_classifier-3.0.0-py3-none-any.whl |
|---|---|
| Size | 23.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1fff5fc54ef1ba3b6f8030184922eccd5095961fd33a89eb8f6dc36c4b2c6a83
|
|
BLAKE2b-256 checksum How to use checksums |
7f5e6ac10bca3a48db60e29aaad83181e28c88e26e03620a269cabef57890264
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logSecurity for genetic-classifier 3.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for genetic_classifier-3.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.