Help for package EconCausal

Type:

Package

Title:

Causal Analysis for Macroeconomic Time Series (ECM-MARS, BSTS, Bayesian GLM-AR(1))

Version:

1.0.2

Description:

Implements three complementary pipelines for causal analysis on macroeconomic time series: (1) Error-Correction Models with Multivariate Adaptive Regression Splines (ECM-MARS), (2) Bayesian Structural Time Series (BSTS), and (3) Bayesian GLM with AR(1) errors validated with Leave-Future-Out (LFO). Heavy backends (Stan) are optional and never used in examples or tests.

VignetteBuilder:

knitr

License:

MIT + file LICENSE

Encoding:

UTF-8

Depends:

R (≥ 4.1)

Imports:

brms, readxl, dplyr, tidyr, tibble, purrr, bsts, BoomSpikeSlab, tseries, urca, vars, progressr, future.apply, rlang, magrittr, parallel, stats, utils

Suggests:

knitr, cmdstanr, rstan, future, RhpcBLASctl, rmarkdown, testthat (≥ 3.0.0)

URL:

https://github.com/IsadoreNabi/EconCausal

BugReports:

https://github.com/IsadoreNabi/EconCausal/issues

Additional_repositories:

https://stan-dev.r-universe.dev

RoxygenNote:

7.3.3

Config/testthat/edition:

Language:

en-US

NeedsCompilation:

Packaged:

2025-10-01 21:20:48 UTC; ROG

Author:

José Mauricio Gómez Julián [aut, cre]

Maintainer:

José Mauricio Gómez Julián <isadore.nabi@pm.me>

Repository:

CRAN

Date/Publication:

2025-10-08 08:40:24 UTC

Bayesian Generalized Linear Model with AR(1) Errors

Description

Implements a Bayesian GLM with autoregressive errors of order 1 for causal inference between economic variables, with emphasis on temporal stability through Leave-Future-Out cross-validation.

Usage

bglmar1(
  data_path,
  circ_vars,
  prod_vars,
  max_lag = 3,
  initial_frac = 0.7,
  initial_min = 90,
  test_h = 12,
  step_h = 12,
  lfo_window = "sliding",
  chains = 4,
  parallel_chains = 4,
  iter = 1500,
  warmup = 750,
  adapt_delta = 0.95,
  trees = 12,
  seed = 2025,
  support_min = 0.6,
  folds_min = 5,
  sup_hi = 0.7,
  sup_lo = 0.6,
  backend = c("auto", "rstan", "cmdstanr")
)

Arguments

data_path

Path to Excel file containing the data

circ_vars

Character vector of circulation variable names

prod_vars

Character vector of production variable names

max_lag

Maximum number of lags for independent variables (default: 3)

initial_frac

Initial fraction of data for training (default: 0.7)

initial_min

Minimum number of observations for initial training (default: 90)

test_h

Test horizon in months (default: 12)

step_h

Step size between folds in months (default: 12)

lfo_window

Type of window for LFO ("sliding" or "expanding", default: "sliding")

chains

Number of MCMC chains (default: 4)

parallel_chains

Number of parallel chains (default: 4)

iter

Total iterations per chain (default: 1500)

warmup

Warmup iterations per chain (default: 750)

adapt_delta

Adapt delta parameter for NUTS (default: 0.95)

trees

Maximum tree depth for NUTS (default: 12)

seed

Random seed (default: 2025)

support_min

Minimum support threshold for stable relationships (default: 0.6)

folds_min

Minimum number of folds required (default: 5)

sup_hi

High support threshold (default: 0.7)

sup_lo

Low support threshold (default: 0.6)

backend

Backend for Stan compilation: "auto" (default), "rstan", or "cmdstanr". If "auto", the function uses 'rstan' when available, otherwise tries 'cmdstanr'.

Details

This function implements a Bayesian GLM with AR(1) errors for assessing causal relationships between economic variables. It uses Leave-Future-Out cross-validation with sliding windows to evaluate temporal stability of relationships. The function no longer requires 'cmdstanr' at install time; if 'backend = "cmdstanr"' is requested but 'cmdstanr' (and a working CmdStan) are not available, it gracefully falls back to 'rstan'. In any case, heavy computations are not run in package examples or tests.

Value

A list containing:

bench_bayes

Full results for all pairs

winners_070

Pairs with support >= 0.70

winners_060

Pairs with support >= 0.60

rank_out

Output from ranking function

Examples

## Not run: 
# Example usage
result <- bglmar1(
  data_path = file.path(tempdir(), "data.xlsx"),
  circ_vars = c("TC_SPOT_CAN_US", "TC_SPOT_US_CAN", "TC_SPOT_US_REMB",
                "IPC", "TdI_LdelT", "TasaDescuento"),
  prod_vars = c("ValorExportaciones", "Real_Net_Profit", 
                "RealSocialConsumptionPerWorker2017", "RealWage_PPP2017",
                "CapitalStock_PPP2017", "LaborProductivity_PPP2017", 
                "InvestmentPerWorker_PPP2017"),
  backend = "auto"
)

## End(Not run)

Bayesian Structural Time Series Model

Description

Implements Bayesian Structural Time Series models with Leave-Future-Out validation for assessing causal relationships between economic variables with temporal stability.

Usage

bsts_model(
  data_path,
  circ_vars,
  prod_vars,
  max_lag = 6,
  lfo_init_frac = 0.8,
  lfo_h = 6,
  lfo_step = 6,
  niter = 2000,
  burn = 500,
  seed = 123,
  seasonality = NULL,
  support_min = 0.6,
  folds_min = 5,
  sup_hi = 0.7,
  sup_lo = 0.6,
  out_dir = NULL
)

Arguments

data_path

Path to Excel file containing the data

circ_vars

Character vector of circulation variable names

prod_vars

Character vector of production variable names

max_lag

Maximum number of lags for independent variables (default: 6)

lfo_init_frac

Initial fraction for LFO (default: 0.8)

lfo_h

Horizon for LFO (default: 6)

lfo_step

Step size for LFO (default: 6)

niter

Number of MCMC iterations (default: 2000)

burn

Number of burn-in iterations (default: 500)

seed

Random seed (default: 123)

seasonality

Seasonality parameter (NULL for none, 12 for monthly)

support_min

Minimum support threshold (default: 0.6)

folds_min

Minimum number of folds required (default: 5)

sup_hi

High support threshold (default: 0.7)

sup_lo

Low support threshold (default: 0.6)

out_dir

Output directory for results (default: "output_bsts")

Details

This function implements Bayesian Structural Time Series models for assessing causal relationships between economic variables. It uses Leave-Future-Out cross-validation with tuning between Local Level and Local Linear Trend specifications. The methodology is described in detail in the methodological document "DETALLES METODOLOGICOS SPACESTATE MODEL.docx".

Value

A list containing:

rank_ss_all

Full results for all pairs

winners_ss_070

Pairs with support >= 0.70

winners_ss_060

Pairs with support >= 0.60

summaries_ss

Summary statistics

Examples

## Not run: 
# Example usage
result <- bsts_model(
  data_path = file.path(tempdir(), "data.xlsx"),
  circ_vars = c("TC_SPOT_CAN_US", "TC_SPOT_US_CAN", "TC_SPOT_US_REMB",
                "IPC", "TdI_LdelT", "TasaDescuento"),
  prod_vars = c("ValorExportaciones", "Real_Net_Profit", 
                "RealSocialConsumptionPerWorker2017", "RealWage_PPP2017",
                "CapitalStock_PPP2017", "LaborProductivity_PPP2017", 
                "InvestmentPerWorker_PPP2017")
)

## End(Not run)

Error Correction Model with Multivariate Adaptive Regression Splines

Description

Implements a robust ECM benchmark with MARS enhancement for analyzing cointegration relationships between economic variables with temporal stability validation.

Usage

ecm_mars(
  data_path,
  circ_vars,
  prod_vars,
  cointeg_rule = "either",
  eg_p_cutoff = 0.05,
  ecm_p_cutoff = 0.05,
  lag_max_ecm = 4,
  min_tr = 20,
  min_te = 8,
  rolling_cv_enable = TRUE,
  rolling_cv_window = "sliding",
  rolling_cv_initial_frac = 0.8,
  rolling_cv_initial_min = 40,
  rolling_cv_test = 12,
  rolling_cv_step = 12,
  nested_tune = TRUE,
  nested_initial_f = 0.6,
  nested_test = 6,
  nested_step = 3,
  mars_grid = expand.grid(degree = c(1, 2), nk = c(15, 25, 35, 50, 65)),
  support_min = 0.75,
  folds_min_abs = 5,
  parallel_enable = TRUE,
  parallel_workers = max(1, parallel::detectCores() - 1)
)

Arguments

data_path

Path to Excel file containing the data

circ_vars

Character vector of circulation variable names

prod_vars

Character vector of production variable names

cointeg_rule

Cointegration rule ("either" for EG or Johansen, "both" for both)

eg_p_cutoff

Significance level for EG/Phillips-Ouliaris test (default: 0.05)

ecm_p_cutoff

Significance level for lambda<0 test in linear ECM (default: 0.05)

lag_max_ecm

Maximum lags in DeltaY and DeltaX for linear ECM (default: 4)

min_tr

Minimum training rows for MARS (default: 20)

min_te

Minimum test rows (default: 8)

rolling_cv_enable

Whether to enable rolling CV (default: TRUE)

rolling_cv_window

Type of window for rolling CV ("sliding" or "expanding", default: "sliding")

rolling_cv_initial_frac

Initial fraction for rolling CV (default: 0.8)

rolling_cv_initial_min

Minimum initial observations (default: 40)

rolling_cv_test

Test horizon for rolling CV (default: 12)

rolling_cv_step

Step size for rolling CV (default: 12)

nested_tune

Whether to enable nested tuning (default: TRUE)

nested_initial_f

Initial fraction for nested tuning (default: 0.6)

nested_test

Test horizon for nested tuning (default: 6)

nested_step

Step size for nested tuning (default: 3)

mars_grid

Data frame with MARS tuning parameters

support_min

Minimum proportion of valid folds (default: 0.75)

folds_min_abs

Minimum absolute number of valid folds (default: 5)

parallel_enable

Whether to enable parallel processing (default: TRUE)

parallel_workers

Number of parallel workers (default: detectCores() - 1)

Details

This function implements an Error Correction Model enhanced with Multivariate Adaptive Regression Splines for analyzing cointegration relationships between economic variables. It includes comprehensive temporal validation through rolling-origin cross-validation and nested tuning for MARS parameters. The methodology is described in detail in the methodological document "DETALLES METODOLOGICOS DE ECM-MARS2.docx".

Value

A data frame with evaluation results for all pairs

Examples

## Not run: 
# Example usage
result <- ecm_mars(
  data_path = file.path(tempdir(), "data.xlsx"),
  circ_vars = c("ER.SPOT.CAN.US", "ER.SPOT.US.CAN", "ER.SPOT.US.REMB",
                "CPI", "TreasuryBonds10y", "FedDiscountRate"),
  prod_vars = c("Exports", "RealNetProfit", "RealSocialConsumptionPerWorker2017",
                "RealWagePPP2017", "CapitalStockPPP2017",
                "LaborProductivityPPP2017", "InvestmentPerWorkerPPP2017")
)

## End(Not run)