---
name: isolation_forest_outliers
kind: function
lang: py
domain: datascience
version: "1.0.0"
purity: pure
signature: "def isolation_forest_outliers(columns: dict, contamination: float = 0.05, max_report: int = 50) -> dict"
description: "Detecta outliers MULTIVARIANTE (filas anomalas considerando todas las columnas a la vez, no columna a columna) con sklearn IsolationForest. Estandariza con StandardScaler, descarta filas con None y usa random_state=0 para resultados deterministas. Devuelve conteo, porcentaje, filas anomalas ordenadas (mas anomala primero) con su score, umbral y dimensiones usadas. Con <2 columnas numericas o <10 filas validas devuelve note 'datos insuficientes' sin petar."
tags: [eda, models, outliers, anomaly-detection, isolation-forest, multivariate, sklearn]
params:
  - name: columns
    desc: "dict {nombre_columna: [valores numericos]}. Listas alineadas por fila (la fila i de cada columna forma una observacion). Solo se usan columnas cuyos valores sean todos numericos (None permitido por fila, NaN/Inf descartan la columna); el resto se ignora."
  - name: contamination
    desc: "Proporcion esperada de outliers en [0, 0.5], pasada a IsolationForest. Sube/baja la fraccion de filas marcadas. Default 0.05."
  - name: max_report
    desc: "Maximo de filas anomalas a devolver en outlier_rows, mas anomala primero. n_outliers cuenta TODAS aunque se trunque el detalle. Default 50."
output: "dict {n_outliers: total de filas outlier; outlier_pct: % sobre filas validas (0-100); outlier_rows: lista de {row_index, score} ordenada por score asc (mas anomala primero), truncada a max_report; threshold: umbral de decision (model.offset_), outlier <=> decision_function < threshold; n_rows_used: filas validas tras descartar None; n_features: columnas numericas usadas}. row_index cuenta SOLO las filas validas (sin None), en orden de aparicion empezando en 0 — no es el indice original si se descarto alguna fila. Si <2 columnas numericas o <10 filas validas: {n_outliers: 0, note: 'datos insuficientes'}."
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: []
tested: true
tests: ["test_cloud_with_three_far_points_flags_them", "test_insufficient_columns_returns_note", "test_insufficient_rows_returns_note"]
test_file_path: "python/functions/datascience/isolation_forest_outliers_test.py"
file_path: "python/functions/datascience/isolation_forest_outliers.py"
---

## Ejemplo

```python
from datascience import isolation_forest_outliers

# Nube densa alrededor de (0, 0) + 3 puntos claramente alejados al final.
xs = [0.1, -0.2, 0.0, 0.3, -0.1, 0.2, -0.3, 0.05, -0.15, 0.25, 0.0, -0.05]
ys = [0.0, 0.1, -0.1, 0.2, -0.2, 0.05, -0.05, 0.15, -0.25, 0.1, 0.0, 0.2]
# 3 outliers multivariante (lejos de la nube en el plano):
xs += [9.0, -8.5, 10.0]
ys += [9.5, -9.0, -8.0]

columns = {"x": xs, "y": ys}
result = isolation_forest_outliers(columns, contamination=0.2, max_report=10)

print(result["n_outliers"])        # >= 3
print(result["n_rows_used"], result["n_features"])  # 15 2
for row in result["outlier_rows"]:
    print(row["row_index"], round(row["score"], 4))
# Las filas 12, 13, 14 (los 3 puntos lejanos) aparecen primero, score mas bajo.
```

## Cuando usarla

Cuando quieras encontrar **filas anomalas de una tabla mirando todas sus
columnas a la vez** en la fase EDA, en lugar de buscar outliers columna a
columna con z-score/IQR. Es el caso en que una observacion es razonable en cada
variable por separado pero rara en su combinacion (p.ej. peso bajo + altura
alta). Pasale las columnas numericas alineadas por fila y te devuelve las filas
mas sospechosas ordenadas por anomalia para inspeccionarlas. Modelo barato y
determinista (`random_state=0`), apto para correr de forma reproducible dentro
de un perfilado.

## Gotchas

- **Pura solo porque fija `random_state=0`**: IsolationForest es estocastico;
  sin la semilla los resultados variarian entre llamadas. No cambiar la semilla
  si se quiere determinismo.
- **row_index es relativo a las filas validas**: si alguna fila tenia None en
  una columna usada, se descarta y los indices se recalculan sobre las filas
  que quedan (orden de aparicion, base 0). No mapea 1:1 con las listas de
  entrada cuando hay None.
- **Seleccion de columnas estricta**: una columna con cualquier valor no
  numerico (str, bool, NaN, Inf) se ignora por completo. Si quedan <2 columnas
  numericas, devuelve `note: "datos insuficientes"`.
- **Minimo 10 filas validas**: con menos, devuelve `note` en vez de un modelo
  poco fiable.
- `contamination` influye en cuantas filas se marcan; con datos sin outliers
  reales un valor alto forzara falsos positivos.