---
name: pca_explained
kind: function
lang: py
domain: datascience
version: "1.0.0"
purity: pure
signature: "def pca_explained(columns: dict, n_components: int = 2) -> dict"
description: "PCA rapido sobre columnas numericas: estandariza (z-score), descarta filas con valores faltantes y ajusta sklearn PCA determinista para revelar estructura latente y cuanta varianza concentran pocos componentes. EDA barato."
tags: [eda, models, pca, dimensionality-reduction, variance, datascience, sklearn]
params:
  - name: columns
    desc: "Mapa {nombre_columna: [valores numericos]}. Listas alineadas por fila (misma longitud). Columnas no numericas o constantes se descartan; None/NaN marcan filas a descartar."
  - name: n_components
    desc: "Numero maximo de componentes principales (default 2). Se acota a min(n_features, n_filas_validas)."
output: "dict con n_components, n_rows_used, n_features, explained_variance_ratio (lista), cumulative (lista), top_loadings (lista de {component, feature, loading}) y projection (matriz cap a 1000 filas). Con <2 columnas numericas o <3 filas validas devuelve {n_components:0, explained_variance_ratio:[], note:'datos insuficientes'}."
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: [numpy, scikit-learn]
tested: true
tests: ["test_pc1_concentra_varianza_con_columnas_colineales", "test_una_sola_columna_numerica_datos_insuficientes", "test_pocas_filas_validas_datos_insuficientes"]
test_file_path: "python/functions/datascience/pca_explained_test.py"
file_path: "python/functions/datascience/pca_explained.py"
---

## Ejemplo

```python
from datascience import pca_explained

# x e y casi colineales (y ~= 2x); z independiente.
n = 50
cols = {
    "x": [float(i) for i in range(n)],
    "y": [2.0 * i for i in range(n)],
    "z": [float((i * 7) % 13) for i in range(n)],
}

res = pca_explained(cols, n_components=2)
# res["explained_variance_ratio"][0] > 0.6  -> PC1 concentra la varianza
# res["cumulative"][-1] ~ 1.0 con 2 componentes sobre 3 features
# res["top_loadings"][0] -> {"component": 0, "feature": "x" o "y", "loading": ...}
```

## Cuando usarla

Cuando exploras un dataset tabular numerico y quieres ver, de un vistazo y sin
montar un pipeline, si pocas dimensiones explican casi toda la varianza (alta
correlacion entre columnas) y que features pesan en cada componente. Util como
primer paso de EDA antes de decidir reduccion de dimensionalidad o seleccion de
variables. Pasa las columnas alineadas por fila; la funcion limpia filas con
faltantes y estandariza por ti.

## Notas

Funcion pura y determinista: estandariza con `StandardScaler`, ajusta
`sklearn.decomposition.PCA` con `random_state=0`. No hace I/O. Las columnas no
numericas o que no pueden coercerse a float se descartan; los None se tratan
como NaN y eliminan la fila completa. `projection` se acota a las primeras 1000
filas para mantener la salida manejable. Degrada con gracia: con menos de 2
columnas numericas o menos de 3 filas validas devuelve `note: "datos
insuficientes"` sin lanzar excepcion.