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