---
id: trend_slope_py_datascience
name: trend_slope
kind: function
lang: py
domain: datascience
version: "1.0.0"
purity: pure
signature: "def trend_slope(values: list, x: list = None) -> dict"
description: "Detecta la tendencia (sube/baja/plana) de una serie via regresion lineal simple del grupo eda y su significancia estadistica. Devuelve slope, r, r_squared, p_value, direction y significant. Descarta pares con None/NaN. Funcion pura, determinista, no muta el input."
tags: [eda, models, trend, regression, timeseries, datascience]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: ["scipy"]
example: |
  from datascience import trend_slope
  trend_slope([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
  # {"slope": 1.0, "intercept": 1.0, "r": 1.0, "r_squared": 1.0,
  #  "p_value": 0.0, "std_err": 0.0, "direction": "up",
  #  "significant": True, "n": 10}
tested: true
tests:
  - "test_increasing_series_slope_positive_up_significant"
  - "test_decreasing_series_slope_negative_down_significant"
  - "test_flat_constant_series_not_significant"
  - "test_random_series_flat_not_significant"
  - "test_custom_x_axis"
  - "test_too_few_pairs_returns_none_slope"
  - "test_drops_none_and_nan_pairs"
  - "test_too_few_valid_pairs_after_dropping"
test_file_path: "python/functions/datascience/trend_slope_test.py"
file_path: "python/functions/datascience/trend_slope.py"
params:
  - name: values
    desc: >
      Serie de valores numericos (variable dependiente, eje Y). Acepta huecos:
      los elementos None o NaN se descartan, emparejados con su x correspondiente,
      antes del ajuste.
  - name: x
    desc: >
      Posiciones de cada valor (variable independiente, eje X). Si es None se
      usa el indice posicional 0..n-1. Cuando se proporciona debe tener la misma
      longitud que values; los pares con x None/NaN tambien se descartan.
output: >
  dict con slope (float|None), intercept (float), r (float), r_squared (float),
  p_value (float), std_err (float), direction ("up"|"down"|"flat"|"unknown"),
  significant (bool, True si p_value<0.05) y n (int, pares validos usados). Con
  menos de 3 pares validos devuelve {slope:None, direction:"unknown",
  significant:False, n:<n>}.
---

## Ejemplo

```python
from datascience import trend_slope

# Serie creciente: tendencia al alza, significativa.
trend_slope([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
# {
#   "slope": 1.0, "intercept": 1.0, "r": 1.0, "r_squared": 1.0,
#   "p_value": 0.0, "std_err": 0.0,
#   "direction": "up", "significant": True, "n": 10,
# }

# Serie plana (constante): no hay tendencia significativa.
trend_slope([5.0] * 12)
# {... "slope": 0.0, "direction": "flat", "significant": False, "n": 12}

# Eje x explicito (no equiespaciado) y serie con hueco.
trend_slope([1, None, 3, float("nan"), 5], x=[0, 1, 2, 3, 4])
# {... "direction": "up", "significant": True, "n": 3}

# Menos de 3 pares validos -> sin ajuste.
trend_slope([1, 2])
# {"slope": None, "direction": "unknown", "significant": False, "n": 2}
```

## Cuando usarla

Cuando tengas una serie (ventas por dia, precio en el tiempo, una metrica del
grupo `eda`) y necesites saber rapido si sube, baja o esta plana, y si ese
movimiento es estadisticamente real o ruido. Util para semaforos de tendencia
en un dashboard, alertas ("esta metrica cae de forma significativa"), o como
feature barata antes de un modelo mas caro. Pasa `x` cuando los puntos no estan
equiespaciados (fechas con huecos); deja `x=None` para tratar la serie como
secuencia ordenada.

## Gotchas

Funcion pura sin I/O, pero depende de `scipy.stats.linregress`. La direccion
solo es `"up"`/`"down"` cuando ademas hay significancia (`p_value < 0.05`); una
pendiente no nula pero ruidosa se reporta como `"flat"`. El umbral 0.05 es fijo
(no parametrizable, KISS). Con menos de 3 pares validos tras descartar None/NaN
no se ajusta nada y `slope` es `None` — comprobar ese caso antes de usar el
valor numerico. Series constantes dan `r_squared` 0 y `direction` `"flat"`.