time | Calls | line |
---|
| | 1 | function t = readtable(filename,varargin)
|
| | 2 | %READTABLE Create a table by reading from a file.
|
| | 3 | %
|
| | 4 | % Use the READTABLE function to create a table by reading column-oriented
|
| | 5 | % data from a file. READTABLE automatically determines the file format from
|
| | 6 | % its extension as described below.
|
| | 7 | %
|
| | 8 | % T = READTABLE(FILENAME) creates a table by reading from a file, where
|
| | 9 | % FILENAME can be one of these:
|
| | 10 | %
|
| | 11 | % - For local files, FILENAME can be a full path that contains
|
| | 12 | % a filename and file extension. FILENAME can also be a relative path
|
| | 13 | % to the current folder, or to a folder on the MATLAB path.
|
| | 14 | % For example, to import a file on the MATLAB path:
|
| | 15 | %
|
| | 16 | % T = readtable("patients.xls");
|
| | 17 | %
|
| | 18 | % - For remote files, FILENAME must be a full path using a uniform
|
| | 19 | % resource locator (URL). For example, to import a remote file from
|
| | 20 | % Amazon S3, specify the full URL for the file:
|
| | 21 | %
|
| | 22 | % T = readtable("s3://bucketname/path_to_file/my_table.xls");
|
| | 23 | %
|
| | 24 | % For more information on accessing remote data, see "Work with Remote Data"
|
| | 25 | % in the documentation.
|
| | 26 | %
|
| | 27 | % T = READTABLE(FILENAME,"FileType",FILETYPE) specifies the file type, where
|
| | 28 | % FILETYPE is one of "text", "delimitedtext", "fixedwidth", or "spreadsheet".
|
| | 29 | %
|
| | 30 | % T = READTABLE(FILENAME,OPTS) creates a table by reading from a file stored
|
| | 31 | % at FILENAME using the supplied ImportOptions OPTS. OPTS specifies variable
|
| | 32 | % names, selected variable names, variable types, and other information regarding
|
| | 33 | % the location of the data.
|
| | 34 | %
|
| | 35 | % For example, import a subset of the data in a file:
|
| | 36 | %
|
| | 37 | % opts = detectImportOptions("patients.xls");
|
| | 38 | % opts.SelectedVariableNames = ["Systolic","Diastolic"];
|
| | 39 | % T = readtable("patients.xls",opts)
|
| | 40 | %
|
| | 41 | % READTABLE reads data from different file types as follows:
|
| | 42 | %
|
| | 43 | % Text files (delimited and fixed-width):
|
| | 44 | %
|
| | 45 | % The following extensions are supported: .txt, .dat, .csv, .log,
|
| | 46 | % .text, .dlm
|
| | 47 | %
|
| | 48 | % Reading from a delimited text file creates one variable in T for each
|
| | 49 | % column in the file. Variable names can be taken from the first row of
|
| | 50 | % the file. By default, the variables created are either double, if the
|
| | 51 | % column is primarily numeric, or datetime, duration, or text etc. If
|
| | 52 | % data in a column cannot be converted to numeric, datetime or
|
| | 53 | % duration, the column is imported as text.
|
| | 54 | %
|
| | 55 | % Spreadsheet files:
|
| | 56 | %
|
| | 57 | % The following extensions are supported: .xls, .xlsx, .xlsb, .xlsm,
|
| | 58 | % .xltm, .xltx, .ods
|
| | 59 | %
|
| | 60 | % Reading from a spreadsheet file creates one variable in T for each
|
| | 61 | % column in the file. By default, the variables created are either
|
| | 62 | % double, datetime or text--depending on the type in the file.
|
| | 63 | %
|
| | 64 | % READTABLE converts both empty fields or cells and values which cannot
|
| | 65 | % be converted to the expected type to:
|
| | 66 | % - NaN (for a numeric or duration variable),
|
| | 67 | % - NaT (for a datetime variable),
|
| | 68 | % - Empty character vector ('') or missing string (for text variables).
|
| | 69 | %
|
| | 70 | %
|
| | 71 | % Name-Value Pairs for ALL file types:
|
| | 72 | % ------------------------------------
|
| | 73 | %
|
| | 74 | % "FileType" - Specify the file as "text", "delimitedtext",
|
| | 75 | % "fixedwidth", or "spreadsheet".
|
| | 76 | %
|
| | 77 | % "VariableNamingRule" - A character vector or a string scalar that
|
| | 78 | % specifies how the output variables are named.
|
| | 79 | % It can have either of the following values:
|
| | 80 | %
|
| | 81 | % 'modify' Modify variable names to make them
|
| | 82 | % valid MATLAB Identifiers.
|
| | 83 | % (default)
|
| | 84 | % 'preserve' Preserve original variable names
|
| | 85 | % allowing names with spaces and
|
| | 86 | % non-ASCII characters.
|
| | 87 | %
|
| | 88 | % "ReadVariableNames" - Whether or not to expect variable names in
|
| | 89 | % the file.
|
| | 90 | %
|
| | 91 | % "ReadRowNames" - Whether or not to import the first column as
|
| | 92 | % row names.
|
| | 93 | %
|
| | 94 | % "TreatAsMissing" - Text which is used in a file to represent
|
| | 95 | % missing data, e.g. "NA".
|
| | 96 | %
|
| | 97 | % "TextType" - The type to use for text variables, specified
|
| | 98 | % as "char" or "string".
|
| | 99 | %
|
| | 100 | % "DatetimeType" - The type to use for date variables, specified
|
| | 101 | % as "datetime", "text", or "exceldatenum".
|
| | 102 | % Note: "exceldatenum" is not allowed for text.
|
| | 103 | %
|
| | 104 | % "ExpectedNumVariables" - The expected number of variables.
|
| | 105 | %
|
| | 106 | % Name-Value Pairs for TEXT and SPREADSHEET only:
|
| | 107 | % -----------------------------------------------
|
| | 108 | %
|
| | 109 | % "Range" - The range to consider when detecting data.
|
| | 110 | % Specified using any of the following syntaxes:
|
| | 111 | % - start cell: A string or character vector
|
| | 112 | % containing a column letter and a row number,
|
| | 113 | % or a 2 element numeric vector indicating
|
| | 114 | % the starting row and column.
|
| | 115 | % - full range: A start and end cell separated
|
| | 116 | % by colon, e.g. "C2:N15", or a four element
|
| | 117 | % numeric vector containing start row, start
|
| | 118 | % column, end row, end column, e.g. [2 3 15 13].
|
| | 119 | % - row range: A string or character vector
|
| | 120 | % containing a starting row number and ending
|
| | 121 | % row number, separated by a colon.
|
| | 122 | % - column range: A string or character vector
|
| | 123 | % containing a starting column letter and
|
| | 124 | % ending column letter, separated by a colon.
|
| | 125 | % - row number: A numeric scalar indicating the
|
| | 126 | % first row where data is found.
|
| | 127 | %
|
| | 128 | % "NumHeaderLines" - The number of header lines in the file.
|
| | 129 | %
|
| | 130 | % Name-Value Pairs for TEXT only:
|
| | 131 | % -------------------------------
|
| | 132 | %
|
| | 133 | % "Encoding" - The character encoding scheme associated with
|
| | 134 | % the file. It is generally not necessary to specify
|
| | 135 | % the encoding as READTABLE will attempt to
|
| | 136 | % automatically determine the encoding.
|
| | 137 | % See the documentation for FOPEN for more information
|
| | 138 | %
|
| | 139 | % "DateLocale" - The locale used to interpret month and day
|
| | 140 | % names in datetime text. Must be a character
|
| | 141 | % vector or scalar string in the form xx_YY.
|
| | 142 | % See the documentation for DATETIME for more
|
| | 143 | % information.
|
| | 144 | %
|
| | 145 | % "DurationType" - The type to use for duration, specified as
|
| | 146 | % "duration" or "text".
|
| | 147 | %
|
| | 148 | % "Whitespace" - Characters to treat as whitespace.
|
| | 149 | %
|
| | 150 | % "DecimalSeparator" - Character used to separate the integer part
|
| | 151 | % of a number from the decimal part of the
|
| | 152 | % number.
|
| | 153 | %
|
| | 154 | % "ThousandsSeparator" - Character used to separate the thousands
|
| | 155 | % place digits.
|
| | 156 | %
|
| | 157 | % "TrimNonNumeric" - Logical used to specify that prefixes and
|
| | 158 | % suffixes must be removed leaving only the
|
| | 159 | % numeric data.
|
| | 160 | %
|
| | 161 | % "HexType" - Set the output type of a hexadecimal
|
| | 162 | % variable.
|
| | 163 | %
|
| | 164 | % "BinaryType" - Set the output type of a binary variable.
|
| | 165 | %
|
| | 166 | %
|
| | 167 | % "Delimiter" - The delimiter(s) to use in the file.
|
| | 168 | %
|
| | 169 | % "CommentStyle" - The style of comments in the file.
|
| | 170 | %
|
| | 171 | % "LineEnding" - The line ending for the file.
|
| | 172 | %
|
| | 173 | % "ConsecutiveDelimitersRule" - Behaviors to apply to fields containing
|
| | 174 | % multiple consecutive delimiters:
|
| | 175 | % - "split" - split consecutive delimiters
|
| | 176 | % into multiple fields.
|
| | 177 | % - "join" - consecutive delimiters are
|
| | 178 | % treated as a single delimiter.
|
| | 179 | % - "error" - Ignored during detection
|
| | 180 | % (treated as "split"), but the
|
| | 181 | % resulting read will error.
|
| | 182 | %
|
| | 183 | % "LeadingDelimitersRule" - Behaviors to apply to delimiters at the
|
| | 184 | % beginning of a line:
|
| | 185 | % - "keep" - keep the delimiter
|
| | 186 | % - "ignore" - ignore the delimiter
|
| | 187 | % - "error" - return an error
|
| | 188 | %
|
| | 189 | % Name-Value Pairs for SPREADSHEET only:
|
| | 190 | % --------------------------------------
|
| | 191 | %
|
| | 192 | % "Sheet" - The sheet from which to detect the timetable.
|
| | 193 | %
|
| | 194 | % "UseExcel" - A logical value that specifies whether or not to read the
|
| | 195 | % spreadsheet file using Microsoft(R) Excel(R) on
|
| | 196 | % Windows(R). Set "UseExcel" to one of these values:
|
| | 197 | % - false - Does not open an instance of Microsoft Excel
|
| | 198 | % to read the file. This is the default setting.
|
| | 199 | % This setting may cause the data to be written
|
| | 200 | % differently for files with live updates (e.g.
|
| | 201 | % formula evaluation or plugins).
|
| | 202 | % - true - Opens an instance of Microsoft Excel to read
|
| | 203 | % the file on a Windows system with Excel installed.
|
| | 204 | %
|
| | 205 | %
|
| | 206 | % Name-Value Pairs supported with Import Options OPTS:
|
| | 207 | % ----------------------------------------------------
|
| | 208 | %
|
| | 209 | % These have slightly different behavior when used with import options:
|
| | 210 | %
|
| | 211 | % T = readtable(FILENAME, OPTS, "Name1", Value1, "Name2", Value2, ...)
|
| | 212 | %
|
| | 213 | % "ReadVariableNames" true - Reads the variable names from the
|
| | 214 | % opts.VariableNamesRange or opts.VariableNamesLine
|
| | 215 | % location.
|
| | 216 | % false - Uses variable names from the import options.
|
| | 217 | %
|
| | 218 | % "ReadRowNames" true - Reads the row names from the opts.RowNamesRange
|
| | 219 | % or opts.RowNamesColumn location.
|
| | 220 | % false - Does not import row names.
|
| | 221 | %
|
| | 222 | % Text parameters:
|
| | 223 | % "DateLocale" - Override the locale used when importing dates.
|
| | 224 | % "Encoding" - Override the encoding defined in import options.
|
| | 225 | %
|
| | 226 | % Spreadsheet only parameters:
|
| | 227 | % "Sheet" - Override the sheet value in the import options.
|
| | 228 | %
|
| | 229 | % See also READTIMETABLE, READMATRIX, READCELL, WRITETABLE, TABLE,
|
| | 230 | % DETECTIMPORTOPTIONS, TEXTSCAN.
|
| | 231 |
|
| | 232 | % Copyright 2012-2020 The MathWorks, Inc.
|
| | 233 |
|
< 0.001 | 2 | 234 | [varargin{1:2:end}] = convertStringsToChars(varargin{1:2:end});
|
< 0.001 | 2 | 235 | names = varargin(1:2:end);
|
< 0.001 | 2 | 236 | try
|
< 0.001 | 2 | 237 | if any(strcmpi(names,"Format"))
|
| | 238 | t = matlab.io.internal.legacyReadtable(filename,varargin);
|
< 0.001 | 2 | 239 | else
|
0.002 | 2 | 240 | func = matlab.io.internal.functions.FunctionStore.getFunctionByName('readtable');
|
0.002 | 2 | 241 | C = onCleanup(@()func.WorkSheet.clear());
|
0.474 | 2 | 242 | t = func.validateAndExecute(filename,varargin{:});
|
< 0.001 | 2 | 243 | end
|
| | 244 | catch ME
|
| | 245 | throw(ME)
|
0.002 | 2 | 246 | end
|
Other subfunctions in this file are not included in this listing.