77 lines
3.5 KiB
Markdown
77 lines
3.5 KiB
Markdown
---
|
|
name: kmeans_segments
|
|
kind: function
|
|
lang: py
|
|
domain: datascience
|
|
version: "1.0.0"
|
|
purity: pure
|
|
signature: "def kmeans_segments(columns: dict, k_min: int = 2, k_max: int = 8) -> dict"
|
|
description: "Detecta segmentos naturales con KMeans eligiendo el mejor k automaticamente por silhouette. Estandariza, descarta filas con None y prueba k de k_min a min(k_max, n_rows-1)."
|
|
tags: [eda, models, kmeans, clustering, segmentation, silhouette, unsupervised]
|
|
uses_functions: []
|
|
uses_types: []
|
|
returns: []
|
|
returns_optional: false
|
|
error_type: ""
|
|
imports: [numpy, scikit-learn]
|
|
tested: true
|
|
tests: ["test_three_separated_blobs_finds_k3", "test_insufficient_rows_returns_note", "test_insufficient_numeric_columns_returns_note", "test_rows_with_none_are_dropped"]
|
|
test_file_path: "python/functions/datascience/kmeans_segments_test.py"
|
|
file_path: "python/functions/datascience/kmeans_segments.py"
|
|
params:
|
|
- name: columns
|
|
desc: "dict {col_name: [valores numericos]} con todas las listas alineadas por fila (misma longitud). Solo se usan columnas numericas; las no numericas se ignoran. Las filas con algun None se descartan."
|
|
- name: k_min
|
|
desc: "Numero minimo de clusters a probar. Default 2. El minimo efectivo de filas validas requerido es k_min*2."
|
|
- name: k_max
|
|
desc: "Numero maximo de clusters a probar. Default 8. Se acota internamente a min(k_max, n_rows_validas-1)."
|
|
output: "dict con best_k (k de mayor silhouette), silhouette (score del mejor k), scores_by_k (lista de {k, silhouette, inertia} por cada k probado), cluster_sizes (tamano de cada cluster del mejor modelo), centers (centroides en espacio estandarizado), n_rows_used (filas validas) y n_features (columnas numericas). Si hay <2 columnas numericas o <k_min*2 filas validas devuelve {best_k: 0, note: 'datos insuficientes'}."
|
|
---
|
|
|
|
## Ejemplo
|
|
|
|
```python
|
|
import sys, os
|
|
sys.path.insert(0, os.path.join("python", "functions"))
|
|
from datascience.kmeans_segments import kmeans_segments
|
|
|
|
# Tres grupos claramente separados en 2D.
|
|
g1 = [(0.0, 0.0)] * 30
|
|
g2 = [(10.0, 10.0)] * 30
|
|
g3 = [(0.0, 10.0)] * 30
|
|
pts = g1 + g2 + g3
|
|
columns = {
|
|
"x": [p[0] for p in pts],
|
|
"y": [p[1] for p in pts],
|
|
}
|
|
|
|
result = kmeans_segments(columns, k_min=2, k_max=6)
|
|
print(result["best_k"]) # 3
|
|
print(round(result["silhouette"], 2)) # ~1.0 (grupos perfectos)
|
|
print(result["cluster_sizes"]) # [30, 30, 30] (en algun orden)
|
|
```
|
|
|
|
## Cuando usarla
|
|
|
|
Usala cuando, durante un EDA, quieras descubrir cuantos segmentos naturales hay en un
|
|
conjunto de columnas numericas sin saber el numero de grupos de antemano: clientes por
|
|
comportamiento, productos por metricas, regiones por indicadores. Elige el k optimo por
|
|
ti via silhouette, asi que no tienes que fijarlo a mano. Pasale solo las columnas
|
|
numericas relevantes alineadas por fila.
|
|
|
|
## Gotchas
|
|
|
|
Funcion pura y determinista (KMeans con random_state=0 y n_init=10), pero requiere
|
|
`numpy` y `scikit-learn` instalados. Los centroides (`centers`) estan en el espacio
|
|
estandarizado (z-scores), no en las unidades originales de las columnas. La silhouette
|
|
puede ser baja o negativa si los datos no tienen estructura de cluster real; un best_k
|
|
alto con silhouette baja sugiere ausencia de segmentacion clara.
|
|
|
|
## Notas
|
|
|
|
Estandariza con StandardScaler antes de clusterizar para que todas las features pesen
|
|
igual. Para cada k en [k_min, min(k_max, n_rows-1)] ajusta KMeans y calcula silhouette;
|
|
devuelve el modelo con mayor silhouette. Guardas de datos insuficientes: <2 columnas
|
|
numericas o <k_min*2 filas validas devuelven {best_k: 0, note: "datos insuficientes"}
|
|
sin lanzar excepcion.
|