ParaMonte MATLAB 3.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation.
AutoCorr.m
Go to the documentation of this file.
1%> \brief
2%> This is the base class for generating objects containing
3%> information about autocorrelation of the input data and
4%> tools for visualizing it.<br>
5%>
6%> \note
7%> This is convenience class for easy computation
8%> of autocorrelation and its storage all in one place.<br>
9%> The primary advantage of this class over the MATLAB
10%> intrinsic functions is in the ability of this class
11%> to compute the result for input dataframe table and
12%> return the results always in MATLAB ``table`` format.<br>
13%>
14%> \note
15%> See the documentation of the class constructor
16%> [pm.stats.AutoCorr::AutoCorr](@ref AutoCorr::AutoCorr) below.<br>
17%>
18%> \final{AutoCorr}
19%>
20%> \author
21%> \JoshuaOsborne, May 21 2024, 4:06 AM, University of Texas at Arlington<br>
22%> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
23%> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
24classdef AutoCorr < pm.matlab.Handle
25
26 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
27
28 properties(Access = public)
29 %>
30 %> ``dfref``
31 %>
32 %> A scalar object of class [pm.container.DataFrame](@ref DataFrame) containing
33 %> (a refernece to) the user-specified data whose covariance must be computed.<br>
34 %>
35 dfref = [];
36 %>
37 %> ``numlag``
38 %>
39 %> The positive scalar MATLAB whole number representing the
40 %> number of lags for which the autocorrelation must be computed.<br>
41 %> This argument is directly passed to the corresponding argument
42 %> of the MATLAB intrinsic ``autocorr()`` in the MATLAB Econometrics Toolbox.<br>
43 %>
44 numlag = [];
45 %>
46 %> ``numstd``
47 %>
48 %> The positive scalar MATLAB double representing the
49 %> number of standard deviations to be used in computing the
50 %> lower and upper significance levels of the autocorrelation.<br>
51 %> This argument is directly passed to the corresponding argument
52 %> of the MATLAB intrinsic ``autocorr()`` in the MATLAB Econometrics Toolbox.<br>
53 %>
54 numstd = 1;
55 %>
56 %> ``bnd``
57 %>
58 %> The MATLAB ``table`` of rank ``2`` serving as a convenient
59 %> storage component each column of which corresponds to the
60 %> absolute ``numstd``-significance bound for the corresponding
61 %> computed autocorrelations of the input data (that is optionally
62 %> stored in the ``val`` component of the parent object).<br>
63 %> The values represent the ``numstd``-sigma standard
64 %> errors on the computed autocorrelations.<br>
65 %> Any autocorrelation value bound within these limits can be
66 %> considered random fluctuations at ``numstd``-sigma confidence level.<br>
67 %> This component is automatically populated when constructing
68 %> an object of class [pm.stats.AutoCorr](@ref AutoCorr).<br>
69 %> It must be populated manually at all other times.<br>
70 %>
71 bnd = [];
72 %>
73 %> ``val``
74 %>
75 %> The MATLAB ``table`` of rank ``2`` serving as a
76 %> convenient storage component for the autocorrelation.<br>
77 %> This component is automatically populated when constructing
78 %> an object of class [pm.stats.AutoCorr](@ref AutoCorr).<br>
79 %> It must be populated manually at all other times.<br>
80 %>
81 %> \note
82 %> The first column of ``val`` always contains the set
83 %> of lags for which the autocorrelation is computed.<br>
84 %>
85 val = [];
86 %>
87 %> ``vis``
88 %>
89 %> The scalar MATLAB ``struct`` containing the set of
90 %> predefined visualizations for the output data.<br>
91 %>
92 vis = [];
93 end
94
95 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
96
97 methods(Access = public)
98
99 %> \brief
100 %> Return an object of class [pm.stats.AutoCorr](@ref AutoCorr).<br>
101 %> This is the constructor of the [pm.stats.AutoCorr](@ref AutoCorr) class.<br>
102 %>
103 %> \param[in] dfref : The input MATLAB matrix or table of rank ``2``
104 %> containing the data as ``ncol`` columns of ``nrow``
105 %> observations whose autocorrelation must be computed.<br>
106 %> Ideally, the user would want to pass a reference
107 %> to a dataframe (e.g., as a function handle ``@()df``)
108 %> so that the data remains dynamically up-to-date.<br>
109 %> (**optional**. If missing, the autocorrelation will not be computed.)
110 %> \param[in] numlag : The input scalar MATLAB positive whole number representing the number
111 %> of lags for which the autocorrelation must be computed.<br>
112 %> This argument is directly passed to the corresponding argument
113 %> of the MATLAB intrinsic ``autocorr()`` in the MATLAB Econometrics Toolbox.<br>
114 %> \param[in] numstd : The input positive scalar MATLAB double representing the
115 %> number of standard deviations to be used in computing the
116 %> lower and upper significance levels of the autocorrelation.<br>
117 %> This argument is directly passed to the corresponding argument
118 %> of the MATLAB intrinsic ``autocorr()`` in the MATLAB Econometrics Toolbox.<br>
119 %> (**optional**, default = ``1``)
120 %>
121 %> \return
122 %> ``self`` : The output object of class [pm.stats.AutoCorr](@ref AutoCorr).<br>
123 %>
124 %> \interface{AutoCorr}
125 %> \code{.m}
126 %>
127 %> acf = pm.stats.AutoCorr()
128 %> acf = pm.stats.AutoCorr([])
129 %> acf = pm.stats.AutoCorr(dfref)
130 %> acf = pm.stats.AutoCorr(dfref, numlag)
131 %> acf = pm.stats.AutoCorr(dfref, [], numstd)
132 %> acf = pm.stats.AutoCorr(dfref, numlag, numstd)
133 %>
134 %> \endcode
135 %>
136 %> \example{AutoCorr}
137 %> \include{lineno} example/stats/AutoCorr/main.m
138 %> \vis{AutoCorr}
139 %> <br><br>
140 %> \image html example/stats/AutoCorr/AutoCorr.unifrnd.plot.line.png width=700
141 %> <br><br>
142 %> \image html example/stats/AutoCorr/AutoCorr.unifrnd.tile.line.png width=700
143 %> <br><br>
144 %> \image html example/stats/AutoCorr/AutoCorr.unifrnd.cascade.line.1.png width=700
145 %> <br><br>
146 %> \image html example/stats/AutoCorr/AutoCorr.unifrnd.cascade.line.2.png width=700
147 %> <br><br>
148 %> \image html example/stats/AutoCorr/AutoCorr.unifrnd.cascade.line.3.png width=700
149 %> <br><br>
150 %> \image html example/stats/AutoCorr/AutoCorr.unifrnd.cascade.line.4.png width=700
151 %>
152 %> \final{AutoCorr}
153 %>
154 %> \author
155 %> \JoshuaOsborne, May 21 2024, 4:10 AM, University of Texas at Arlington<br>
156 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
157 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
158 function self = AutoCorr(dfref, numlag, numstd)
159
160 if nargin < 3
161 numstd = 1;
162 end
163
164 if nargin < 2
165 numlag = [];
166 end
167
168 if nargin < 1
169 self.numlag = numlag;
170 self.numstd = numstd;
171 else
172 [self.val, self.bnd] = self.get(dfref, numlag, numstd);
173 end
174
175 self.setvis();
176
177 end
178
179 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
180
181 %> \brief
182 %> Return the autocorrelation of the input
183 %> data from a lag of ``0`` to ``numlag``.<br>
184 %>
185 %> \details
186 %> This is a dynamic method of the [pm.stats.AutoCorr](@ref AutoCorr) class.<br>
187 %> This method automatically stores any input information
188 %> in the corresponding components of the parent object.<br>
189 %> However, any components of the parent object
190 %> corresponding to the output of this method
191 %> must be set explicitly manually.<br>
192 %>
193 %> \param[inout] self : The input/output parent object of class [pm.stats.AutoCorr](@ref AutoCorr)
194 %> which is **implicitly** passed to this dynamic method (not by the user).<br>
195 %> \param[in] dfref : The input MATLAB matrix or table of rank ``2``
196 %> containing the data as ``ncol`` columns of ``nrow``
197 %> observations whose autocorrelation must be computed.<br>
198 %> Ideally, the user would want to pass a reference
199 %> to a dataframe (e.g., as a function handle ``@()df``)
200 %> so that the data remains dynamically up-to-date.<br>
201 %> (**optional**. If missing, the contents of the corresponding
202 %> internal component of the parent object will be used.)
203 %> \param[in] numlag : The input positive scalar MATLAB integer representing the
204 %> number of lags to be used in computing the autocorrelation.<br>
205 %> The default value will be used if the input ``numlag``
206 %> is unspecified or empty ``[]``.<br>
207 %> (**optional**, default = ``size(dfref.copy(), 1) - 1``)
208 %> \param[in] numstd : The input positive scalar MATLAB double representing the
209 %> number of standard deviations to be used in computing the
210 %> lower and upper significance levels of the autocorrelation.<br>
211 %> This argument is directly passed to the corresponding argument
212 %> of the MATLAB intrinsic ``autocorr()`` in the MATLAB Econometrics Toolbox.<br>
213 %> The default value will be used if the input ``numstd`` is empty ``[]``.<br>
214 %> (**optional**, default = ``1``)
215 %>
216 %> \return
217 %> ``val`` : The output MATLAB ``table`` of size ``numlag + 1``
218 %> containing the autocorrelation from lag ``0`` to ``numlag``.<br>
219 %> The first column of ``val`` always contains the set of ``numlag + 1``
220 %> autocorrelation lags from ``0`` to ``numlag``.<br>
221 %> ``bnd`` : The output MATLAB ``table`` of ``size(dfref.copy(), 2)`` rows by one column
222 %> containing the absolute ``numstd``-significance level of the
223 %> computed autocorrelations. Any autocorrelation value whose
224 %> magnitude is smaller than the corresponding ``bnd`` element
225 %> can be considered insignificant and mere fluctuation.<br>
226 %>
227 %> \interface{get}
228 %> \code{.m}
229 %>
230 %> acf = pm.stats.AutoCorr()
231 %> [acf.val, acf.bnd] = acf.get(dfref)
232 %> [acf.val, acf.bnd] = acf.get(dfref, [])
233 %> [acf.val, acf.bnd] = acf.get(dfref, numlag)
234 %> [acf.val, acf.bnd] = acf.get(dfref, [], numstd)
235 %> [acf.val, acf.bnd] = acf.get(dfref, numlag, numstd)
236 %>
237 %> \endcode
238 %>
239 %> \note
240 %> See the documentation of the class constructor
241 %> [pm.stats.AutoCorr](@ref AutoCorr::AutoCorr) for example usage.<br>
242 %>
243 %> \final{get}
244 %>
245 %> \author
246 %> \JoshuaOsborne, May 21 2024, 4:14 AM, University of Texas at Arlington<br>
247 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
248 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
249 function [val, bnd] = get(self, dfref, numlag, numstd)
250
251 %%%%
252 %%%% Define the data.
253 %%%%
254
255 if nargin < 2
256 dfref = [];
257 end
258
259 if ~isempty(dfref)
260 self.dfref = pm.container.DataFrame(dfref);
261 end
262
263 dfcopy = self.dfref.copy();
264
265 if ~isempty(dfcopy)
266 data = dfcopy{:,:};
267 else
268 help("pm.stats.AutoCorr");
269 error ( newline ...
270 + "A non-mepty ``dfref`` attribute or input argument is required for computing the autocorrelation." + newline ...
271 + newline ...
272 );
273 end
274
275 %%%%
276 %%%% Define the number of lags.
277 %%%%
278
279 if nargin < 3
280 numlag = [];
281 end
282
283 if ~isempty(numlag)
284 self.numlag = numlag;
285 elseif isempty(self.numlag)
286 self.numlag = size(data, 1) - 1;
287 end
288
289 %%%%
290 %%%% Define the number of standard deviations for the bounds.
291 %%%%
292
293 if nargin < 4
294 numstd = [];
295 end
296
297 if ~isempty(numstd)
298 self.numstd = numstd;
299 elseif isempty(self.numstd)
300 self.numstd = 1;
301 end
302
303 %%%%
304 %%%% Compute the ACF.
305 %%%%
306
307 bnd = zeros(size(data, 2), 1);
308 val = zeros(self.numlag + 1, size(data, 2) + 1);
309
310 try
311
312 for icol = 1 : size(data, 2)
313 [val(:, icol + 1), val(:, 1), bounds] = autocorr(data(:, icol), "numlags", self.numlag);
314 bnd(icol) = abs(bounds(1)) * self.numstd;
315 end
316 val = array2table(val);
317
318 catch me
319
320 %val = NaN(numlag, size(data, 2));
321 warning ( newline ...
322 + string(me.identifier) + " : " + string(me.message) + newline ...
323 + "skipping the autocorrelation computation..." + newline ...
324 + newline ...
325 );
326 return;
327
328 end
329
330 val.Properties.VariableNames = ["Lag", "ACF(" + string(dfcopy.Properties.VariableNames) + ")"];
331
332 end
333
334 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
335
336 end
337
338 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
339
340 methods(Access = public, Hidden)
341
342 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
343
344 %> \brief
345 %> Set up the visualization tools of the autocorrelation.<br>
346 %>
347 %> \details
348 %> This is a dynamic ``Hidden`` method of the [pm.stats.AutoCorr](@ref AutoCorr) class.<br>
349 %> This method is inaccessible to the end users of the ParaMonte MATLAB library.<br>
350 %>
351 %> \param[inout] self : The **implicitly-passed** input argument representing the parent object of the method.<br>
352 %> \param[in] val : The input (reference of function handle returning a) MATLAB matrix or table of rank ``2``
353 %> containing the computed autocorrelation to be visualized.<br>
354 %> Ideally, the user would want to pass a reference to a dataframe (e.g., as a function handle ``@()df``)
355 %> so that the data remains dynamically up-to-date.<br>
356 %> (**optional**. If missing, the contents of the corresponding ``var`` attribute of the parent object will be used.)
357 %>
358 %> \interface{get}
359 %> \code{.m}
360 %>
361 %> acf = pm.stats.AutoCorr(dfref, method)
362 %> acf.setvis(); % This method is automatically called within the object constructor.
363 %>
364 %> \endcode
365 %>
366 %> \final{get}
367 %>
368 %> \author
369 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
370 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
371 function setvis(self, val)
372
373 if 1 < nargin
374 self.val = val;
375 end
376
377 self.vis = struct();
378
379 self.vis.plot = struct();
380 self.vis.plot.line = pm.vis.PlotLine( @()self.val ...
381 , "colx", 1, "coly", 2 : size(self.val, 2) ...
382 , "legend", {"enabled", true} ..., "labels", self.val.Properties.VariableNames(2:end)} ...
383 , "ylabel", {"txt", "Autocorrelation Function (ACF)"} ...
384 , "xlabel", {"txt", "Autocorrelation Lag"} ...
385 , "colormap", {"enabled", false} ...
386 , "axes", {"xscale", "log"} ...
387 , "ylim", [-1, 1] ...
388 );
389
390 self.vis.tile = struct();
391 self.vis.tile.line = pm.vis.TileLine( @()self.val ...
392 , "colx", 1, "coly", 2 : size(self.val, 2) ...
393 , "ylabel", {"txt", "Autocorrelation Function (ACF)"} ...
394 , "xlabel", {"txt", "Autocorrelation Lag"} ...
395 , "colormap", {"enabled", false} ...
396 , "legend", {"enabled", true} ...
397 , "axes", {"xscale", "log"} ...
398 , "tiledlayout", {"TileSpacing", "tight"} ...
399 , "ylim", [-1, 1] ...
400 );
401
402 self.vis.cascade = struct();
403 self.vis.cascade.line = pm.vis.CascadeLine ( @()self.val ...
404 , "colx", 1, "coly", 2 : size(self.val, 2) ...
405 , "ylabel", {"txt", "Autocorrelation Function (ACF)"} ...
406 , "xlabel", {"txt", "Autocorrelation Lag"} ...
407 , "colormap", {"enabled", false} ...
408 , "legend", {"enabled", true} ...
409 , "axes", {"xscale", "log"} ...
410 , "ylim", [-1, 1] ...
411 );
412
413 end
414
415 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
416
417 end
418
419 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
420
421end
abs
function abs(in path, in style)
Return the Get absolute canonical path of a file or folder.
AutoCorr
This is the base class for generating objects containing information about autocorrelation of the inp...
Definition: AutoCorr.m:25
AutoCorr::vis
Property vis
Definition: AutoCorr.m:100
AutoCorr::setvis
function setvis(in self, in val)
Set up the visualization tools of the autocorrelation.
AutoCorr::bnd
Property bnd
Definition: AutoCorr.m:77
AutoCorr::numstd
Property numstd
Definition: AutoCorr.m:59
AutoCorr::AutoCorr
function AutoCorr(in dfref, in numlag, in numstd)
Return an object of class pm.stats.AutoCorr. This is the constructor of the pm.stats....
AutoCorr::numlag
Property numlag
Definition: AutoCorr.m:48
AutoCorr::dfref
Property dfref
Definition: AutoCorr.m:38
AutoCorr::get
function get(in self, in dfref, in numlag, in numstd)
Return the autocorrelation of the input data from a lag of 0 to numlag.
AutoCorr::val
Property val
Definition: AutoCorr.m:92
DataFrame
This is the abstract class for generating instances of objects that can contain basic attributes requ...
Definition: DataFrame.m:25
Handle
This is the base class for generating subclass of MATLAB handle superclass whose annoying methods are...
Definition: Handle.m:24
which
function which(in vendor)
Return the a MATLAB string containing the path to the first mpiexec executable binary found in system...