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>
9%> See the documentation of the
class constructor.<br>
12%> See below
for information on the attributes (properties).<br>
15%> See below
for information on the methods.<br>
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>
24 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
26 properties(Access =
public)
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>
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>
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>
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
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
78 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
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>
90 %> This is an internal ``Hidden``
class attribute
91 %> that is inaccessible to the end users.<br>
93 slfcname =
"sampleLogFunc";
96 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
98 methods(Access =
public)
100 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
103 %> Return a scalar
object of
class [pm.sampling.FileContentsSample](@ref
FileContentsSample).<br>
106 %> This is the constructor of the
class [pm.sampling.FileContentsSample](@ref
FileContentsSample).<br>
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 = ``
","``)
115 %> ``self`` : The output scalar
object of
class [pm.sampling.FileContentsSample](@ref
FileContentsSample).<br>
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)
131 %> See the documentations of the subclasses of
this class for example usage.<br>
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>
148 self = self@pm.io.FileContentsTabular(file, silent, sep);
150 for icol = 1 : self.ncol
151 if strcmpi(self.df.Properties.VariableNames{icol}, self.slfcname)
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 ...
162 + pm.io.
tab() + self.file + newline ...
164 + "for computing the covariance/correlation matrices. Skipping..." + newline ...
171 %%%%
statistics (actual computations are all done in the ``setstats`` method and respective subclasses).
177 %%%% visualization (actual visualization setup are all done in ``setvis`` method and the respective subclasses).
184 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
188 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
190 methods(Access = public, Hidden)
192 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
196 %> and store the results in the respective fields of the ``stats`` attribute of the parent
object.<br>
200 %> It is **inaccessible** to the end users of the library.<br>
203 %>
which is **implicitly** passed to this dynamic method (not by the user).<br>
205 %> \interface{setstats}
208 %> contents = pm.sampling.FileContentsSample();
210 %> contents.setstats();
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)
221 self.stats =
struct();
223 self.checkpoint(
"adding the stats components...",
false);
226 %%%% Add chain cormat.
229 self.checkpoint(
"computing the sample correlation matrix...",
false);
230 self.stats.cor = pm.stats.Cor(self.df(:, self.slfc + 1 : end));
234 %%%% Add chain covmat.
237 self.checkpoint(
"computing the sample covariance matrix...",
false);
238 self.stats.cov = pm.stats.Cov(self.df(:, self.slfc + 1 : end));
245 self.checkpoint(
"computing the sample autocorrelation...",
false);
246 self.stats.acf = pm.stats.AutoCorr(self.df(:, self.slfc : end));
249 self.stats.max =
struct(
"val", [],
"loc", []);
250 self.stats.min =
struct(
"val", [],
"loc", []);
253 %%%% The `{:,:}` slice is essential in MATLAB ~2020a.
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{:,:});
262 %%%% Add the ACF stats information.
265 self.stats.acf = pm.stats.AutoCorr(@()self.df);
268 %%%% Add the correlation/covariance matrix information.
271 self.stats.cor = pm.stats.Cor(@()self.df);
272 self.stats.cov = pm.stats.Cov(@()self.df);
278 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
282 %> and store the results in the respective fields of the ``stats`` attribute of the parent
object.<br>
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>
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>
291 %> \interface{setvis}
294 %> contents = pm.sampling.FileContentsSample();
296 %> contents.setvis();
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)
309 self.checkpoint(
"adding the visualization components...",
false);
312 cols = self.slfc + [1 : self.ndim];
313 silent_kws = {
"silent", self.silent};
315 self.vis.cascade =
struct();
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{:});
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{:});
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{:});
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{:});
333 self.vis.plot =
struct();
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{:});
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{:});
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{:});
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{:});
351 self.vis.tile =
struct();
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{:});
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{:});
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{:});
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{:});
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}) ...
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}) ...
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}) ...
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 = [];
398 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
402 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
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...