This repository contains a set of experiments for the inference in Nonlinear AutoRegressive Moving Average with eXogenous input (NARMAX) through message-passing.

Dependencies

Before running the experiments, you need to have Julia 1.6.x installed on your machine. We use the DrWatson.jl package to structure our experiments such that you can reproduce them quickly. DrWatson.jl has to be installed in your global Julia environment before running the experiments. You can add DrWatson.jl by calling

(@v1.6) pkg> add DrWatson

or

julia -e 'import Pkg; Pkg.add("DrWatson")

We use git-lfs to commit binaries (e.g. plots and images) in the repository. While it's not required, it's highly recommended to have it installed on your machine.

Instantiating

For reproducibility, we have fixed the versions of all required packages in this project. To instantiate the project, you may use the following command in a terminal:

julia --project -e 'import Pkg; Pkg.instantiate()'

This command will install all required packages and will prepare the project environment.

Experiments

The experiments are located in the experiments folder. To run Julia experiment, you may use the following command in a terminal:

julia experiments/synth_narmax.jl

It is also possible to run experiments from any IDE (Visual Studio Code), or within the experiments folder directly:

cd experiments
julia synth_narmax.jl

It is unnecessary to activate a project environment before running experiments since DrWatson.jl will do this automatically.

Note

We used MATLAB to (1) generate the synthetic signal datasets/verification/realizations and (2) to run Iterative Least Squares estimator datasets/verification/ils_results. The new dataset can be generated by running matlab/run_experiments_NARMAX.m. The new datasets and reference results will appear in matlab/realizations and matlab/ils_results folders respectively. You can manually move those folders into datasets/verification/.

Cached results

Some experiments may take a lot of time to complete. Optionally you can download the dump.zip archive from the GitHub releases section, containing precomputed JLD2 files for the synthetic experiments. By default, the experiments pipeline searches for cached results in the dump folder and doesn't recompute them if the corresponding cache exists. It is possible to reload the precomputed results and analyze them in REPL or Visual Studio Code without running all experiments from scratch.

To force the experiments pipeline to recompute results, you may either remove the corresponding cached results from the dump folder or modify experiments to use the force = true flag in the produce_or_load method:

result, _ = produce_or_load(..., force = true) do params
    run_experiment(params)
end

Project structure

• datasets/realizations - datasets of synthetic data used for experiments
• datasets/ils_results - results of ILS estimator
• dump - (optional), cached results of the experiments in JLD2 files
• experiments - code/scripts for experiments
• demonstrator - Jupyter notebooks for the fast exposition of the results.
• experiments/results - plots
• src - reused code, project module, model definitions, and utilities