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%> \JoshuaOsborne, May 21 2024, 3:32 AM, University of Texas at Arlington<br>
21%> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
22%> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute
for Computational Engineering and Sciences (ICES), UT Austin<br>
25 properties(Access =
public)
27 %> ``stats`` : The scalar MATLAB
object containing the set of
28 %> computed properties of the contents of the file.<br>
32 %> ``ndim`` : The scalar MATLAB integer representing the number of
33 %> dimensions of the domain of the objective function sampled.<br>
34 %> This integer is also the number of columns in the file that
35 %> correspond that contain the sampled states from the domain
36 %> of the mathematical objective function.<br>
40 %> ``sampleLogFuncColIndex`` : 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>
55 sampleLogFuncColIndex = 0;
60 %> ``sampleLogFuncColName`` : The scalar MATLAB
string representing the column
61 %>
name of the dataframe component ``df`` that contains
62 %> the natural logarithm of the objective function values
63 %> corresponding to the sampled states next to
this column.<br>
65 sampleLogFuncColName =
"sampleLogFunc";
68 methods(Access =
public)
71 %> Return a scalar
object of
class [pm.sampling.FileContentsSample](@ref
FileContentsSample).<br>
72 %> This is the constructor of the
class [pm.sampling.FileContentsSample](@ref
FileContentsSample).<br>
74 %> \param[in] file : The input scalar MATLAB
string containing the path to an external file.<br>
75 %> \param[in] silent : See the corresponding argument of [pm.sampling.FileContentsRestart](@ref
FileContentsRestart)
class.<br>
76 %> (**optional**. The
default is set by [pm.sampling.FileContentsRestart](@ref
FileContentsRestart).)
77 %> \param[in] sep : The input scalar MATLAB
string containing the field separator used in the file.<br>
78 %> (**optional**,
default = ``
","``)
81 %> ``self`` : The output scalar
object of
class [pm.sampling.FileContentsSample](@ref
FileContentsSample).<br>
87 %> contents = pm.sampling.FileContentsSample(file, [])
88 %> contents = pm.sampling.FileContentsSample(file, silent)
89 %> contents = pm.sampling.FileContentsSample(file, [], [])
90 %> contents = pm.sampling.FileContentsSample(file, [], sep)
91 %> contents = pm.sampling.FileContentsSample(file, silent, [])
92 %> contents = pm.sampling.FileContentsSample(file, silent, sep)
99 %> \JoshuaOsborne, May 21 2024, 3:36 AM, University of Texas at Arlington<br>
100 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
101 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute
for Computational Engineering and Sciences (ICES), UT Austin<br>
109 self = self@pm.io.FileContentsTabular(file, silent, sep);
111 for icol = 1 : self.ncol
112 if strcmpi(self.df.Properties.VariableNames{icol}, self.sampleLogFuncColName)
116 self.sampleLogFuncColIndex = icol;
117 self.ndim = self.ncol - self.sampleLogFuncColIndex;
118 if self.nrow <= self.ndim
119 warning ( newline ...
120 + "There are insufficient number of states in the specified file:" + newline ...
122 + pm.io.
tab() + self.file + newline ...
124 + "for computing the covariance/correlation matrices. Skipping..." + newline ...
134 self.stats = struct();
136 %%%% Add chain cormat.
138 self.checkpoint("computing the sample correlation matrix...", false);
139 self.stats.cor = pm.stats.
Cor(self.df(:, self.sampleLogFuncColIndex + 1 : end));
142 %%%% Add chain covmat.
144 self.checkpoint("computing the sample covariance matrix...", false);
145 self.stats.cov = pm.stats.
Cov(self.df(:, self.sampleLogFuncColIndex + 1 : end));
150 self.checkpoint("computing the sample autocorrelation...", false);
151 self.stats.acf = pm.stats.
AutoCorr(self.df(:, self.sampleLogFuncColIndex : end));
154 self.stats.max = struct("val", [], "loc", []);
155 self.stats.min = struct("val", [], "loc", []);
157 %%%% The `{:,:}` slice is essential in MATLAB ~2020a.
159 [self.stats.max.val, self.stats.max.loc] = max(self.df{:,:});
160 [self.stats.min.val, self.stats.min.loc] = min(self.df{:,:});
161 self.stats.avg = mean(self.df{:,:});
162 self.stats.std = std(self.df{:,:});
function name(in vendor)
Return the MPI library name as used in naming the ParaMonte MATLAB shared libraries.
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 containing information about autocorrelation of the inp...
This is the base class for generating objects with methods and storage components for computing and s...
This is the base class for generating objects with methods and storage components for computing and s...
This is the base class for generating objects that contain the contents of a restart file generated b...
This is the base class for generating objects that contain the contents of a sample/chain file genera...
Property sampleLogFuncColName
Property sampleLogFuncColIndex
function FileContentsSample(in file, in silent, in sep)
Return a scalar object of class pm.sampling.FileContentsSample. This is the constructor of the class...
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.