feat(eda): capítulo AutomaticEDA CAT DISTR + funciones cardinalidad/pie

Capítulo cat_distr del motor AutomaticEDA: distribuciones categóricas con
explicación de entropía de Shannon, métricas de cardinalidad por columna
(valores distintos, % distintos, total de filas, valores únicos, entropía y
su máximo log2(k) + normalizada), tabla top-k y un donut de las categorías
más comunes (top-k + «Otros»). Marca columnas id-like y dominadas.

Delegadas a fn-constructor (grupo eda):
- categorical_cardinality_block: deriva métricas de cardinalidad/entropía.
- categorical_top_pie_figure: figura donut top-k + «Otros», leyenda lateral.

Defensivo (dict-no-throw): None si no hay columnas categóricas; normaliza
mode_pct a escala 0-100 (summarize_categorical lo emite como fracción).
Tablas vía DataTable y figura perezosa: el paginador del núcleo garantiza
no-corte en PDF y PPTX. Tests: golden + edge (sin categóricas) + anti-corte
(label largo / muchas columnas) en ambos renderers.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

python/functions/datascience/categorical_cardinality_block.md

@@ -0,0 +1,115 @@
+---
+id: categorical_cardinality_block_py_datascience
+name: categorical_cardinality_block
+kind: function
+lang: py
+domain: datascience
+version: "1.0.0"
+purity: pure
+signature: "def categorical_cardinality_block(cat: dict, n_rows: int) -> dict"
+description: "Deriva métricas de cardinalidad listas para renderizar a partir de la salida de summarize_categorical para UNA columna categórica más el número total de filas. Calcula pct_distinct, entropy_max=log2(n_distinct), entropy_norm (recortada a [0,1]), n_singletons (sobre el top visible) y los flags id_like / dominated. NO recalcula la entropía ni reimplementa summarize_categorical: la consume. Estilo dict-no-throw del grupo eda — nunca lanza."
+tags: [eda, categorical, cardinality, entropy, profiling, datascience, pure]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: ""
+imports: [math]
+example: |
+  from categorical_cardinality_block import categorical_cardinality_block
+  cat = {"top": [{"value": "a", "count": 5, "pct": 0.5}], "mode": "a",
+         "mode_pct": 0.5, "n_distinct": 4, "entropy": 1.685, "imbalance": 5.0,
+         "len_min": 1, "len_mean": 1.0, "len_max": 1}
+  block = categorical_cardinality_block(cat, n_rows=10)
+tested: true
+tests:
+  - "test_normal_case"
+  - "test_empty_cat_does_not_raise"
+  - "test_none_cat_does_not_raise"
+  - "test_n_rows_zero_no_zero_division"
+  - "test_id_like_when_distinct_near_rows"
+  - "test_dominated_when_mode_pct_high"
+  - "test_mode_pct_fallback_from_top_fraction"
+  - "test_n_singletons_partial_when_top_truncated"
+  - "test_single_distinct_value_entropy_norm_none"
+test_file_path: "python/functions/datascience/categorical_cardinality_block_test.py"
+file_path: "python/functions/datascience/categorical_cardinality_block.py"
+params:
+  - name: cat
+    desc: "Dict producido por summarize_categorical para UNA columna categórica. Claves leídas (todas opcionales, lectura defensiva): top (list de {value,count,pct}), mode, mode_pct (puede faltar), n_distinct, entropy (Shannon en bits), imbalance, len_min, len_mean, len_max. None o no-dict se tratan como {}."
+  - name: n_rows
+    desc: "Número total de filas del dataset. Usado para pct_distinct. Si es 0 o None, pct_distinct sale None (sin ZeroDivisionError)."
+output: "Dict con exactamente 16 claves, todas siempre presentes: n_distinct, n_rows, pct_distinct, entropy, entropy_max, entropy_norm, mode, mode_pct, imbalance, n_singletons, n_singletons_partial, len_min, len_mean, len_max, id_like, dominated. Valores None/False cuando no son derivables; la función nunca lanza. pct_distinct en escala 0-100. entropy_max=log2(n_distinct) (0.0 si n_distinct in {0,1}). entropy_norm=entropy/entropy_max recortada a [0,1]. n_singletons = nº de elementos de top con count==1 (None si top vacío). n_singletons_partial=True si n_distinct>len(top). id_like=pct_distinct>=99. dominated=mode_pct>=90."
+---
+
+## Ejemplo
+
+```python
+from categorical_cardinality_block import categorical_cardinality_block
+
+# Salida típica de summarize_categorical para una columna, con n_rows del dataset.
+cat = {
+    "top": [
+        {"value": "a", "count": 5, "pct": 0.5},
+        {"value": "b", "count": 3, "pct": 0.3},
+        {"value": "c", "count": 1, "pct": 0.1},
+        {"value": "d", "count": 1, "pct": 0.1},
+    ],
+    "mode": "a",
+    "mode_pct": 0.5,
+    "n_distinct": 4,
+    "entropy": 1.685,   # Shannon en bits (<= log2(4) = 2.0)
+    "imbalance": 5.0,
+    "len_min": 1, "len_mean": 1.0, "len_max": 1,
+}
+
+categorical_cardinality_block(cat, n_rows=10)
+# {
+#   "n_distinct": 4, "n_rows": 10,
+#   "pct_distinct": 40.0,            # 4 / 10 * 100
+#   "entropy": 1.685,
+#   "entropy_max": 2.0,             # log2(4)
+#   "entropy_norm": 0.8425,         # 1.685 / 2.0, recortado a [0,1]
+#   "mode": "a", "mode_pct": 0.5,
+#   "imbalance": 5.0,
+#   "n_singletons": 2,             # c y d con count == 1
+#   "n_singletons_partial": False, # top cubre los 4 distintos
+#   "len_min": 1, "len_mean": 1.0, "len_max": 1,
+#   "id_like": False,              # pct_distinct 40 < 99
+#   "dominated": False,            # mode_pct 0.5 < 90
+# }
+```
+
+## Cuando usarla
+
+Úsala justo después de `summarize_categorical`, cuando vayas a renderizar el
+bloque de cardinalidad de una columna categórica en un EDA: necesitas el ratio
+de valores distintos (`pct_distinct`), la entropía normalizada al rango `[0,1]`
+para comparar columnas con cardinalidades distintas, el conteo de singletons, y
+las banderas heurísticas `id_like` (la columna parece un identificador) y
+`dominated` (una sola categoría domina). Pásale el dict crudo de
+`summarize_categorical` para esa columna y el `n_rows` total del dataset. No
+reimplementa nada: solo deriva métricas de presentación a partir de lo ya
+calculado.
+
+## Gotchas
+
+- **`mode_pct` se pasa tal cual viene en `cat`.** `summarize_categorical`
+  produce `mode_pct` como **fracción** (0–1), no como porcentaje. El flag
+  `dominated` compara `mode_pct >= 90.0`, así que con la salida cruda de
+  `summarize_categorical` (fracciones) `dominated` no se dispara: aliméntalo con
+  `mode_pct` en escala 0–100 si quieres usar esa bandera. Solo el camino de
+  *fallback* (cuando `cat` no trae `mode_pct` y se deriva de `top[0]['pct']`)
+  normaliza una fracción `<= 1` multiplicándola por 100.
+- **`n_singletons` solo cubre el `top` visible.** Si `summarize_categorical` se
+  llamó con `top_k` pequeño, hay valores fuera del top; en ese caso
+  `n_singletons_partial` es `True` para avisar de que el conteo es parcial.
+- **`pct_distinct` es `None` si `n_rows` es 0 o `None`** (no lanza
+  `ZeroDivisionError`); por tanto `id_like` queda `False` en ese caso.
+- **`entropy_norm` es `None` cuando `entropy_max <= 0`** (columna constante,
+  `n_distinct in {0,1}`): no hay división por cero y no se inventa un 0/1.
+- **No recalcula la entropía.** Si `cat['entropy']` es incoherente con
+  `n_distinct`, `entropy_norm` se recorta a `[0,1]` pero el valor de entrada no
+  se corrige.
+- **`bool` no cuenta como número.** Un `True`/`False` en una clave numérica de
+  `cat` se trata como ausente (`None`), por la guarda defensiva.