---
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.