genetic-classifier 3.0.0__tar.gz

genetic_classifier-3.0.0/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+# Publishes to PyPI when a version tag (e.g. v3.0.0) is pushed to GitHub,
+# or manually from the Actions tab -> "Publish to PyPI" -> Run workflow.
+# Uses Trusted Publishing: no token needed, PyPI trusts this repository.
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

genetic_classifier-3.0.0/.gitignore

@@ -0,0 +1,12 @@
+venv_ag/
+__pycache__/
+*.pyc
+.DS_Store
+tests/*.ipynb
+dist/
+build/
+*.egg-info/
+.dist/
+
+# PDF and LaTeX guide: delivered separately, kept out of Git
+documentacao/

genetic_classifier-3.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fellipe Almassy and Matheus Gomes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

genetic_classifier-3.0.0/PKG-INFO

@@ -0,0 +1,298 @@
+Metadata-Version: 2.5
+Name: genetic-classifier
+Version: 3.0.0
+Summary: Linear classifier (binary and ordinal) trained by a genetic algorithm, built with NumPy
+Project-URL: Repository, https://github.com/FeAlmassy/Genetic-Classifier
+Project-URL: Issues, https://github.com/FeAlmassy/Genetic-Classifier/issues
+Author: Fellipe Almassy, Matheus Gomes
+License-Expression: MIT
+License-File: LICENSE
+Keywords: classification,evolutionary algorithm,genetic algorithm,machine learning,ordinal classification
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: numpy>=2.1
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pandas>=2.2
+Description-Content-Type: text/markdown
+
+# 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+**.
+
+```bash
+pip install genetic-classifier
+```
+
+Or straight from GitHub:
+
+```bash
+pip install git+https://github.com/FeAlmassy/Genetic-Classifier.git
+```
+
+### For development
+
+```bash
+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
+
+```python
+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 `train` already 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:
+
+```python
+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 as `None`.
+- **`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, use `1`; with many, `2` or `3`.
+- **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`:
+
+```python
+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`](https://github.com/FeAlmassy/Genetic-Classifier/blob/main/examples/template/template.xlsx).
+
+---
+
+## Examples and results
+
+| Notebook | Dataset | Classes | Test accuracy* |
+|---|---|---|---|
+| [`binary_example.ipynb`](https://github.com/FeAlmassy/Genetic-Classifier/blob/main/examples/example_1_binary/binary_example.ipynb) | `binary_data_1.xlsx` (539 samples, 18 features) | 2 | **87%** |
+| [`multiclass_example.ipynb`](https://github.com/FeAlmassy/Genetic-Classifier/blob/main/examples/example_2_multiclass/multiclass_example.ipynb) | `multiclass_data.xlsx` (261 samples, 30 features) | 5 | **79%** |
+| [`mushroom_classification.ipynb`](https://github.com/FeAlmassy/Genetic-Classifier/blob/main/examples/mushroom_classification/mushroom_classification.ipynb) | `mushroom_data.xlsx` (8124 samples, 117 features) | 2 | **100%** |
+| [`heart_disease_classification.ipynb`](https://github.com/FeAlmassy/Genetic-Classifier/blob/main/examples/heart_disease_classification/heart_disease_classification.ipynb) | `heart_data.xlsx` (917 samples, 21 features) | 2 | **85%** |
+| [`diabetes_classification.ipynb`](https://github.com/FeAlmassy/Genetic-Classifier/blob/main/examples/diabetes_classification/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`** (import `genetic_classifier`). The Portuguese version stays available as `algoritmo-genetico` 2.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 `rodar` was 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 **`evaluate`** function (`avaliar`), which prints and returns accuracy, fitness, recall per class and the confusion matrix. The matrix can also be obtained on its own with **`confusion_matrix`**.
+- `read_excel` and `read_csv` got the **`has_labels`** parameter: with `has_labels=False` they 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
+- `rodar` was renamed to **`treinar`** (now `train`), pairing with `prever` (now `predict`).
+- **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 `X` to float internally, which makes it up to ~6x faster when the data is integer (as read by `read_csv`).
+
+---
+
+## License
+
+Distributed under the [MIT license](https://github.com/FeAlmassy/Genetic-Classifier/blob/main/LICENSE): you can use, modify and redistribute it freely, as long as you keep the copyright notice.
+
+---
+
+## Authors
+
+- **Fellipe Almassy** — [GitHub](https://github.com/FeAlmassy)
+- **Matheus Gomes** — [GitHub](https://github.com/matheos-hash)

genetic_classifier-3.0.0/README.md

@@ -0,0 +1,277 @@
+# 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+**.
+
+```bash
+pip install genetic-classifier
+```
+
+Or straight from GitHub:
+
+```bash
+pip install git+https://github.com/FeAlmassy/Genetic-Classifier.git
+```
+
+### For development
+
+```bash
+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
+
+```python
+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 `train` already 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:
+
+```python
+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 as `None`.
+- **`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, use `1`; with many, `2` or `3`.
+- **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`:
+
+```python
+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`](https://github.com/FeAlmassy/Genetic-Classifier/blob/main/examples/template/template.xlsx).
+
+---
+
+## Examples and results
+
+| Notebook | Dataset | Classes | Test accuracy* |
+|---|---|---|---|
+| [`binary_example.ipynb`](https://github.com/FeAlmassy/Genetic-Classifier/blob/main/examples/example_1_binary/binary_example.ipynb) | `binary_data_1.xlsx` (539 samples, 18 features) | 2 | **87%** |
+| [`multiclass_example.ipynb`](https://github.com/FeAlmassy/Genetic-Classifier/blob/main/examples/example_2_multiclass/multiclass_example.ipynb) | `multiclass_data.xlsx` (261 samples, 30 features) | 5 | **79%** |
+| [`mushroom_classification.ipynb`](https://github.com/FeAlmassy/Genetic-Classifier/blob/main/examples/mushroom_classification/mushroom_classification.ipynb) | `mushroom_data.xlsx` (8124 samples, 117 features) | 2 | **100%** |
+| [`heart_disease_classification.ipynb`](https://github.com/FeAlmassy/Genetic-Classifier/blob/main/examples/heart_disease_classification/heart_disease_classification.ipynb) | `heart_data.xlsx` (917 samples, 21 features) | 2 | **85%** |
+| [`diabetes_classification.ipynb`](https://github.com/FeAlmassy/Genetic-Classifier/blob/main/examples/diabetes_classification/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`** (import `genetic_classifier`). The Portuguese version stays available as `algoritmo-genetico` 2.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 `rodar` was 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 **`evaluate`** function (`avaliar`), which prints and returns accuracy, fitness, recall per class and the confusion matrix. The matrix can also be obtained on its own with **`confusion_matrix`**.
+- `read_excel` and `read_csv` got the **`has_labels`** parameter: with `has_labels=False` they 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
+- `rodar` was renamed to **`treinar`** (now `train`), pairing with `prever` (now `predict`).
+- **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 `X` to float internally, which makes it up to ~6x faster when the data is integer (as read by `read_csv`).
+
+---
+
+## License
+
+Distributed under the [MIT license](https://github.com/FeAlmassy/Genetic-Classifier/blob/main/LICENSE): you can use, modify and redistribute it freely, as long as you keep the copyright notice.
+
+---
+
+## Authors
+
+- **Fellipe Almassy** — [GitHub](https://github.com/FeAlmassy)
+- **Matheus Gomes** — [GitHub](https://github.com/matheos-hash)

genetic_classifier-3.0.0/docs/.gitignore

@@ -0,0 +1,7 @@
+*.aux
+*.fdb_latexmk
+*.fls
+*.log
+*.out
+*.synctex.gz
+*.toc