---
name: spearman_corr
kind: function
lang: py
domain: datascience
version: "1.0.0"
purity: pure
signature: "def spearman_corr(xs: list, ys: list) -> float"
description: "Coeficiente de correlacion de Spearman (correlacion de rangos) entre dos listas pareadas. Capta relaciones monotonicas no lineales que Pearson no detecta. Descarta pares None/NaN/no-numericos; <3 pares validos o varianza cero -> 0.0."
tags: [statistics, correlation, spearman, rank, eda, monotonic, python]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: [math, scipy]
params:
  - name: xs
    desc: "lista de valores numericos de la primera variable. None/NaN/no-numericos se descartan junto a su par."
  - name: ys
    desc: "lista de valores numericos de la segunda variable, pareada por indice con xs."
output: "coeficiente de Spearman en rango [-1, 1] como float. 1.0=relacion monotonica creciente perfecta, -1.0=decreciente perfecta, 0.0=sin relacion monotonica o datos insuficientes. Nunca None ni excepcion."
tested: true
tests: ["test_relacion_monotonica_perfecta", "test_relacion_monotonica_decreciente", "test_pares_con_none_se_ignoran", "test_pares_con_nan_se_ignoran", "test_menos_de_3_pares_validos_retorna_cero", "test_varianza_cero_retorna_cero", "test_listas_vacias_retorna_cero", "test_resultado_es_float"]
test_file_path: "python/functions/datascience/spearman_corr_test.py"
file_path: "python/functions/datascience/spearman_corr.py"
---

## Ejemplo

```python
from datascience import spearman_corr

# Relacion monotonica NO lineal (ys = x**2): Pearson < 1, Spearman = 1.0
xs = [1, 2, 3, 4, 5, 6]
ys = [x ** 2 for x in xs]          # [1, 4, 9, 16, 25, 36]
spearman_corr(xs, ys)             # -> 1.0

# Pares con None se descartan automaticamente
spearman_corr([1, 2, None, 4], [2, 4, 99, 8])  # -> 1.0
```

## Cuando usarla

Cuando sospechas una relacion monotonica no lineal entre dos variables que
Pearson (lineal) no capta: una crece consistentemente cuando la otra crece,
pero no en linea recta (curvas exponenciales, logaritmicas, potencias). Util
en EDA para rankear que pares de variables estan asociadas antes de modelar,
y cuando hay outliers que distorsionarian a Pearson (Spearman usa rangos).

## Gotchas

- Es pura pero importa `scipy.stats.spearmanr` (scipy ya vive en `python/.venv`).
- Necesita al menos 3 pares validos tras limpiar None/NaN; si no, devuelve 0.0.
- Si alguna de las dos series es constante (varianza cero), Spearman es
  indefinido -> devuelve 0.0 en lugar de NaN.
- Solo detecta monotonicidad: una relacion en U (sube y luego baja) puede dar
  ~0 aunque exista dependencia. Para eso usa otra metrica.
