fn_registry/python/functions/datascience/stl_decompose.md

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

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
stl_decompose	function	py	datascience	1.0.0	pure	def stl_decompose(values: list, period: int = None, robust: bool = True) -> dict	Descomposicion STL (Seasonal-Trend using Loess, statsmodels) de una serie temporal en tendencia, estacional y resto. Si period es None lo infiere por autocorrelacion. Devuelve las 3 componentes (o estadisticos si son largas), mas la fuerza de tendencia y de estacionalidad de Hyndman (1 - Var(resto)/Var(resto+componente)). Descarta None/NaN; serie corta (<2*period) -> nota.	statistics timeseries decomposition stl seasonality trend eda forecasting python				false		math numpy statsmodels	name desc values serie temporal de valores numericos en orden cronologico. None/NaN/infinitos/no-numericos se descartan antes de descomponer. name desc period periodo estacional (observaciones por ciclo, p.ej. 12 para mensual con estacionalidad anual). Si None se infiere por autocorrelacion; si no hay periodo claro devuelve nota. name desc robust si True (default) usa el ajuste robusto de STL, que reduce el efecto de outliers sobre tendencia y estacionalidad.	dict con 'period' usado, 'period_inferred' (bool), 'trend'/'seasonal'/'resid' (cada uno min/max/mean/std + values si la serie es corta, si no None), 'trend_strength' y 'seasonal_strength' (medidas de Hyndman en [0,1]). Serie insuficiente o sin periodo inferible: dict con 'note' y strengths en None. Nunca lanza excepcion.	true	test_serie_con_tendencia_y_estacionalidad test_fuerza_estacional_alta_con_estacionalidad_fuerte test_infiere_periodo_si_none test_serie_corta_devuelve_nota test_muestra_insuficiente_devuelve_nota test_descarta_none_y_nan test_serie_larga_resume_sin_values	python/functions/datascience/stl_decompose_test.py	python/functions/datascience/stl_decompose.py

Ejemplo

from datascience import stl_decompose
import numpy as np

# Serie mensual = tendencia lineal + ciclo estacional anual (periodo 12) + ruido
rng = np.random.default_rng(0)
n = 120
serie = [0.3 * i + 10 * np.sin(2 * np.pi * i / 12) + rng.normal(0, 1) for i in range(n)]

res = stl_decompose(serie, period=12)
res["trend_strength"]       # -> ~0.99 (tendencia clara)
res["seasonal_strength"]    # -> ~0.98 (estacionalidad clara)
res["seasonal"]["values"][:3]   # primeras 3 muestras de la componente estacional

# Sin pasar periodo: lo infiere por autocorrelacion
stl_decompose(serie)["period_inferred"]   # -> True

Cuando usarla

Cuando quieres separar una serie temporal en sus partes para entenderla o prepararla para modelar: cuanta de su variacion es tendencia de fondo, cuanta es ciclo estacional repetitivo y cuanta es ruido. Util en EDA para decidir si merece la pena desestacionalizar antes de comparar periodos, para detectar un cambio de tendencia, o para extraer features (las fuerzas de tendencia/estacionalidad de Hyndman resumen la serie en dos numeros comparables entre series).

Gotchas

• Es pura pero importa statsmodels.tsa.seasonal.STL y numpy (en python/.venv).
• STL exige al menos dos ciclos completos: con n < 2*period devuelve una nota en vez de descomponer. Para datos mensuales con estacionalidad anual (period=12) necesitas >= 24 meses.
• La inferencia automatica de period busca el pico de autocorrelacion; es heuristica. Si conoces el periodo real (12 mensual, 7 diario-semanal, 24 horario-diario), pasalo explicito: es mas fiable.
• Las componentes largas (> 200 puntos) se resumen en estadisticos y values queda en None para no inflar el payload; las cortas vienen completas.
• Las fuerzas estan en [0,1] por construccion (se recortan a 0 si la varianza del resto supera la de resto+componente, lo que indica componente inexistente).