ParaMonte MATLAB 3.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation.
DataFrame.m
Go to the documentation of this file.
1%> \brief
2%> This is the abstract class for generating instances of objects
3%> that can contain basic attributes required for tabular read-only
4%> access to a MATLAB table-compatible data stored externally.<br>
5%>
6%> \details
7%> This class is merely a convenience read-only wrapper
8%> to reference external tabular data as table.<br>
9%> This class primarily exist to facilitate bypassing
10%> the lack of references and pointers in MATLAB.<br>
11%>
12%> \remark
13%> See the constructor documentation for example usage.<br>
14%>
15%> \see
16%> [DataRef](@ref DataRef)<br>
17%>
18%> \final
19%>
20%> \author
21%> \JoshuaOsborne, May 21 2024, 4:45 PM, University of Texas at Arlington<br>
22%> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
23%> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
24classdef DataFrame < pm.data.DataRef
25
26 methods(Access = public)
27
28 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
29
30 %> \brief
31 %> Generate an return an object of class [pm.data.DataFrame](@ref DataFrame)
32 %> from the input dataframe or its specified input reference.<br>
33 %>
34 %> \details
35 %> This is the constructor of the class [pm.data.DataFrame](@ref DataFrame).<br>
36 %>
37 %> \param[in] dfref : The input MATLAB 2D matrix or table containing the target dataset
38 %> or function handle that takes no arguments and returns the dataset.<br>
39 %> Specifying a function handle is superior to specifying the dataset
40 %> directly, because the function handle will always allow the use of
41 %> the most updated version of the user table or matrix.<br>
42 %> (**optional**. default = ``table(zeros(0, 0))``)
43 %>
44 %> \return
45 %> ``self`` : The output scalar object of class [pm.data.DataFrame](@ref DataFrame).<br>
46 %>
47 %> \interface{DataFrame}
48 %> \code{.m}
49 %>
50 %> df = pm.data.DataFrame(dfref);
51 %>
52 %> \endcode
53 %>
54 %> \example{DataFrame}
55 %> \include{lineno} example/data/DataFrame/main.m
56 %> \output{DataFrame}
57 %> \include{lineno} example/data/DataFrame/main.out.m
58 %>
59 %> \final{DataFrame}
60 %>
61 %> \author
62 %> \JoshuaOsborne, May 21 2024, 4:54 PM, University of Texas at Arlington<br>
63 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
64 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
65 function self = DataFrame(dfref)
66 if nargin < 1
67 dfref = [];
68 end
69 if isempty(dfref)
70 dfref = table(zeros(0, 0));
71 end
72 self = self@pm.data.DataRef(dfref);
73 end
74
75 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
76
77 %> \brief
78 %> Generate and return a table copy of the dataframe contained in the
79 %> user-specified input ``dfref`` to the constructor of the parent object.<br>
80 %>
81 %> \details
82 %> This class method offers the only way to access the user-specified dataframe.<br>
83 %> The underlying logic behind the use of function to access the dataframe
84 %> originates from the lack of the concept of references (pointers)
85 %> in the MATLAB computing language.<br>
86 %>
87 %> \return
88 %> ``df`` : The output scalar MATLAB table a full copy of the dataframe
89 %> contained in the user-specified input ``dfref`` passed
90 %> to the constructor of the parent object.<br>
91 %>
92 %> \interface{copy}
93 %> \code{.m}
94 %>
95 %>
96 %> df = pm.data.DataFrame.copy()
97 %>
98 %> \endcode
99 %>
100 %> \remark
101 %> See the constructor documentation for example usage.<br>
102 %>
103 %> \final{copy}
104 %>
105 %> \author
106 %> \JoshuaOsborne, May 21 2024, 4:54 PM, University of Texas at Arlington<br>
107 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
108 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
109 function df = copy(self)
110 df = copy@pm.data.DataRef(self);
111 if ~istable(df)
112 df = array2table(df);
113 end
114 end
115
116 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
117
118 %> \brief
119 %> Generate and return the number of columns in the user-specified
120 %> dataframe ``dfref`` at the time of constructing the parent object.<br>
121 %>
122 %> \details
123 %> This class method is a handy shorthand for ``size(self.dfref, 2)``, particularly
124 %> useful for specifying a range of indices of columns in visualization tasks.<br>
125 %>
126 %> \return
127 %> ``count`` : The output scalar MATLAB whole-number representing the number
128 %> of columns in the ``dfref`` component of the parent object.
129 %>
130 %> \interface{ncol}
131 %> \code{.m}
132 %>
133 %>
134 %> count = pm.data.DataFrame.ncol()
135 %>
136 %> \endcode
137 %>
138 %> \remark
139 %> See the constructor documentation for example usage.<br>
140 %>
141 %> \final{ncol}
142 %>
143 %> \author
144 %> \JoshuaOsborne, May 21 2024, 5:00 PM, University of Texas at Arlington<br>
145 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
146 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
147 function count = ncol(self)
148 count = size(self.copy(), 2);
149 end
150
151 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
152
153 %> \brief
154 %> Generate and return the number of rows in the user-specified
155 %> dataframe ``dfref`` at the time of constructing the parent object.<br>
156 %>
157 %> \details
158 %> This class method is a handy shorthand for ``size(self.dfref, 2)``,
159 %> particularly useful for specifying a range of indices of rows to visualize.<br>
160 %>
161 %> \param[in] `None`
162 %>
163 %> \return
164 %> ``count`` : The output scalar MATLAB whole-number representing the number
165 %> of rows in the ``dfref`` component of the parent object.<br>
166 %>
167 %> \interface{nrow}
168 %> \code{.m}
169 %>
170 %> count = pm.data.DataFrame.nrow()
171 %>
172 %> \endcode
173 %>
174 %> \remark
175 %> See the constructor documentation for example usage.<br>
176 %>
177 %> \final{nrow}
178 %>
179 %> \author
180 %> \JoshuaOsborne, May 21 2024, 5:04 PM, University of Texas at Arlington<br>
181 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
182 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
183 function count = nrow(self)
184 count = size(self.copy(), 1);
185 end
186
187 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
188
189 %> \brief
190 %> Generate and return a natural logarithmically-spaced
191 %> range of indices from the row indices of the input
192 %> dataframe ``dfref`` to the parent object.<br>
193 %>
194 %> \details
195 %> This method is a convenience wrapper
196 %> around function [pm.array.logrange](@ref logrange).<br>
197 %>
198 %> \warning
199 %> Beware of the different order of the input arguments
200 %> between this method and [pm.array.logrange](@ref logrange).<br>
201 %>
202 %> \param[in] count : The input scalar MATLAB whole-number (integer)
203 %> representing the maximum size of the output range.<br>
204 %> Due to rounding operation involved in creating the
205 %> output range, it is impossible to prespecify the
206 %> output range size, only the maximum.<br>
207 %> (**optional**, default = ``1000``)
208 %>
209 %> \param[in] start : The input scalar MATLAB whole-number (integer)
210 %> representing the starting point of the output range.<br>
211 %> It must be a number in the range ``[1, size(self.dfref, 1)]``.
212 %> Otherwise, the value ``max(1, min(start, self.nrow()))`` will be used.<br>
213 %> (**optional**, default = ``1``)
214 %>
215 %> \param[in] stop : The input scalar MATLAB whole-number (integer)
216 %> representing the stopping point of the output range.<br>
217 %> It must be a number in the range ``[1, size(self.dfref, 1)]``.
218 %> Otherwise, the value ``max(start, min(stop, self.nrow()))`` will be used.<br>
219 %> (**optional**, default = ``1``)
220 %>
221 %> \return
222 %> ``indices`` : The output vector of MATLAB real values containing
223 %> the set of naturally logarithmically-spaced integer
224 %> values in the specified input range.<br>
225 %>
226 %> \interface{rowslog}
227 %> \code{.m}
228 %>
229 %> indices = pm.data.DataFrame()
230 %> indices = pm.data.DataFrame([])
231 %>
232 %> indices = pm.data.DataFrame([], [])
233 %> indices = pm.data.DataFrame([], start)
234 %> indices = pm.data.DataFrame(count, [])
235 %> indices = pm.data.DataFrame(count, start)
236 %>
237 %> indices = pm.data.DataFrame([], [], [])
238 %> indices = pm.data.DataFrame(count, [], [])
239 %> indices = pm.data.DataFrame([], start, [])
240 %> indices = pm.data.DataFrame([], [], stop)
241 %> indices = pm.data.DataFrame([], start, stop)
242 %> indices = pm.data.DataFrame(count, [], stop)
243 %> indices = pm.data.DataFrame(count, start, [])
244 %> indices = pm.data.DataFrame(count, start, stop)
245 %>
246 %> \endcode
247 %>
248 %> \remark
249 %> See the constructor documentation for example usage.<br>
250 %>
251 %> \final{rowslog}
252 %>
253 %> \author
254 %> \JoshuaOsborne, May 21 2024, 5:10 PM, University of Texas at Arlington<br>
255 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
256 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
257 function indices = rowslog(self, count, start, stop)
258 if nargin < 4
259 stop = [];
260 end
261 if nargin < 3
262 start = [];
263 end
264 if nargin < 2
265 count = [];
266 end
267 if isempty(stop)
268 stop = self.nrow();
269 end
270 if isempty(start)
271 start = 1;
272 end
273 if isempty(count)
274 count = 1000;
275 end
276 indices = pm.array.logrange(max(1, min(start, self.nrow())), max(start, min(stop, self.nrow())), count);
277 end
278
279 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
280
281 end
282
283 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
284
285end
version
function version(in silent)
Return a scalar MATLAB string containing the latest available ParaMonte MATLAB version newer than the...
DataFrame
This is the abstract class for generating instances of objects that can contain basic attributes requ...
Definition: DataFrame.m:25
DataFrame::copy
function copy(in self)
Generate and return a table copy of the dataframe contained in the user-specified input dfref to the ...
DataFrame::DataFrame
function DataFrame(in dfref)
Generate an return an object of class pm.data.DataFrame from the input dataframe or its specified inp...
DataFrame::nrow
function nrow(in self)
Generate and return the number of rows in the user-specified dataframe dfref at the time of construct...
DataFrame::rowslog
function rowslog(in self, in count, in start, in stop)
Generate and return a natural logarithmically-spaced range of indices from the row indices of the inp...
DataFrame::ncol
function ncol(in self)
Generate and return the number of columns in the user-specified dataframe dfref at the time of constr...
DataRef
This is the abstract class for generating instances of objects that can contain basic attributes requ...
Definition: DataRef.m:27
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...
logrange
function logrange(in start, in stop, in sizemax)
Return a set of maximum sizemax unique integer spacings almost linearly spaced in the natural logarit...