fn_registry/python/functions/datascience/kmeans_segments.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, tested, tests, test_file_path, file_path, params, output

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	tested	tests	test_file_path	file_path	params	output
kmeans_segments	function	py	datascience	1.0.0	pure	def kmeans_segments(columns: dict, k_min: int = 2, k_max: int = 8) -> dict	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).	eda models kmeans clustering segmentation silhouette unsupervised				false		numpy scikit-learn	true	test_three_separated_blobs_finds_k3 test_insufficient_rows_returns_note test_insufficient_numeric_columns_returns_note test_rows_with_none_are_dropped	python/functions/datascience/kmeans_segments_test.py	python/functions/datascience/kmeans_segments.py	name desc columns 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 desc k_min Numero minimo de clusters a probar. Default 2. El minimo efectivo de filas validas requerido es k_min*2. name desc k_max Numero maximo de clusters a probar. Default 8. Se acota internamente a min(k_max, n_rows_validas-1).	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

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.