| Title: | Economic Nowcasting with Bridge Equations and Real-Time Evaluation |
|---|---|
| Description: | Provides bridge equations with optional autoregressive terms for nowcasting low-frequency macroeconomic variables (e.g. quarterly GDP) from higher-frequency indicators (e.g. monthly retail sales). Handles the ragged-edge problem where different indicators have different publication lags via mixed-frequency alignment. Includes pseudo-real-time evaluation with expanding or rolling windows, and the Diebold-Mariano test for comparing forecast accuracy following Harvey, Leybourne, and Newbold (1997) <doi:10.1016/S0169-2070(96)00719-4>. No API calls; designed to work with data from any source. |
| Authors: | Charles Coverdale [aut, cre, cph] |
| Maintainer: | Charles Coverdale <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.0 |
| Built: | 2026-05-30 15:07:12 UTC |
| Source: | https://github.com/charlescoverdale/nowcast |
Aggregate a time series from a higher frequency to a lower frequency. For example, convert monthly data to quarterly by taking the mean, sum, or last observation.
nc_aggregate(data, to = c("quarterly", "annual"), fun = mean)nc_aggregate(data, to = c("quarterly", "annual"), fun = mean)
data |
A data frame with columns |
to |
Character. Target frequency: |
fun |
Function used for aggregation (default mean). |
The default aggregation function is mean, which is appropriate for
flow variables measured as rates or indices (e.g. GDP growth, CPI).
For flow variables measured in levels (e.g. total retail sales), use
fun = sum. For stock variables (e.g. interest rates, exchange
rates), use fun = function(x, ...) tail(x, 1) to take the
end-of-period value.
A data frame with columns date and value at the target frequency.
monthly <- data.frame( date = seq(as.Date("2020-01-01"), as.Date("2020-12-01"), by = "month"), value = rnorm(12) ) nc_aggregate(monthly, to = "quarterly") nc_aggregate(monthly, to = "annual", fun = sum)monthly <- data.frame( date = seq(as.Date("2020-01-01"), as.Date("2020-12-01"), by = "month"), value = rnorm(12) ) nc_aggregate(monthly, to = "quarterly") nc_aggregate(monthly, to = "annual", fun = sum)
Merges a quarterly target series with one or more higher-frequency indicator series into a single aligned dataset. Monthly indicators are aggregated to the quarterly frequency using the specified function (default: mean).
nc_align(target, ..., freq_ratio = 3L, agg_fun = mean)nc_align(target, ..., freq_ratio = 3L, agg_fun = mean)
target |
A data frame with columns |
... |
One or more data frames, each with columns |
freq_ratio |
Integer. The number of high-frequency observations per low-frequency period (default 3 for monthly-to-quarterly). |
agg_fun |
Function used to aggregate indicators to the target frequency (default mean). |
The default agg_fun = mean is appropriate for flow variables measured
as rates or indices (GDP growth, CPI). For stock variables (interest rates,
exchange rates), pass agg_fun = function(x, ...) tail(x, 1) to take
end-of-period values. For flow variables in levels (total sales), use
agg_fun = sum – but note that sum will understate the true quarterly
total for partial quarters at the ragged edge (a warning is emitted).
When a quarter has fewer than freq_ratio monthly observations (a partial
quarter at the ragged edge), the aggregation proceeds on the available
data and a message is emitted. The n_months column in the output data
frame records how many observations contributed to each quarterly value
for each indicator.
An nc_dataset object — a list with components:
A data frame with date (quarter start dates) plus columns
for the target and each indicator.
Name of the target column.
Character vector of indicator column names.
Detected frequency of the target series.
Detected frequency of the indicator series.
A data frame summarising data availability per series.
# Create synthetic quarterly target and monthly indicators target <- data.frame( date = as.Date(paste0(2020:2023, "-01-01")), value = c(0.5, -0.3, 0.8, 0.2) ) ind1 <- data.frame( date = seq(as.Date("2020-01-01"), as.Date("2023-12-01"), by = "month"), value = rnorm(48) ) aligned <- nc_align(target, indicator1 = ind1)# Create synthetic quarterly target and monthly indicators target <- data.frame( date = as.Date(paste0(2020:2023, "-01-01")), value = c(0.5, -0.3, 0.8, 0.2) ) ind1 <- data.frame( date = seq(as.Date("2020-01-01"), as.Date("2023-12-01"), by = "month"), value = rnorm(48) ) aligned <- nc_align(target, indicator1 = ind1)
Returns a data frame describing the nowcasting methods implemented in the package.
nc_available()nc_available()
A data frame with columns method, description, and available.
nc_available()nc_available()
Evaluate a nowcasting method by simulating its real-time performance on final revised data. At each evaluation step, the model is estimated using only data from periods 1 to i-1 (expanding window) or a rolling window ending at i-1, then used to produce a nowcast for period i. The nowcast is compared against the actual value at period i.
nc_backtest( formula, data, method = "bridge", ar_order = 1L, start = 10L, window = c("expanding", "rolling"), window_size = 20L, alpha = 0.05 )nc_backtest( formula, data, method = "bridge", ar_order = 1L, start = 10L, window = c("expanding", "rolling"), window_size = 20L, alpha = 0.05 )
formula |
A formula for the bridge equation (e.g. |
data |
A data frame (or |
method |
Character. Currently only |
ar_order |
Integer. Number of autoregressive lags of the target to include (default 1). Set to 0 for a static bridge equation. |
start |
Integer. Minimum number of observations before the first backtest evaluation (default 10). |
window |
Character. |
window_size |
Integer. Number of observations in the rolling window
(ignored if |
alpha |
Numeric. Significance level for prediction intervals (default 0.05). |
This is a pseudo-real-time exercise: it uses final revised data throughout, not the data that would have been available at each point in time (vintage data). As noted by Banbura et al. (2013, ECB WP 1564), data revisions can be material for some variables, so results may overstate true real-time accuracy.
Prediction intervals are computed using the full prediction standard
error from predict.lm(..., interval = "prediction"), accounting for
both residual variance and coefficient estimation uncertainty.
A nowcast_backtest object with components:
A data frame with columns date, nowcast, actual,
error, ci_lower, ci_upper.
The actual values used for evaluation.
The method used.
"expanding" or "rolling".
A data frame with RMSE, MAE, and bias.
set.seed(42) n <- 30 d <- data.frame( date = seq(as.Date("2015-01-01"), by = "quarter", length.out = n), gdp = cumsum(rnorm(n, 0.5, 0.3)), ind1 = cumsum(rnorm(n, 0.4, 0.2)) ) bt <- nc_backtest(gdp ~ ind1, data = d, start = 15) btset.seed(42) n <- 30 d <- data.frame( date = seq(as.Date("2015-01-01"), by = "quarter", length.out = n), gdp = cumsum(rnorm(n, 0.5, 0.3)), ind1 = cumsum(rnorm(n, 0.4, 0.2)) ) bt <- nc_backtest(gdp ~ ind1, data = d, start = 15) bt
Estimate a bridge equation via OLS and produce a nowcast for the current
or specified period. Bridge equations translate higher-frequency indicators
(e.g. monthly) into estimates of a lower-frequency target (e.g. quarterly
GDP). Following standard central bank practice (Baffigi et al. 2004,
Runstler and Sedillot 2003), an autoregressive term for the target
variable can be included via the ar_order argument.
nc_bridge(formula, data, newdata = NULL, ar_order = 1L, alpha = 0.05)nc_bridge(formula, data, newdata = NULL, ar_order = 1L, alpha = 0.05)
formula |
A formula with the target variable on the left-hand side
and indicator variables on the right (e.g. |
data |
A data frame (or |
newdata |
A one-row data frame with indicator values for the nowcast
period. If |
ar_order |
Integer. Number of autoregressive lags of the target to include (default 1). Set to 0 for a static bridge equation with no AR terms. |
alpha |
Numeric. Significance level for prediction intervals (default 0.05). |
Prediction intervals are computed using the full prediction standard error, which accounts for both residual variance and estimation uncertainty in the coefficients, evaluated against a t distribution with appropriate degrees of freedom.
When ar_order > 0, the model includes a lagged dependent variable.
The reported standard errors assume homoskedastic, serially uncorrelated
errors. If residuals exhibit autocorrelation (indicated by the Durbin-Watson
statistic in details$dw_stat), consider extracting the fitted model via
result$model and applying HAC standard errors from the
sandwich package.
A nowcast_result object.
Baffigi, A., Golinelli, R. and Parigi, G. (2004). Bridge models to forecast the euro area GDP. International Journal of Forecasting, 20(3), 447–460.
# Synthetic example set.seed(42) d <- data.frame( date = as.Date(paste0(2015:2024, "-01-01")), gdp = cumsum(rnorm(10, 0.5, 0.3)), ind1 = cumsum(rnorm(10, 0.4, 0.2)), ind2 = cumsum(rnorm(10, 0.3, 0.4)) ) nc_bridge(gdp ~ ind1 + ind2, data = d)# Synthetic example set.seed(42) d <- data.frame( date = as.Date(paste0(2015:2024, "-01-01")), gdp = cumsum(rnorm(10, 0.5, 0.3)), ind1 = cumsum(rnorm(10, 0.4, 0.2)), ind2 = cumsum(rnorm(10, 0.3, 0.4)) ) nc_bridge(gdp ~ ind1 + ind2, data = d)
A generic dispatcher that calls the appropriate nc_* function based
on a string method name. Useful for programmatic workflows.
nc_compute(data, method = "bridge", ...)nc_compute(data, method = "bridge", ...)
data |
A data frame or |
method |
Character. Name of the method: |
... |
Additional arguments passed to the underlying function. |
A nowcast_result object.
set.seed(42) d <- data.frame( date = as.Date(paste0(2015:2024, "-01-01")), gdp = cumsum(rnorm(10, 0.5, 0.3)), ind1 = cumsum(rnorm(10, 0.4, 0.2)) ) nc_compute(d, method = "bridge", formula = gdp ~ ind1)set.seed(42) d <- data.frame( date = as.Date(paste0(2015:2024, "-01-01")), gdp = cumsum(rnorm(10, 0.5, 0.3)), ind1 = cumsum(rnorm(10, 0.4, 0.2)) ) nc_compute(d, method = "bridge", formula = gdp ~ ind1)
Tests whether two sets of forecast errors have equal predictive accuracy. Implements the modified test of Harvey, Leybourne, and Newbold (1997), which applies a finite-sample correction to the original Diebold and Mariano (1995) statistic and uses the t distribution rather than the normal. The Bartlett (triangular) kernel is used for HAC variance estimation, which guarantees a non-negative variance estimate.
nc_dm_test( e1, e2, alternative = c("two.sided", "less", "greater"), h = 1L, loss = c("squared", "absolute") )nc_dm_test( e1, e2, alternative = c("two.sided", "less", "greater"), h = 1L, loss = c("squared", "absolute") )
e1 |
Numeric vector. Forecast errors from model 1. |
e2 |
Numeric vector. Forecast errors from model 2 (same length). |
alternative |
Character. |
h |
Integer. Forecast horizon (default 1). Used for the Newey-West bandwidth and HLN correction. |
loss |
Character. Loss function: |
A list with components statistic, p_value, alternative,
method, and n.
Diebold, F.X. and Mariano, R.S. (1995). Comparing predictive accuracy. Journal of Business & Economic Statistics, 13(3), 253–263. doi:10.1080/07350015.1995.10524599
Harvey, D., Leybourne, S. and Newbold, P. (1997). Testing the equality of prediction mean squared errors. International Journal of Forecasting, 13(2), 281–291. doi:10.1016/S0169-2070(96)00719-4
set.seed(1) e1 <- rnorm(50, sd = 1) e2 <- rnorm(50, sd = 1.5) nc_dm_test(e1, e2)set.seed(1) e1 <- rnorm(50, sd = 1) e2 <- rnorm(50, sd = 1.5) nc_dm_test(e1, e2)
Compute standard forecast evaluation metrics: root mean squared error (RMSE), mean absolute error (MAE), and mean bias.
nc_evaluate(forecast, actual)nc_evaluate(forecast, actual)
forecast |
Numeric vector of nowcast/forecast values. |
actual |
Numeric vector of realised values (same length as |
A data frame with one row and columns rmse, mae, and bias.
nc_evaluate(c(1.0, 2.0, 3.0), c(1.1, 1.8, 3.2))nc_evaluate(c(1.0, 2.0, 3.0), c(1.1, 1.8, 3.2))
Shows which series have data through which date, highlighting the ragged edge where indicators have different publication lags.
nc_ragged_edge(data)nc_ragged_edge(data)
data |
An |
A data frame with columns series, first_date, last_date,
n_obs, and n_missing.
target <- data.frame( date = as.Date(c("2020-01-01", "2020-04-01", "2020-07-01")), value = c(0.5, -0.3, 0.8) ) ind <- data.frame( date = seq(as.Date("2020-01-01"), as.Date("2020-09-01"), by = "month"), value = rnorm(9) ) ds <- nc_align(target, indicator = ind) nc_ragged_edge(ds)target <- data.frame( date = as.Date(c("2020-01-01", "2020-04-01", "2020-07-01")), value = c(0.5, -0.3, 0.8) ) ind <- data.frame( date = seq(as.Date("2020-01-01"), as.Date("2020-09-01"), by = "month"), value = rnorm(9) ) ds <- nc_align(target, indicator = ind) nc_ragged_edge(ds)
Apply common transformations to make a time series stationary. Supports first differencing, log differencing (growth rates), and standardisation.
nc_transform(data, method = c("diff", "log_diff", "standardize"))nc_transform(data, method = c("diff", "log_diff", "standardize"))
data |
A data frame with columns |
method |
Character. One of |
A data frame with columns date and value (if input was a data
frame), or a numeric vector (if input was numeric). The output is shorter
by one observation for "diff" and "log_diff".
df <- data.frame( date = seq(as.Date("2020-01-01"), as.Date("2020-06-01"), by = "month"), value = c(100, 102, 101, 105, 103, 108) ) nc_transform(df, method = "diff") nc_transform(df, method = "log_diff") nc_transform(df, method = "standardize")df <- data.frame( date = seq(as.Date("2020-01-01"), as.Date("2020-06-01"), by = "month"), value = c(100, 102, 101, 105, 103, 108) ) nc_transform(df, method = "diff") nc_transform(df, method = "log_diff") nc_transform(df, method = "standardize")
Plots nowcast versus actual values over the backtest evaluation period.
## S3 method for class 'nowcast_backtest' plot(x, ...)## S3 method for class 'nowcast_backtest' plot(x, ...)
x |
A |
... |
Additional arguments passed to |
The input object, invisibly.
Plots actual versus fitted values from the nowcast model, with the nowcast point highlighted.
## S3 method for class 'nowcast_result' plot(x, ...)## S3 method for class 'nowcast_result' plot(x, ...)
x |
A |
... |
Additional arguments passed to |
The input object, invisibly.
Generate predictions from a fitted nowcast model for new indicator data.
## S3 method for class 'nowcast_result' predict(object, newdata, ...)## S3 method for class 'nowcast_result' predict(object, newdata, ...)
object |
A |
newdata |
A data frame with indicator values. |
... |
Additional arguments (currently unused). |
A numeric vector of predictions.
Print Method for nc_dataset Objects
## S3 method for class 'nc_dataset' print(x, ...)## S3 method for class 'nc_dataset' print(x, ...)
x |
An |
... |
Additional arguments (currently unused). |
The input object, invisibly.
Print Method for Backtest Results
## S3 method for class 'nowcast_backtest' print(x, ...)## S3 method for class 'nowcast_backtest' print(x, ...)
x |
A |
... |
Additional arguments (currently unused). |
The input object, invisibly.
Print Method for Nowcast Results
## S3 method for class 'nowcast_result' print(x, ...)## S3 method for class 'nowcast_result' print(x, ...)
x |
A |
... |
Additional arguments (currently unused). |
The input object, invisibly.
Summary Method for Backtest Results
## S3 method for class 'nowcast_backtest' summary(object, ...)## S3 method for class 'nowcast_backtest' summary(object, ...)
object |
A |
... |
Additional arguments (currently unused). |
The input object, invisibly.
Summary Method for Nowcast Results
## S3 method for class 'nowcast_result' summary(object, ...)## S3 method for class 'nowcast_result' summary(object, ...)
object |
A |
... |
Additional arguments (currently unused). |
The input object, invisibly.