ICAR-IASRI | Statistical Web Tool

DLNM Explorer
Distributed Lag Non-Linear Modelling of Exogenous Shocks on Agricultural System

A user-friendly platform to quantify how an external shock - such as geopolitical risk, weather or climate anomalies, or policy and price shocks - affects a time series of interest (trade, prices, production, arrivals) through non-linear and delayed (lagged) pathways.

What the tool does

Upload a Y file (response series) and an X file (shock/exposure series)

Explore descriptive statistics, distributions and correlations

Test for non-linearity using the BDS test on ARIMAX residuals

Fit penalised DLNMs and estimate cumulative and lag-specific effects

Visualise the effects and download all tables and figures

About the method

Why Distributed Lag Non-Linear Models?

Shocks rarely act instantly or linearly. A sudden rise in geopolitical risk or a climate anomaly may influence trade or prices only after several months, and a large shock may matter far more than a small one. The DLNM framework captures both features at once.

Descriptive statistics

Mean, median, dispersion, skewness, kurtosis, Jarque-Bera and Shapiro-Wilk normality tests and ADF stationarity test for every series.

BDS non-linearity test

An ARIMAX model is fitted for each response-exposure pair and the BDS test checks the residuals for remaining non-linear dependence.

Penalised DLNM

A cross-basis of exposure and lag is estimated within a Gaussian GAM (mgcv) with penalised splines and REML smoothing selection.

Cumulative effects

Overall effect summed across all lags at chosen exposure levels (percentiles or user values), relative to a reference level.

Lag-specific effects

Effects at selected lags with confidence intervals, Z statistics, p-values and significance stars, plus 3D and contour surfaces.

Interactive plots and downloads

3D exposure-lag-response surface, contour map, lag-response and exposure-response curves, with Excel tables and publication-quality figures.

Model in brief

For a response series $Y_t$ and an exposure series $x_t$, the DLNM is

$$Y_t = \alpha + \sum_{j=1}^{v_x}\sum_{k=1}^{v_\ell} \eta_{jk}\, w_{t,jk} + f(t) + s(\text{season}_t) + \varepsilon_t,\qquad w_{t,jk} = \sum_{\ell=0}^{L} b_j(x_{t-\ell})\, c_k(\ell)$$

where $b_j(\cdot)$ are basis functions for the exposure dimension, $c_k(\cdot)$ basis functions for the lag dimension, $L$ is the maximum lag, $f(t)$ an optional trend and $s(\cdot)$ an optional seasonal term. Penalties on $\eta$ are selected by REML. The effect of exposure level $x$ at lag $\ell$ relative to a reference $x_0$ is $\beta_{x,\ell}$, and the cumulative effect is $\beta_x = \sum_{\ell=0}^{L} \beta_{x,\ell}$.

Outputs you get

Descriptive statistics table and interactive time-series, distribution and correlation plots
BDS test table (embedding dimensions 2 to m, four epsilon values)
Cumulative effect table and selected lag-effect table with CI, Z, p-value and significance
Interactive 3D surface, contour, lag-response, exposure-response and cumulative effect plots
One-click Excel workbook of all tables and a ZIP of publication-quality (300/600 dpi) figures

Key references

Gasparrini, A., Armstrong, B. and Kenward, M.G. (2010). Distributed lag non-linear models. Statistics in Medicine, 29(21), 2224-2234.
Gasparrini, A., Scheipl, F., Armstrong, B. and Kenward, M.G. (2017). A penalized framework for distributed lag non-linear models. Biometrics, 73(3), 938-948.
Brock, W.A., Dechert, W.D., Scheinkman, J.A. and LeBaron, B. (1996). A test for independence based on the correlation dimension. Econometric Reviews, 15(3), 197-235.
Wood, S.N. (2017). Generalized Additive Models: An Introduction with R (2nd ed.). Chapman and Hall/CRC.

Analysis workspace

Run the DLNM analysis

Follow the steps from left to right. Every step uses the column names of your own files - nothing is fixed in advance.

New here? Load the built-in sample (monthly trade values of five commodities and two geopolitical-risk indices) to try the tool.

Upload Y file Time column (any format) + one or more dependent (response) variable columns

Browse

Sample Y file: CSV Excel

Upload X file Time column (any format) + N explanatory (exposure / shock) variable columns

Browse

Sample X file: CSV Excel

Data options

Time format

Auto-detect reads dates, months, quarters, weeks, years, financial years, date-times and any labels (t1, Period 1, ...).

Missing values

Merged analysis dataset Y and X matched on the time column

Upload both files (or load the sample) to see descriptive statistics.

Descriptive statistics JB = Jarque-Bera, SW = Shapiro-Wilk (normality); ADF = Augmented Dickey-Fuller (H0: unit root)

Original data Transformed data (as set in Model settings)

Visual exploration

Standardise (z-scores) to compare scales

Upload data first.

Variables and data

Response (Y) variables to analyse

Each selected Y is analysed against each selected X.

Exposure (X) variables to analyse

Transformation of Y

Transformation of X

Seasonal period (observations per cycle)

Effect axis label (optional)

Lag axis label (optional)

DLNM structure

Maximum lag (L)

Number of past periods over which the shock can act.

Exposure basis

Exposure df

Spline / polynomial degree

Lag basis

Lag df

Time trend

Trend df per seasonal cycle

Seasonality control

Season = month, quarter, week, weekday or hour depending on the data; for plain time labels it is the position within the cycle set above.

Smoothing-parameter estimation

P-spline and cr bases are penalised (penalised DLNM). ns, bs, poly and lin are fitted unpenalised.

Prediction and effects

Reference (centering) exposure

Reference quantile

Reference value

Exposure levels for effects

Percentiles (comma separated)

Number of grid points

Custom exposure values (comma separated)

Selected lags for lag-specific effects

Comma separated; values above the maximum lag are ignored.

Confidence level

BDS non-linearity test

Maximum embedding dimension (m)

The BDS test is reported for embedding dimensions 2 to m on ARIMAX residuals.

For each response-exposure pair an ARIMAX model is fitted automatically and its residuals are tested for remaining non-linear dependence at epsilon = 0.5, 1, 1.5 and 2 times the residual standard deviation.

Ready to estimate

BDS test on ARIMAX residuals. A small p-value rejects the i.i.d. hypothesis, indicating remaining non-linear structure that supports the DLNM approach. Epsilon is expressed as a multiple of the residual standard deviation. Stars: *** p<0.01, ** p<0.05, * p<0.10.

Overall effect of the exposure level summed over lags 0 to L, relative to the reference level. Stars: *** p<0.01, ** p<0.05, * p<0.10. Rows are shaded green when significant.

Effect at each selected lag for each exposure level, relative to the reference level.

Response (Y)

Exposure (X)

Hover, zoom, rotate; camera icon saves PNG.

Run the analysis first; downloads will appear here.

Excel workbook All result tables, data used, descriptive statistics and settings

Sheets: Data_Used, Descriptive_Stats, BDS_Test, Cumulative_Effects, Selected_Lag_Effects, Error_Log, Settings.

Download Excel workbook

Publication figures PNG figures for every response-exposure pair, in a ZIP archive

3D surface, contour, lag-response, exposure-response by lag and cumulative effect.

Resolution

300 dpi 600 dpi (slower)

Download figures (ZIP)

User guide

How to use the tool

Prepare two files, upload them, explore, set the model and run. The tool adapts to any number of variables and any regular time frequency.

Prepare your Y file (response / dependent variables)

One time column in any format and any position (usually the first column). It is read automatically and shown back exactly as you wrote it.
One or more numeric columns with the dependent variables, e.g. trade value, price, production, arrivals.
Column headers in the first row. Accepted formats: .csv, .xlsx, .xls (choose the sheet after upload).

Time	Y1	Y2	...
2015-01-01	768.20	1266.65	...
2015-02-01	928.81	1178.63	...

Prepare your X file (explanatory / exposure variables)

One time column written in the same way as in the Y file (same frequency).
N numeric columns of explanatory variables (shocks), e.g. geopolitical risk index, rainfall or temperature anomaly, exchange rate.
Rows are matched with the Y file by time, so only common time points are used. Row order does not matter for calendar times.

Time	X1	X2	...
2015-01-01	106.22	85.59	...
2015-02-01	84.38	88.39	...

Sample Y and X files (CSV and Excel) can be downloaded on the Method > Upload data page.

Upload and check the data

Go to Method > 1. Upload data . Upload the Y file in the left box and the X file in the right box, or click Load sample data .
For Excel files, choose the worksheet. Confirm the time column for each file (detected automatically).
The time column can be written in any way. Automatically recognised: dates (2015-01-31, 31/01/2015, 31.01.2015), months (Jan-2015, January 2015, 01/2015, 2015-01, 201501), quarters (2015Q1, Q1-2015, Quarter 1 2015), half-years (2015H1), weeks (2015-W05, Week 5 2015), years (2015), financial / agricultural years (2015-16, FY2015-16), date-times (2015-01-31 14:00, 31/01/2015 2:00 PM), clock times, Excel date serials, and plain time indices or labels (1, 2, 3 / t1, t2 / Period 1 / Kharif-2015).
The page shows how the time column was read (e.g. 'Q1-2015' = 2015-01-01). If it is misread, choose the Time format manually, or 'Plain time index / labels' to keep the order of the file.
Choose how missing values are handled (remove rows or linear interpolation). Check the merged dataset summary: observations, period, frequency and variables.

Explore descriptive statistics

The table reports N, mean, median, SD, min, quartiles, max, CV (%), skewness, kurtosis, Jarque-Bera and Shapiro-Wilk normality tests and the ADF unit-root test.
Use the plot tabs to view time series (optionally standardised), box plots, histograms and the correlation matrix. Tables can be copied or exported with the buttons above them.

Set the model

All settings have sensible defaults. Main options:

Setting	Meaning and guidance
Y / X variables	Choose which responses and exposures to analyse. Every Y is paired with every X (one DLNM per pair).
Transformation	Levels, log, log return [ln(Z_t) - ln(Z_t-1)], first difference, % change or standardisation. Differencing removes the first observation.
Seasonal period	Auto-detected from the time column (12 for monthly, 4 for quarterly, 7 for daily, 24 for hourly ...); used for the seasonal term and trend flexibility. Set it manually for plain time labels.
Maximum lag (L)	How many past periods the shock may influence Y (e.g. 12 months). Must be well below half the number of observations.
Exposure / lag basis and df	Shape flexibility in the exposure and lag dimensions. P-splines (ps) with df = 6 give a penalised DLNM; lag df is automatically limited to L + 1.
Trend and seasonality	Control for long-run trend (linear, quadratic or smooth) and seasonal pattern (dummies or cyclic spline).
Reference exposure	Effects are expressed relative to this level (median by default); its effect is zero by construction.
Exposure levels	Levels at which effects are reported: percentiles (5, 25, 50, 75, 95 by default), an even grid or your own values.
Selected lags	Lags reported in the lag-specific table and exposure-response plot.
BDS test	Maximum embedding dimension (m) for the BDS non-linearity test on ARIMAX residuals.

Run and interpret

Click Run Analysis . A progress bar shows each response-exposure pair. If a pair fails (e.g. lag too long), the reason is listed in the Error log and the others still run.
Cumulative effects: the total change in Y over lags 0 to L when X is at a given level instead of the reference. A positive value means an increase in Y.
Lag-specific effects: when the effect occurs. Look for lags where the confidence interval excludes zero.
BDS test: p < 0.05 indicates non-linear dependence left by a linear ARIMAX model, which supports the use of DLNM.
Plots: choose a pair to see the 3D exposure-lag-response surface, contour map, lag-response curves, exposure-response curves at selected lags and the cumulative curve.

Download

Method > 5. Downloads: one Excel workbook with every table (plus data used and settings) and a ZIP of publication-quality PNG figures at 300 or 600 dpi.
Every table also has Copy / CSV / Excel buttons, and every interactive plot has a camera icon to save a PNG.

Troubleshooting

'No common time points' - the Y and X files cover different periods or their time columns are written differently. Write both the same way, or set the Time format manually.
'Maximum lag is too large' - reduce the maximum lag or use a longer series.
Log transformation error - log and log-return need strictly positive values; use first difference or none instead.
Analysis is slow - reduce the number of response-exposure pairs or the maximum lag, or use fewer exposure levels.
Numbers with commas (e.g. 1,234.5) are cleaned automatically; non-numeric columns are ignored with a message.