SAtom

Sensitivity Analysis using the Kolmogorov-Smirnov 2-sample test (TOM method)

An improved MATLAB implementation of the SAtom method originally developed by Torben Østergård and further developed by Markus Schaffer at Aalborg University.

It is highly recommended to use SAtom, not SAtom_org, for better reproducibility and speed.

Installation

1. Clone or download this repository
2. Add the repository folder to your MATLAB path:

addpath('/path/to/satom_matlab')

Or add it permanently:

addpath('/path/to/satom_matlab')
savepath

Quick start

% Example: Ishigami-Homma function (3 inputs, Uniform[-π, π])
rng(123);
N = 10000;
X = -pi + 2*pi*rand(N, 3);
a = 7;
b = 0.1;
Y = sin(X(:,1)) + a * sin(X(:,2)).^2 + b * X(:,3).^4 .* sin(X(:,1));

% Run SAtom
[KS2_mean, KS2] = SAtom(X, Y, false, 2000, 0, N, false, 0, {}, 42);

disp('KS2 mean distances:');
disp(KS2_mean);
% → ranking reveals relative importance of each input

Available Functions

SAtom (Improved Version - v1.0.0)

The main sensitivity analysis function includes performance optimisations and interactive convergence checking.

Syntax:

[KS2_mean, KS2] = SAtom(X, Y, dummyYN, J, checkInterval, N, plotYN, SScompare, X_label, seed)

Syntax:

[KS2_mean, KS2] = SAtom_par(X, Y, dummyYN, J, checkInterval, N, plotYN, SScompare, X_label, seed, parallelYN)

SAtom_org (Original Version - v0.9.4)

The original implementation for reference and backward compatibility.

Syntax:

[KS2_mean, KS2] = SAtom_org(X, Y, dummyYN, J, N, plotYN, SScompare, X_label, standardizeX_YN, p)

Parameters (SAtom)

Parameter	Type	Default	Description
X	matrix (N, nIn)	required	Input sample matrix
Y	matrix (N, nOut)	required	Output sample matrix
dummyYN	logical	false	Add a random-permutation dummy column
J	integer	100	Number of random subsamples (min: 100)
checkInterval	integer	0	Interactive convergence check interval (0 = off)
N	integer	size(X,1)	Number of rows to use
plotYN	logical	false	Show boxplot and convergence figures
SScompare	integer	0	Comparison mode: 0, 1, or 2
X_label	cell array	{}	Labels for input variables
seed	integer	42	Random seed for reproducibility

SScompare Modes

• 0: Non-behavioural vs. all (Default)
• 1: Behavioural vs. all
• 2: Non-behavioural vs. behavioural

Returns

• KS2_mean – Row vector – Mean KS2 distance per input variable (higher = more important)
• KS2 – Matrix (J × nIn) – Full KS2 distance matrix for all repetitions

Examples

Basic Usage

% Load your data
X = [...]; % Input matrix (N × nIn)
Y = [...]; % Output matrix (N × nOut)

% Run sensitivity analysis
[KS2_mean, KS2] = SAtom(X, Y);

% Display results sorted by importance
[~, idx] = sort(KS2_mean, 'descend');
disp('Variable importance ranking:');
for i = 1:length(idx)
    fprintf('%d. Variable %d: %.4f\n', i, idx(i), KS2_mean(idx(i)));
end

With Custom Labels and Plotting

% Define input labels
X_label = {'Temperature', 'Pressure', 'Flow Rate', 'Concentration'};

% Run with plots and custom parameters
[KS2_mean, KS2] = SAtom(X, Y, false, 500, 0, size(X,1), true, 0, X_label, 42);

Interactive Convergence Checking

% Check convergence every 100 iterations (up to 1000 max)
[KS2_mean, KS2] = SAtom(X, Y, false, 1000, 100, size(X,1), true, 0, X_label, 42);
% User can stop early once convergence is confirmed

Using the Original Version

% Original implementation with standardization
[KS2_mean, KS2] = SAtom_org(X, Y, false, 200, size(X,1), true, 0, X_label, true, 0.05);

Performance Notes

• The improved version (SAtom) uses optimised algorithms with up to 30× speedup over the original

References

Østergård, T., Jensen, R.L., and Maagaard, S.E. (2017) Interactive Building Design Space Exploration Using Regionalized Sensitivity Analysis. Proc. 15th IBPSA, San Francisco, USA.

License

BSD 2-Clause – see LICENSE.