macroshock 0.1.2__tar.gz → 0.2.2__tar.gz

macroshock-0.2.2/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: macroshock
+Version: 0.2.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.
+        
+Project-URL: GitHub repository, https://github.com/patricioariaslpz/macroshock.git
+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** is a Python library for the estimation and analysis of **SVAR** (Structural Vector Autoregression) models aimed at applied macroeconometrics. It allows you to estimate restricted VARs, identify the structural system using four different methodologies, compute impulse-response functions (IRF), forecast error variance decomposition (FEVD), and forecasts, all with bootstrap confidence intervals and ready-to-use plotting.
+
+## Main Features
+
+* - **Restricted VAR estimation** (Lütkepohl-style GLS), with support for:
+
+  - Constant, trend and quadratic trend.
+  - Exogenous variables.
+  - Seasonal dummies (quarterly or monthly).
+  - Linear restrictions on the coefficients (`restrictions='zeros'` or `'custom zeros'`).
+* - **Four structural identification methods**:
+
+|Method|Description|
+|-|-|
+|`short`|Short-run restrictions (Cholesky or custom restrictions via optimization)|
+|`long`|Long-run restrictions (Cholesky or custom restrictions via optimization)|
+|`signs`|Sign restrictions (orthogonal rotation sampling with acceptance/rejection)|
+|`IV`|Instrumental variable identification (proxy-SVAR)|
+
+* - **Impulse-response functions (IRF)** with confidence bands.
+* - **Forecast error variance decomposition (FEVD)**.
+* - **Conditional forecasts** with confidence bands.
+* - **Bootstrap** (normal or *wild* resampling) for inference.
+* - **Built-in plots** for IRF, forecasts and FEVD, publication-ready.
+* - **Stability test** of the system (characteristic polynomial roots).
+
+## Installation
+
+```bash
+pip install macroshock
+```
+
+### Requirements
+
+* Python >= 3.9
+* `numpy >= 1.24.0`
+* `pandas >= 2.0.0`
+* `scipy`
+* `matplotlib >= 3.7.0`
+
+## Quick Start
+
+```python
+import pandas as pd
+from macroshock import SVAR
+
+# df is a DataFrame with your series in columns
+df = pd.read\_csv("my\_dataset.csv")
+
+model = SVAR(
+    data=df,
+    variables=\["gdp", "inflation", "interest\_rate"],
+    lags=4,
+    const=1,          # 0: no constant, 1: constant, 2: +trend, 3: +quadratic trend
+    method="short",    # 'short', 'long', 'signs' or 'IV'
+    steps=24,          # horizon for IRF/FEVD
+    horizon=8,         # forecast horizon
+    past=12,           # past periods to show in the forecast
+    alpha=32,          # confidence interval level (32 -> 68% central band)
+    reps=1000, # bootstrap replications
+)
+
+# Runs the complete pipeline: Y/X construction, VAR estimation,
+# structural identification and results summary
+model.run(showIR=True, showFC=True, showVD=True)
+
+# System stability check
+model.stability(show=True)
+```
+
+### Step-by-step Usage
+
+```python
+model.YX()             # builds Y, X and the restriction matrix R
+model.VAR()             # estimates the reduced-form VAR and the companion matrix F
+model.S()                # identifies the structural system (matrix B)
+model.summary()          # prints the estimation summary
+
+# Impulse response to shock 1, with "pair" bands (low/high percentile)
+ir = model.ImpulseResponse(1, show=True, bands="pair")
+
+# Forecast with "many" bands (multiple stacked confidence levels)
+fc = model.Forecast(show=True, bands="many")
+
+# Forecast error variance decomposition for variable 1
+vd = model.VarianceDecomp(1, show=True)
+```
+
+Each of these methods returns a dictionary with the point estimate and confidence bands at different levels (`'point'`, `'low'`, `'high'`, `2.5`, `5`, `95`, `97.5`, `0.5`, `99.5`), indexed by variable name.
+
+## Structural Identification
+
+### 1\. Short-run (Cholesky / custom restrictions)
+
+```python
+model = SVAR(data=df, variables=variables, lags=4, method="short")
+```
+
+By default it uses the Cholesky decomposition. If `matrix\_short` is passed (a binary matrix of 1s and 0s), the `B` matrix satisfying the indicated zero restrictions is solved numerically.
+
+### 2\. Long-run (Blanchard-Quah)
+
+```python
+model = SVAR(data=df, variables=variables, lags=4, method="long")
+```
+
+By default it uses the Cholesky decomposition. If `matrix\_long` is passed (a binary matrix of 1s and 0s), the `B` matrix satisfying the indicated zero restrictions is solved numerically.
+
+### 3\. Sign restrictions
+
+```python
+matrix\_signs = \[\[1, -1, 0],
+                \[1,  1, 0],
+                \[0,  0, 1]]
+
+model = SVAR(
+    data=df, variables=variables, lags=4,
+    method="signs",
+    matrix\_signs=matrix\_signs,
+    steps\_signs=4,       # horizons over which signs are checked
+    reps=1000,   # number of accepted B matrices
+)
+```
+
+### 4\. Instrumental variables (Proxy-SVAR)
+
+```python
+model = SVAR(
+    data=df, variables=variables, lags=4,
+    method="IV",
+    iv=\["instrument\_1"],  # DataFrame column(s) with the instrument(s)
+)
+```
+
+## Package Structure
+
+
+```
+macroshock/
+├── data.py # construction of Y, X and restriction matrix R
+├── var.py # reduced-form VAR estimation (restricted GLS, IC, t-stats)
+├── stats.py # statistical utilities (Student's t CDF and p-values)
+├── identification.py # the 4 structural identification methods
+├── irf.py # impulse-response functions and bands from bootstrap
+├── fevd.py # forecast error variance decomposition
+├── fc.py # forecast computation
+├── bootstrap.py # bootstrap (normal / wild) for IR, FC and FEVD
+├── plotting.py # IRF, forecast and FEVD plots
+└── macroshock.py # main SVAR class (and SVEC, LP scaffolds for future development)
+```
+
+## Roadmap
+
+* Full documentation (Sphinx / ReadTheDocs)
+* SVEC model (structural Vector Error Correction)
+* Local Projections (LP)
+* Historical decomposition (`HistoricalDecomp`)
+* Unit tests and CI
+
+## Contributing
+
+Issues and pull requests are welcome. If you find a bug or have an improvement proposal, open an issue in the project's repository.
+
+## License
+
+This project is distributed under the MIT license. See the `LICENSE` file for more details.
+

macroshock-0.2.2/README.md

@@ -0,0 +1,169 @@
+# macroshock
+
+**macroshock** is a Python library for the estimation and analysis of **SVAR** (Structural Vector Autoregression) models aimed at applied macroeconometrics. It allows you to estimate restricted VARs, identify the structural system using four different methodologies, compute impulse-response functions (IRF), forecast error variance decomposition (FEVD), and forecasts, all with bootstrap confidence intervals and ready-to-use plotting.
+
+## Main Features
+
+* - **Restricted VAR estimation** (Lütkepohl-style GLS), with support for:
+
+  - Constant, trend and quadratic trend.
+  - Exogenous variables.
+  - Seasonal dummies (quarterly or monthly).
+  - Linear restrictions on the coefficients (`restrictions='zeros'` or `'custom zeros'`).
+* - **Four structural identification methods**:
+
+|Method|Description|
+|-|-|
+|`short`|Short-run restrictions (Cholesky or custom restrictions via optimization)|
+|`long`|Long-run restrictions (Cholesky or custom restrictions via optimization)|
+|`signs`|Sign restrictions (orthogonal rotation sampling with acceptance/rejection)|
+|`IV`|Instrumental variable identification (proxy-SVAR)|
+
+* - **Impulse-response functions (IRF)** with confidence bands.
+* - **Forecast error variance decomposition (FEVD)**.
+* - **Conditional forecasts** with confidence bands.
+* - **Bootstrap** (normal or *wild* resampling) for inference.
+* - **Built-in plots** for IRF, forecasts and FEVD, publication-ready.
+* - **Stability test** of the system (characteristic polynomial roots).
+
+## Installation
+
+```bash
+pip install macroshock
+```
+
+### Requirements
+
+* Python >= 3.9
+* `numpy >= 1.24.0`
+* `pandas >= 2.0.0`
+* `scipy`
+* `matplotlib >= 3.7.0`
+
+## Quick Start
+
+```python
+import pandas as pd
+from macroshock import SVAR
+
+# df is a DataFrame with your series in columns
+df = pd.read\_csv("my\_dataset.csv")
+
+model = SVAR(
+    data=df,
+    variables=\["gdp", "inflation", "interest\_rate"],
+    lags=4,
+    const=1,          # 0: no constant, 1: constant, 2: +trend, 3: +quadratic trend
+    method="short",    # 'short', 'long', 'signs' or 'IV'
+    steps=24,          # horizon for IRF/FEVD
+    horizon=8,         # forecast horizon
+    past=12,           # past periods to show in the forecast
+    alpha=32,          # confidence interval level (32 -> 68% central band)
+    reps=1000, # bootstrap replications
+)
+
+# Runs the complete pipeline: Y/X construction, VAR estimation,
+# structural identification and results summary
+model.run(showIR=True, showFC=True, showVD=True)
+
+# System stability check
+model.stability(show=True)
+```
+
+### Step-by-step Usage
+
+```python
+model.YX()             # builds Y, X and the restriction matrix R
+model.VAR()             # estimates the reduced-form VAR and the companion matrix F
+model.S()                # identifies the structural system (matrix B)
+model.summary()          # prints the estimation summary
+
+# Impulse response to shock 1, with "pair" bands (low/high percentile)
+ir = model.ImpulseResponse(1, show=True, bands="pair")
+
+# Forecast with "many" bands (multiple stacked confidence levels)
+fc = model.Forecast(show=True, bands="many")
+
+# Forecast error variance decomposition for variable 1
+vd = model.VarianceDecomp(1, show=True)
+```
+
+Each of these methods returns a dictionary with the point estimate and confidence bands at different levels (`'point'`, `'low'`, `'high'`, `2.5`, `5`, `95`, `97.5`, `0.5`, `99.5`), indexed by variable name.
+
+## Structural Identification
+
+### 1\. Short-run (Cholesky / custom restrictions)
+
+```python
+model = SVAR(data=df, variables=variables, lags=4, method="short")
+```
+
+By default it uses the Cholesky decomposition. If `matrix\_short` is passed (a binary matrix of 1s and 0s), the `B` matrix satisfying the indicated zero restrictions is solved numerically.
+
+### 2\. Long-run (Blanchard-Quah)
+
+```python
+model = SVAR(data=df, variables=variables, lags=4, method="long")
+```
+
+By default it uses the Cholesky decomposition. If `matrix\_long` is passed (a binary matrix of 1s and 0s), the `B` matrix satisfying the indicated zero restrictions is solved numerically.
+
+### 3\. Sign restrictions
+
+```python
+matrix\_signs = \[\[1, -1, 0],
+                \[1,  1, 0],
+                \[0,  0, 1]]
+
+model = SVAR(
+    data=df, variables=variables, lags=4,
+    method="signs",
+    matrix\_signs=matrix\_signs,
+    steps\_signs=4,       # horizons over which signs are checked
+    reps=1000,   # number of accepted B matrices
+)
+```
+
+### 4\. Instrumental variables (Proxy-SVAR)
+
+```python
+model = SVAR(
+    data=df, variables=variables, lags=4,
+    method="IV",
+    iv=\["instrument\_1"],  # DataFrame column(s) with the instrument(s)
+)
+```
+
+## Package Structure
+
+
+```
+macroshock/
+├── data.py # construction of Y, X and restriction matrix R
+├── var.py # reduced-form VAR estimation (restricted GLS, IC, t-stats)
+├── stats.py # statistical utilities (Student's t CDF and p-values)
+├── identification.py # the 4 structural identification methods
+├── irf.py # impulse-response functions and bands from bootstrap
+├── fevd.py # forecast error variance decomposition
+├── fc.py # forecast computation
+├── bootstrap.py # bootstrap (normal / wild) for IR, FC and FEVD
+├── plotting.py # IRF, forecast and FEVD plots
+└── macroshock.py # main SVAR class (and SVEC, LP scaffolds for future development)
+```
+
+## Roadmap
+
+* Full documentation (Sphinx / ReadTheDocs)
+* SVEC model (structural Vector Error Correction)
+* Local Projections (LP)
+* Historical decomposition (`HistoricalDecomp`)
+* Unit tests and CI
+
+## Contributing
+
+Issues and pull requests are welcome. If you find a bug or have an improvement proposal, open an issue in the project's repository.
+
+## License
+
+This project is distributed under the MIT license. See the `LICENSE` file for more details.
+

{macroshock-0.1.2 → macroshock-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "macroshock"
-version = "0.1.2"
+version = "0.2.2"
 requires-python = ">=3.10"
 dependencies = [
     "numpy>=1.24.0",
@@ -18,3 +18,6 @@ authors = [
 description = "Powerful time series econometrics for Structural Vector Autoregressions (SVAR)"
 readme = {file = "README.md", content-type = "text/markdown"}
 license = { file = "LICENSE"}
+
+[project.urls]
+"GitHub repository" = "https://github.com/patricioariaslpz/macroshock.git"

{macroshock-0.1.2 → macroshock-0.2.2}/src/macroshock/bootstrap.py

@@ -5,10 +5,12 @@ import numpy as np
 import pandas as pd
 from scipy.linalg import solve_triangular
 from .var import estimate_var
+from .irf import impulse_response
 from .fc import compute_forecast
+from .fevd import forecast_error_variance_decomposition
 
 
-def bootstrap_svar(model, typ: str, shock: int = 1):
+def bootstrap_svar(model, typ: str, shock: int = 1, reps: int = 100, impact: float = 1.0, steps: int = 30, horizon: int = 5, past: int = 24):
     """
     Replica la lógica original de SVAR.Bootstrap, pero fuera de la clase.
 
@@ -28,25 +30,28 @@ def bootstrap_svar(model, typ: str, shock: int = 1):
         - IR: (reps, steps)
         - FC: (reps, past + horizon)
     """
+    if model.method == 'signs':
+        raise ValueError("No bootstrap in sign restriction SVAR")
+    
+    
     # BEGIN BOOTSTRAP
     b = 0
 
     if typ == "IR":
-        draws = {var: np.zeros((model.reps, model.steps)) for var in model.variables}
+        draws = {var: np.zeros((reps, steps)) for var in model.variables}
     elif typ == "FC":
-        draws = {
-            var: np.zeros((model.reps, model.past + model.horizon))
-            for var in model.variables
-        }
+        draws = {var: np.zeros((reps, past + horizon)) for var in model.variables}
+    elif typ == "VD":
+        draws = {var: np.zeros((reps, steps)) for var in model.variables}
     else:
-        raise ValueError("typ must be 'IR' or 'FC'.")
+        raise ValueError("typ must be 'IR', 'FC' or 'VD'.")
 
     while True:
         # progreso
         if b in list(
-            range(int(model.reps / 10) - 1, model.reps, int(model.reps / 10))
+            range(int(reps / 10) - 1, reps, int(reps / 10))
         ):
-            print(str(b + 1) + "/" + str(model.reps))
+            print(str(b + 1) + "/" + str(reps))
 
         # ---------- tipo de remuestreo ----------
         if model.resampling == 1:  # normal
@@ -152,11 +157,11 @@ def bootstrap_svar(model, typ: str, shock: int = 1):
                 [np.ones((model.n_obs, 1)), trend, trend**2, Xsim]
             )
 
-        if model.EXOGdata is not None:
-            if len(model.EXOG) == model.n_obs:
-                Xsim_exog = model.EXOGdata
+        if model.data_exogenous is not None:
+            if len(model.variables_exogenous) == model.n_obs:
+                Xsim_exog = model.data_exogenous
             else:
-                Xsim_exog = model.EXOGdata[-model.n_obs :]
+                Xsim_exog = model.data_exogenous[-model.n_obs :]
                 if len(Xsim_exog) != model.n_obs:
                     print("Exogenous variables in different domain")
             Xsim = np.hstack([Xsim, Xsim_exog])
@@ -237,8 +242,8 @@ def bootstrap_svar(model, typ: str, shock: int = 1):
 
         # ---------- almacenar draws ----------
         if typ == "IR":
-            ir_b = model.IR(Bsim, Fsim, shock)
-
+            ir_b = impulse_response(Bsim, Fsim, shock, steps=steps, impact=impact)
+        
             if np.any(Bsim != 0):
                 if model.method in ("short", "long", "IV"):
                     for k in range(model.n_vars):
@@ -252,8 +257,20 @@ def bootstrap_svar(model, typ: str, shock: int = 1):
                     for k in range(model.n_vars):
                         draws[model.variables[k]][b, :] = fc_b[:, k]
                     b += 1
+        
+        if typ == "VD":
+            vd_dict = forecast_error_variance_decomposition(
+                Bsim, Fsim, steps=steps
+            )
+            if np.any(Bsim != 0):
+                if model.method in ("short", "long", "IV"):
+                    for k in range(model.n_vars):
+                        # vd_dict[k + 1] gets the (steps, n_vars) FEVD matrix for variable k+1.
+                        # [:, shock - 1] isolates the proportion of variance explained by 'shock'.
+                        draws[model.variables[k]][b, :] = vd_dict[k + 1][:, shock - 1]
+                    b += 1
 
-        if b >= model.reps:
+        if b >= reps:
             break
 
     return draws

{macroshock-0.1.2 → macroshock-0.2.2}/src/macroshock/data.py

@@ -32,11 +32,11 @@ def YX(model) -> YXR:
     
     model.n_obs, _ = X.shape
     
-    if model.EXOGdata is not None:
+    if model.data_exogenous is not None:
         if model.n_obsex==model.n_obs:
-            X_exog=model.EXOGdata
+            X_exog=model.data_exogenous
         else:
-            X_exog=model.EXOGdata[-model.n_obs:]
+            X_exog=model.data_exogenous[-model.n_obs:]
             if len(X_exog)!=model.n_obs:
                 print('Exogenous variables in different domain')
         X=np.hstack([X,X_exog])

{macroshock-0.1.2 → macroshock-0.2.2}/src/macroshock/fc.py

@@ -38,7 +38,7 @@ def compute_forecast(modelo, F):
         if modelo.const == 1:
             FYs += beta_const
         elif modelo.const == 2:
-            FYs += beta_const + ((i + modelo.lags) * beta_trend)
+            FYs += beta_const + (i * beta_trend)
         elif modelo.const == 3:
             FYs += beta_const + (i * beta_trend) + ((i**2) * beta_sqrd)
             

macroshock-0.2.2/src/macroshock/fevd.py

@@ -0,0 +1,63 @@
+# fevd.py
+from __future__ import annotations
+
+import numpy as np
+
+
+def forecast_error_variance_decomposition(
+    B: np.ndarray,
+    F: np.ndarray,
+    steps: int = 10,
+) -> dict[int, np.ndarray]:
+    """Compute Forecast Error Variance Decomposition (FEVD) for a given structural matrix B
+
+    and companion matrix F.
+
+    Parameters
+    ----------
+    B : np.ndarray
+        Impact matrix of shape (n_vars, n_vars).
+    F : np.ndarray
+        Companion matrix of shape (n_vars * lags, n_vars * lags).
+    steps : int, optional
+        Forecast horizon steps (default is 10).
+
+    Returns
+    -------
+    dict[int, np.ndarray]
+        Dictionary keyed by 1-based variable index (1, 2, ..., n_vars).
+        Each value is an array of shape (steps, n_vars) containing the share
+        of variance contributed by each shock j to variable i over horizon h.
+    """
+    B = np.asarray(B, dtype=float)
+    F = np.asarray(F, dtype=float)
+
+    n_vars = B.shape[0]
+
+    # 1. Pre-calculate Orthogonalized Impulse Responses for all horizons.
+    # Accumulate F^h incrementally (F^h = F^(h-1) @ F) instead of calling
+    # np.linalg.matrix_power(F, h) from scratch at every horizon.
+    theta = np.zeros((steps, n_vars, n_vars))
+    F_power = np.eye(F.shape[0])  # F^0
+    for h in range(steps):
+        Psi_h = F_power[:n_vars, :n_vars]
+        theta[h] = Psi_h @ B
+        F_power = F_power @ F  # advance to F^(h+1) for the next iteration
+
+    # 2. Calculate Variance Decomposition per variable
+    VD = {}
+    for i in range(n_vars):
+        vardec = np.zeros((steps, n_vars))
+        for k in range(steps):
+            # Squared responses of variable i to all shocks j up to step k
+            squared_responses = theta[: k + 1, i, :] ** 2
+            mse_ij = np.sum(squared_responses, axis=0)
+
+            total_mse_i = np.sum(mse_ij)
+            if total_mse_i > 0:
+                vardec[k, :] = mse_ij / total_mse_i
+
+        # Store using 1-based variable index
+        VD[i + 1] = vardec
+
+    return VD