ParaMonte MATLAB 3.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation.
FileContentsSample.m
Go to the documentation of this file.
1%> \brief
2%> This is the base class for generating objects
3%> that contain the contents of a sample/chain file
4%> generated by a ParaMonte sampler.<br>
5%> This class is meant to be primarily internally
6%> used by the ParaMonte MATLAB library samplers.<br>
7%>
8%> \note
9%> See the documentation of the class constructor.<br>
10%>
11%> \note
12%> See below for information on the attributes (properties).<br>
13%>
14%> \note
15%> See below for information on the methods.<br>
16%>
17%> \final{FileContentsSample}
18%>
19%> \author
20%> \AmirShahmoradi, 3:31 PM Friday, November 8, 2024, Dallas, TX<br>
21%> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
22classdef FileContentsSample < pm.io.FileContentsTabular
23
24 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
25
26 properties(Access = public)
27 %>
28 %> ``ndim``
29 %>
30 %> The scalar MATLAB integer representing the number of
31 %> dimensions of the domain of the objective function sampled.<br>
32 %> This integer is also the number of columns in the file that
33 %> correspond that contain the sampled states from the domain
34 %> of the mathematical objective function.<br>
35 %>
36 ndim = 0;
37 %>
38 %> ``slfc``
39 %>
40 %> The scalar MATLAB integer representing the column
41 %> index of the dataframe component ``df`` that contains
42 %> the natural logarithm of the objective function values
43 %> corresponding to the sampled states next to this column,
44 %> such that the following relationship holds.<br>
45 %>
46 %> \code{.m}
48 %> \endcode
49 %>
50 %> While this column index can be readily inferred by exploring
51 %> the contents of the dataframe component, this column index is also
52 %> computed and explicitly offered to conveniently slice the values of
53 %> the sampled states and their corresponding log-function values.<br>
54 %>
55 slfc = 0;
56 %>
57 %> ``stats``
58 %>
59 %> The scalar MATLAB object containing the set of
60 %> computed properties of the contents of the file.<br>
61 %> This component is populated by the subclasses automatically.<br>
62 %> It can also be manually constructed by calling the ``Hidden`` class method
63 %> [pm.sampling.FileContentsSample::setstats](@ref FileContentsSample::setstats).<br>
64 %>
65 stats = [];
66 %>
67 %> ``vis``
68 %>
69 %> The scalar MATLAB ``struct`` containing the set of
70 %> predefined visualizations for the output data.<br>
71 %> This component is populated by the subclasses automatically.<br>
72 %> It can also be manually constructed by calling the ``Hidden`` class method
73 %> [pm.sampling.FileContentsSample::setvis](@ref FileContentsSample::setvis).<br>
74 %>
75 vis = [];
76 end
77
78 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
79
80 properties(Hidden)
81 %>
82 %> ``slfcname``
83 %>
84 %> The ``Hidden`` scalar MATLAB string representing
85 %> the column name of the dataframe component ``df`` that
86 %> contains the natural logarithm of the objective function
87 %> values corresponding to the sampled states next to this column.<br>
88 %>
89 %> \warning
90 %> This is an internal ``Hidden`` class attribute
91 %> that is inaccessible to the end users.<br>
92 %>
93 slfcname = "sampleLogFunc";
94 end
95
96 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
97
98 methods(Access = public)
99
100 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
101
102 %> \brief
103 %> Return a scalar object of class [pm.sampling.FileContentsSample](@ref FileContentsSample).<br>
104 %>
105 %> \details
106 %> This is the constructor of the class [pm.sampling.FileContentsSample](@ref FileContentsSample).<br>
107 %>
108 %> \param[in] file : The input scalar MATLAB string containing the path to an external file.<br>
109 %> \param[in] silent : See the corresponding argument of [pm.sampling.FileContentsTabular](@ref FileContentsTabular) class.<br>
110 %> (**optional**. The default is set by [pm.sampling.FileContentsTabular](@ref FileContentsTabular).)
111 %> \param[in] sep : The input scalar MATLAB string containing the field separator used in the file.<br>
112 %> (**optional**, default = ``","``)
113 %>
114 %> \return
115 %> ``self`` : The output scalar object of class [pm.sampling.FileContentsSample](@ref FileContentsSample).<br>
116 %>
117 %> \interface{FileContentsSample}
118 %> \code{.m}
119 %>
120 %> contents = pm.sampling.FileContentsSample(file)
121 %> contents = pm.sampling.FileContentsSample(file, [])
122 %> contents = pm.sampling.FileContentsSample(file, silent)
123 %> contents = pm.sampling.FileContentsSample(file, [], [])
124 %> contents = pm.sampling.FileContentsSample(file, [], sep)
125 %> contents = pm.sampling.FileContentsSample(file, silent, [])
126 %> contents = pm.sampling.FileContentsSample(file, silent, sep)
127 %>
128 %> \endcode
129 %>
130 %> \note
131 %> See the documentations of the subclasses of this class for example usage.<br>
132 %>
133 %> \final{FileContentsSample}
134 %>
135 %> \author
136 %> \JoshuaOsborne, May 21 2024, 3:36 AM, University of Texas at Arlington<br>
137 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
138 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
139 function self = FileContentsSample(file, silent, sep)
140
141 if nargin < 3
142 sep = [];
143 end
144 if nargin < 2
145 silent = [];
146 end
148 self = self@pm.io.FileContentsTabular(file, silent, sep);
149
150 for icol = 1 : self.ncol
151 if strcmpi(self.df.Properties.VariableNames{icol}, self.slfcname)
152 break;
153 end
154 end
155
156 self.slfc = icol;
157 self.ndim = self.ncol - self.slfc;
158 if self.nrow <= self.ndim
159 warning ( newline ...
160 + "There are insufficient number of states in the specified file:" + newline ...
161 + newline ...
162 + pm.io.tab() + self.file + newline ...
163 + newline ...
164 + "for computing the covariance/correlation matrices. Skipping..." + newline ...
165 + newline ...
166 );
167 return;
168 end
169
170 %%%%
171 %%%% statistics (actual computations are all done in the ``setstats`` method and respective subclasses).
172 %%%%
173
174 %self.setstats();
175
176 %%%%
177 %%%% visualization (actual visualization setup are all done in ``setvis`` method and the respective subclasses).
178 %%%%
179
180 %self.setvis();
181
182 end
183
184 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
185
186 end
187
188 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
189
190 methods(Access = public, Hidden)
191
192 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
193
194 %> \brief
195 %> Compute the statistics of the parent object of class [pm.sampling.FileContentsSample](@ref FileContentsSample)
196 %> and store the results in the respective fields of the ``stats`` attribute of the parent object.<br>
197 %>
198 %> \details
199 %> This is a dynamic ``Hidden`` method of class [pm.sampling.FileContentsSample](@ref FileContentsSample).<br>
200 %> It is **inaccessible** to the end users of the library.<br>
201 %>
202 %> \param[in] self : The input parent object of class [pm.sampling.FileContentsSample](@ref FileContentsSample)
203 %> which is **implicitly** passed to this dynamic method (not by the user).<br>
204 %>
205 %> \interface{setstats}
206 %> \code{.m}
207 %>
208 %> contents = pm.sampling.FileContentsSample();
209 %>
210 %> contents.setstats();
211 %>
212 %> \endcode
213 %>
214 %> \final{setstats}
215 %>
216 %> \author
217 %> \AmirShahmoradi, 2:11 PM Friday, November 8, 2024, Dallas, TX<br>
218 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
219 function setstats(self)
220
221 self.stats = struct();
222
223 self.checkpoint("adding the stats components...", false);
224
225 %%%%
226 %%%% Add chain cormat.
227 %%%%
229 self.checkpoint("computing the sample correlation matrix...", false);
230 self.stats.cor = pm.stats.Cor(self.df(:, self.slfc + 1 : end));
231 self.checkpoint();
232
233 %%%%
234 %%%% Add chain covmat.
235 %%%%
236
237 self.checkpoint("computing the sample covariance matrix...", false);
238 self.stats.cov = pm.stats.Cov(self.df(:, self.slfc + 1 : end));
239 self.checkpoint();
240
241 %%%%
242 %%%% Add chain acf.
243 %%%%
244
245 self.checkpoint("computing the sample autocorrelation...", false);
246 self.stats.acf = pm.stats.AutoCorr(self.df(:, self.slfc : end));
247 self.checkpoint();
248
249 self.stats.max = struct("val", [], "loc", []);
250 self.stats.min = struct("val", [], "loc", []);
251
252 %%%%
253 %%%% The `{:,:}` slice is essential in MATLAB ~2020a.
254 %%%%
255
256 [self.stats.max.val, self.stats.max.loc] = max(self.df{:,:});
257 [self.stats.min.val, self.stats.min.loc] = min(self.df{:,:});
258 self.stats.avg = mean(self.df{:,:});
259 self.stats.std = std(self.df{:,:});
260
261 %%%%
262 %%%% Add the ACF stats information.
263 %%%%
264
265 self.stats.acf = pm.stats.AutoCorr(@()self.df);
266
267 %%%%
268 %%%% Add the correlation/covariance matrix information.
269 %%%%
270
271 self.stats.cor = pm.stats.Cor(@()self.df);
272 self.stats.cov = pm.stats.Cov(@()self.df);
273
274 self.checkpoint();
275
276 end
277
278 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
279
280 %> \brief
281 %> Compute the statistics of the parent object of class [pm.sampling.FileContentsSample](@ref FileContentsSample)
282 %> and store the results in the respective fields of the ``stats`` attribute of the parent object.<br>
283 %>
284 %> \details
285 %> This is a dynamic ``Hidden`` method of class [pm.sampling.FileContentsSample](@ref FileContentsSample).<br>
286 %> It is **inaccessible** to the end users of the library.<br>
287 %>
288 %> \param[in] self : The input parent object of class [pm.sampling.FileContentsSample](@ref FileContentsSample)
289 %> which is **implicitly** passed to this dynamic method (not by the user).<br>
290 %>
291 %> \interface{setvis}
292 %> \code{.m}
293 %>
294 %> contents = pm.sampling.FileContentsSample();
295 %>
296 %> contents.setvis();
297 %>
298 %> \endcode
299 %>
300 %> \final{setvis}
301 %>
302 %> \author
303 %> \AmirShahmoradi, 2:12 PM Friday, November 8, 2024, Dallas, TX<br>
304 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
305 function setvis(self)
306
307 self.vis = struct();
308
309 self.checkpoint("adding the visualization components...", false);
310
311 colf = self.slfc;
312 cols = self.slfc + [1 : self.ndim];
313 silent_kws = {"silent", self.silent};
314
315 self.vis.cascade = struct();
316
317 self.vis.cascade.line = pm.vis.CascadeLine(@()self.df, "coly", cols, "colc", colf, silent_kws{:});
318 self.vis.cascade.scatter = pm.vis.CascadeScatter(@()self.df, "coly", cols, "colc", colf, silent_kws{:});
319 self.vis.cascade.lineScatter = pm.vis.CascadeLineScatter(@()self.df, "coly", cols, "colc", colf, silent_kws{:});
320
321 self.vis.cascade.line3 = pm.vis.CascadeLine3(@()self.df, "coly", cols, "colz", colf, "colc", colf, silent_kws{:});
322 self.vis.cascade.scatter3 = pm.vis.CascadeScatter3(@()self.df, "coly", cols, "colz", colf, "colc", colf, silent_kws{:});
323 self.vis.cascade.lineScatter3 = pm.vis.CascadeLineScatter3(@()self.df, "coly", cols, "colz", colf, "colc", colf, silent_kws{:});
324
325 self.vis.cascade.histfit = pm.vis.CascadeHistfit(@()self.df, "colx", cols, silent_kws{:});
326 self.vis.cascade.histogram = pm.vis.CascadeHistogram(@()self.df, "colx", cols, silent_kws{:});
327 self.vis.cascade.histogram2 = pm.vis.CascadeHistogram2(@()self.df, "colx", cols, "coly", colf, silent_kws{:});
328
329 self.vis.cascade.contour = pm.vis.CascadeContour(@()self.df, "colx", cols, "coly", colf, silent_kws{:});
330 self.vis.cascade.contourf = pm.vis.CascadeContourf(@()self.df, "colx", cols, "coly", colf, silent_kws{:});
331 self.vis.cascade.contour3 = pm.vis.CascadeContour3(@()self.df, "colx", cols, "coly", colf, silent_kws{:});
332
333 self.vis.plot = struct();
334
335 self.vis.plot.line = pm.vis.PlotLine(@()self.df, "coly", cols, "colc", colf, silent_kws{:});
336 self.vis.plot.scatter = pm.vis.PlotScatter(@()self.df, "coly", cols, "colc", colf, silent_kws{:});
337 self.vis.plot.lineScatter = pm.vis.PlotLineScatter(@()self.df, "coly", cols, "colc", colf, silent_kws{:});
338
339 self.vis.plot.line3 = pm.vis.PlotLine3(@()self.df, "coly", cols, "colc", colf, silent_kws{:});
340 self.vis.plot.scatter3 = pm.vis.PlotScatter3(@()self.df, "coly", cols, "colz", colf, "colc", colf, silent_kws{:});
341 self.vis.plot.lineScatter3 = pm.vis.PlotLineScatter3(@()self.df, "coly", cols, "colz", colf, "colc", colf, silent_kws{:});
342
343 self.vis.plot.histfit = pm.vis.PlotHistfit(@()self.df, "colx", cols, silent_kws{:});
344 self.vis.plot.histogram = pm.vis.PlotHistogram(@()self.df, "colx", cols, silent_kws{:});
345 self.vis.plot.histogram2 = pm.vis.PlotHistogram2(@()self.df, "colx", colf, "coly", cols, silent_kws{:});
346
347 self.vis.plot.contour = pm.vis.PlotContour(@()self.df, "colx", cols, "coly", colf, silent_kws{:});
348 self.vis.plot.contourf = pm.vis.PlotContourf(@()self.df, "colx", cols, "coly", colf, silent_kws{:});
349 self.vis.plot.contour3 = pm.vis.PlotContour3(@()self.df, "colx", cols, "coly", colf, silent_kws{:});
350
351 self.vis.tile = struct();
352
353 self.vis.tile.line = pm.vis.TileLine(@()self.df, "coly", cols, "colc", colf, silent_kws{:});
354 self.vis.tile.scatter = pm.vis.TileScatter(@()self.df, "coly", cols, "colc", colf, silent_kws{:});
355 self.vis.tile.lineScatter = pm.vis.TileLineScatter(@()self.df, "coly", cols, "colc", colf, silent_kws{:});
356
357 self.vis.tile.line3 = pm.vis.TileLine3(@()self.df, "coly", cols, "colc", colf, silent_kws{:});
358 self.vis.tile.scatter3 = pm.vis.TileScatter3(@()self.df, "coly", cols, "colz", colf, "colc", colf, silent_kws{:});
359 self.vis.tile.lineScatter3 = pm.vis.TileLineScatter3(@()self.df, "coly", cols, "colz", colf, "colc", colf, silent_kws{:});
360
361 self.vis.tile.histfit = pm.vis.TileHistfit(@()self.df, "colx", cols, silent_kws{:});
362 self.vis.tile.histogram = pm.vis.TileHistogram(@()self.df, "colx", cols, silent_kws{:});
363 self.vis.tile.histogram2 = pm.vis.TileHistogram2(@()self.df, "colx", colf, "coly", cols, silent_kws{:});
364
365 self.vis.tile.contour = pm.vis.TileContour(@()self.df, "colx", cols, "coly", colf, silent_kws{:});
366 self.vis.tile.contourf = pm.vis.TileContourf(@()self.df, "colx", cols, "coly", colf, silent_kws{:});
367 self.vis.tile.contour3 = pm.vis.TileContour3(@()self.df, "colx", cols, "coly", colf, silent_kws{:});
368
369 self.vis.triplex.lshc2 = pm.vis.Triplex ( pm.vis.SubplotLineScatter(@()self.df, "colx", cols, "coly", cols, "colc", colf, "colorbar", {"enabled", false}) ...
370 , pm.vis.SubplotHistogram(@()self.df, "colx", cols) ...
371 , pm.vis.SubplotContour(@()self.df, "colx", cols, "coly", cols, "colorbar", {"enabled", false}) ...
372 , silent_kws{:} ...
373 );
374
375 self.vis.triplex.lshcf = pm.vis.Triplex ( pm.vis.SubplotLineScatter(@()self.df, "colx", cols, "coly", cols, "colc", colf, "colorbar", {"enabled", false}) ...
376 , pm.vis.SubplotHistogram(@()self.df, "colx", cols) ...
377 , pm.vis.SubplotContourf(@()self.df, "colx", cols, "coly", cols, "colorbar", {"enabled", false}) ...
378 , silent_kws{:} ...
379 );
380
381 self.vis.triplex.lshc3 = pm.vis.Triplex ( pm.vis.SubplotLineScatter(@()self.df, "colx", cols, "coly", cols, "colc", colf, "colorbar", {"enabled", false}) ...
382 , pm.vis.SubplotHistogram(@()self.df, "colx", cols) ...
383 , pm.vis.SubplotContour3(@()self.df, "colx", cols, "coly", cols, "colorbar", {"enabled", false}) ...
384 , silent_kws{:} ...
385 );
386
387 %if 5 < ndim
388 % self.vis.triplex.layout.tiling.position = [.1, .1, nan, nan];
389 % self.vis.triplex.layout.cbarh.position = [];
390 % self.vis.triplex.layout.cbarv.position = [];
391 % self.vis.triplex.layout.tiling.tile.width = [];
392 %end
393
394 self.checkpoint();
395
396 end
397
398 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
399
400 end
401
402 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
403
404end
function name(in vendor)
Return the MPI library name as used in naming the ParaMonte MATLAB shared library directories.
function index(in array)
Given array(1 : n), return the array index indx(1 : n) such that array(indx) is in ascending order.
This is the base class for generating objects that contain the contents of a sample/chain file genera...
function setvis(in self)
Compute the statistics of the parent object of class pm.sampling.FileContentsSample and store the res...
function setstats(in self)
Compute the statistics of the parent object of class pm.sampling.FileContentsSample and store the res...
function FileContentsSample(in file, in silent, in sep)
Return a scalar object of class pm.sampling.FileContentsSample.
This is the base class for generating objects that contain the tabular contents of a given file.
function statistics()
Return a scalar MATLAB logical that is true if and only if the current installation of MATLAB contain...
function tab()
Return a scalar MATLAB string containing 4 blank characters equivalent to a tab character.
function which(in vendor)
Return the a MATLAB string containing the path to the first mpiexec executable binary found in system...