| Type: | Package |
| Title: | Echo State Networks for Time Series Modeling and Forecasting |
| Version: | 1.0.2 |
| Description: | Provides a lightweight implementation of functions and methods for fast and fully automatic time series modeling and forecasting using Echo State Networks (ESNs). |
| License: | GPL-3 |
| URL: | https://github.com/ahaeusser/echos,https://ahaeusser.github.io/echos/ |
| BugReports: | https://github.com/ahaeusser/echos/issues |
| Depends: | R (≥ 4.0.0), fabletools (≥ 0.3.0) |
| Imports: | Rcpp (≥ 1.0.3), RcppArmadillo, tsibble, dplyr, tidyr, rlang,distributional |
| LinkingTo: | Rcpp, RcppArmadillo |
| Encoding: | UTF-8 |
| LazyData: | true |
| RoxygenNote: | 7.3.2 |
| Suggests: | knitr, rmarkdown, tidyverse, fable, testthat (≥ 3.0.0) |
| VignetteBuilder: | knitr |
| Config/testthat/edition: | 3 |
| NeedsCompilation: | yes |
| Packaged: | 2025-06-22 10:46:30 UTC; Alexander Häußer |
| Author: | Alexander Häußer [aut, cre, cph] |
| Maintainer: | Alexander Häußer <alexander-haeusser@gmx.de> |
| Repository: | CRAN |
| Date/Publication: | 2025-06-23 10:20:10 UTC |
Train an Echo State Network
Description
Train an Echo State Network (ESN) to a univariate time series. The function automatically manages data pre-processing, reservoirgeneration (i.e., internal states) and model estimation and selection. The function is a wrapper fortrain_esn() and intended to be used in combination withfabletools::model().
Usage
ESN(formula, ...)Arguments
formula | Model specification (currently not in use). |
... | Further arguments passed to |
Value
An object of classESN.
Examples
library(tsibble)library(fable)AirPassengers %>%as_tsibble() %>%model("ESN" = ESN(value))Filter ESN models
Description
Filter an object of classmdl_df ("mable") to include ESN models only, i.e., other models like ARIMA or ETS are excluded fromthe mable.
Usage
filter_esn(object)Arguments
object | An object of class |
Value
An object of classmdl_df in long-format.
Examples
library(tsibble)library(fable)AirPassengers %>%as_tsibble() %>%model("ESN" = ESN(value)) %>%filter_esn()Extract fitted values from a trained ESN
Description
Extract fitted values from a trained ESN astsibble.
Usage
## S3 method for class 'ESN'fitted(object, ...)Arguments
object | An object of class |
... | Currently not in use. |
Value
Fitted values extracted from the object.
Examples
library(tsibble)library(fable)AirPassengers %>%as_tsibble() %>%model("ESN" = ESN(value)) %>%fitted()Forecast an Echo State Network
Description
Forecast an Echo State Network (ESN) from a trained model viarecursive forecasting. Forecast intervals are generated by simulatingfuture sample path based on a moving block bootstrap of the residuals andestimating the quantiles from the simulations. The function is a wrapperforforecast_esn() and intended to be used in combination withfabletools::model().
Usage
## S3 method for class 'ESN'forecast( object, new_data, normal = TRUE, n_sim = 200, specials = NULL, xreg = NULL, ...)Arguments
object | An object of class |
new_data | Forecast horizon (n-step ahead forecast). |
normal | Logical value. If |
n_sim | Integer value. The number of future sample path generated during simulation. |
specials | Currently not in use. |
xreg | A |
... | Currently not in use. |
Value
An object of classfbl_ts ("fable").
Examples
library(tsibble)library(fable)AirPassengers %>%as_tsibble() %>%model("ESN" = ESN(value)) %>%forecast(h = 18)Forecast an Echo State Network
Description
Forecast an Echo State Network (ESN) from a trained model viarecursive forecasting. Forecast intervals are generated by simulatingfuture sample path based on a moving block bootstrap of the residuals andestimating the quantiles from the simulations.
Usage
forecast_esn( object, n_ahead = 18, levels = c(80, 95), n_sim = 100, n_seed = 42)Arguments
object | An object of class |
n_ahead | Integer value. The number of periods for forecasting (i.e. forecast horizon). |
levels | Integer vector. The levels of the forecast intervals, e.g., 80% and 95%. |
n_sim | Integer value. The number of future sample path generated during simulation. |
n_seed | Integer value. The seed for the random number generator (for reproducibility). |
Value
Alist containing:
point: Numeric vector containing the point forecasts.interval: Numeric matrix containing the forecast intervals.sim: Numeric matrix containing the simulated future sample path.levels: Integer vector. The levels of the forecast intervals.actual: Numeric vector containing the actual values.fitted: Numeric vector containing the fitted values.n_ahead: Integer value. The number of periods for forecasting (forecast horizon).model_spec: Character value. The model specification as string.
Examples
xdata <- as.numeric(AirPassengers)xmodel <- train_esn(y = xdata)xfcst <- forecast_esn(xmodel, n_ahead = 12)plot(xfcst)Summary of trained models during random search
Description
Return summary statistics from trained ESN models during random search astibble.
model: Model identifier.loglik: Log-likelihood.nobs: Number of observations.df: Effective degrees of freedom.lambda: Regularization parameter.aic: Akaike Information Criterion.aicc: Corrected Akaike Information Criterion.bic: Bayesian Information Criterion.hqc: Hannan-Quinn Information Criterion.mse: Mean Squared Error.mae: Mean Absolute Error.
Usage
## S3 method for class 'ESN'glance(x, ...)Arguments
x | An object of class |
... | Currently not in use. |
Value
Summary statistics extracted from the object.
Examples
library(tsibble)library(fable)AirPassengers %>%as_tsibble() %>%model("ESN" = ESN(value)) %>%glance()Checks if object is of class "esn"
Description
ReturnsTRUE if the object is of class "esn".
Usage
is.esn(object)Arguments
object | object to be tested. |
Value
Logical value. IfTRUE, the object is of class "esn".
Examples
xdata <- as.numeric(AirPassengers)xmodel <- train_esn(y = xdata)is.esn(xmodel)Checks if object is of class "forecast_esn"
Description
ReturnsTRUE if the object is of class "forecast_esn".
Usage
is.forecast_esn(object)Arguments
object | object to be tested. |
Value
Logical value. IfTRUE, the object is of class "forecast_esn".
Examples
xdata <- as.numeric(AirPassengers)xmodel <- train_esn(y = xdata)xfcst <- forecast_esn(xmodel, n_ahead = 12)is.forecast_esn(xfcst)M4 dataset
Description
tsibble with six monthly time series from the M4 Forecasting Competition. The datasets contains the following time series:
M21655 (Demographic), 1995 Jan - 2015 Mar
M21683 (Demographic), 2000 Jan - 2023 Apr
M2717 (Macro), 1996 Jan - 2016 Nov
M28597 (Industry), 1996 Jan - 2016 Dec
M42529 (Finance), 2001 Jan - 2009 Apr
M4813 (Macro), 1994 Apr - 2006 May
Usage
data(m4_data)Format
A time series object of classtsibble with 1.152 rows and 4 columns:
series: Unique identifier ascharacter(key variable).category: Category (e.g., Demographic, Macro) asfactor.index: Date asyearmonth(index variable).value: Value asnumeric(measurement variable).
Source
Examples
data(m4_data)Model specification of a trained ESN model
Description
Provides a compact overview of the model specification in the formatESN({n_states, alpha, rho}, {n_models, df}).
Usage
## S3 method for class 'ESN'model_sum(x)Arguments
x | An object of class |
Value
Model summary extracted from the object.
Examples
library(tsibble)library(fable)AirPassengers %>%as_tsibble() %>%model("ESN" = ESN(value))Plot internal states of a trained ESN model
Description
Plot internal states (i.e., the reservoir) of a trained ESN model as line chart.
Usage
## S3 method for class 'esn'plot(x, ...)Arguments
x | An object of class |
... | Further arguments passed to |
Value
Line chart of internal states.
Examples
xdata <- as.numeric(AirPassengers)xmodel <- train_esn(y = xdata)plot(xmodel)Plot forecasts of a trained ESN model
Description
Plot point forecasts and forecast intervals, actual values of a trained ESN model. Optionally, test data (out-of-sample) and fitted valuescan be added to the plot.
Usage
## S3 method for class 'forecast_esn'plot(x, test = NULL, fitted = TRUE, interval = TRUE, n_obs = NULL, ...)Arguments
x | An object of class |
test | Numeric vector. Test data, i.e., out-of-sample actual values. |
fitted | Logical value. If |
interval | Logical value. If |
n_obs | Integer value. If |
... | Currently not in use. |
Value
Line chart of point forecast and actual values.
Examples
xdata <- as.numeric(AirPassengers)xmodel <- train_esn(y = xdata)xfcst <- forecast_esn(xmodel, n_ahead = 12)plot(xfcst)Print model specification of the trained ESN model
Description
Provides a compact overview of the model specification in the formatESN({n_states, alpha, rho}, {n_models, df}).
Usage
## S3 method for class 'esn'print(x, ...)Arguments
x | An object of class |
... | Currently not in use. |
Value
Print specification of the trained ESN model.
Examples
xdata <- as.numeric(AirPassengers)xmodel <- train_esn(y = xdata)print(xmodel)Provide a detailed summary of the trained ESN model
Description
Provide a detailed summary of the trained ESN model. The function is a wrapper forsummary.esn().
Usage
## S3 method for class 'ESN'report(object, ...)Arguments
object | An object of class |
... | Currently not in use. |
Value
Print detailed model summary.
Examples
library(tsibble)library(fable)AirPassengers %>%as_tsibble() %>%model("ESN" = ESN(value)) %>%report()Return the reservoir from a trained ESN as tibble
Description
Return the reservoir (internal states) from atrained ESN as tibble. The function works only for modelsof classESN.
Usage
reservoir(object)Arguments
object | An object of class |
Value
A tibble containing the reservoir (internal states).
Examples
library(tsibble)library(fable)AirPassengers %>%as_tsibble() %>%model("ESN" = ESN(value)) %>%reservoir()Extract residuals from a trained ESN
Description
Extract residuals from a trained ESN astsibble.
Usage
## S3 method for class 'ESN'residuals(object, ...)Arguments
object | An object of class |
... | Currently not in use. |
Value
Residuals extracted from the object.
Examples
library(tsibble)library(fable)AirPassengers %>%as_tsibble() %>%model("ESN" = ESN(value)) %>%residuals()Run reservoir
Description
Run reservoir creates the internal states for the ESN.
Arguments
input | Numeric matrix containing the input features |
win | Numeric matrix. The input weight matrix. |
wres | Numeric matrix. The reservoir weight matrix. |
alpha | Numeric value. The leakage rate (smoothing parameter). |
Value
states train Numeric matrix with the internal states.
Provide a detailed summary of the trained ESN model
Description
Provide a detailed summary of the trained ESN model.
Usage
## S3 method for class 'esn'summary(object, ...)Arguments
object | An object of class |
... | Currently not in use. |
Value
Print detailed model summary.
Examples
xdata <- as.numeric(AirPassengers)xmodel <- train_esn(y = xdata)summary(xmodel)Synthetic data
Description
tibble with ten synthetic time series. The dataset contains the following time series:
Square Wave
Sawtooth Wave
Harmonic Wave
Harmonic Wave w/ Trend
Amplitude Modulated Wave
Frequency Modulated Wave
AR(1) Process
MA(2) Process
White Noise Process
Random Walk Process
Usage
data(synthetic_data)Format
An object of classtibble with 2.000 rows and 3 columns:
variable: Unique identifier ascharacter(key variable).index: Index asinteger(index variable).value: Value asnumeric(measurement variable).
Examples
data(synthetic_data)Estimated coefficients
Description
Return the estimated coefficients from a trained ESN astibble.
Usage
## S3 method for class 'ESN'tidy(x, ...)Arguments
x | An object of class |
... | Currently not in use. |
Value
Coefficients extracted from the object.
Examples
library(tsibble)library(fable)AirPassengers %>%as_tsibble() %>%model("ESN" = ESN(value)) %>%tidy()Train an Echo State Network
Description
Train an Echo State Network (ESN) to a univariate time series.The function automatically manages data pre-processing, reservoirgeneration (i.e., internal states) and model estimation and selection.
Usage
train_esn( y, lags = 1, inf_crit = "bic", n_diff = NULL, n_states = NULL, n_models = NULL, n_initial = NULL, n_seed = 42, alpha = 1, rho = 1, density = 0.5, lambda = c(1e-04, 2), scale_win = 0.5, scale_wres = 0.5, scale_inputs = c(-0.5, 0.5))Arguments
y | Numeric vector containing the response variable. |
lags | Integer vector with the lag(s) associated with the input variable. |
inf_crit | Character value. The information criterion used for variable selection |
n_diff | Integer vector. The nth-differences of the response variable. |
n_states | Integer value. The number of internal states per reservoir. |
n_models | Integer value. The maximum number of (random) models to train for model selection. |
n_initial | Integer value. The number of observations of internal states for initial drop out (throw-off). |
n_seed | Integer value. The seed for the random number generator (for reproducibility). |
alpha | Numeric value. The leakage rate (smoothing parameter) applied to the reservoir. |
rho | Numeric value. The spectral radius for scaling the reservoir weight matrix. |
density | Numeric value. The connectivity of the reservoir weight matrix (dense or sparse). |
lambda | Numeric vector. Lower and upper bound of lambda sequence for ridge regression. |
scale_win | Numeric value. The lower and upper bound of the uniform distribution for scaling the input weight matrix. |
scale_wres | Numeric value. The lower and upper bound of the uniform distribution for scaling the reservoir weight matrix. |
scale_inputs | Numeric vector. The lower and upper bound for scaling the time series data. |
Value
Alist containing:
actual: Numeric vector containing the actual values.fitted: Numeric vector containing the fitted values.resid: Numeric vector containing the residuals.states_train: Numeric matrix containing the internal states.method: Alistcontaining several objects and meta information of the trained ESN (weight matrices, hyperparameters, model metrics, etc.).
Examples
xdata <- as.numeric(AirPassengers)xmodel <- train_esn(y = xdata)summary(xmodel)