ParaMonte MATLAB 3.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation.
Cor.m
Go to the documentation of this file.
1%> \brief
2%> This is the base class for generating objects with methods
3%> and storage components for computing, storing, and visualizing
4%> the correlation matrix of an input data.<br>
5%>
6%> \details
7%> This is convenience class for easy correlation computation
8%> and its storage and visualization all in one place.<br>
9%> The primary advantage of this class over the MATLAB
10%> intrinsic functions is in the ability of this class
11%> to compute the result for input dataframe table and
12%> return the results always in MATLAB ``table`` format.<br>
13%>
14%> \note
15%> See the documentation of the class constructor below.<br>
16%>
17%> \note
18%> See also the documentation of the superclass [pm.stats.Cov](@ref Cov).<br>
19%>
20%> \final
21%>
22%> \author
23%> \JoshuaOsborne, May 21 2024, 4:16 AM, University of Texas at Arlington<br>
24%> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
25%> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
26classdef Cor < pm.stats.Cov
27
28 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
29
30 properties(Access = public)
31 end
32
33 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
34
35 methods(Access = public)
36
37 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
38
39 %> \brief
40 %> Return an object of class [pm.stats.Cor](@ref Cor).<br>
41 %>
42 %> \details
43 %> This is the constructor of the [pm.stats.Cor](@ref Cor) class.<br>
44 %>
45 %> \param[in] dfref : The input MATLAB matrix or table of rank ``2``
46 %> containing the data as ``ncol`` columns of ``nrow``
47 %> observations whose correlation matrix must be computed.<br>
48 %> Ideally, the user would want to pass a reference
49 %> to a dataframe (e.g., as a function handle ``@()df``)
50 %> so that the data remains dynamically up-to-date.<br>
51 %> (**optional**. If missing or empty, the correlation matrix will not be computed.)
52 %> \param[in] method : The input scalar MATLAB string that can be either:<br>
53 %> <ol>
54 %> <li> ``"pearson"`` : for computing the Pearson correlation matrix of the input data.<br>
55 %> <li> ``"kendall"`` : for computing the Kendall correlation matrix of the input data.<br>
56 %> <li> ``"spearman"`` : for computing the Spearman rank correlation matrix of the input data.<br>
57 %> </ol>
58 %> (**optional**, default = ``"pearson"``)
59 %>
60 %> \return
61 %> ``self`` : The output object of class [pm.stats.Cor](@ref Cor).<br>
62 %>
63 %> \interface{Cor}
64 %> \code{.m}
65 %>
66 %> mat = pm.stats.Cor([])
67 %> mat = pm.stats.Cor([], [])
68 %> mat = pm.stats.Cor([], method)
69 %>
70 %> mat = pm.stats.Cor(dfref)
71 %> mat = pm.stats.Cor(dfref, [])
72 %> mat = pm.stats.Cor(dfref, method)
73 %>
74 %> \endcode
75 %>
76 %> \example{Cor}
77 %> \include{lineno} example/stats/Cor/main.m
78 %> \output{Cor}
79 %> \include{lineno} example/stats/Cor/main.out.m
80 %> \vis{Cor}
81 %> \image html example/stats/Cor/Cor.unifrnd.png width=700
82 %>
83 %> \final{Cor}
84 %>
85 %> \author
86 %> \JoshuaOsborne, May 21 2024, 4:22 AM, University of Texas at Arlington<br>
87 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
88 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
89 function self = Cor(dfref, method)
90
91 if 1 < nargin
92 self.method = method;
93 end
94
95 if 0 < nargin
96 self.val = self.get(dfref, self.method);
97 end
98
99 self.setvis();
100
101 end
102
103 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
104
105 %> \brief
106 %> Return the correlation matrix of the input data.<br>
107 %>
108 %> \details
109 %> This is a dynamic method of the ``Cor`` class.<br>
110 %> This method automatically stores any input information
111 %> in the corresponding components of the parent object.<br>
112 %> However, any components of the parent object
113 %> corresponding to the output of this method
114 %> must be set explicitly manually.<br>
115 %>
116 %> \param[inout] self : The **implicitly-passed** input argument representing the parent object of the method.<br>
117 %> \param[in] dfref : The input (reference of function handle returning a) MATLAB matrix or table of rank ``2``
118 %> containing the ``ncol`` columns of ``nrow`` data whose correlation matrix must be computed.<br>
119 %> Ideally, the user would want to pass a reference to a dataframe (e.g., as a function handle ``@()df``)
120 %> so that the data remains dynamically up-to-date.<br>
121 %> (**optional**. If missing, the correlation matrix will not be computed.)
122 %> \param[in] method : The input scalar MATLAB string that can be either:<br>
123 %> <ol>
124 %> <li> ``"pearson"`` : for computing the Pearson correlation matrix of the input data.<br>
125 %> <li> ``"kendall"`` : for computing the kendall rank correlation matrix of the input data.<br>
126 %> <li> ``"spearman"`` : for computing the Spearman rank correlation matrix of the input data.<br>
127 %> </ol>
128 %> (**optional**, default = ``"pearson"``)
129 %>
130 %> \return
131 %> ``val`` : The output MATLAB ``table`` containing the correlation matrix.<br>
132 %>
133 %> \interface{get}
134 %> \code{.m}
135 %>
136 %> mat = pm.stats.Cor(dfref, method)
137 %>
138 %> mat.val = mat.get()
139 %> mat.val = mat.get([])
140 %> mat.val = mat.get([], [])
141 %> mat.val = mat.get([], method)
142 %>
143 %> mat.val = mat.get(dfref)
144 %> mat.val = mat.get(dfref, [])
145 %> mat.val = mat.get(dfref, method)
146 %>
147 %> \endcode
148 %>
149 %> \note
150 %> See the documentation of the class constructor
151 %> [pm.stats.Cor](@ref Cor::Cor) for example usage.<br>
152 %>
153 %> \final{get}
154 %>
155 %> \author
156 %> \JoshuaOsborne, May 21 2024, 4:24 AM, University of Texas at Arlington<br>
157 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
158 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
159 function val = get(self, dfref, method)
160
161 if nargin < 3
162 method = "pearson";
163 end
164
165 if nargin < 2
166 dfref = [];
167 end
168
169 self.method = method;
170 if ~isempty(dfref)
171 self.dfref = pm.container.DataFrame(dfref);
172 end
173
174 dfcopy = self.dfref.copy();
175
176 if ~isempty(dfcopy)
177 data = dfcopy{:,:};
178 else
179 help("pm.stats.Cov");
180 error ( newline ...
181 + "A non-mepty ``dfref`` attribute or input argument is required for computing the covariance matrix." + newline ...
182 + newline ...
183 );
184 end
185
186 %%%%
187 %%%% Compute the correlation matrix.
188 %%%%
189
190 try
191 val = array2table(corr(data, "type", self.method));
192 catch me
193 val = NaN(size(data, 2), size(data, 2));
194 warning ( newline ...
195 + string(me.identifier) + " : " + string(me.message) + newline ...
196 + "skipping the correlation matrix computation..." + newline ...
197 );
198 return;
199 end
200
201 %%%%
202 %%%% Set the matrix column and row names.
203 %%%%
204
205 if isa(dfcopy, "table")
206 val.Properties.VariableNames = dfcopy.Properties.VariableNames;
207 end
208 val.Properties.RowNames = val.Properties.VariableNames;
209
210 end
211
212 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
213
214 end
215
216 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
217
218 methods(Access = public, Hidden)
219
220 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
221
222 %> \brief
223 %> Set up the visualization tools of the correlation matrix.<br>
224 %>
225 %> \details
226 %> This is a dynamic ``Hidden`` method of the [pm.stats.Cor](@ref Cor) class.<br>
227 %> This method is inaccessible to the end users of the ParaMonte MATLAB library.<br>
228 %>
229 %> \param[inout] self : The **implicitly-passed** input argument representing the parent object of the method.<br>
230 %> \param[in] val : The input (reference of function handle returning a) MATLAB matrix or table of rank ``2``
231 %> containing the computed correlation matrix to be visualized.<br>
232 %> Ideally, the user would want to pass a reference to a dataframe (e.g., as a function handle ``@()df``)
233 %> so that the data remains dynamically up-to-date.<br>
234 %> (**optional**. If missing, the contents of the corresponding ``var`` attribute of the parent object will be used.)
235 %>
236 %> \interface{setvis}
237 %> \code{.m}
238 %>
239 %> mat = pm.stats.Cor(dfref, method)
240 %> mat.setvis(); % This method is automatically called within the object constructor.
241 %>
242 %> \endcode
243 %>
244 %> \final{setvis}
245 %>
246 %> \author
247 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
248 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
249 function setvis(self, val)
250
251 if 1 < nargin
252 self.val = val;
253 end
254
255 setvis@pm.stats.Cov(self);
256 self.vis.heatmap.subplot.title.titletext = "Correlation Matrix";
257
258 end
259
260 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
261
262 end
263
264 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
265
266end
Cor
This is the base class for generating objects with methods and storage components for computing,...
Definition: Cor.m:27
Cor::get
function get(in self, in dfref, in method)
Return the correlation matrix of the input data.
Cor::Cor
function Cor(in dfref, in method)
Return an object of class pm.stats.Cor.
Cor::setvis
function setvis(in self, in val)
Set up the visualization tools of the correlation matrix.
Cov
This is the base class for generating objects with methods and storage components for computing and s...
Definition: Cov.m:21