Although LTPDA is built on top of MATLAB, there are a number of differences in the way it should be used. What follows here is a set of best-practices that should help produce readable and reusable LTPDA scripts which properly capture history.
The MATLAB editor has a number of powerful features which can be leveraged to ensure the maximum readability of scripts. The following features are recommended when scripting for LTPDA:
pl = plist('param1', 1, 'param2', 'my name', 'param3', a, 'param4', 'some value', 'param5', 2, 'param6', 'x');
pl = plist(... 'param1', 1, ... % My first parameter 'param2', 'my name', ... % My second parameter 'param3', a, ... % My third parameter 'param4', 'some value', ... % My fourth parameter 'param5', 2, ... % My fifth parameter 'param6', 'x' ... % My sixth parameter );
%% Create some objects % build an AO with value 1 test_ao_1 = ao(1); % build an AO with value 2 test_ao_2 = ao(2); %% Add the objects together aoSum = test_ao_1 + test_ao_2;
help utils.modules.buildModule help utils.modules.makeMethod
An investigation can typically be broken down into logical steps. For example, it's likely you can break-down any investigation into the following steps:
What follows here is a set of best-practices to help develop a modular and clear scripting work-flow:
% A script which simulates a full system-identification investigation of % LISA Pathfinder using statespace models to generate the data. The parameter % estimation is performed using different techniques and the results compared. % % % The script requires the use of the 'LPF_DA_Module' extension module. % % M Hewitson 2024-02-30 % % VERSION: 1.0 % % Create the simulated data set createSimulatedDataSet; % Build the ssm model to be used for fitting buildFittingModel; % Calculate the expected covariance of the parameters given the model calculateExpectedParameterCovariance; % Perform parameter estimation using MCMC method performMCMCParameterEstimation; % Perform parameter estimation using linear fit performLinearParameterEstimation; % Compare results compareResults;
As well as the formal MATLAB rules about variable names (documented here: Variables), here are some further recommendations about variable names:
Here are some examples of bad variable names:
% A plist for using when calculating a PSD p = plist('navs', 10); % An ao created from a file on disk a = ao('command_force_x2.mat'); % PSD of some data p = psd(a);
% A plist for using when calculating a PSD psdPlist = plist('navs', 10); % An ao created from a file on disk F_cmd_x2 = ao('command_force_x2.mat'); % PSD of some data S_x2 = psd(x2);
A script can not have too much documentation. MATLAB's documentation system is extensive and allows for automatic document publishing when used sensibly. Here are some best-practices that should be followed for documenting scripts.
% A script which takes measurements of the thingemijig and estimates % the amplitude of the thrust manipulator by extracting the coherence % between the first and second whizzmeters. % % The script requires the use of the 'BigMachine' extension module and % assumes the preprocessing of the raw data has been done with the script % entitled 'preprocess_BigMachine_data.m'. % % M Hewitson 2024-02-30 %
Many methods in LTPDA can be used to modify an object. Generally, if you give an output variable, the original object(s) will be copied, rather than modified. Here's an example:
% Create a time-series ao timeSeries = ao.randn(100, 10); % take the absolute value of the data and store in another object absData = timeSeries.abs(); % the original timeSeries object is left untouched % take the absolute value of the data timeSeries.abs(); % the original timeSeries object is modified; the original data is discarded.
% Create an ao minusOne = ao(-1); % take the absolute value of the data minusOne.abs(); % The value of the ao is no longer -1 --> confusing! % Create a time-series ao timeSeries = ao.randn(100, 10); % Estimate the PSD of the data in timeSeries timeSeries.psd(); % The data in timeSeries is no longer a time-series --> confusing!
The following rules should be adhered to, whenever possible, in the use of LTPDA methods.
% Create a time-series ao, take its PSD and plot it iplot(psd(ao.randn(100,10))); % An alternative to the above, but still hard to read ao.randn(100,10).psd.iplot;
% Create a time-series ao noiseData = ao.randn(100, 10); % Estimate PSD S_noiseData = psd(noiseData); % Plot the PSD iplot(S_noiseData);
% Create a some random noise randomNoise1 = ao(plist('waveform', 'noise', 'fs', 10, 'nsecs', 100)); % Create some more random noise randomNoise2 = ao(plist('waveform', 'noise', 'fs', 10, 'nsecs', 100));
% A plist for creating random noise noisePlist = plist(... 'waveform', 'noise', ... 'fs', 10, ... 'nsecs', 100 ... ); % Create a some random noise randomNoise1 = ao(noisePlist); % Create some more random noise randomNoise2 = ao(noisePlist);
|Review of filtering and whitening in LTPDA||Introduction to LTPDA extension modules|