cefeste

Credito Emiliano - Feature Selection, Transformation and Elimination (CE - FeSTE)

La repository contiene il codice per implementare la manipolazione delle feature dei dati utilizzati nei sistemi di ML in produzione con 4 moduli:

• Analisi: contiene le funzioni di analisi delle feature
• Selezione: contiene le funzioni di selezione preliminare delle feature
• Trasformazione: contiene le funzioni di pre-processing delle feature
• Eliminazione: contiene le funzioni di eliminazione delle feature

Analisi

La classe principale di questo modulo è FeatureAnalysis, nonchè la classe madre delle classi presenti nei moduli Elimination e Selection. Utile per ottenere analisi di base dalle feature o gestire i parametri della classe.

Contiene dei metodi per ottenere o settare gli attributi della classe e un metodo che per ogni feature:

• feature categorica: fornisce il conteggio di ogni valore.
• feature numerica: fornisce il conteggio dei valori e statistiche descrittive come media, deviazione standard, quantili e valori min/max.

Selezione

La classe principale di questo modulo è FeatureSelection. Applica diversi filtri che possono essere raggruppati come segue:

• Filtri univariati:
  • Nessuna feature con valore costante
  • Nessuna feature con numero di valori distinti troppo basso
  • Nessuna feature con numero di valori mancanti troppo alto
  • Nessuna feature con un valore troppo frequente
  • Nessuna feature con instabilità tra le distribuzioni dei dati di train e valid
• Filtri multivariati:
  • Correlazione di Spearman per feature numeriche
  • V di Cramer per feature categoriche
  • R2 per feature miste
  • VIF per feature collineari
• Filtri esplicativi:
  • AUROC della feature per la classificazione del target
  • Correlazione della feature con il target per la regressione

Trasformazione

È più un modulo tecnico che contiene 6 classi utili per generare la pipeline di produzione:

• ColumnExtractor: per estrarre colonne da un dataset
• ColumnRenamer: per rinominare colonne di un dataset
• Categorizer: per trasformare il dtype delle colonne di un dataset da 'object' a 'category'
• Dummitizer: per trasformare le feature in variabili dummy rispetto ad un valore di base.
• ManageOutlier: per gestire gli outlier tramite capping.
• LogTransformer: per applicare una trasformazione logaritmica alle feature numeriche.

Eliminazione

La classe principale di questo modulo è FeatureElimination, utile per selezionare le feature più utili da mantenere nel modello utilizzando la tecnica RFE.

È un metodo ricorsivo che ad ogni iterazione può:

• Addestrare un modello ottimizzando gli iperparametri con modello, griglia, metodo di ricerca e metrica di valutazione definiti dall'utente.
• Calcolare il valore di importanza shap delle feature.
• Identificare l'ultima/e feature(/s) per importanza ed eliminarla/e per l'iterazione successiva.

Guida per sviluppatori

• main branch ha una Policy che evita di inserire codice direttamente su di esso. Sono consentite solo Pull requests. Le Pull requests devono essere approvate da almeno 2 revisori, uno dei quali può essere il richiedente.
• Come best practice, il nome del ramo dovrebbe seguire questa convenzione di denominazione: NNN-related_work_item dove NNN è il numero assegnato da Azure all'elemento di lavoro correlato al ramo e related_work_item è il nome dell'elemento di lavoro sostituendo ' ' (spazi bianchi) con '_' (underscores). Tra il numero e il nome usa '-' (segno meno).
• Usa un virtual environment dedicato (guarda le note per il codice).
• Ricorda di riempire ed installare in modo opportuno i requirements.

pip install -r requirements_dev.txt  --trusted-host artifactory.group.credem.net  -i https://artifactory.group.credem.net/artifactory/api/pypi/virtualPypi/simple

• Ricorda di intallare il pre-commit (solo per la prima volta)

pre-commit install

• Si noti che il pacchetto cefeste viene installato automaticamente installando i requirements. Se i requirements non vengono utilizzati, eseguire quanto segue per installare in editable mode:

pip install -e .

Documentazione

(Visualizza la documentazione a questo link).

La documentazione del codice viene generata automaticamente utilizzando Sphinx in formato HTML. I passaggi per generare la documetazione sono i seguenti:

• Installa Sphinx presente nel file di requirements_dev.txt:

pip install -r requirements_dev.txt

• Installa il codice come developer:

pip install -e .

• Crea un folder docs/ ed entra digitando da terminale:

cd docs/

• Inizializza sphinx, se la prima volta, digitando da terminale:

sphinx-quickstart

Questo comando, dopo alcune domande, creerà una struttura del tipo:

source/          
|
└─── conf.py      
|
└─── index.rst
|
└─── _static/
|
└─── _templates/
build/    
Makefile
make.bat

Nel file docs/source/conf.py, puoi configurare Sphinx. Un esempio di conf.py può essere:

import pathlib
import sys

sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix() + "/src/cefeste")
project = "documentazione_ce-feste"
copyright = "2025, Team AIS"
author = "Team AIS"

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = ["sphinx.ext.autodoc", "sphinx.ext.autosummary", "sphinx.ext.napoleon", "custom_extension"]

templates_path = ["_templates"]

# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

autosummary_generate = True
html_theme = "classic"
html_static_path = ["_static"]

Nei file index.rst e nei _templates/ si può configurare l'autogenerazione della documentazione e i template da usare per farlo.

• Builda la documentazione, digitando da terminale:

sphinx-build -b html source build

Il risultato sarà in docs/build/index.html.

Una volta creata la documentazione questa viene inserita in un progetto GitHub per poterla collegare ad un sito di hosting (es. ReadTheDocs). Per avere un risultato sempre aggiornato bisogna cambiare ad ogni modifica i file html inseriti nel progetto GitHub (ReadTheDocs in automatico si accorge dei cambiamenti e aggiorna la documentazione).

Struttura

ce-feste/
|
└─── .pre-commit-config.yaml
|
└─── pyproject.toml
|
└─── LICENCE
|
└─── MANIFEST.in
|
└─── README.md
|
└─── requirements_dev.txt
|
└─── setup.py
|
└─── .gitignore
|
└─── docs/
|   |── build/
|   |   └── (Generated HTML output will be here)
|   └── source/
|   |   ├── _ext/
|   |   |   └── custom_extension.py
|   |   ├── _static/
|   |   |   └── (Static files)
|   |   ├── _templates/
|   |   |   └── autosummary/
|   |   |       ├── class.rst
|   |   |       ├── base.rst
|   |   |       └── module.rst
|   |   ├── conf.py
|   |   ├── index.rst
|   |   └── modules/
|   |       └── (Autogenerated rst files will be here)
|   |
|   └── Makefile
|   |
|   └── make.bat
|
└─── src/
    |
    └─── cefeste/
        |
        └─── __init__.py
        |
        └─── custom_extension.py
        |
        └─── config.py
        |
        └─── utils.py
        |
        └─── config
        |       params.yml
        └─── elimination
        |       __init__.py
        |       shap_rfe.py
        └─── selection
        |       __init__.py
        |       explanatory.py
        |       multivariate.py
        |       univariate.py
        └─── transform
        |       __init__.py