CLI

Installation

To use pySPADS, first install it using pip - it is recommended you do this in a virtual environment.:

(.venv) $ pip install pySPADS

Once installed, the CLI will be available as the command pySPADS. If installed under a virtual envionment, you will first need to activate the environment before running the command. If installed globally, the command should be available from any terminal.

Run pySPADS –help to see the available commands and options.

Steps

pySPADS analysis occurs in several steps, each of which is implemented as a separate command:

1. pySPADS decompose - Decomposition of signal and driver timeseries into IMFs

2. pySPADS match - Matching of component frequencies between signal and driver IMFs

3. pySPADS fit - Fitting of a linear model to predict each signal component from the driver components

4. pySPADS predict - Prediction of future signal components using the fitted model

For more information on each command, run pySPADS <command> –help.

The CLI assumes the location and file name format of intermediate files, so that for a standard analysis you only need to specify minimal options, e.g.:

(.venv) $ pySPADS decompose ./input --signal shore --timecol date --noise 0.1 0.2 0.3 0.4 0.5
(.venv) $ pySPADS match --signal shore
(.venv) $ pySPADS fit --signal shore --model mreg2 --fit-intecept --normalize
(.venv) $ pySPADS predict --signal shore

The commands above should perform a complete analysis, generating the following files, relative to the current directory:

./imfs/<column_name>_imf_<noise>.csv	Decomposed IMFs for each input signal and noise level
./frequencies/frequencies_<noise>.csv	The indices of the matched frequencies between signal and driver IMFs
./coefficients/coefficients_<noise>.csv	The coefficients of the linear model expressing each signal component as a function of the driver components
./predictions_<noise>.csv	The prediction of the target signal from the fitted model, for each noise level
./reconstructed_total.csv	The total signal reconstructed from the predicted components, averaged over all noise levels

CLI reference

pySPADS

pySPADS [OPTIONS] COMMAND [ARGS]...

Options

--version

Show the version and exit.

decompose

Decompose input data into IMFs

FILES expects either a single .csv, a list of .csvs or a directory containing .csv files. Files containing more than one timeseries will result in multiple separate output files.

Resulting files will be named <column_name>_imf_<noise>.csv

e.g.: if an input file contains columns ‘a’ and ‘b’, and noise values 0.1 and 0.2 are specified, the output files will be: a_imf_0.1.csv, a_imf_0.2.csv, b_imf_0.1.csv, b_imf_0.2.csv

Timeseries will be decomposed for the full time range available. If this is not what you intend (e.g.: if performing a hindcast where you are training against only part of your signal data, and will use the rest for validation), you should ensure that the input files provided are contain the correct subset of data.

pySPADS decompose [OPTIONS] [FILES]...

Options

-o, --output <output>

Output directory. Defaults to ./imfs

--timecol <timecol>

Column name of time index

-n, --noise <noise>

Noise values to use when decomposing IMFs, e.g. -n 0.1 0.2 0.3

--noise-threshold <noise_threshold>

Threshold for rejecting IMF modes containing noise. If omitted, no modes will be rejected

--overwrite

Overwrite existing IMF files in output directory

Arguments

FILES

Optional argument(s)

fit

Fit a linear model expressing each component of the signal as a linear combination of the components of the drivers

Results will be saved as a JSON file for each noise value, named <output>/coefficients_<noise>.json

IMF_DIR is the directory containing the IMF files, which should be named <column_name>_imf_<noise>.csv

if omitted, this defaults to ./imfs

FREQUENCY_DIR is the directory containing the frequency files, which should be named frequencies_<noise>.csv

if omitted, this defaults to ./frequencies

pySPADS fit [OPTIONS]

Options

-i, --imf_dir <imf_dir>

Directory containing the IMF files, defaults to ./imfs

-f, --frequency_dir <frequency_dir>

Directory containing the frequency files, defaults to ./frequencies

-o, --output <output>

Output directory, defaults to ./coefficients

-s, --signal <signal>

Required Column name of signal to fit to

-n, --noises <noises>

Noise values to use when fitting IMFs, defaults to all noises present in IMF_DIR, e.g. -n 0.1 0.2 0.3

-m, --model <model>

Model to use for fitting linear regression, one of mreg2, linreg, ridge

Options:

mreg2 | linreg | ridge

--fit-intercept

Fit intercept in linear regression model

--normalize

Normalize input data in linear regression model

match

Matches each component mode of the signal to component modes of each driver with similar frequencies

IMF_DIR is the directory containing the IMF files, which should be named <column_name>_imf_<noise>.csv

if omitted, this defaults to ./imfs

The output will be a CSV file for each noise value, named <output>/frequencies_<noise>.csv

pySPADS match [OPTIONS]

Options

-i, --imf_dir <imf_dir>

Directory containing the IMF files, defaults to ./imfs

-o, --output <output>

Output directory, defaults ./frequencies

-s, --signal <signal>

Required Column name of signal to fit to

--frequency-threshold <frequency_threshold>

Threshold for accepting IMF modes with similar frequencies to signal frequency, default=0.25

reconstruct

Reconstruct signal from IMFs using linear regression coefficients

Results will be saved as a CSV file for each noise value, named <output>/predictions_<noise>.csv

and a CSV file for the total signal, named <output>/reconstructed_total.csv

IMF_DIR is the directory containing the IMF files, which should be named <column_name>_imf_<noise>.csv

if omitted, this defaults to ./imfs

FREQUENCY_DIR is the directory containing the frequency files, which should be named frequencies_<noise>.csv

if omitted, this defaults to ./frequencies

COEFF_DIR is the directory containing the coefficient files, which should be named coefficients_<noise>.csv

if omitted, this defaults to ./coefficients

pySPADS reconstruct [OPTIONS]

Options

-i, --imf_dir <imf_dir>

Directory containing the IMF files, defaults to ./imfs

-f, --frequency_dir <frequency_dir>

Directory containing the frequency files, defaults to ./frequencies

-c, --coeff_dir <coeff_dir>

Directory containing the coefficient files, defaults to ./coefficients

-o, --output <output>

Output directory, defaults to current directory

-s, --signal <signal>

Required Column name of signal to fit to

-n, --noises <noises>

Noise values to use when fitting IMFs, defaults to all noises present in IMF_DIR, e.g. -n 0.1 0.2 0.3