ParaMonte MATLAB 3.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation.
TilingSymm.m
Go to the documentation of this file.
1%> \brief
2%> This is the base class for generating instances
3%> of figures containing a symmetric square grid or corner of subplots.<br>
4%>
5%> \note
6%> See the list of class attributes below,
7%> also those of the superclass [pm.vis.Tiling](@ref Tiling).<br>
8%>
9%> \note
10%> See also the documentation of the constructor of the class [pm.vis.Corner::Corner](@ref Corner::Corner).<br>
11%>
12%> \final
13%>
14%> \author
15%> \JoshuaOsborne, May 21 2024, 9:20 AM, University of Texas at Arlington<br>
16%> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
17%> \AmirShahmoradi, July 7 2024, 12:53 AM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
18classdef Corner < pm.vis.Tiling
19
20 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
21
22 properties(Access = public, Hidden)
23 % %
24 % % df
25 % %
26 % % A scalar object of class [pm.data.DataFrame](@ref DataFrame)
27 % % containing the user-specified data to visualize.
28 % %
29 % df = [];
30 %
31 % rows
32 %
33 % A numeric vector that serves as a storage for an arbitrary subset of indices
34 % of the rows of the input dataframe reference ``dfref`` to the class constructor .
35 %
36 % It can be either:
37 %
38 % 1. a numeric range, or,
39 % 2. a list of row indices of the ``dfref``.
40 %
41 % Example usage:
42 %
43 % 1. rows = 15 : -2 : 8
44 % 2. rows = [12, 46, 7, 8, 9, 4, 7, 163]
45 %
46 % If ``rows`` is empty, the default will be set by the template subplots
47 % specified in the components ``diag``, ``lower``, and ``upper`` of the
48 % parent corner object.
49 %
50 %rows = [];
51 end
52
53 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
54
55 properties(Access = public)
56 %>
57 %> ``cols`` (standing for columns)
58 %>
59 %> The vector of MATLAB integers or names of of the input dataframe columns
60 %> that determines the columns of the specified dataframe to visualize.
61 %> It can have multiple forms:<br>
62 %> 1. a numeric or cell array of column indices in the input ``dfref``.
63 %> 2. a string or cell array of column names in ``dfref.Properties.VariableNames``.
64 %> 3. a cell array of a mix of the above two.
65 %> 4. a numeric range.<br>
66 %> Example usage:<br>
67 %> 1. self.cols = [7, 8, 9]
68 %> 2. self.cols = ["sampleLogFunc", "sampleVariable1"]
69 %> 3. self.cols = {"sampleLogFunc", 9, "sampleVariable1"}
70 %> 4. self.cols = 7:9 # every column in the data frame starting from column #7 to #9
71 %> 5. self.cols = 7:2:20 # every other column in the data frame starting from column #7 to #20
72 %> The ``i``th element of the specified ``cols`` will be used as value for:<br>
73 %> 1. the ``i``th column of data to visualize on the x-axis in subplot ``subplot{i, i}``.<br>
74 %> 1. the ``i``th column of data to visualize on the x-axis in subplot ``subplot{i, :}``.<br>
75 %> 1. the ``i``th column of data to visualize on the y-axis in subplot ``subplot{:, i}``.<br>
76 %> If ``cols`` is empty, no visualizations will be made.
77 %>
78 cols = [];
79 %>
80 %> ``diag``
81 %>
82 %> The scalar object of superclass [pm.vis.Subplot](@ref Subplot)
83 %> representing the template of the diagonal subplots to display.<br>
84 %> Note that only the visualization properties of the template are used.<br>
85 %> The data properties of the template are set by the ``make()`` method.<br>
86 %> (**optional**. The default value is [pm.vis.SubplotHistogram](@ref SubplotHistogram).)
87 %>
88 diag = pm.vis.SubplotHistogram();
89 %>
90 %> ``lower``
91 %>
92 %> The scalar object of superclass [pm.vis.Subplot](@ref Subplot)
93 %> representing the template of the lower-triangle subplots to display.<br>
94 %> The data properties of the template are set by the ``make()`` method.<br>
95 %> (**optional**. The default value is [pm.vis.SubplotContour](@ref SubplotContour).)
96 %>
97 lower = pm.vis.SubplotContour();
98 %>
99 %> ``upper``
100 %>
101 %> The scalar object of superclass [pm.vis.Subplot](@ref Subplot)
102 %> representing the template of the upper-triangle subplots to display.<br>
103 %> The data properties of the template are set by the ``make()`` method.<br>
104 %> (**optional**. The default value is [pm.vis.SubplotLineScatter](@ref SubplotLineScatter).)
105 %>
106 upper = pm.vis.SubplotLineScatter();
107 end
108
109 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
110
111 methods(Access = public)
112
113 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
114
115 %> \brief
116 %> Generate an return an object of class [pm.vis.Corner](@ref Corner).<br>
117 %>
118 %> \details
119 %> This is the constructor of the class [pm.vis.Corner](@ref Corner).<br>
120 %>
121 %> \param[in] dfref : See the documentation of the corresponding input
122 %> argument of the class [pm.vis.Subplot](@ref Subplot).<br>
123 %> (**optional**. default = ``table(zeros(0, 0))``)
124 %>
125 %> \param[in] varargin : Any ``property, value`` pair of the parent object.<br>
126 %> If the property is a ``struct()``, then its value must be given as a cell array,
127 %> with consecutive elements representing the struct ``property-name, property-value`` pairs.<br>
128 %> Note that all of these property-value pairs can be also directly set via the
129 %> parent object attributes, before calling the ``make()`` method.<br>
130 %>
131 %> \return
132 %> ``self`` : The output scalar object of class [pm.vis.Corner](@ref Corner).
133 %>
134 %> \interface{Corner}
135 %> \code{.m}
136 %>
137 %> plot = pm.vis.Corner(subplot);
138 %>
139 %> \endcode
140 %>
141 %> \note
142 %> See the list of class attributes below,
143 %> also those of the superclass [pm.vis.Tiling](@ref Tiling).
144 %>
145 %> \final{Corner}
146 %>
147 %> \author
148 %> \JoshuaOsborne, May 22 2024, 9:39 PM, University of Texas at Arlington<br>
149 function self = Corner(df, varargin)
150 if nargin < 3
151 upper = [];
152 end
153 if nargin < 2
154 lower = [];
155 end
156 if nargin < 1
157 diag = [];
158 end
159 self = self@pm.vis.Tiling(cell(0, 0), varargin{:});
160 end
161
162 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
163
164 %> \brief
165 %> Configure the figure settings and specifications,
166 %> make the figure and the subplots, and return nothing.
167 %> The subplots are made by calling their ``make()`` methods.
168 %>
169 %> \warning
170 %> This method has side-effects by manipulating
171 %> the existing attributes of the parent object.
172 %>
173 %> \param[in] varargin : Any ``property, value`` pair of the parent object.<br>
174 %> If the property is a ``struct()``, then its value must be given as a cell array,
175 %> with consecutive elements representing the struct ``property-name, property-value`` pairs.
176 %> Note that all of these property-value pairs can be also directly set via the
177 %> parent object attributes, before calling the ``make()`` method.
178 %>
179 %> \interface{make}
180 %> \code{.m}
181 %>
182 %> f = pm.vis.Corner.make(varargin);
183 %>
184 %> \endcode
185 %>
186 %> \example{make}
187 %>
188 %> f = pm.vis.Corner();
189 %> f.make()
190 %>
191 %> \final{make}
192 %>
193 %> \author
194 %> \JoshuaOsborne, May 21 2024, 7:56 AM, University of Texas at Arlington<br>
195 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
196 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
197 function make(self, varargin)
198
199 self.premake(varargin{:});
200
201 %%%% First set the tile dimensions.
202
203 if isempty(self.cols)
204 warning ( "The ``cols`` component of the parent corner object is empty." + newline ...
205 + "There is nothing to visualize." + newline ...
206 );
207 return;
208 else
209 rank = length(self.cols);
210 end
211
212 %%%% Define the subplot cell matrix.
213 %%%% The following code block may be improved in
214 %%%% the future to avoid full data copy to subplots.
215
216 iplt = 0;
217 self.subplot = cell(rank, rank);
218 for irow = 1 : rank
219 for icol = 1 : rank
220 iplt = iplt + 1;
221 if icol == irow
222 copyStream = getByteStreamFromArray(self.diag);
223 elseif icol < irow
224 copyStream = getByteStreamFromArray(self.lower);
225 elseif irow < icol
226 copyStream = getByteStreamFromArray(self.upper);
227 end
228 self.subplot{irow, icol} = getArrayFromByteStream(copyStream);
229 isEllipsoid = isa(self.subplot{irow, icol}, "pm.vis.SubplotEllipse") || isa(self.subplot{irow, icol}, "pm.vis.SubplotEllipse3");
230
231 if isEllipsoid
232 self.subplot{irow, icol}.dimx = self.cols(irow);
233 self.subplot{irow, icol}.dimy = self.cols(icol);
234 else
235 if isprop(self.subplot{irow, icol}, "colx")
236 self.subplot{irow, icol}.colx = self.cols(icol);
237 end
238 if isprop(self.subplot{irow, icol}, "coly")
239 self.subplot{irow, icol}.coly = self.cols(irow);
240 end
241
242 if 1 < lencolc
243 self.subplot{irow, icol}.colc = self.template.colc(iplt);
244 elseif lencolc == 1 && isprop(self.template, "colorbar") && isempty(self.template.colorbar.enabled)
245 self.subplot{irow, icol}.colorbar.enabled = false;
246 elseif lencolc == 0 && isprop(self.template, "colormap") && isempty(self.template.colormap.enabled)
247 self.subplot{irow, icol}.colormap.enabled = true;
248 end
249 end
250 end
251 end
252
253 make@pm.vis.Tiling(self);
254
255 %%%% Define a single colorbar.
256
257 if ~isEllipsoid
258
259 unicbar = lencolc == 1;
260 if unicbar && ~isempty(self.template.colormap.enabled)
261 unicbar = self.template.colormap.enabled;
262 end
263 if unicbar && ~isempty(self.template.colorbar.enabled)
264 unicbar = self.template.colorbar.enabled;
265 end
266 if unicbar
267
268 %%%% Get the start and end positions of the leftmost, lowest, rightmost, and highest axes.
269
270 % iplt = 0;
271 % positions = zeros(4, nplt);
272 % for icol = 1 : ncol
273 % for irow = 1 : nrow
274 % if pm.introspection.istype(self.subplot{irow, icol}, "pm.vis.Subplot")
275 % iplt = iplt + 1;
276 % positions(:, iplt) = self.subplot{irow, icol}.fout.axes.Position;
277 % end
278 % end
279 % end
280 %
281 % for i = 2 : -1 : 1
282 % start(i) = min(positions(i, :));
283 % finit(i) = max(positions(i, :) + positions(i + 2, :));
284 % end
285
286 %%%% Create new invisible axes.
287
288 kws = struct();
289 for prop = [ "colorbar" ...
290 ]
291 if isprop(self.template, prop)
292 kws.(prop) = self.template.comp2hash(prop);
293 end
294 end
295 %ax = axes("position", [start, finit], "visible", "off");
296 self.fout.colorbar = colorbar(kws.colorbar{:});
297 self.fout.colorbar.Layout.Tile = 'east';
298
299 dfcopy = self.template.df.copy();
300 [~, colnamc] = pm.str.locname(dfcopy.Properties.VariableNames, self.template.colc);
301 ylabel(self.fout.colorbar, colnamc(1));
302
303 end
304
305 end
306
307 end % function
308
309 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
310
311 %> \brief
312 %> Reset the properties of the figure to the original default settings.
313 %> Use this method when you change many attributes of the plot and
314 %> you want to clean up and go back to the default settings.
315 %>
316 %> \param[in] varargin : Any ``property, value`` pair of the parent object.<br>
317 %> If the property is a ``struct()``, then its value must be given as a cell array,
318 %> with consecutive elements representing the struct ``property-name, property-value`` pairs.
319 %> Note that all of these property-value pairs can be also directly set via the
320 %> parent object attributes, before calling the ``make()`` method.
321 %>
322 %> \interface{reset}
323 %> \code{.m}
324 %>
325 %> pm.vis.Corner.reset() % reset all object properties to the default settings.
326 %>
327 %> \endcode
328 %>
329 %> \final{reset}
330 %>
331 %> \author
332 %> \JoshuaOsborne, May 21 2024, 7:58 AM, University of Texas at Arlington<br>
333 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
334 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
335 function reset(self, varargin)
336
337 self.dfref = [];
338 self.cols = [];
339 self.rows = [];
340
341 reset@pm.vis.Tiling(self, varargin{:});
342
343 if isempty(self.diag)
344 self.diag = pm.vis.SubplotHistogram([]);
345 end
346 if isempty(self.lower)
347 self.diag = pm.vis.SubplotContour([]);
348 end
349 if isempty(self.upper)
350 self.diag = pm.vis.SubplotLineScatter([]);
351 end
352
353 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
354 %%%% RULE 0: Any non-MATLAB-default setting must be preferably set in the make() method to override user null values.
355 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
356
357 %self.premake(varargin{:}); % This is the subclass method!
358 end
359
360 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
361
362 %> \brief
363 %> Prepare the corner plot specs for subsequent visualization by ``make()``.
364 %>
365 %> \warning
366 %> This method causes side-effects by manipulating
367 %> the existing attributes of the object.
368 %>
369 %> \param[in] varargin : Any ``property, value`` pair of the parent object.<br>
370 %> If the property is a ``struct()``, then its value must be given as a cell array,
371 %> with consecutive elements representing the struct ``property-name, property-value`` pairs.
372 %> Note that all of these property-value pairs can be also directly set via the
373 %> parent object attributes, before calling the ``make()`` method.
374 %>
375 %> \example{premake}
376 %>
377 %> For example, change the left/bottom margin of the main
378 %> axis of the figure to provide room for lengthy variable names.
379 %> Then call the ``self.update()`` method to reflect the changes.
380 %>
381 %> \final{premake}
382 %>
383 %> \author
384 %> \JoshuaOsborne, May 21 2024, 8:00 AM, University of Texas at Arlington<br>
385 function premake(self, varargin)
386
387 premake@pm.vis.Tiling(self, varargin{:});
388 % if ~isa(self.diag, "self.type.is.histfit") && ~isa(self.diag, "self.type.is.histogram")
389 % help("pm.vis.Corner");
390 % error ( newline ...
391 % + "The component ``diag`` of the parent object must be of" + newline ...
392 % + "superclass [pm.vis.SubplotHistfit](@ref SubplotHistfit) or [pm.vis.SubplotHistogram](@ref SubplotHistogram)." + newline ...
393 % + "For more information, see the class documentation displayed above." + newline ...
394 % + newline ...
395 % );
396 % end
397 %
398 % if self.lower.type.is.d1
399 % help("pm.vis.Corner");
400 % error ( newline ...
401 % + "The component ``lower`` of the parent object must be of superclass" + newline ...
402 % + " 1. pm.vis.SubplotLine" + newline ...
403 % + " 2. pm.vis.SubplotScatter" + newline ...
404 % + " 3. pm.vis.SubplotLineScatter" + newline ...
405 % + " 4. pm.vis.SubplotLineScatter" + newline ...
406 % + "For more information, see the class documentation displayed above." + newline ...
407 % + newline ...
408 % );
409 % end
410
411 end
412
413 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
414
415 end
416
417 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
418
419 methods(Access = public, Hidden)
420
421 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
422
423 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
424
425 end
426
427 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
428
429end
name
function name(in vendor)
Return the MPI library name as used in naming the ParaMonte MATLAB shared libraries.
list
function list()
Return a list of MATLAB strings containing the names of OS platforms supported by the ParaMonte MATLA...
Corner
This is the base class for generating instances of figures containing a symmetric square grid or corn...
Definition: Corner.m:19
Corner::cols
Property cols
Definition: Corner.m:81
Corner::diag
Property diag
Definition: Corner.m:92
Corner::premake
function premake(in self, in varargin)
Prepare the corner plot specs for subsequent visualization by make().
Corner::upper
Property upper
Definition: Corner.m:112
Corner::lower
Property lower
Definition: Corner.m:102
Corner::reset
function reset(in self, in varargin)
Reset the properties of the figure to the original default settings. Use this method when you change ...
Corner::make
function make(in self, in varargin)
Configure the figure settings and specifications, make the figure and the subplots,...
Corner::Corner
function Corner(in df, in varargin)
Generate an return an object of class pm.vis.Corner.
DataFrame
This is the abstract class for generating instances of objects that can contain basic attributes requ...
Definition: DataFrame.m:25
SubplotContour
This is the SubplotContour class for generating instances of 2-dimensional Contour Subplot visualizat...
Definition: SubplotContour.m:30
SubplotHistogram
This is the SubplotHistogram class for generating instances of 1-dimensional Histogram Subplot visual...
Definition: SubplotHistogram.m:26
SubplotLineScatter
This is the SubplotLineScatter class for generating instances of 2-dimensional Line-Scatter Subplot v...
Definition: SubplotLineScatter.m:26
Subplot
This is the abstract class for generating instances of axes with various types of plots from one or m...
Definition: Subplot.m:188
Tiling
This is the base class for generating instances of figures containing a tile of subplots.
Definition: Tiling.m:19
clean
function clean()
Remove all paths that contain the ParaMonte lib directory from the MATLAB path variable.
copy
function copy(in from, in to, in fields)
Copy the contents of the struct/object from to the struct/object to recursively and without destroyin...
istype
function istype(in varval, in vartype, in varsize)
Return true if and only if the input varval conforms with the specified input type vartype and the sp...