fn_registry/python/functions/datascience/categorical_cardinality_block.md

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

id	name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	example	tested	tests	test_file_path	file_path	params	output
categorical_cardinality_block_py_datascience	categorical_cardinality_block	function	py	datascience	1.0.0	pure	def categorical_cardinality_block(cat: dict, n_rows: int) -> dict	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.	eda categorical cardinality entropy profiling datascience pure				false		math	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)	true	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	python/functions/datascience/categorical_cardinality_block_test.py	python/functions/datascience/categorical_cardinality_block.py	name desc cat 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 desc n_rows Número total de filas del dataset. Usado para pct_distinct. Si es 0 o None, pct_distinct sale None (sin ZeroDivisionError).	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

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.