Metadata-Version: 2.4
Name: macroshock
Version: 0.1.2
Summary: Powerful time series econometrics for Structural Vector Autoregressions (SVAR)
Author-email: Patricio Arias <patoariaslopez2@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Patricio
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: matplotlib>=3.7.0
Dynamic: license-file

# macroshock

**macroshock** es una librería de Python para la estimación y el análisis de modelos **SVAR** (Structural Vector Autoregression) orientada a macroeconometría aplicada. Permite estimar VARs con restricciones, identificar el sistema estructural mediante cuatro metodologías distintas, calcular funciones impulso-respuesta (IRF), descomposición de varianza del error de pronóstico (FEVD) y pronósticos, todo con intervalos de confianza vía bootstrap y graficado listo para usar.

\---

## Características principales

* **Estimación de VAR restringido** (GLS a la Lütkepohl), con soporte para:

  * Constante, tendencia y tendencia cuadrática.
  * Variables exógenas.
  * Dummies estacionales (trimestrales o mensuales).
  * Restricciones lineales sobre los coeficientes (`restrictions='zeros'` o `'custom zeros'`).
* **Cuatro métodos de identificación estructural**:

|Método|Descripción|
|-|-|
|`short`|Restricciones de corto plazo (Cholesky o restricciones custom vía optimización)|
|`long`|Restricciones de largo plazo (tipo Blanchard-Quah)|
|`signs`|Restricciones de signo (muestreo de rotaciones ortogonales con aceptación/rechazo)|
|`IV`|Identificación por variables instrumentales (proxy-SVAR)|

* **Funciones impulso-respuesta (IRF)** con bandas de confianza.
* **Descomposición de varianza del error de pronóstico (FEVD)**.
* **Pronósticos condicionales** con bandas de confianza.
* **Bootstrap** (remuestreo normal o *wild*) para inferencia.
* **Gráficos integrados** para IRF, pronósticos y FEVD, listos para publicación.
* **Prueba de estabilidad** del sistema (raíces del polinomio característico).

\---

## Instalación

```bash
pip install macroshock
```

### Requisitos

* Python >= 3.9
* `numpy`
* `pandas`
* `scipy`
* `matplotlib`

\---

## Inicio rápido

```python
import pandas as pd
from macroshock import SVAR

# df es un DataFrame con tus series en columnas
df = pd.read\_csv("mi\_dataset.csv")

modelo = SVAR(
    data=df,
    variables=\["pib", "inflacion", "tasa\_interes"],
    lags=4,
    const=1,          # 0: sin constante, 1: constante, 2: +tendencia, 3: +tendencia cuadrática
    method="short",    # 'short', 'long', 'signs' o 'IV'
    steps=24,          # horizonte para IRF/FEVD
    horizon=8,         # horizonte de pronóstico
    past=12,           # periodos históricos a mostrar en el pronóstico
    alpha=32,          # nivel para el intervalo de confianza (32 -> banda central 68%)
    reps\_default=1000, # réplicas de bootstrap
)

# Corre el pipeline completo: construcción de Y/X, estimación VAR,
# identificación estructural y resumen de resultados
modelo.run(showIR=True, showFC=True, showVD=True)

# Chequeo de estabilidad del sistema
modelo.stability(show=True)
```

### Uso paso a paso

```python
modelo.YX()             # construye Y, X y la matriz de restricciones R
modelo.VAR()             # estima el VAR reducido y la matriz companion F
modelo.S()                # identifica el sistema estructural (matriz B)
modelo.summary()          # imprime el resumen de la estimación

# Impulso-respuesta al shock 1, con bandas "pair" (percentil bajo/alto)
ir = modelo.ImpulseResponse(shock=1, show=True, bands="pair")

# Pronóstico con bandas "many" (múltiples niveles de confianza apilados)
fc = modelo.Forecast(show=True, bands="many")

# Descomposición de varianza del error de pronóstico para el shock 1
vd = modelo.VarianceDecomp(shock=1, show=True)
```

Cada uno de estos métodos regresa un diccionario con la estimación puntual y las bandas de confianza en distintos niveles (`'point'`, `'low'`, `'high'`, `2.5`, `5`, `95`, `97.5`, `0.5`, `99.5`), indexado por nombre de variable.

\---

## Identificación estructural

### 1\. Corto plazo (Cholesky / restricciones custom)

```python
modelo = SVAR(data=df, variables=variables, lags=4, method="short")
```

Por defecto usa la descomposición de Cholesky. Si se pasa `matrix\_short` (matriz binaria de 1s y 0s), se resuelve numéricamente la matriz `B` que satisface las restricciones de cero indicadas.

### 2\. Largo plazo (Blanchard-Quah)

```python
modelo = SVAR(data=df, variables=variables, lags=4, method="long")
```

### 3\. Restricciones de signo

```python
matrix\_signs = \[\[1, -1, 0],
                \[1,  1, 0],
                \[0,  0, 1]]

modelo = SVAR(
    data=df, variables=variables, lags=4,
    method="signs",
    matrix\_signs=matrix\_signs,
    steps\_signs=4,       # horizontes en los que se verifican los signos
    reps\_default=1000,   # número de matrices B aceptadas
)
```

### 4\. Variables instrumentales (Proxy-SVAR)

```python
modelo = SVAR(
    data=df, variables=variables, lags=4,
    method="IV",
    iv=\["instrumento\_1"],  # columna(s) del DataFrame con el/los instrumento(s)
)
```

\---

## Estructura del paquete

```
macroshock/
├── data.py             # construcción de Y, X y matriz de restricciones R
├── var.py               # estimación del VAR reducido (GLS restringido, IC, t-stats)
├── stats.py              # utilidades estadísticas (CDF y p-valores t-Student)
├── identification.py      # los 4 métodos de identificación estructural
├── irf.py                  # funciones impulso-respuesta y bandas desde bootstrap
├── fevd.py                  # descomposición de varianza del error de pronóstico
├── fc.py                     # cálculo de pronósticos
├── bootstrap.py                # bootstrap (normal / wild) para IR, FC y FEVD
├── plotting.py                  # gráficos de IRF, pronóstico y FEVD
└── macroshock.py                 # clase principal SVAR (y esqueletos de SVEC, LP para desarrollo futuro)
```

\---

## Hoja de ruta

* \[ ] Documentación completa (Sphinx / ReadTheDocs)
* \[ ] Modelo SVEC (Vector Error Correction estructural)
* \[ ] Local Projections (LP)
* \[ ] Descomposición histórica (`HistoricalDecomp`)
* \[ ] Tests unitarios y CI

\---

## Contribuciones

Los issues y pull requests son bienvenidos. Si encuentras un bug o tienes una propuesta de mejora, abre un issue en el repositorio del proyecto.

## Licencia

Este proyecto se distribuye bajo la licencia MIT. Ver el archivo `LICENSE` para más detalles.

