time | Calls | line |
---|
| | 191 | function t = table(varargin)
|
| | 192 | %TABLE Create a table from workspace variables or with a given size.
|
| | 193 | % T = TABLE(VAR1, VAR2, ...) creates a table T from the workspace
|
| | 194 | % variables VAR1, VAR2, ... . All variables must have the same number
|
| | 195 | % of rows.
|
| | 196 | %
|
| | 197 | % T = TABLE('Size', [N M], 'VariableTypes', {'type1', ..., 'typeM'})
|
| | 198 | % creates a table with the given size and variable types. Each
|
| | 199 | % variable in T has N rows to contain data that you assign later.
|
| | 200 | %
|
| | 201 | % T = TABLE(..., 'VariableNames', {'name1', ..., 'name_M'}) creates a
|
| | 202 | % table containing variables that have the specified variable names.
|
| | 203 | % The names must be valid MATLAB identifiers, and unique.
|
| | 204 | %
|
| | 205 | % T = TABLE(..., 'RowNames', {'name1', ..., 'name_N'}) creates a table
|
| | 206 | % that has the specified row names. The names need not be valid MATLAB
|
| | 207 | % identifiers, but must be unique.
|
| | 208 | %
|
| | 209 | % Tables can contain variables that are built-in types, or objects that
|
| | 210 | % are arrays and support standard MATLAB parenthesis indexing of the form
|
| | 211 | % var(i,...), where i is a numeric or logical vector that corresponds to
|
| | 212 | % rows of the variable. In addition, the array must implement a SIZE method
|
| | 213 | % with a DIM argument, and a VERTCAT method.
|
| | 214 | %
|
| | 215 | %
|
| | 216 | % Examples:
|
| | 217 | % % Create a table from individual workspace variables.
|
| | 218 | % load patients
|
| | 219 | % patients = table(LastName,Gender,Age,Height,Weight,Smoker,Systolic,Diastolic)
|
| | 220 | % patients.Properties.Description = 'Simulated patient data';
|
| | 221 | % patients.Properties.VariableUnits = {'' '' 'Yrs' 'In' 'Lbs' '' 'mm Hg' 'mm Hg'};
|
| | 222 | %
|
| | 223 | % See also READTABLE, CELL2TABLE, ARRAY2TABLE, STRUCT2TABLE.
|
| | 224 | import matlab.internal.datatypes.isText
|
| | 225 | import matlab.internal.datatypes.isIntegerVals
|
| | 226 | import matlab.internal.datatypes.parseArgsTabularConstructors
|
| | 227 |
|
< 0.001 | 8 | 228 | if nargin == 0
|
| | 229 | % Nothing to do
|
| | 230 | else
|
| | 231 | % Count number of data variables and the number of rows, and
|
| | 232 | % check each data variable.
|
| | 233 | [numVars,numRows] = tabular.countVarInputs(varargin,'MATLAB:table:StringParamNameNotSupported');
|
| | 234 |
|
| | 235 | if numVars < nargin
|
| | 236 | pnames = {'Size' 'VariableTypes' 'VariableNames' 'RowNames' };
|
| | 237 | dflts = { [] {} {} {} };
|
| | 238 | partialMatchPriority = [0 0 1 0]; % 'Var' -> 'VariableNames' (backward compat)
|
| | 239 | try
|
| | 240 | [sz, vartypes, varnames,rownames,supplied] ...
|
| | 241 | = parseArgsTabularConstructors(pnames, dflts, partialMatchPriority, ...
|
| | 242 | 'MATLAB:table:StringParamNameNotSupported', ...
|
| | 243 | varargin{numVars+1:end});
|
| | 244 | catch ME
|
| | 245 | % The inputs included a 1xM char row that was interpreted as the
|
| | 246 | % start of param name/value pairs, but something went wrong. If
|
| | 247 | % all of the preceding inputs had one row, the WrongNumberArgs
|
| | 248 | % or BadParamName (when the unrecognized name was first among
|
| | 249 | % params) errors suggest that the char row might have been
|
| | 250 | % intended as data. Suggest alternative options in that case.
|
| | 251 | errIDs = {'MATLAB:table:parseArgs:WrongNumberArgs' ...
|
| | 252 | 'MATLAB:table:parseArgs:BadParamNamePossibleCharRowData'};
|
| | 253 | if any(strcmp(ME.identifier,errIDs))
|
| | 254 | if (numVars == 0) || (numRows == 1)
|
| | 255 | pname1 = varargin{numVars+1}; % always the first char row vector
|
| | 256 | ME = ME.addCause(MException(message('MATLAB:table:ConstructingFromCharRowData',pname1)));
|
| | 257 | end
|
| | 258 | end
|
| | 259 | % 'StringParamNameNotSupported' suggests the opposite: a 1-row string intended as a param.
|
| | 260 | throw(ME);
|
| | 261 | end
|
| | 262 | else
|
| | 263 | supplied.Size = false;
|
| | 264 | supplied.VariableTypes = false;
|
| | 265 | supplied.VariableNames = false;
|
| | 266 | supplied.RowNames = false;
|
| | 267 | end
|
| | 268 |
|
| | 269 | if supplied.Size % preallocate from specified size and var types
|
| | 270 | if numVars > 0
|
| | 271 | % If using 'Size' parameter, cannot have data variables as inputs
|
| | 272 | error(message('MATLAB:table:InvalidSizeSyntax'));
|
| | 273 | elseif ~isIntegerVals(sz,0) || ~isequal(numel(sz),2)
|
| | 274 | error(message('MATLAB:table:InvalidSize'));
|
| | 275 | end
|
| | 276 | sz = double(sz);
|
| | 277 |
|
| | 278 | if sz(2) == 0
|
| | 279 | % If numVars is 0, VariableTypes must be empty (or not supplied)
|
| | 280 | if ~isequal(numel(vartypes),0)
|
| | 281 | error(message('MATLAB:table:VariableTypesAndSizeMismatch'))
|
| | 282 | end
|
| | 283 | elseif ~supplied.VariableTypes
|
| | 284 | error(message('MATLAB:table:MissingVariableTypes'));
|
| | 285 | elseif ~isText(vartypes,true) % require list of names
|
| | 286 | error(message('MATLAB:table:InvalidVariableTypes'));
|
| | 287 | elseif ~isequal(sz(2), numel(vartypes))
|
| | 288 | error(message('MATLAB:table:VariableTypesAndSizeMismatch'))
|
| | 289 | end
|
| | 290 |
|
| | 291 | numRows = sz(1); numVars = sz(2);
|
| | 292 | vars = tabular.createVariables(vartypes,sz);
|
| | 293 |
|
| | 294 | if ~supplied.VariableNames
|
| | 295 | % Create default var names, which never conflict with
|
| | 296 | % the default row times name.
|
| | 297 | varnames = t.varDim.dfltLabels(1:numVars);
|
| | 298 | end
|
| | 299 |
|
| | 300 | else % create from data variables
|
| | 301 | if supplied.VariableTypes
|
| | 302 | if (numVars == 2) && (numRows == 1)
|
| | 303 | % Apparently no 'Size' param, but it may have been provided as
|
| | 304 | % "Size". Be helpful for that specific case.
|
| | 305 | arg1 = varargin{1};
|
| | 306 | if isstring(arg1) && isscalar(arg1) && startsWith("size",arg1,'IgnoreCase',true) % partial case-insensitive
|
| | 307 | error(message('MATLAB:table:StringParamNameNotSupported',arg1));
|
| | 308 | end
|
| | 309 | end
|
| | 310 | % VariableTypes may not be supplied with data variables
|
| | 311 | error(message('MATLAB:table:IncorrectVariableTypesSyntax'));
|
| | 312 | end
|
| | 313 |
|
| | 314 | vars = varargin(1:numVars);
|
| | 315 |
|
| | 316 | if supplied.RowNames
|
| | 317 | if numVars == 0, numRows = length(rownames); end
|
| | 318 | else
|
| | 319 | rownames = {};
|
| | 320 | end
|
| | 321 |
|
| | 322 | if ~supplied.VariableNames
|
| | 323 | % Get the workspace names of the input arguments from inputname
|
| | 324 | varnames = repmat({''},1,numVars);
|
| | 325 | for i = 1:numVars, varnames{i} = inputname(i); end
|
| | 326 | % Fill in default names for data args where inputname couldn't
|
| | 327 | empties = cellfun('isempty',varnames);
|
| | 328 | if any(empties)
|
| | 329 | varnames(empties) = t.varDim.dfltLabels(find(empties)); %#ok<FNDSB>
|
| | 330 | end
|
| | 331 | % Make sure default names or names from inputname don't conflict
|
| | 332 | varnames = matlab.lang.makeUniqueStrings(varnames,{},namelengthmax);
|
| | 333 | end
|
| | 334 | end
|
| | 335 | t = t.initInternals(vars, numRows, rownames, numVars, varnames);
|
| | 336 |
|
| | 337 | % Detect conflicts between the var names and the default dim names.
|
| | 338 | t.metaDim = t.metaDim.checkAgainstVarLabels(varnames);
|
< 0.001 | 8 | 339 | end
|
< 0.001 | 8 | 340 | end % table constructor
|
Other subfunctions in this file are not included in this listing.