ParaMonte MATLAB 3.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation.
FileContentsChainMCMC.m
Go to the documentation of this file.
1%> \brief
2%> This is the base class for generating objects that contain the contents of a chain
3%> file generated by the ParaMonte MCMC samplers such as [pm.sampling.Paradram](@ref Paradram).<br>
4%>
5%> \details
6%> This class is meant to be primarily internally used by the ParaMonte MATLAB library samplers.<br>
7%> This class merely adds a number of visualizations to its superclass which are
8%> specific to the [pm.sampling.Paradram](@ref Paradram) sampler.<br>
9%>
10%> \note
11%> See also the documentation of the class constructor
12%> [pm.sampling.FileContentsChainMCMC::FileContentsChainMCMC](@ref FileContentsChainMCMC::FileContentsChainMCMC).<br>
13%>
14%> \note
15%> See also the documentation of the superclass [pm.sampling.FileContentsChain](@ref FileContentsChain).<br>
16%>
17%> \note
18%> See below for information on the attributes (properties).<br>
19%>
20%> \note
21%> See below for information on the class methods.<br>
22%>
23%> \final{FileContentsChainMCMC}
24%>
25%> \author
26%> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
27%> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
28classdef FileContentsChainMCMC < pm.sampling.FileContentsChain
29
30 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
31
32 properties(Access = public)
33 end
34
35 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
36
37 properties(Hidden)
38 end
39
40 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
41
42 methods(Access = public)
43
44 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
45
46 %> \brief
47 %> Return a scalar object of class [pm.sampling.FileContentsChainMCMC](@ref FileContentsChainMCMC).<br>
48 %>
49 %> \details
50 %> This is the constructor of the class [pm.sampling.FileContentsChainMCMC](@ref FileContentsChainMCMC).<br>
51 %>
52 %> \param[in] file : The input scalar MATLAB string containing the path or web address to an external file.<br>
53 %> \param[in] silent : See the corresponding argument of the superclass constructor [pm.sampling.FileContentsChain::FileContentsChain](@ref FileContentsChain::FileContentsChain).<br>
54 %> (**optional**. The default is set by the superclass constructor [pm.sampling.FileContentsChain::FileContentsChain](@ref FileContentsChain::FileContentsChain).)
55 %> \param[in] sep : See the corresponding argument of the superclass constructor [pm.sampling.FileContentsChain::FileContentsChain](@ref FileContentsChain::FileContentsChain).<br>
56 %> (**optional**. The default is set by the superclass constructor [pm.sampling.FileContentsChain::FileContentsChain](@ref FileContentsChain::FileContentsChain).)
57 %> \param[in] format : The input scalar MATLAB string containing the reading format of the Markov chain:
58 %> <ol>
59 %> <li> If ``format`` is set to ``"compact"``,
60 %> the Markov chain will be read in compact (weighted) format.<br>
61 %> This format is fast and potentially highly memory-efficient.<br>
62 %> Beware that this format does not necessarily generate a compact chain
63 %> when the specified chain file is already written in verbose format.<br>
64 %> <li> If ``format`` is set to ``"verbose"``,
65 %> the Markov chain will be read in verbose (unweighted or unrolled) format.<br>
66 %> While the chain in this format is the **actual Markov chain**,
67 %> reading the chain in this format can be highly inefficient as it
68 %> can use too much memory for high-dimensional density functions.<br>
69 %> </ol>
70 %> (**optional**, default = ``"compact"``.)
71 %>
72 %> \return
73 %> ``self`` : The output scalar object of class [pm.sampling.FileContentsChainMCMC](@ref FileContentsChainMCMC).<br>
74 %>
75 %> \interface{FileContentsChainMCMC}
76 %> \code{.m}
77 %>
78 %> contents = pm.sampling.FileContentsChainMCMC(file)
79 %> contents = pm.sampling.FileContentsChainMCMC(file, [])
80 %> contents = pm.sampling.FileContentsChainMCMC(file, silent)
81 %> contents = pm.sampling.FileContentsChainMCMC(file, [], sep)
82 %> contents = pm.sampling.FileContentsChainMCMC(file, silent, sep)
83 %>
84 %> \endcode
85 %>
86 %> \remark
87 %> See also the documentation of the subclasses for example usage.<br>
88 %>
89 %> \final{FileContentsChainMCMC}
90 %>
91 %> \author
92 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
93 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
94 function self = FileContentsChainMCMC(file, silent, sep, format)
95
96 if nargin < 4
97 format = [];
98 end
99
100 if nargin < 3
101 sep = [];
102 end
103
104 if nargin < 2
105 silent = [];
106 end
107
108 self = self@pm.sampling.FileContentsChain(file, silent, sep);
109
110 %%%%
111 %%%% Unroll the chain if necessary and add the Markov-specific stats information.
112 %%%%
113
114 if pm.introspection.istype(format, "string") && strcmpi(format, "verbose")
115
116 %%%% Unpack the chain data frames.
117
118 self.df = pm.array.verbose(self.df, 1, self.df.sampleWeight);
119 self.df.sampleWeight(:) = 1;
120
121 elseif ~isempty(format) && ~(pm.introspection.istype(format, "string") && strcmpi(format, "compact"))
122
123 help("pm.sampling.Paradram.readChain");
124 disp("format");
125 disp( format );
126 error ( newline ...
127 + "Unrecognized input value for ``format``." + newline ...
128 + "See the documnetation displayed above for more information." + newline ...
129 + "Here is the error message:" + newline ...
130 + newline ...
131 + string(me.identifier) + newline + string(me.message) + newline ...
132 + newline ...
133 );
134
135 end
136
137 end
138
139 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
140
141 end
142
143 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
144
145 methods(Access = public, Hidden)
146
147 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
148
149 %> \brief
150 %> Compute the statistics of the parent object of class [pm.sampling.FileContentsChainMCMC](@ref FileContentsChainMCMC)
151 %> and store the results in the respective fields of the ``stats`` attribute of the parent object.<br>
152 %>
153 %> \brief
154 %> This is a dynamic ``Hidden`` method of class [pm.sampling.FileContentsChainMCMC](@ref FileContentsChainMCMC).<br>
155 %> It is **inaccessible** to the end users of the library.<br>
156 %>
157 %> \param[in] self : The input parent object of class [pm.sampling.FileContentsChainMCMC](@ref FileContentsChainMCMC)
158 %> which is **implicitly** passed to this dynamic method (not by the user).<br>
159 %>
160 %> \interface{setstats}
161 %> \code{.m}
162 %>
163 %> contents = pm.sampling.FileContentsChainMCMC();
164 %>
165 %> contents.setstats();
166 %>
167 %> \endcode
168 %>
169 %> \final{setstats}
170 %>
171 %> \author
172 %> \AmirShahmoradi, 2:11 PM Friday, November 8, 2024, Dallas, TX<br>
173 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
174 function setstats(self)
175
176 setstats@pm.sampling.FileContentsChain(self);
177
178 %%%%
179 %%%% Add chain cormat.
180 %%%%
181
182 self.checkpoint("computing the sample correlation matrix...", false);
183 self.stats.cor = pm.stats.Cor(@()self.df(:, self.slfc + 1 : end));
184 self.checkpoint();
185
186 %%%%
187 %%%% Add chain covmat.
188 %%%%
189
190 self.checkpoint("computing the sample covariance matrix...", false);
191 self.stats.cov = pm.stats.Cov(@()self.df(:, self.slfc + 1 : end));
192 self.checkpoint();
193
194 %%%%
195 %%%% Add chain acf.
196 %%%%
197
198 self.checkpoint("computing the sample autocorrelation...", false);
199 self.stats.acf = pm.stats.AutoCorr(@()self.df(:, self.slfc : end));
200 self.checkpoint();
201
202 self.stats.max = struct("val", [], "loc", []);
203 self.stats.min = struct("val", [], "loc", []);
204
205 %%%%
206 %%%% The `{:,:}` slice is essential in MATLAB ~2020a.
207 %%%%
208
209 [self.stats.max.val, self.stats.max.loc] = max(self.df{:,:});
210 [self.stats.min.val, self.stats.min.loc] = min(self.df{:,:});
211 self.stats.avg = mean(self.df{:,:});
212 self.stats.std = std(self.df{:,:});
213
214 end
215
216 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
217
218 %> \brief
219 %> Compute the statistics of the parent object of class [pm.sampling.FileContentsChainMCMC](@ref FileContentsChainMCMC)
220 %> and store the results in the respective fields of the ``stats`` attribute of the parent object.<br>
221 %>
222 %> \brief
223 %> This is a dynamic ``Hidden`` method of class [pm.sampling.FileContentsChainMCMC](@ref FileContentsChainMCMC).<br>
224 %> It is **inaccessible** to the end users of the library.<br>
225 %>
226 %> \param[in] self : The input parent object of class [pm.sampling.FileContentsChainMCMC](@ref FileContentsChainMCMC)
227 %> which is **implicitly** passed to this dynamic method (not by the user).<br>
228 %>
229 %> \interface{setvis}
230 %> \code{.m}
231 %>
232 %> contents = pm.sampling.FileContentsChainMCMC();
233 %>
234 %> contents.setvis();
235 %>
236 %> \endcode
237 %>
238 %> \final{setvis}
239 %>
240 %> \author
241 %> \AmirShahmoradi, 2:12 PM Friday, November 8, 2024, Dallas, TX<br>
242 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
243 function setvis(self)
244
245 setvis@pm.sampling.FileContentsChain(self);
246
247 self.checkpoint("adding the ParaDRAM-specific visualization components...", false);
248
249 silent_kws = {"silent", self.silent};
250 self.checkpoint("adding DRAM-specific visualizations to the chain object...", false);
251
252 %%%%
253 %%%% Add the visualizations for ``meanAcceptanceRate``.
254 %%%%
255
256 try
257
258 %%%% Find the keywords in the column names.
259 %%%% This avoids exact matching, which is problematic between ParaMonte 1 and 2).
260 for colname = string(self.df.Properties.VariableNames)
261 if contains(lower(colname), "mean")
262 break;
263 end
264 end
265
266 self.vis.(colname) = struct();
267 self.vis.(colname).line = pm.vis.PlotLine ( @()self.df, "coly", colname, "colc", self.slfc ...
268 , "ylabel", {"txt", "Mean Acceptance Rate"} ...
269 , "xlabel", {"txt", "Sampling Step"} ...
270 , "axes", {"xscale", "log"} ...
271 , "plot", {"linewidth", 3} ...
272 , silent_kws{:} ...
273 );
274
275 catch me
276
277 warning ( newline ...
278 + "Failed to create the visualizations for the " + colname + " data column of the chain file." + newline ...
279 + "Here is the error message:" + newline ...
280 + newline ...
281 + string(me.identifier) + newline + string(me.message) + newline ...
282 + newline ...
283 );
284
285 end
286
287 %%%%
288 %%%% Add the visualizations for ``burninLocation``.
289 %%%%
290
291 try
292
293 %%%% Find the keywords in the column names.
294 %%%% This avoids exact matching, which is problematic between ParaMonte 1 and 2).
295 for colname = [string(self.df.Properties.VariableNames)]
296 if contains(lower(colname), "burnin")
297 break;
298 end
299 end
300
301 self.vis.(colname) = struct();
302 self.vis.(colname).line = pm.vis.PlotLine ( @()self.df, "coly", colname, "colc", self.slfc ...
303 , "ylabel", {"txt", "MCMC Burnin Location"} ...
304 , "xlabel", {"txt", "Sampling Step"} ...
305 , "axes", {"xscale", "log"} ...
306 , "plot", {"linewidth", 3} ...
307 , silent_kws{:} ...
308 );
309
310 catch me
311
312 warning ( newline ...
313 + "Failed to create the visualizations for the " + colname + " data column of the chain file." + newline ...
314 + "Here is the error message:" + newline ...
315 + newline ...
316 + string(me.identifier) + newline + string(me.message) + newline ...
317 + newline ...
318 );
319
320 end
321
322 %%%%
323 %%%% Add the visualizations for ``proposalAdaptation``.
324 %%%%
325
326 try
327
328 %%%% Find the keywords in the column names.
329 %%%% This avoids exact matching, which is problematic between ParaMonte 1 and 2).
330 for colname = [string(self.df.Properties.VariableNames)]
331 if contains(lower(colname), "adaptation")
332 break;
333 end
334 end
335
336 self.vis.(colname) = struct();
337 self.vis.(colname).line = pm.vis.PlotLine ( @()self.df, "coly", colname, "colc", self.slfc ...
338 , "ylabel", {"txt", "Proposal Adaptation"} ...
339 , "xlabel", {"txt", "Sampling Step"} ...
340 , "axes", {"yscale", "log"} ...
341 , "plot", {"linewidth", 2} ...
342 , silent_kws{:} ...
343 );
344 self.vis.(colname).scatter = pm.vis.PlotScatter ( @()self.df, "coly", colname, "colc", self.slfc ...
345 , "ylabel", {"txt", "Proposal Adaptation"} ...
346 , "xlabel", {"txt", "Sampling Step"} ...
347 , "axes", {"yscale", "log"} ...
348 , silent_kws{:} ...
349 );
350
351 catch me
352
353 warning ( newline ...
354 + "Failed to create the visualizations for the " + colname + " data column of the chain file." + newline ...
355 + "Here is the error message:" + newline ...
356 + newline ...
357 + string(me.identifier) + newline + string(me.message) + newline ...
358 + newline ...
359 );
360
361 end
362
363 %%%%
364 %%%% Report the timing.
365 %%%%
366
367 self.checkpoint();
368
369 end
370
371 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
372
373 end
374
375 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
376
377end
FileContentsChainMCMC
This is the base class for generating objects that contain the contents of a chain file generated by ...
Definition: FileContentsChainMCMC.m:29
FileContentsChainMCMC::FileContentsChainMCMC
function FileContentsChainMCMC(in file, in silent, in sep, in format)
Return a scalar object of class pm.sampling.FileContentsChainMCMC.
FileContentsChainMCMC::setstats
function setstats(in self)
Compute the statistics of the parent object of class pm.sampling.FileContentsChainMCMC and store the ...
FileContentsChainMCMC::setvis
function setvis(in self)
Compute the statistics of the parent object of class pm.sampling.FileContentsChainMCMC and store the ...
FileContentsChain
This is the base class for generating objects that contain the contents of a chain file generated by ...
Definition: FileContentsChain.m:24
Paradram
This is the ParaDRAM class for generating instances of serial and parallel Delayed-Rejection Adaptive...
Definition: Paradram.m:18
PlotLine
This is the PlotLine class for generating instances of 2-dimensional Line Plot visualizations based o...
Definition: PlotLine.m:30
statistics
function statistics()
Return a scalar MATLAB logical that is true if and only if the current installation of MATLAB contain...
verbose
function verbose(in cmat, in dim, in weight, in checked)
Return a MATLAB double, cell, or table matrix whose rows or columns are unrolled according to a presp...
which
function which(in vendor)
Return the a MATLAB string containing the path to the first mpiexec executable binary found in system...