Package 'EconCausal' reference manual

Title:	Causal Analysis for Macroeconomic Time Series (ECM-MARS, BSTS, Bayesian GLM-AR(1))
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.
Authors:	José Mauricio Gómez Julián [aut, cre]
Maintainer:	José Mauricio Gómez Julián <[email protected]>
License:	MIT + file LICENSE
Version:	1.0.2
Built:	2026-06-02 09:51:22 UTC
Source:	https://github.com/IsadoreNabi/EconCausal

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")
)
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)

## 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
)
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)

## 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)
)
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)

## 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)

Package 'EconCausal'

Help Index

Bayesian Generalized Linear Model with AR(1) Errors

Description

Usage

Arguments

Details

Value

Examples

Bayesian Structural Time Series Model

Description

Usage

Arguments

Details

Value

Examples

Error Correction Model with Multivariate Adaptive Regression Splines

Description

Usage

Arguments

Details

Value

Examples