Saltar a contenido

Referencia

Todo se importa desde el paquete: import banxicolab as sie.

Cliente

Banxico

Cliente del SIE de Banco de México.

Parameters:

Name Type Description Default
token (str, opcional)

Token de consulta. Lo normal es no pasarlo y dejar que se resuelva desde el entorno; ver :func:banxicolab.obtener_token.

None
timeout float

Segundos de espera por petición.

30
reintentos int

Reintentos ante fallas de red o errores 5xx (con espera creciente).

3
cache bool

Guarda en memoria las respuestas para no gastar consultas repitiendo la misma petición. Banxico recomienda expresamente cachear.

True
espera_maxima float

Si se supera el límite de consultas y el desbloqueo ocurre en menos de estos segundos, se espera y se reintenta; si no, se lanza :class:~banxicolab.LimiteExcedido.

60
sesion (Session, opcional)

Sesión propia (proxies, certificados corporativos, pruebas).

None

Examples:

>>> import banxicolab as sie
>>> bmx = sie.Banxico()
>>> bmx.descargar(["inpc", "fix"], inicio="2015-01-01")

limpiar_cache

limpiar_cache()

Olvida las respuestas guardadas (p. ej. tras una nueva publicación).

descargar

descargar(series=None, inicio=None, fin=None, *, tema=None, incremento=None)

Descarga una o varias series y las devuelve alineadas por fecha.

Hay tres formas de decir qué se quiere: por clave del SIE, por alias del catálogo o un tema completo.

Parameters:

Name Type Description Default
series str, lista o dict

Identificadores del SIE ("SF43718"), alias del catálogo ("fix") o un diccionario {clave: nombre_de_columna}. No hay límite de 20 series: la consulta se parte en lotes automáticamente.

None
tema (str, opcional)

En lugar de series, todas las del catálogo de un tema ("tasas", "tipo_de_cambio"…); ver :func:banxicolab.catalogo.

None
inicio (fecha, opcional)

Cualquier cosa que entienda pandas.Timestamp. Si se omiten ambas se descarga la historia completa; si falta fin se usa hoy.

None
fin (fecha, opcional)

Cualquier cosa que entienda pandas.Timestamp. Si se omiten ambas se descarga la historia completa; si falta fin se usa hoy.

None
incremento ('mensual', 'anual', 'acumulado')

Pide a Banxico la variación porcentual ya calculada en lugar del nivel: respecto a la observación anterior, al mismo periodo del año anterior, o al cierre del año anterior.

"mensual"

Returns:

Type Description
DataFrame

DatetimeIndex llamado fecha, una columna por serie y valores float (NaN donde el SIE reporta N/E). Las fechas sin ningún dato se descartan. Los títulos oficiales quedan en df.attrs["series"].

Raises:

Type Description
SerieNoEncontrada

Si alguna clave no existe en el SIE.

SinDatos

Si ninguna serie tiene observaciones en el periodo.

panel

panel(series=None, inicio=None, fin=None, *, tema=None, como=None)

Panel mensual listo para analizar, aunque las series tengan frecuencias distintas.

Descarga las series y lleva a frecuencia mensual las diarias, semanales y quincenales, cada una con la regla que le corresponde según el catálogo: último dato para precios y saldos, promedio para tasas, suma para flujos. Evita tener que descargar por grupos y agregar a mano.

Parameters:

Name Type Description Default
series Series | None

Igual que en :meth:descargar.

None
inicio Series | None

Igual que en :meth:descargar.

None
fin Series | None

Igual que en :meth:descargar.

None
tema Series | None

Igual que en :meth:descargar.

None
como (dict, opcional)

{columna: regla} para cambiar la regla de alguna serie o fijar la de una clave que no está en el catálogo (por omisión, "ultimo"). Reglas: "ultimo", "promedio", "suma", "primero".

None

Returns:

Type Description
DataFrame

Indexado al primer día de cada mes. La regla aplicada a cada columna queda en df.attrs["agregacion"].

Examples:

>>> import banxicolab as sie
>>> sie.panel(["inpc", "fix", "tasa_objetivo"], "2015-01-01")

serie

serie(clave, inicio=None, fin=None, *, incremento=None)

Como :meth:descargar, pero para una sola serie y sin valores faltantes.

metadatos

metadatos(series)

Título, periodicidad, unidad y cobertura de cada serie.

Conviene revisarlo antes de transformar: indica si la serie es un índice, una tasa o un saldo, y desde cuándo existe.

oportuno

oportuno(series)

Último dato publicado de cada serie (consulta barata: 80 por minuto).

buscar

buscar(texto, limite=30)

Busca series por texto en el catálogo público del SIE. No usa token.

Notes

Se apoya en el buscador de la página del catálogo, que no forma parte de la API documentada: funciona mejor con una o dos palabras ("subyacente", "cetes") y podría cambiar sin aviso.

info

info(clave)

Ficha de una serie desde el catálogo público. No usa token ni gasta consultas.

inflacion

inflacion(inicio=None, fin=None, *, indice='inpc')

Tabla de inflación calculada a partir del índice de precios.

Descarga 13 meses extra hacia atrás para que la variación anual exista desde inicio. Ver :func:banxicolab.inflacion para las columnas.

inflacion_implicita

inflacion_implicita(plazo=10, inicio=None, fin=None)

Inflación implícita diaria en los precios de Bonos M y Udibonos.

Descarga el vector de precios de Banxico, calcula el rendimiento a vencimiento de cada título y los compara. Ver :func:banxicolab.inflacion_implicita para la interpretación.

Parameters:

Name Type Description Default
plazo (3, 10, 20, 30)

Plazo de referencia en años.

3

Returns:

Type Description
DataFrame

nominal (Bono M) y real (Udibono) en % anual, implicita en %, y el plazo efectivo en años de cada título (plazo_nominal, plazo_real), que rara vez coinciden exactamente.

Token

obtener_token

obtener_token(token=None, *, preguntar=True)

Resuelve el token siguiendo el orden descrito en el módulo.

Parameters:

Name Type Description Default
token (str, opcional)

Token explícito. Si se da, solo se valida su formato.

None
preguntar bool

Si no se encuentra en ninguna fuente y la sesión es interactiva, pedirlo con getpass.

True

Raises:

Type Description
TokenNoEncontrado

Si no hay token y no se puede preguntar.

TokenInvalido

Si el token encontrado tiene un formato imposible.

guardar_token

guardar_token(token=None, *, verificar=True)

Configura el token: lo pide, lo comprueba con Banxico y lo guarda.

Es el paso que se hace una sola vez por computadora. El token queda en un archivo que solo tu usuario puede leer, y a partir de ahí la librería lo encuentra sola.

Parameters:

Name Type Description Default
token (str, opcional)

Si se omite (lo recomendable) se pide con getpass, de modo que nunca queda escrito en la celda del notebook ni en el historial.

None
verificar bool

Hace una consulta de prueba antes de guardar. Si Banxico rechaza el token no se guarda nada y se lanza :class:~banxicolab.TokenInvalido.

True

Returns:

Type Description
Path

Ruta del archivo escrito.

Examples:

>>> import banxicolab as sie
>>> sie.guardar_token()
Pega tu token del SIE (no se mostrará en pantalla): ········
Token verificado con Banxico y guardado. Ya puedes descargar series.

borrar_token

borrar_token()

Elimina el archivo creado por :func:guardar_token. Devuelve si existía.

catalogo(tema=None, *, buscar=None)

Tabla con los alias disponibles.

Parameters:

Name Type Description Default
tema (str, opcional)

Filtra por tema: "precios", "expectativas", "tipo_de_cambio", "tasas", "actividad", "externo" o "dinero".

None
buscar (str, opcional)

Texto a buscar en el alias o la descripción, sin distinguir mayúsculas ni acentos (buscar="inflacion").

None

Examples:

>>> catalogo("tipo_de_cambio").index.tolist()
['fix', 'fix_liquidacion', 'fix_promedio_mensual', 'euro']
>>> catalogo(buscar="cetes")["id"].tolist()
['SF60633', 'SF60634']

Las funciones descargar, panel, serie, metadatos, oportuno, buscar e info existen también a nivel de módulo (sie.descargar(...)), con los mismos parámetros que los métodos de Banxico.

Frecuencia y diagnóstico

frecuencia

frecuencia(serie)

Frecuencia aproximada según la separación mediana entre observaciones.

Returns:

Type Description
str

"Diaria", "Semanal", "Quincenal", "Mensual", "Trimestral" o "Anual".

diagnostico

Conocer los datos antes de transformarlos, y verificar después.

diagnostico

diagnostico(datos)

Resumen mínimo por serie: cobertura, frecuencia, faltantes y rango.

La columna razon_max_min orienta sobre el logaritmo: si una serie positiva se multiplicó varias veces, su varianza casi seguro crece con el nivel.

faltantes cuenta los huecos entre la primera y la última observación de cada columna, así que diagnostica por separado las series de frecuencias distintas: al juntarlas en una tabla, los días sin dato mensual contarían como faltantes.

prueba_adf

prueba_adf(datos, alfa=0.05)

Prueba Dickey–Fuller Aumentada para una o varias series.

Acepta un diccionario {nombre: serie}, ideal para comparar la misma variable bajo distintas transformaciones. H0: la serie tiene raíz unitaria; se rechaza (estacionaria = True) cuando p_valor < alfa.

a_mensual

a_mensual(datos, como='ultimo')

Lleva una serie de alta frecuencia a frecuencia mensual.

Parameters:

Name Type Description Default
datos Series o DataFrame

Serie diaria o semanal.

required
como ('ultimo', 'promedio', 'suma', 'primero')

Regla de agregación. La elección no es neutral: "ultimo" para precios y saldos (tipo de cambio, reservas), "promedio" para tasas de interés, "suma" para flujos. Promediar un precio reduce artificialmente su volatilidad. Con un DataFrame puede darse un diccionario {columna: regla}.

"ultimo"

Returns:

Type Description
Series o DataFrame

Indexado al primer día de cada mes, igual que las series mensuales del SIE, para que se puedan unir sin desfases.

valor_en

valor_en(serie, fecha)

Último valor disponible en o antes de fecha.

Evita el KeyError cuando la fecha exacta no existe (fines de semana, series mensuales fechadas el día 1, etc.).

Números índice

indice_base

indice_base(datos, base=None, valor=100)

Convierte a número índice: valor × X_t / X_base.

Parameters:

Name Type Description Default
base (fecha, opcional)

Periodo base. Se toma el último dato en o antes de esa fecha; si se omite, la primera observación válida.

None
valor float

Valor del índice en la base (100 por convención).

100

cambiar_base

cambiar_base(indice, base, valor=100)

Rebasifica un índice ya construido, sin volver a los datos originales.

empalmar

empalmar(anterior, nueva, traslape=None)

Une dos tramos de un índice con bases distintas en una sola serie.

El tramo anterior se reescala para que coincida con nueva en la fecha de traslape; de ahí en adelante se usa nueva tal cual. Las tasas de variación de ambos tramos se conservan intactas.

Parameters:

Name Type Description Default
traslape (fecha, opcional)

Fecha común en la que se igualan. Por omisión, la primera fecha de nueva que también existe en anterior.

None

Tasas de variación

variacion

variacion(datos, periodos=1, *, log=False, porcentaje=True)

Tasa de variación respecto a periodos observaciones atrás.

Parameters:

Name Type Description Default
periodos int

1 para la variación periodo a periodo; 12 para la anual de una serie mensual (ver también :func:variacion_anual).

1
log bool

Si es True devuelve la diferencia de logaritmos, que es aditiva en el tiempo. Se aproxima a la variación simple solo para cambios pequeños.

False
porcentaje bool

Multiplica por 100.

True

variacion_anual

variacion_anual(datos, *, log=False, porcentaje=True)

Variación contra el mismo periodo del año anterior.

Detecta sola si la serie es quincenal, mensual, trimestral o anual. Al comparar cada mes con el mismo mes del año previo, cancela la estacionalidad estable.

anualizar

anualizar(tasa, periodos_por_anio=12, *, porcentaje=True)

Anualiza una tasa por capitalización compuesta: (1 + r)^k − 1.

Multiplicar por k subestima el resultado; el error crece con la tasa.

Parameters:

Name Type Description Default
tasa Series, DataFrame o número

Tasa por periodo (en % si porcentaje=True).

required
periodos_por_anio int

12 para una tasa mensual, 4 para trimestral.

12

Inflación y precios constantes

inflacion

inflacion(indice)

Las cuatro lecturas habituales de la inflación, en %.

Parameters:

Name Type Description Default
indice Series

Índice de precios mensual (INPC, subyacente, etc.).

required

Returns:

Type Description
DataFrame
  • mensual: variación respecto al mes anterior.
  • anual: respecto al mismo mes del año anterior (la que se compara con la meta de 3 % de Banxico).
  • acumulada: respecto a diciembre del año anterior.
  • mensual_anualizada: la mensual capitalizada a 12 meses; muy volátil y afectada por la estacionalidad.

Examples:

>>> import banxicolab as sie
>>> sie.inflacion(sie.serie("inpc", "2020-01-01")).tail()

inflacion_entre

inflacion_entre(indice, inicio, fin)

Inflación acumulada (en %) entre dos fechas.

Examples:

>>> import pandas as pd
>>> inpc = pd.Series([100.0, 110.0], index=pd.to_datetime(["2020-01-01", "2021-01-01"]))
>>> round(inflacion_entre(inpc, "2020-01-01", "2021-01-01"), 2)
10.0

deflactar

deflactar(nominal, precios, base=None)

Expresa una serie monetaria en pesos constantes.

Parameters:

Name Type Description Default
nominal Series o DataFrame

Montos en pesos corrientes.

required
precios Series

Índice de precios (normalmente el INPC) con la misma frecuencia y fechas que nominal.

required
base (fecha, opcional)

Los resultados quedan en pesos de esa fecha. Si se omite se usa la base propia del índice (se divide entre precios / 100).

None

a_pesos_de

a_pesos_de(monto, origen, destino, precios)

Convierte un monto de la fecha origen a pesos de la fecha destino.

Examples:

>>> import pandas as pd
>>> inpc = pd.Series([100.0, 110.0], index=pd.to_datetime(["2020-01-01", "2021-01-01"]))
>>> a_pesos_de(1000, "2020-01-01", "2021-01-01", inpc)
1100.0

tasa_real

tasa_real(nominal, inflacion, *, exacta=True)

Tasa de interés real ex-post (ecuación de Fisher), en %.

Parameters:

Name Type Description Default
nominal Series

Ambas en % anual y con el mismo índice.

required
inflacion Series

Ambas en % anual y con el mismo índice.

required
exacta bool

True: (1 + i) / (1 + π) − 1. False: la aproximación i − π, que siempre sobreestima y empeora cuando la inflación es alta.

True

Tendencia y pronósticos

impulso

impulso(indice, meses=3, *, ajustar=True)

Ritmo reciente de la inflación: promedio móvil contra el previo, anualizado.

Compara el promedio del índice en los últimos meses con el de los meses anteriores y anualiza el resultado (el «3m/3m anualizado» de los reportes de bancos centrales). Detecta los cambios de tendencia varios meses antes que la variación anual, que arrastra lo ocurrido hace un año.

Parameters:

Name Type Description Default
indice Series

Índice de precios mensual.

required
meses int

Tamaño de la ventana (3 o 6 son los habituales).

3
ajustar bool

Desestacionaliza antes con :func:banxicolab.desestacionalizar. Sin ajuste, el resultado refleja sobre todo el calendario.

True

Returns:

Type Description
Series

En % anualizado.

persistencia

persistencia(serie, rezagos=12, ventana=None)

Persistencia de la inflación: suma de los coeficientes de un AR(p).

Cerca de 1, los choques tardan mucho en disiparse (la inflación se comporta casi como una caminata aleatoria); cerca de 0, se revierten pronto.

Parameters:

Name Type Description Default
serie Series

Inflación mensual (idealmente desestacionalizada) u otra serie estacionaria.

required
rezagos int

Orden p del autorregresivo, estimado por mínimos cuadrados.

12
ventana (int, opcional)

Si se indica, estima en ventanas móviles de ese tamaño y devuelve un Series para ver cómo cambia en el tiempo; si no, un solo número.

None

pronosticar_inflacion

pronosticar_inflacion(indice, horizonte=12, *, metodo='sarima', nivel=0.9, orden=(0, 1, 1), orden_estacional=(0, 1, 1, 12), simulaciones=2000, semilla=0)

Pronostica la inflación a partir del índice de precios.

Parameters:

Name Type Description Default
indice Series

Índice de precios mensual (INPC, subyacente…), al menos 5 años.

required
horizonte int

Meses a pronosticar.

12
metodo ('sarima', 'ingenuo')
  • "sarima": SARIMA sobre el logaritmo del índice. El valor por omisión, (0,1,1)(0,1,1)₁₂, es el «modelo de aerolíneas», la referencia habitual para series mensuales con estacionalidad.
  • "ingenuo": la inflación anual se mantiene en su último valor. Es sorprendentemente difícil de superar a 12 meses; todo modelo debería compararse contra él.
"sarima"
nivel float

Cobertura del intervalo (0.90 → de 5 % a 95 %). Solo con "sarima".

0.9
orden tuple

Especificación del SARIMA.

(0, 1, 1)
orden_estacional tuple

Especificación del SARIMA.

(0, 1, 1)
simulaciones int

Trayectorias simuladas para construir el intervalo de la inflación anual, que depende de varios meses pronosticados a la vez.

2000
semilla (int, opcional)

Fija las simulaciones para que el resultado sea reproducible.

0

Returns:

Type Description
DataFrame

Una fila por mes futuro: indice, mensual, anual y, con SARIMA, anual_inf y anual_sup. Todo en % salvo el índice.

Notes

El intervalo refleja solo la incertidumbre de los choques futuros bajo el modelo; no incluye la de los parámetros ni la de haber elegido mal el modelo, así que es más estrecho que la incertidumbre real.

evaluar_pronosticos

evaluar_pronosticos(indice, horizontes=(1, 3, 6, 12), *, desde=None, paso=3, metodos=METODOS, orden=(0, 1, 1), orden_estacional=(0, 1, 1, 12))

Compara los métodos con pronósticos fuera de muestra de origen móvil.

Para cada fecha de origen se estima el modelo solo con los datos disponibles hasta entonces, se pronostica la inflación anual y se compara con lo que realmente ocurrió.

Parameters:

Name Type Description Default
horizontes tuple de int

Meses hacia adelante a evaluar.

(1, 3, 6, 12)
desde (fecha, opcional)

Primer origen. Por omisión, el último tercio de la muestra.

None
paso int

Meses entre orígenes consecutivos. 1 es lo más preciso y lo más lento (cada origen reestima el SARIMA).

3

Returns:

Type Description
DataFrame

Raíz del error cuadrático medio, en puntos porcentuales de inflación anual, por horizonte (filas) y método (columnas), más n pronósticos evaluados. Los errores individuales quedan en .attrs["errores"].

Rendimientos e inflación implícita

rendimiento_bono

rendimiento_bono(precio_limpio, cupon, plazo_dias, valor_nominal=100, dias_cupon=182)

Rendimiento a vencimiento (% anual) a partir del precio limpio.

Inversa de :func:precio_bono, resuelta por bisección. Para un Udibono, el precio debe estar en UDIS (precio en pesos entre el valor de la UDI) y el resultado es un rendimiento real.

Examples:

>>> round(float(rendimiento_bono(100, 8, 3640)), 4)   # a la par rinde su cupón
8.0

precio_bono

precio_bono(rendimiento, cupon, plazo_dias, valor_nominal=100, dias_cupon=182)

Precio limpio de un bono a tasa fija con la convención mexicana.

Parameters:

Name Type Description Default
rendimiento número o Series

Rendimiento a vencimiento, en % anual.

required
cupon número o Series

Tasa cupón, en % anual.

required
plazo_dias número o Series

Días por vencer.

required
valor_nominal float

100 pesos en los Bonos M; 100 UDIS en los Udibonos.

100
dias_cupon int

Días entre cupones (182).

182
Notes

Con R = rendimiento × 182/360, cupón C = VN × cupón × 182/360, K cupones por cobrar y d días transcurridos del cupón vigente:

precio sucio = [C + C·(1/R − 1/(R(1+R)^(K−1))) + VN/(1+R)^(K−1)] / (1+R)^(1−d/182)

y el precio limpio descuenta los intereses devengados C·d/182.

inflacion_implicita

inflacion_implicita(nominal, real)

Inflación implícita (breakeven): (1 + i) / (1 + r) − 1, en %.

Es la inflación promedio que iguala el rendimiento de un bono nominal con el de uno indexado a la inflación del mismo plazo.

Parameters:

Name Type Description Default
nominal número o Series

Rendimiento nominal (Bono M, Cetes), en % anual.

required
real número o Series

Rendimiento real (Udibono), en % anual.

required
Notes

No es una expectativa pura. Incluye una prima por riesgo inflacionario (la sube) y una prima de liquidez de los Udibonos (la baja). Banxico la llama «compensación por inflación y riesgo inflacionario». Compárala con las expectativas de la encuesta ("expectativa_inflacion_12m") antes de interpretarla.

Examples:

>>> round(inflacion_implicita(9.5, 5.0), 4)
4.2857

inflacion_implicita_forward

inflacion_implicita_forward(corta, larga, plazo_corto, plazo_largo)

Inflación implícita entre dos plazos futuros, en % anual.

Con las implícitas a 10 y 20 años, por ejemplo, devuelve la que el mercado descuenta para los diez años que empiezan dentro de diez («10a10a»). Aísla el largo plazo de los choques de corto plazo.

Parameters:

Name Type Description Default
corta número o Series

Inflación implícita al plazo corto y al largo, en %.

required
larga número o Series

Inflación implícita al plazo corto y al largo, en %.

required
plazo_corto float

Plazos en años.

required
plazo_largo float

Plazos en años.

required

Cambio de unidades

estandarizar

estandarizar(datos, referencia=None)

Puntaje z: (x − media) / desviación estándar.

Parameters:

Name Type Description Default
referencia Series o DataFrame, opcional

Muestra de la que se calculan media y desviación. Al evaluar un modelo pasa aquí solo el conjunto de entrenamiento para no filtrar información del futuro (data leakage).

None

min_max

min_max(datos, a=0, b=1, referencia=None)

Reescala linealmente al intervalo [a, b].

Muy sensible a valores atípicos. Con referencia (entrenamiento) los datos nuevos pueden salir de [a, b]: eso es información, no un error.

escalar_robusto

escalar_robusto(datos, referencia=None)

(x − mediana) / rango intercuartílico: resistente a valores atípicos.

Estacionalidad y estacionariedad

desestacionalizar

desestacionalizar(serie, modelo='multiplicativo', periodo=None)

Ajuste estacional sencillo por descomposición clásica (medias móviles).

Sirve para explorar y enseñar. No reproduce las cifras oficiales, que usan X-13ARIMA-SEATS con efectos de calendario; si existe la serie desestacionalizada oficial (p. ej. "igae_desestacionalizado"), úsala.

Parameters:

Name Type Description Default
modelo ('multiplicativo', 'aditivo')
"multiplicativo"
periodo (int, opcional)

Observaciones por ciclo; por omisión 12 o 4 según la frecuencia.

None

prueba_adf

prueba_adf(datos, alfa=0.05)

Prueba Dickey–Fuller Aumentada para una o varias series.

Acepta un diccionario {nombre: serie}, ideal para comparar la misma variable bajo distintas transformaciones. H0: la serie tiene raíz unitaria; se rechaza (estacionaria = True) cuando p_valor < alfa.

Excepciones

Excepciones de la librería.

Todas heredan de :class:BanxicoError, así que basta un solo except para atrapar cualquier fallo relacionado con el SIE.

BanxicoError

Bases: Exception

Error base de la librería.

TokenNoEncontrado

Bases: BanxicoError

No se encontró un token en ninguna de las fuentes soportadas.

TokenInvalido

Bases: BanxicoError

El SIE rechazó el token (o tiene un formato imposible).

LimiteExcedido

Bases: BanxicoError

Se superó el límite de consultas del token.

Attributes:

Name Type Description
segundos int | None

Segundos que faltan para que Banxico desbloquee el token.

SerieNoEncontrada

Bases: BanxicoError

La clave no existe en el SIE ni en el catálogo de alias.

SinDatos

Bases: BanxicoError

La consulta fue válida pero no devolvió ninguna observación.

ErrorDeConexion

Bases: BanxicoError

No fue posible comunicarse con el servidor del SIE.