20  Encontrar tipos de lugares: k-means

Palabras clave

Quarto, publicación reproducible, agentes de programación, Markdown, Python, EPUB, análisis de datos, k-means

Los datos del agua tienen ahora 11,235 filas preparadas, cada una descrita por nueve puntajes z. Nadie puede leer tantas filas. El agrupamiento las convierte en unos pocos tipos a los que una persona puede ponerles nombre, comparar y sobre los que puede actuar: estas zonas municipales se parecen entre sí, y no se parecen a aquellas. Un funcionario puede preguntar qué tipos necesitan qué ayuda; un concejo puede ver a qué tipo pertenecen sus propias zonas. El agrupamiento no necesita etiquetas, así que es una primera mirada a datos que nadie ha clasificado, y un clúster raro puede señalar un error en los datos o un caso especial. Lo que no puede hacer es explicar: los clústeres describen, no muestran causas.

Si las matemáticas te intimidan, no tienen por qué. El algoritmo es lo bastante simple como para verlo paso a paso, y el criterio que necesita, cuántos tipos buscar, es una decisión que puedes escribir y revisar antes de ver la respuesta.

En este capítulo
  • Describir el ciclo de k-means, y por qué necesita muchos inicios y una semilla fija.
  • Aplicar la regla escrita para k, y decir qué tan ajustada fue la decisión.
  • Interpretar una silueta baja, una comprobación de estabilidad y una imagen de PCA sin leer de más.
  • Ejecutar el paso de agrupamiento y revisar la explicación del agente sobre k.

Partes deEl proyecto tal como lo dejó el Capítulo 19.

ConstruyesEl paso de agrupamiento, outputs/clusters.parquet y clusters.qmd.

Punto de controlcheckpoints/07-water-cluster/.

20.1 k-means en cuatro pasos

k-means necesita un número de entrada: \(k\), cuántos clústeres encontrar. Hace un inicio y luego repite dos movimientos hasta que no cambian nada:

  1. Coloca \(k\) centros en \(k\) puntos de los datos elegidos al azar.
  2. Asigna cada punto a su centro más cercano.
  3. Mueve cada centro a la media de los puntos que tiene asignados.
  4. Repite 2 y 3 hasta que nada cambie.

Ninguno de los dos movimientos sube nunca la inercia, la suma de las distancias al cuadrado de cada punto a su centro,

\[\text{inercia} = \sum_{i} \lVert x_i - c_{\ell(i)} \rVert^2 ,\]

donde \(x_i\) es el punto \(i\) (en los datos del agua, los nueve puntajes z de una fila), \(c_{\ell(i)}\) es el centro al que está asignado y \(\lVert x_i - c_{\ell(i)} \rVert\) es la distancia en línea recta entre ellos (Sección 19.3). Sobre puntajes z, la inercia está en desviaciones estándar al cuadrado, una unidad sin significado cotidiano, así que solo importan sus cambios. Hay solo una cantidad finita de formas de agrupar los puntos, así que el algoritmo siempre se detiene. No siempre se detiene en la mejor respuesta: un mal inicio puede atraparlo en un agrupamiento peor. La Figura 20.1 muestra el algoritmo sobre 560 puntos sintéticos en tres grupos, datos de juguete inventados para la ilustración, no los datos del agua.

1. coloca 3 centros en puntos al azar

Figura 20.1: k-means sobre puntos sintéticos de juguete. Los botones numerados recorren el algoritmo paso a paso y “fijar” detiene la reproducción automática; de “inicio 1” a “inicio 3” se elige uno de tres inicios al azar, de los cuales dos llegan al mejor agrupamiento y uno se atasca. Arrastra para girar.
Cuatro diagramas de dispersión pequeños de los puntos de juguete. En el primero, todos los puntos son grises y tres centros están en puntos al azar. En el segundo, los puntos tienen el color de su centro más cercano y los colores dividen mal los grupos. En el tercero, los centros se movieron hacia los tres grupos. En el cuarto, cada grupo tiene su propio color con su centro en el medio.
Figura 20.2: El mismo algoritmo sobre los puntos de juguete, aplanados a dos de sus tres dimensiones: el inicio al azar, la primera asignación, una asignación a mitad de camino y el resultado estable.

Inicios distintos pueden terminar en agrupamientos distintos, así que el análisis real ejecuta k-means desde 20 inicios (el n_init de scikit-learn) y se queda con el de menor inercia. Los inicios son aleatorios, pero repetibles: una semilla aleatoria fija, el número que pone en marcha el generador de números aleatorios de la computadora, los hace iguales en cada ejecución, así que tu proyecto, las diapositivas del taller y este libro obtienen los mismos clústeres.

NotaPor qué funciona

Los inicios reales no se colocan al azar, como en el juguete. El método por defecto de scikit-learn, k-means++ (Arthur y Vassilvitskii, 2007), elige el primer centro al azar entre los datos y cada uno de los siguientes con una probabilidad proporcional a su distancia al cuadrado del centro más cercano ya elegido. Eso dispersa los centros y hace menos probable un inicio atascado; scikit-learn usa una variante voraz que saca varios candidatos en cada paso y se queda con el mejor.

20.2 Elegir k

k es un hiperparámetro: una opción que el algoritmo no puede aprender de su propio objetivo, porque la inercia siempre baja a medida que k crece, hasta cero cuando cada punto es su propio clúster. Así que el análisis ajusta k-means para k de 2 a 8 y lee dos medidas (Figura 20.3). La primera es dónde la inercia deja de bajar mucho, el codo. La segunda, la silueta, puntúa de −1 a 1 cuánto más cerca está cada punto de su propio clúster que del siguiente, promediado sobre los puntos. Necesita todas las distancias entre puntos, así que se calcula sobre una muestra fija de 5,000 filas, lo que la mantiene rápida.

Dos gráficos de líneas para k de 2 a 8. La inercia baja sin parar, con fuerza al principio y más suavemente después de k igual a 4. La silueta es más alta en k igual a 2, luego plana cerca de 0.19 a 0.20 de k igual a 3 a 7, y más baja en 8. El k elegido, 4, está marcado en los dos.
Figura 20.3: Elegir k: la inercia y la silueta para k = 2 a 8, ajustadas sobre todas las filas conservadas. El k elegido está marcado.

La regla, escrita en choose_k() en el script del análisis, tiene tres partes, y la Tabla 20.1 la aplica fila por fila:

  • Se excluye k = 2. Dos clústeres separan sobre todo las filas urbanas de las rurales, cosa que ya sabíamos: coinciden con la zona en el 86% de las filas. El script lo mide con el índice de Rand ajustado (ARI), que puntúa cuánto coinciden dos agrupamientos más allá de lo que daría el azar: 1 significa idénticos, 0 no mejor que el azar. Aquí es 0.50.
  • El codo: toma el k más pequeño, de 3 en adelante, después del cual un clúster más recorta la inercia en menos de un 10%. Aquí es k = 4: un quinto clúster recorta la inercia solo un 7%.
  • La comprobación de la silueta: la silueta de k debe estar a menos de 0.01 de la mejor para k ≥ 3. En k = 4 es 0.195. La comprobación aquí solo descarta k = 8.
Tabla 20.1: La regla de choose_k(), fila por fila, sobre las filas conservadas: cuánto recortaría la inercia un clúster más, la silueta (sobre la muestra fija) y el veredicto. Calculado por el analysis.py del proyecto terminado.
k Un clúster más recorta Silueta Veredicto
2 14.9% 0.237 excluido: la separación urbana–rural
3 10.8% 0.194 uno más todavía recorta un 10% o más
4 6.7% 0.195 elegido: el más pequeño que pasa
5 6.3% 0.189 pasa, pero es más grande
6 5.4% 0.196 pasa, pero es más grande
7 4.7% 0.191 pasa, pero es más grande
8 – 0.166 silueta demasiado por debajo de la mejor

El codo es ajustado. El cuarto clúster en sí recorta la inercia un 10.8% (la fila de k = 3), apenas por encima del umbral del 10%, así que un umbral del 11% elegiría k = 3. Y los cuatro clústeres explican el 41% de la dispersión de los datos, uno menos la razón entre su inercia y la de un solo clúster; el resto es diferencia dentro de los tipos.

Después del ajuste vienen dos comprobaciones más. Estabilidad: los reajustes desde 5 semillas distintas coinciden, con un índice de Rand ajustado de al menos 0.998, así que el resultado no depende del inicio. Eso no dice nada sobre otros datos, otras características u otro k; reajustar sobre filas sacadas otra vez al azar (un bootstrap), o dejar fuera un año a la vez, pondría eso a prueba. Orden: los clústeres se numeran según el IRCA de su centro, del más bajo al más alto, así que una nueva ejecución conserva los mismos números y colores.

AdvertenciaError frecuente

Una silueta cerca de 0.2 es baja. En la lectura subjetiva que proponen Rousseeuw y sus colegas, una silueta promedio máxima de 0.25 o menos significa que “no se ha encontrado una estructura sustancial” (Struyf, Hubert y Rousseeuw, 1997, Tabla 2; cita traducida), y la mejor aquí, con cualquier k, es 0.24. Los tipos se superponen: resumen un continuo más que separar islas de datos. Así que trata k como una cuestión de criterio, y no fuerces un número de clústeres para contar una historia más bonita. Escribir la regla antes de ver el resultado es lo que mantiene honesta esa elección; choose_k() al menos hace explícita la regla, para que cualquiera pueda revisarla y ver qué tan ajustada fue la decisión.

Detente y piensa

Un funcionario lee el informe y pregunta: “¿Entonces Colombia tiene cuatro tipos de zona municipal?” ¿Qué le respondes?

Respuesta

Que cuatro es un resumen útil, no un descubrimiento. Una regla escrita lo eligió por un margen estrecho, y un umbral un punto porcentual más alto elige tres; la silueta baja dice que los tipos se superponen. Los clústeres describen combinaciones típicas de agua, servicios y contexto, y una zona cerca del borde de uno podría estar igual de bien en el siguiente.

20.3 Una imagen de los clústeres

Nueve dimensiones no se pueden dibujar. El análisis de componentes principales (PCA) encuentra las direcciones en las que más varían los datos y proyecta las filas sobre ellas. Cada dirección, una componente principal, es una suma ponderada de los nueve puntajes z, y sus pesos, llamados cargas, dicen qué mide. La Figura 20.4 usa las dos primeras componentes, que conservan el 30% y el 21% de la varianza.

Diagrama de dispersión de unos once mil puntos en cuatro grupos de colores que se superponen en sus bordes. El clúster 4 se extiende hacia un lado, los clústeres 1 y 2 hacia otros, y el clúster 3 queda en el medio, dibujado encima.
Figura 20.4: Cada punto es una zona-año sobre las dos primeras componentes principales de las nueve características en puntaje z, con color y forma según el clúster. El PCA es solo para la imagen: k-means usó las nueve características.

Las superposiciones de la imagen pueden ser separaciones en las dimensiones que deja fuera. Agregar una tercera componente, que conserva otro 16% de la varianza, muestra cuánto (Figura 20.5). En dos componentes, en promedio el 78% de los 15 vecinos más cercanos de una zona-año están en su propio clúster; en tres, el 94%. La tercera componente sube con la altitud y baja con la precipitación, sus dos cargas más grandes. El clúster 3, el más mezclado en dos dimensiones, queda por debajo de los demás a lo largo de ella: es el más bajo y el más lluvioso de los tipos.

Figura 20.5: Las zonas-año sobre las tres primeras componentes principales, con color y forma según el clúster. De frente, la nube es la imagen 2-D. Arrastra para girar y desplázate para acercar.

20.4 Dónde están los clústeres

La altitud lleva la carga más grande de la tercera componente. Un mapa muestra la altitud directamente (Figura 20.6): una columna por cada una de las 966 zonas urbanas agrupadas en 2023, en el centroide de su municipio, tan alta como la altitud de su cabecera (un punto SRTM derivado, exagerado 50 veces) y con el color de su clúster.

Figura 20.6: Las zonas urbanas agrupadas como columnas a la altitud de sus cabeceras, con el color de su clúster. Las etiquetas nombran las diez capitales de departamento más pobladas y Tunja. Arrastra para girar y desplázate para acercar.

Las zonas urbanas del clúster 2 son las más altas, con una mediana de altitud de 1,766 m, y el 56% de ellas están en la región Centro Oriente (la agrupación regional del DANE). Las del clúster 3 son las más bajas, a 130 m, y el 53% de ellas están en Caribe. Esto muestra dónde están los tipos, no por qué difieren. La cabecera de Tunja está a 2,695 m, y sus 16 zonas-año, urbanas y rurales, caen todas en el clúster 1.

El mapa dibuja solo zonas urbanas, una columna por municipio, porque la altitud es la de la cabecera. Así que muestra poco del clúster 4, cuyas zonas-año son rurales en un 91%. Sus pocas columnas urbanas son bajas, con una mediana de 159 m, pero la mediana de la altitud de las cabeceras de sus zonas-año rurales es de 1,475 m, así que el mapa dice poco sobre dónde se encuentra ese tipo.

20.5 Usar el modelo, o construirlo

Hay dos rutas para el modelado, y las dos terminan con los mismos outputs/ y las mismas páginas:

  • Usarlo (la ruta normal): copia el analysis.py terminado desde el punto de control de este paso, ejecútalo y dedica tu esfuerzo a revisar lo que eligió y a las publicaciones.
  • Construirlo (un desafío): dale al agente el prompt de abajo y haz que escriba él mismo el paso de agrupamiento.

Este es un libro sobre publicar, así que usar el modelo terminado es la ruta normal, no un plan B. Pero un script copiado solo es tan confiable como tu lectura de él, así que la ruta tiene dos prompts: uno ejecuta el script y el otro hace que el agente explique lo que imprimió.

Pídele a tu agente
Copia ../quarto-workshop/checkpoints/07-water-cluster/scripts/analysis.py sobre scripts/analysis.py (guarda el mío como scripts/analysis-before-07.py), ejecútalo con `uv run python scripts/analysis.py` y dime cuál es k.
Probablemente ejecute

copia el script, guardando el tuyo · uv run python scripts/analysis.py · informa k = 4

Entre lo que imprime, el script muestra la tabla detrás de la Figura 20.3 y luego su veredicto en una sola línea, en inglés, que con los datos de este libro dice:

k = 4: the next cluster cuts inertia by only 7% (< 10%), and its silhouette 0.195 is within 0.01 of the best k >= 3 (0.196).

Es decir: con k = 4, el clúster siguiente recorta la inercia solo un 7% (menos del 10%), y su silueta está cerca de la mejor para k ≥ 3. Pídele al agente que desarme esa línea:

Pídele a tu agente
Explica lo que imprimió scripts/analysis.py sobre k: qué significan `inertia`, `silhouette`, ari_vs_zone e inertia_drop para cada k, y qué prueba de choose_k() eligió k. Cita las líneas de choose_k() que lo deciden.
Probablemente ejecute

lee la tabla impresa y choose_k() · explica cada columna y la regla, citando el código

Detente y piensa

Mientras lo explica: ¿qué prueba de choose_k() eligió k, y cuál solo habría podido descartar uno?

Respuesta

Lo eligió el codo: k = 4 es el k más pequeño, de 3 en adelante, después del cual un clúster más recorta la inercia en menos de un 10%. k = 2 queda excluido antes de cualquier prueba, y la comprobación de la silueta solo veta: aquí solo descarta k = 8. Compara la explicación del agente con esto y con la Tabla 20.1: si dice que la silueta eligió k, leyó mal la regla.

Para construirlo (opcional):

Pídele a tu agente
En scripts/analysis.py, ejecuta k-means sobre las características z_ para k=2–8 (random_state=42, n_init=20); guarda la inercia y la silueta en outputs/k_selection.csv; elige k por el codo, revisa la silueta y el ARI con 5 semillas; numera los clústeres según el IRCA del centroide; guarda outputs/clusters.parquet (las columnas preparadas + `cluster`, pc1, pc2). Ejecútalo; explica k.
TipEn la práctica

Si lo construyes, tu k puede ser distinto de 4 cuando tu preparación es distinta, y está bien si la razón es sólida. Lo que importa es que la regla para elegir k quede escrita antes de ver la respuesta, y que los clústeres se numeren con una regla fija (aquí, el IRCA del centro, que el prompt llama IRCA del centroide), para que una nueva ejecución conserve los mismos números y colores.

20.6 La página de los clústeres

Las dos rutas construyen luego la segunda página del proyecto, que solo lee outputs/ y nunca vuelve a ajustar:

Pídele a tu agente
Crea clusters.qmd, en inglés, que lea outputs/k_selection.csv y outputs/clusters.parquet y muestre un gráfico del codo, la silueta por k y un diagrama de dispersión de PCA (pc1, pc2) coloreado por clúster, cada uno con pie de figura y texto alternativo. Renderízalo y cuéntame si hay errores.
Probablemente ejecute

escribe clusters.qmd · uv run quarto render clusters.qmd

Tú haces

abres clusters.html en tu navegador

ImportantePruébalo

Toma una de las rutas para el modelo y luego construye la página de los clústeres.

Terminaste cuando outputs/clusters.parquet existe, puedes decir cuál es k y por qué, y clusters.html muestra el codo, la silueta y la imagen de PCA.

¿Dos minutos sin avanzar? Pega esto en tu agente. Respalda tu trabajo y lleva el proyecto hasta este punto; luego sigue leyendo desde aquí.

Catch me up: follow ../quarto-workshop/checkpoints/07-water-cluster/README.md

Resumen

  • k-means asigna los puntos al centro más cercano y mueve los centros a la media de sus puntos; puede estancarse, así que se queda con el mejor de muchos inicios con semilla.
  • k se elige con una regla escrita de antemano: excluir k = 2, tomar el codo, dejar que la silueta vete.
  • El codo es ajustado y la silueta, baja: los tipos resumen un continuo.
  • La coincidencia entre semillas muestra independencia del inicio, no de los datos ni de las características.
  • El PCA y el mapa muestran dónde están los tipos, no por qué, y el mapa deja fuera las zonas-año rurales.
  • Usar el modelo terminado es legítimo si puedes explicar lo que eligió.

Por ahora, los tipos son solo números, del clúster 1, el de IRCA del centro más bajo, al clúster 4: el capítulo siguiente averigua qué distingue a cada uno, le pone nombre con una regla y compara las variables de resultado que el agrupamiento nunca vio.

Lecturas adicionales

  • scikit-learn, Clustering: k-means y silhouette analysis (consultados el 2026-11-12).
  • scikit-learn, Principal component analysis (consultado el 2026-11-12).
  • Stuart P. Lloyd, “Least squares quantization in PCM”, IEEE Transactions on Information Theory 28(2), 129–137, 1982, https://doi.org/10.1109/TIT.1982.1056489: el algoritmo detrás de k-means (consultado el 2026-11-12).
  • Peter J. Rousseeuw, “Silhouettes: a graphical aid to the interpretation and validation of cluster analysis”, Journal of Computational and Applied Mathematics 20, 53–65, 1987, https://doi.org/10.1016/0377-0427(87)90125-7: la silueta (consultado el 2026-11-12).
  • Anja Struyf, Mia Hubert y Peter Rousseeuw, “Clustering in an object-oriented environment”, Journal of Statistical Software 1(4), 1997, https://doi.org/10.18637/jss.v001.i04: la Tabla 2 interpreta el coeficiente de silueta (consultado el 2026-11-12).
  • David Arthur y Sergei Vassilvitskii, “k-means++: the advantages of careful seeding”, SODA 2007 (ACM-SIAM Symposium on Discrete Algorithms), https://theory.stanford.edu/~sergei/papers/kMeansPP-soda.pdf (consultado el 2026-11-12).
  • examples/water/references.bib en el repositorio del taller: los artículos sobre k-means, la silueta y el índice de Rand ajustado que cita el documento técnico terminado, revisados contra las páginas de sus editoriales.