ParaMonte MATLAB 3.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation.
TilingLayout.m
Go to the documentation of this file.
1%> \brief
2%> This is the base class for generating instances of objects that contains
3%> layout information for a set of tiled subplots in a single figure.<br>
4%>
5%> \details
6%> For more information, see the documentation of the class constructor
7%> [pm.vis.TilingLayout::TilingLayout](@ref TilingLayout::TilingLayout).<br>
8%>
9%> \note
10%> This class is not meant to be used directly by the end users.<br>
11%> Instead, use other classes that internally use this class as a component.<br>
12%>
13%> \note
14%> See the list of class attributes below,
15%> also those of the superclass [pm.matlab.Handle](@ref Handle).<br>
16%>
17%> \note
18%> The tiling layout generated by this class is different from new MATLAB ``tiledlayout``.<br>
19%> Specifically, this class aims to mimic the layout originally devised the first version of ParaMonte MATLAB library release.<br>
20%> This ParaMonte tiling layout is, for example, used in making corner plots (formerly known as ``GridPlot`` in ParaMonte V1).<br>
21%>
22%> \final
23%>
24%> \author
25%> \AmirShahmoradi, August 31 2024, 6:40 AM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
26classdef TilingLayout < pm.matlab.Handle
27
28 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
29
30 properties(Access = public)
31 %>
32 %> ``position``
33 %>
34 %> The MATLAB vector of length four containing a set of positive values
35 %> representing the figure pixel coordinates as ``[startx, starty, width, height]`` with respect to the screen.<br>
36 %> The default value is set such that the whole tiling looks square-shaped.<br>
37 %>
38 position = [];
39 %>
40 %> ``tiling``
41 %>
42 %> The scalar MATLAB ``struct`` containing the following components:<br>
43 %> <ol>
44 %> <li> ``nrow`` : The MATLAB scalar positive whole-number
45 %> representing the number of subplots in each column of the subplot tiling.<br>
46 %> <li> ``ncol`` : The MATLAB scalar positive whole-number
47 %> representing the number of subplots in each row of the subplot tiling.<br>
48 %> <li> ``tile`` : The scalar MATLAB ``struct`` containing the following components:<br>
49 %> <ol>
50 %> <li> ``width`` : The MATLAB scalar positive number in the range ``[0, 1]``,
51 %> containing the width of each tile (subplot) along the x-axis
52 %> in normalized units **with respect to the tiling width**.<br>
53 %> The default value is ``14 / 15``.<br>
54 %> <li> ``height`` : The MATLAB scalar positive number in the range ``[0, 1]``,
55 %> containing the height of each tile (subplot) along the x-axis in normalized units.<br>
56 %> in normalized units **with respect to the tiling height**.<br>
57 %> The default value is ``14 / 15``.<br>
58 %> <li> ``position`` : The MATLAB tensor of shape ``[4, nrow, ncol]``, each ``[:, irow, icol]``
59 %> slice of which contains a set of positive normalized values in the range ``[0, 1]``,
60 %> representing the position of the tile sitting at ``[irow, icol]`` starting from
61 %> the top-left corner of the tiling.<br>
62 %> The positions are computed **with respect to the figure container**.<br>
63 %> The position values are calculated based on the tiling position.<br>
64 %> **Beware that this component is always set by the ``update()`` method.**<br>
65 %> </ol>
66 %> <li> ``position`` : The MATLAB vector of length four containing
67 %> a set of positive normalized values in the range ``[0, 1]``,
68 %> representing the whole tiling coordinates as ``[startx, starty, width, height]``.<br>
69 %> The default value is ``[0.07, 0.07, 0.93, 0.93]``.<br>
70 %> </ol>
71 %>
72 tiling = struct();
73 %>
74 %> ``cbarh``
75 %>
76 %> The MATLAB ``struct`` containing information about the **horizontal colorbar**
77 %> that can be optionally added to the main axes (i.e., the collection of all axes).<br>
78 %> It has the following components:<br>
79 %>
80 %> <ol>
81 %> <li> ``position`` : The MATLAB vector of length four containing
82 %> a set of positive normalized values in the range ``[0, 1]``,
83 %> representing the whole colorbar coordinates as ``[startx, starty, width, height]``.<br>
84 %> The default value is set such that the colorbar sits reasonably at the top of the tiling.<br>
85 %> <li> ``margint`` : The MATLAB scalar positive ``double`` in the range ``[0, 1]``,
86 %> representing the top margin of the horizontal colorbar that appears on top of the tiling.<br>
87 %> This margin adds room for adding the colorbar axes label and tick marks.<br>
88 %> The default value is ``0.07``.<br>
89 %> <li> ``enabled`` : The MATLAB ``logical`` scalar that allows addition of the colorbar if ``true``.<br>
90 %> The default value is ``false``.<br>
91 %> </ol>
92 %>
93 cbarh = struct();
94 %>
95 %> ``cbarh``
96 %>
97 %> The MATLAB ``struct`` containing information about the **horizontal colorbar**
98 %> that can be optionally added to the main axes (i.e., the collection of all axes).<br>
99 %> It has the following components:<br>
100 %>
101 %> <ol>
102 %> <li> ``position`` : The MATLAB vector of length four containing
103 %> a set of positive normalized values in the range ``[0, 1]``,
104 %> representing the whole colorbar coordinates as ``[startx, starty, width, height]``.<br>
105 %> The default value is set such that the colorbar sits reasonably at the top of the tiling.<br>
106 %> <li> ``marginr`` : The MATLAB scalar positive ``double`` in the range ``[0, 1]``,
107 %> representing the top margin of the vertical colorbar that appears to the right of the tiling.<br>
108 %> This margin adds room for adding the colorbar axes label and tick marks.<br>
109 %> The default value is ``0.07``.<br>
110 %> <li> ``enabled`` : The MATLAB ``logical`` scalar that allows addition of the colorbar if ``true``.<br>
111 %> The default value is ``false``.<br>
112 %> </ol>
113 %>
114 cbarv = struct();
115 end
116
117 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
118
119 methods(Access = public)
120
121 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
122
123 %> \brief
124 %> Construct and return an object of class [pm.vis.TilingLayout](@ref TilingLayout).<br>
125 %>
126 %> \details
127 %> This is the constructor of the class [pm.vis.TilingLayout](@ref TilingLayout).<br>
128 %>
129 %> \param[in] nrow : The input scalar MATLAB positive whole-number, containing the number of rows of axes in the tiling.<br>
130 %> \param[in] ncol : The input scalar MATLAB positive whole-number, containing the number of columns of axes in the tiling.<br>
131 %> \param[in] varargin : Any ``property, value`` pair of the parent object.<br>
132 %> If the property is a ``struct()``, then its value must be given as a cell array,
133 %> with consecutive elements representing the struct ``property-name, property-value`` pairs.<br>
134 %> Note that all of these property-value pairs can be also directly set via the
135 %> parent object attributes, before calling the ``make()`` method.<br>
136 %>
137 %> \return
138 %> ``self`` : The output scalar object of class [pm.vis.TilingLayout](@ref TilingLayout).<br>
139 %>
140 %> \interface{TilingLayout}
141 %> \code{.m}
142 %>
143 %> g = pm.vis.TilingLayout([], [], varargin);
144 %> g = pm.vis.TilingLayout([], ncol, upper, varargin);
145 %> g = pm.vis.TilingLayout(nrow, [], upper, varargin);
146 %> g = pm.vis.TilingLayout(nrow, ncol, upper, varargin);
147 %>
148 %> \endcode
149 %>
150 %> \example{TilingLayout}
151 %> \include{lineno} example/vis/TilingLayout/main.m
152 %> \vis{TilingLayout}
153 %> \image html example/vis/TilingLayout/TilingLayout.1.png width=700
154 %>
155 %> \final{TilingLayout}
156 %>
157 %> \author
158 %> \AmirShahmoradi, August 31 2024, 6:40 AM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
159 function self = TilingLayout(nrow, ncol, varargin)
160 self.tiling.nrow = nrow;
161 self.tiling.ncol = ncol;
162 self.reset(varargin{:});
163 end
164
165 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
166
167 %> \brief
168 %> Reset the properties of the figure to the original default settings.<br>
169 %>
170 %> \details
171 %> Use this method when you change many attributes of the plot and
172 %> you want to clean up and go back to the default settings.<br>
173 %>
174 %> \param[in] self : The **implicitly-passed** input argument representing the parent object of the method.<br>
175 %> \param[in] varargin : Any ``property, value`` pair of the parent object.<br>
176 %> If the property is a ``struct()``, then its value must be given as a cell array,
177 %> with consecutive elements representing the struct ``property-name, property-value`` pairs.<br>
178 %> Note that all of these property-value pairs can be also directly set via the
179 %> parent object attributes, before calling the ``make()`` method.<br>
180 %>
181 %> \interface{reset}
182 %> \code{.m}
183 %>
184 %> g = pm.vis.TilingLayout(varargin)
185 %> g.reset(varargin); % reset all object properties to the default settings.
186 %>
187 %> \endcode
188 %>
189 %> \final{reset}
190 %>
191 %> \author
192 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
193 %> \AmirShahmoradi, July 7 2024, 12:53 AM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
194 function reset(self, varargin)
195 self.tiling.tile = struct();
196 self.position = nan * zeros(4, 1);
197 self.tiling.position = nan * zeros(4, 1);
198 self.tiling.tile.position = nan * zeros(4, self.tiling.nrow, self.tiling.ncol);
199 self.tiling.tile.height = [];
200 self.tiling.tile.width = [];
201 self.tiling.height = [];
202 self.tiling.width = [];
203 self.cbarh.margint = [];
204 self.cbarv.marginr = [];
205 for cbar = ["cbarh", "cbarv"]
206 self.(cbar).enabled = [];
207 self.(cbar).position = [];
208 end
209 self.update(varargin{:});
210 end
211
212 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
213
214 %> \brief
215 %> Update the figure, tiling, and colorbar layout based on the specified components positions.<br>
216 %>
217 %> \details
218 %> For example, change the tiling or colorbar positions or the tile counts through the relevant object components,
219 %> then use this method to renormalize all positions (to range ``[0, 1]``) and update the individual tile positions.<br>
220 %>
221 %> \param[in] self : The **implicitly-passed** input argument representing the parent object of the method.<br>
222 %> \param[in] varargin : Any ``property, value`` pair of the parent object.<br>
223 %> If the property is a ``struct()``, then its value must be given as a cell array,
224 %> with consecutive elements representing the struct ``property-name, property-value`` pairs.<br>
225 %> Note that all of these property-value pairs can be also directly set via the
226 %> parent object attributes, before calling the ``make()`` method.<br>
227 %>
228 %> \interface{update}
229 %> \code{.m}
230 %>
231 %> g = pm.vis.TilingLayout(subplot, varargin);
232 %> g.update(varargin);
233 %>
234 %> \endcode
235 %>
236 %> \warning
237 %> This method causes side-effects by manipulating
238 %> the existing attributes of the object.<br>
239 %>
240 %> \example{update}
241 %>
242 %> \final{update}
243 %>
244 %> \author
245 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
246 %> \AmirShahmoradi, July 7 2024, 12:53 AM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
247 function update(self, varargin)
248
249 %%%%
250 %%%% parse optional arguments.
251 %%%%
252
253 if ~isempty(varargin)
254 self.hash2comp(varargin);
255 end
256
257 %%%%
258 %%%% parse optional arguments.
259 %%%%
260
261 for cbar = ["cbarh", "cbarv"]
262 if isempty(self.(cbar).enabled)
263 self.(cbar).enabled = false;
264 end
265 end
266
267 %%%%
268 %%%% Setup default tiling dimensions.
269 %%%%
270
271 self.setKeyVal("tiling", "nrow", 1);
272 self.setKeyVal("tiling", "ncol", 1);
273 self.setKeyVal("tiling", "tile", "width", 14 / 15);
274 self.setKeyVal("tiling", "tile", "height", 14 / 15);
275
276 %%%%
277 %%%% Setup tiling position.
278 %%%%
279
280 if isnan(self.tiling.position(1)); self.tiling.position(1) = 0.07; end
281 if isnan(self.tiling.position(2)); self.tiling.position(2) = 0.07; end
282 if isnan(self.tiling.position(3)); self.tiling.position(3) = 1 - self.tiling.position(1); end
283 if isnan(self.tiling.position(4)); self.tiling.position(4) = 1 - self.tiling.position(2); end
284
285 %%%%
286 %%%% vertical colorbar specs.
287 %%%%
288
289 def = [ self.tiling.position(1) + self.tiling.position(3) ...
290 , self.tiling.position(2) ...
291 , 0.03 ...
292 , self.tiling.position(4) - (1 - self.tiling.tile.height) ...
293 ];
294 if isempty(self.cbarv.position)
295 self.cbarv.position = def;
296 else
297 for i = 1 : length(self.cbarv.position)
298 if isnan(self.cbarv.position(i))
299 self.cbarv.position(i) = def(i);
300 end
301 end
302 end
303 if isempty(self.cbarv.marginr) || isnan(self.cbarv.marginr)
304 self.cbarv.marginr = 0.07;
305 end
306
307 %%%%
308 %%%% horizontal colorbar specs.
309 %%%%
310
311 def = [ self.tiling.position(1) ...
312 , self.tiling.position(2) + self.tiling.position(4) ...
313 , self.tiling.position(3) - (1 - self.tiling.tile.width) ...
314 , 0.03 ...
315 ];
316 if isempty(self.cbarh.position)
317 self.cbarh.position = def;
318 else
319 for i = 1 : length(self.cbarh.position)
320 if isnan(self.cbarh.position(i))
321 self.cbarh.position(i) = def(i);
322 end
323 end
324 end
325 if isempty(self.cbarh.margint) || isnan(self.cbarh.margint)
326 self.cbarh.margint = 0.07;
327 end
328
329 normfac = struct("cbarv", 1, "cbarh", 1, "width", 1, "height", 1);
330
331 %%%%
332 %%%% Renormalize positions if colorbars are activated.
333 %%%%
334
335 if self.cbarv.enabled
336 normfac.cbarv = 1 / (self.cbarv.position(1) + self.cbarv.position(3) + self.cbarv.marginr); % last term adds a right margin.
337 self.tiling.position(1) = self.tiling.position(1) * normfac.cbarv;
338 self.tiling.position(3) = self.tiling.position(3) * normfac.cbarv;
339 self.cbarv.position(1) = self.cbarv.position(1) * normfac.cbarv;
340 self.cbarv.position(3) = self.cbarv.position(3) * normfac.cbarv;
341 self.cbarh.position(1) = self.cbarh.position(1) * normfac.cbarv;
342 self.cbarh.position(3) = self.cbarh.position(3) * normfac.cbarv;
343 end
344
345 if self.cbarh.enabled
346 normfac.cbarh = 1 / (self.cbarh.position(2) + self.cbarh.position(4) + self.cbarh.margint); % last term adds a right margin.
347 self.tiling.position(2) = self.tiling.position(2) * normfac.cbarh;
348 self.tiling.position(4) = self.tiling.position(4) * normfac.cbarh;
349 self.cbarh.position(2) = self.cbarh.position(2) * normfac.cbarh;
350 self.cbarh.position(4) = self.cbarh.position(4) * normfac.cbarh;
351 self.cbarv.position(2) = self.cbarv.position(2) * normfac.cbarh;
352 self.cbarv.position(4) = self.cbarv.position(4) * normfac.cbarh;
353 end
354
355 %%%%
356 %%%% Set the tile positions.
357 %%%%
358
359 self.tiling.tile.position = zeros(4, self.tiling.nrow, self.tiling.ncol);
360 tile_height_wrt_fig = self.tiling.position(4) / self.tiling.nrow;
361 tile_width_wrt_fig = self.tiling.position(3) / self.tiling.ncol;
362 for icol = 1 : self.tiling.ncol
363 for irow = 1 : self.tiling.nrow
364 jrow = self.tiling.nrow - irow + 1;
365 self.tiling.tile.position(:, irow, icol) = [ self.tiling.position(1) + (icol - 1) * tile_width_wrt_fig ...
366 , self.tiling.position(2) + (jrow - 1) * tile_height_wrt_fig ...
367 , self.tiling.tile.width * tile_width_wrt_fig ...
368 , self.tiling.tile.height * tile_height_wrt_fig ...
369 ];
370 end
371 end
372
373 %%%%
374 %%%% Add the missing margin lengths to the colorbar axes.
375 %%%%
376 if self.cbarv.enabled
377 self.cbarv.position(4) = self.tiling.position(4) - (1 - self.tiling.tile.height) * tile_height_wrt_fig;
378 end
379 if self.cbarh.enabled
380 self.cbarh.position(3) = self.tiling.position(3) - (1 - self.tiling.tile.width) * tile_width_wrt_fig;
381 end
382
383 %%%%
384 %%%% Set the figure position.
385 %%%%
386
387 if isempty(self.position) || any(isnan(self.position))
388 fig = struct();
389 self.position = get(0, 'ScreenSize');
390 fig.center = [mean(self.position([1, 3])), mean(self.position([2, 4]))];
391 fig.length = min(self.position(3 : 4)) * .8; % The fraction accounts for padding.
392 if ~self.cbarh.enabled && self.cbarv.enabled
393 normfac.height = normfac.cbarv;
394 end
395 if ~self.cbarv.enabled && self.cbarh.enabled
396 normfac.width = normfac.cbarh;
397 end
398 fig.width = fig.length * normfac.width;
399 fig.height = fig.length * normfac.height;
400 self.position = [ fig.center(1) - 0.5 * fig.width ...
401 , fig.center(2) - 0.5 * fig.height ...
402 , fig.width ...
403 , fig.height ...
404 ];
405 end
406
407 end
408
409 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
410
411 end
412
413 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
414
415end
name
function name(in vendor)
Return the MPI library name as used in naming the ParaMonte MATLAB shared library directories.
list
function list()
Return a list of MATLAB strings containing the names of OS platforms supported by the ParaMonte MATLA...
version
function version(in silent)
Return a scalar MATLAB string containing the latest available ParaMonte MATLAB version newer than the...
Handle
This is the base class for generating subclass of MATLAB handle superclass whose annoying methods are...
Definition: Handle.m:24
TilingLayout
This is the base class for generating instances of objects that contains layout information for a set...
Definition: TilingLayout.m:27
TilingLayout::position
Property position
Definition: TilingLayout.m:41
TilingLayout::cbarh
Property cbarh
Definition: TilingLayout.m:98
TilingLayout::update
function update(in self, in varargin)
Update the figure, tiling, and colorbar layout based on the specified components positions.
TilingLayout::reset
function reset(in self, in varargin)
Reset the properties of the figure to the original default settings.
TilingLayout::cbarv
Property cbarv
Definition: TilingLayout.m:120
TilingLayout::tiling
Property tiling
Definition: TilingLayout.m:76
TilingLayout::TilingLayout
function TilingLayout(in nrow, in ncol, in varargin)
Construct and return an object of class pm.vis.TilingLayout.
clean
function clean()
Remove all paths that contain the ParaMonte lib directory from the MATLAB path variable.
release
function release(in type)
Return a scalar MATLAB string containing the MATLAB release version, year, or season as requested.
which
function which(in vendor)
Return the a MATLAB string containing the path to the first mpiexec executable binary found in system...