SubplotEllipse3 Class Reference

This is the SubplotEllipse3 class for generating instances of 3-dimensional Ellipse Subplot visualizations based on the relevant MATLAB intrinsic functions.
More...

Inheritance diagram for SubplotEllipse3:

Collaboration diagram for SubplotEllipse3:

Public Member Functions
function	SubplotEllipse3 (in gramian, in center, in zval, in cval, in varargin)
	Construct and return an object of class pm.vis.SubplotEllipse. More...
function	reset (in self, in varargin)
	Reset the properties of the plot to the original default settings. More...
function	premake (in self, in varargin)
	Prepare the subplot for visualization. More...
function	make (in self, in varargin)
	Generate a plot from the selected dimensions of the input ellipsoid data to the object constructor. More...

Data Fields
Property	names
Property	dimx
Property	dimy
Property	ellindex
Property	gramian
Property	center
Property	zval
Property	cval
Property	ndim
Property	nell
Property	npnt
Property	workspace

Detailed Description

This is the SubplotEllipse3 class for generating instances of 3-dimensional Ellipse Subplot visualizations based on the relevant MATLAB intrinsic functions.

Note

See the documentation of the constructor of the class pm.vis.SubplotEllipse3 for example usage.

See the list of class attributes below, also those of the superclass pm.vis.SubplotLineScatter3.

See also

pm.vis.Cascade
pm.vis.Subplot
pm.vis.Triplex
pm.vis.Figure
pm.vis.Plot
pm.vis.Tile

Final Remarks ⛓

---

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
   
2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
   

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright

Computational Data Science Lab

Author:

Fatemeh Bagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.
Amir Shahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin

Definition at line 27 of file SubplotEllipse3.m.

Constructor & Destructor Documentation

SubplotEllipse3()

function SubplotEllipse3::SubplotEllipse3	(	in	gramian,
		in	center,
		in	zval,
		in	cval,
		in	varargin
	)

Construct and return an object of class pm.vis.SubplotEllipse.

In the following documentation,

1. The variable ndim represents the number of ellipsoids in the input data.
   The value of ndim is inferred from the shapes of the input gramian and center arguments as max([2, size(gramian, 1), size(center, 1)]).
   

2. The variable nell represents the number of ellipsoids in the input data.
   The value of nell is inferred from the shapes of the input gramian, center, zval, and cval arguments as max([size(gramian, 3), size(center, 2), size(zval, 2), size(cval, 2)]).
   If the above expression yields zero, then nell is set to 75.
   

3. The variable npnt represents the number of points used in visualizing each ellipsoid.
   The value of npnt is inferred from the shapes of the input arguments zval and czval as max(size(zval, 1), size(cval, 1)).
   If the above expression yields zero or one, then npnt is set to 100.
   

Parameters

[in]	gramian	: The MATLAB (function handle returning an) object that can be either, an empty object (e.g., []), in which case, the value repmat(eye(ndim, ndim), 1, 1, nell) will be used. a scalar, containing the value of the diagonal elements of the diagonal matrices representing the Gramian matrices of all nell ellipsoids in the input data. a vector of shape [1, 1, nell] such that gramian(1, 1, iell) represents the diagonal value to be used in constructing the Gramian matrix of the ellipsoid iell` in the inputnell`` ellipsoid data. a matrix of shape [ndim, ndim, 1] used in constructing the Gramian matrices of all nell ellipsoids in the input data. a tensor of shape [ndim, ndim, nell] such that gramian(:, :, iell) represents the Gramian matrix of the ellipsoid `iell in the input data. While it is possible to pass a data directly to this class, it is highly recommended to pass a function handle that returns such data when called, allowing the visualization data to be dynamically updated when needed.
[in]	center	: The MATLAB (function handle returning an) object that can be either, an empty object (e.g., []), in which case, the value zeros(ndim, nell) will be used. a scalar, containing the value to assign to all coordinates of the centers of all nell ellipsoids in the input data. a vector of shape [1, nell] such that center(1, iell) represents the value of all coordinates of the center of the ellipsoid iell` in the inputnell`` ellipsoid data. a vector of shape [ndim, 1] such that center(idim, 1) represents the value of idim coordinate of the centers of all nell ellipsoids in the input data. a matrix of shape [ndim, nell] such that center(:, iell) represents the coordinates of the center of the ellipsoid `iell in the input data. While it is possible to pass data directly to this class, it is highly recommended to pass a function handle that returns such data when called, allowing the visualization data to be dynamically updated when needed.
[in]	zval	: The MATLAB (function handle returning an) object that can be either, an empty object (e.g., []), in which case, the value repmat(1 : nell, npnt, 1) will be used. a scalar, containing the value to assign to the z-axis coordinates of all npnt points used in the visualization of nell ellipsoids in the input data. a vector of shape [1, nell] such that zval(1, iell) represents the value of z-axis coordinates of all npnt points used in the visualization of the ellipsoid iell` in the inputnell`` ellipsoid data. a vector of shape [npnt, 1] such that zval(ipnt, 1) contains the z-axis value of ipnt points in the representations of all nell ellipsoids in the input data. a matrix of shape [npnt, nell] such that zval(:, iell) represents the z-axis coordinates of all npnt points used in the visualization of the ellipsoid `iell in the input data. While it is possible to pass data directly to this class, it is highly recommended to pass a function handle that returns such data when called, allowing the visualization data to be dynamically updated when needed.
[in]	cval	: The MATLAB (function handle returning an) object that can be either, an empty object (e.g., []), in which case, the input value zval will be used. a scalar, containing the value to assign to color values of all npnt points used in the visualization of nell ellipsoids in the input data. a vector of shape [1, nell] such that cval(1, iell) represents the color values of all npnt points used in the visualization of the ellipsoid iell` in the inputnell`` ellipsoid data. a vector of shape [npnt, 1] such that cval(ipnt, 1) contains the color values of ipnt points in the representations of all nell ellipsoids in the input data. a matrix of shape [npnt, nell] such that center(:, iell) represents the color values of all npnt points used in the visualization of the ellipsoid `iell in the input data. While it is possible to pass data directly to this class, it is highly recommended to pass a function handle that returns such data when called, allowing the visualization data to be dynamically updated when needed. The input value for cval is used only if colormap.enabled component of the output object of class pm.vis.SubplotEllipse3 is set to true.
[in]	varargin	: Any property, value pair of the object. If the property is a struct(), then its value must be given as a cell array, with consecutive elements representing the struct property-name, property-value pairs. Note that all of these property-value pairs can be also directly set via the parent object attributes, before calling the make() method.

Returns

self : The output object of class pm.vis.SubplotEllipse3.

Possible calling interfaces ⛓

s = pm.vis.SubplotEllipse3();
s = pm.vis.SubplotEllipse3(gramian);
s = pm.vis.SubplotEllipse3(gramian, center);
s = pm.vis.SubplotEllipse3(gramian, center, zval);
s = pm.vis.SubplotEllipse3(gramian, center, zval, cval);
s = pm.vis.SubplotEllipse3(gramian, center, zval, cval, varargin);

Note

To generate a 2D plot of ellipsoids, simply execute the MATLAB command view(2) to change the camera view to 2D.

See also the documentation of the attributes of the superclass pm.vis.SubplotLineScatter3.

Example usage ⛓

cd(fileparts(mfilename('fullpath'))); % Change working directory to source code directory.
addpath('../../../'); % Add the ParaMonte library root directory to the search path.
 
sampler = pm.sampling.Paradram();
sampler.spec.outputStatus = "retry";
sampler.spec.outputFileName = "mvn";
sampler.spec.randomSeed = 28457353; % make sampling reproducible.
sampler.spec.outputChainSize = 30000; % Use a small chain size for illustration.
sampler.spec.outputRestartFileFormat = "ascii";
sampler.silent = true;
sampler.run ( @(x) -sum((x - [-5; 5; 10; -10]) .^ 2) ...
            , 4 ...
            );
 
restart = sampler.readRestart();
restart = restart{1};
 
figure("color", "white");
sv = pm.vis.SubplotEllipse3(restart.proposalCov, restart.proposalMean, transpose(restart.uniqueStateVisitCount));
sv.make("axes", {"zscale", "log"}, "dimx", [1, 3], "dimy", [1, 3] + 1);
pm.vis.figure.savefig("SubplotEllipse3.1.png", "-m3");
 
close all;

Visualization of the example output ⛓

Final Remarks ⛓

---

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
   
2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
   

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright

Computational Data Science Lab

Author:

Joshua Alexander Osborne, May 21 2024, 5:35 PM, University of Texas at Arlington
Fatemeh Bagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.
Amir Shahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin

Member Function Documentation

make()

function SubplotEllipse3::make	(	in	self,
		in	varargin
	)

Generate a plot from the selected dimensions of the input ellipsoid data to the object constructor.

Note

This method is pure, except for the changes in fout component.

Parameters

[in,out]	self	: The input/output parent object of class pm.vis.SubplotEllipse3 which is implicitly passed to this dynamic method (not by the user).
[in]	varargin	: Any property, value pair of the parent object. If the property is a struct(), then its value must be given as a cell array, with consecutive elements representing the struct property-name, property-value pairs. Note that all of these property-value pairs can be also directly set via the parent object attributes, before calling the make() method.

Possible calling interfaces ⛓

pm.vis.SubplotEllipse3.make();
pm.vis.SubplotEllipse3.make(varargin);

Example usage ⛓

cd(fileparts(mfilename('fullpath'))); % Change working directory to source code directory.
addpath('../../../'); % Add the ParaMonte library root directory to the search path.
 
sampler = pm.sampling.Paradram();
sampler.spec.outputStatus = "retry";
sampler.spec.outputFileName = "mvn";
sampler.spec.randomSeed = 28457353; % make sampling reproducible.
sampler.spec.outputChainSize = 30000; % Use a small chain size for illustration.
sampler.spec.outputRestartFileFormat = "ascii";
sampler.silent = true;
sampler.run ( @(x) -sum((x - [-5; 5; 10; -10]) .^ 2) ...
            , 4 ...
            );
 
restart = sampler.readRestart();
restart = restart{1};
 
figure("color", "white");
sv = pm.vis.SubplotEllipse3(restart.proposalCov, restart.proposalMean, transpose(restart.uniqueStateVisitCount));
sv.make("axes", {"zscale", "log"}, "dimx", [1, 3], "dimy", [1, 3] + 1);
pm.vis.figure.savefig("SubplotEllipse3.1.png", "-m3");
 
close all;

Visualization of the example output ⛓

Final Remarks ⛓

---

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
   
2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
   

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright

Computational Data Science Lab

Author:

Joshua Alexander Osborne, May 22 2024, 5:46 PM, University of Texas at Arlington
Fatemeh Bagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.
Amir Shahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin

premake()

function SubplotEllipse3::premake	(	in	self,
		in	varargin
	)

Prepare the subplot for visualization.

Warning

This method has side-effects by manipulating the existing attributes of the parent object.

Parameters

[in,out]	self	: The input/output parent object of class pm.vis.SubplotEllipse3 which is implicitly passed to this dynamic method (not by the user).
[in]	varargin	: Any property, value pair of the parent object. If the property is a struct(), then its value must be given as a cell array, with consecutive elements representing the struct property-name, property-value pairs. Note that all of these property-value pairs can be also directly set via the parent object attributes, before calling the premake() method.

Possible calling interfaces ⛓

pm.vis.SubplotEllipse3.premake();
pm.vis.SubplotEllipse3.premake(varargin);

Example usage ⛓

s = pm.vis.SubplotEllipse3();
s.premake("dimx", 1, "dimy", 2], "colormap", {"map", "autumn"})

Final Remarks ⛓

---

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
   
2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
   

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright

Computational Data Science Lab

Author:

Joshua Alexander Osborne, May 22 2024, 5:45 PM, University of Texas at Arlington
Fatemeh Bagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.
Amir Shahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin

reset()

function SubplotEllipse3::reset	(	in	self,
		in	varargin
	)

Reset the properties of the plot to the original default settings.

Use this method when you change many attributes of the plot and you want to clean up and go back to the default settings.

Parameters

[in,out]	self	: The implicitly-passed input argument representing the parent object of the method.
[in]	varargin	: Any property, value pair of the parent object. If the property is a struct(), then its value must be given as a cell array, with consecutive elements representing the struct property-name, property-value pairs. Note that all of these property-value pairs can be also directly set via the parent object attributes, before calling the make() method.

Possible calling interfaces ⛓

pm.vis.SubplotEllipse3.reset() % reset the plot to the default settings.
pm.vis.SubplotEllipse3.reset(varargin)

Final Remarks ⛓

---

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
   
2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
   

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright

Computational Data Science Lab

Author:

Joshua Alexander Osborne, May 22 2024, 5:42 PM, University of Texas at Arlington
Amir Shahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin

Field Documentation

center

Property SubplotEllipse3::center

center

A scalar object of class pm.container.DataRef containing the user-specified center data to visualize.

Definition at line 87 of file SubplotEllipse3.m.

cval

Property SubplotEllipse3::cval

cval

A scalar object of class pm.container.DataRef containing the user-specified color data in colormap.
If empty or unspecified, it will be set to zval component.

Definition at line 104 of file SubplotEllipse3.m.

dimx

Property SubplotEllipse3::dimx

dimx

The MATLAB scalar (or vector) of whole-number(s) representing the dimension(s) of the input gramian and center data to be used on the x-axis of 2D ellipsoid visualization.
The default is 1 if dimy component is also unspecified, or the appropriate data column adjacent to dimmy.
If the condition dimx == dimy holds, then the resulting ellipses will be circles.

Definition at line 50 of file SubplotEllipse3.m.

dimy

Property SubplotEllipse3::dimy

dimy

The MATLAB scalar (or vector) of whole-number(s) representing the dimension(s) of the input gramian and center data to be used on the y-axis of 2D ellipsoid visualization.
The default is 1 if dimx component is also unspecified, or the appropriate data column adjacent to dimmx.
If the condition dimx == dimy holds, then the resulting ellipses will be circles.

Definition at line 60 of file SubplotEllipse3.m.

ellindex

Property SubplotEllipse3::ellindex

ellindex

The vector of MATLAB whole numbers representing the ellindex of the 2D ellipsoids to display, represented by the input gramian and center.
The specified ellindex will serve as the visualization values on the z-axis.
The default is ellindex = pm.array.logrange(start = 1, stop = nell, count = 75);, where nell represents the number of ellipsoids to visualize.

Definition at line 71 of file SubplotEllipse3.m.

gramian

Property SubplotEllipse3::gramian

gramian

A scalar object of class pm.container.DataRef containing the user-specified Gramian data to visualize.

Definition at line 79 of file SubplotEllipse3.m.

names

Property SubplotEllipse3::names

names

The vector of MATLAB strings containing the names of dimensions of the space within which the Gramian matrices are defined.
The default is "Dimension i" where i is replaced by the ID of the corresponding axis.

Definition at line 40 of file SubplotEllipse3.m.

ndim

Property SubplotEllipse3::ndim

ndim

A scalar MATLAB whole number representing the total number of the dimensions of ellipsoids identified based on the input that can be visualized.
It is set to max(2, size(gramian, 2), size(center, 1)).

Definition at line 116 of file SubplotEllipse3.m.

nell

Property SubplotEllipse3::nell

nell

A scalar MATLAB whole number representing the total number of ellipsoids identified based on the input that can be visualized.
It is set to max(20, size(gramian, 3), size(center, 2), size(zval, 2)).

Definition at line 125 of file SubplotEllipse3.m.

npnt

Property SubplotEllipse3::npnt

npnt

The scalar MATLAB whole number representing the number of points with which the 2D ellipsoid boundaries are delineated.
It is set to max(size(zval, 1), size(cval, 1)) or otherwise, 100.

Definition at line 134 of file SubplotEllipse3.m.

workspace

Property SubplotEllipse3::workspace

workspace

A scalar MATLAB struct() containing the current visualization information.
This information is updated with every call to the make() method.
The contents of this component are temporary and must remain read-only.
This component is solely provided for better insight into the internal workings of the make() method of the parent object and the resulting visualization.

Definition at line 146 of file SubplotEllipse3.m.

zval

Property SubplotEllipse3::zval

zval

A scalar object of class pm.container.DataRef containing the user-specified z-axis data to visualize.

Definition at line 95 of file SubplotEllipse3.m.

---

The documentation for this class was generated from the following file:

• src/matlab/main/+pm/+vis/SubplotEllipse3.m