readtable

Create table from file.

📝Syntax

T = readtable(filename)
T = readtable(filename, opts)
T = readtable(filename, 'TextType', type)
T = readtable(filename, Name, Value)

📥Input Arguments

Parameter	Description
filename	a string: filename source.
opts	nelson.io.text.DelimitedTextImportOptions object
type	a string: 'char' (default, text columns as a cell array of character vectors) or 'string' (text columns as a string array).
Name, Value	optional name-value arguments. For a JSON file: FileType, TableSelector, TableNodeName, VariableSelectors, RowNamesSelector, VariableUnitsSelector, VariableDescriptionsSelector, RepeatedNodeRule, ParsingMode, AllowComments, AllowInfAndNaN, AllowTrailingCommas, MissingRule, ImportErrorRule and TextType.

📤Output Arguments

Parameter	Description
T	a table.

📄Description

T = readtable(filename) creates a table by importing column-oriented data from a text or spreadsheet file.

T = readtable(filename, opts) creates a table using the settings defined in the opts import options object. The importoptions object allows you to customize howreadtable interprets the file, offering greater control, improved performance, and the ability to reuse the configuration compared to the default syntax.

T = readtable(filename, 'Range', range) reads only the rectangular block of the file selected by range. For a delimited text file, range can be given as corner cells ('A1:B5' or a single corner 'A2'), a column span ('A:B'), a row span ('2:4'), or a numeric vector [firstRow firstCol lastRow lastCol]. When the first row of the range is made only of non-numeric text it is used for the variable names, otherwise the columns are named Var1, Var2, and so on.

The 'Sheet' name-value option applies to spreadsheet files only and is not supported for a delimited text file.

JSON files: a file with the .json extension, or any file read with 'FileType', 'json', is decoded with jsondecode and converted into a table.

An array of objects gives one row per object and object keys become variables. Nested objects are flattened: each leaf value becomes a variable named after its key.
An object whose values are all objects gives one row per key. Use "Keys" in VariableSelectors to read the keys.
When the root of the file is an object, the first array of objects found is read.
Numbers give double, true and false give logical, text gives string (char with 'TextType', 'char'), date and time text gives datetime or duration.
null values and absent keys are missing values: NaN, <missing> or false for a logical variable.
A JSON array value (repeated node) gives a matrix variable with one column per element.

JSON name-value arguments:

TableSelector: RFC 6901 JSON Pointer of the table. "" refers to the whole file.
TableNodeName: key name of the table data.
VariableSelectors: JSON Pointers of the variables, relative to a row object. "Keys" reads the object keys.
RowNamesSelector: JSON Pointer of the row names.
VariableUnitsSelector, VariableDescriptionsSelector: JSON Pointers, from the root of the file, of an object that maps variable names to units or descriptions.
RepeatedNodeRule: 'addcol' (default), 'ignore' (first element only) or 'error'.
ParsingMode: 'lenient' (default) or 'strict'. It sets AllowComments (// and /* */ comments), AllowInfAndNaN (Inf, -Inf, Infinity, NaN) and AllowTrailingCommas, which can also be given one by one.
MissingRule, ImportErrorRule: 'fill' (default), 'error', 'omitrow' or 'omitvar'.

With a JSON file, opts is a nelson.io.json.JSONImportOptions object (see jsonImportOptions).

💡Examples

Names = {'John'; 'Alice'; 'Bob'; 'Diana'}; Age = [28; 34; 22; 30]; Height = [175; 160; 180; 165]; Weight = [70; 55; 80; 60]; T1 = table(Names, Age, Height, Weight); writetable(T1, [tempdir,'readtable_1.csv']) T2 = readtable([tempdir,'readtable_1.csv'])

Names = {'John'; 'Alice'; 'Bob'; 'Diana'}; Age = [28; 34; 22; 30]; Height = [175; 160; 180; 165]; Weight = [70; 55; 80; 60]; T = table(Names, Age, Height, Weight); writetable(T, [tempdir,'readtable_1.csv']) options = detectImportOptions([tempdir,'readtable_1.csv']); T1 = readtable([tempdir,'readtable_1.csv'], options) options.DataLines = [1 Inf] T2 = readtable([tempdir,'readtable_1.csv'], options)

Read a JSON file:

T = table([1; 2; NaN], ["a"; "b"; missing], 'VariableNames', {'x', 'name'}); f = [tempdir, 'readtable_json.json']; writetable(T, f); T2 = readtable(f) opts = detectImportOptions(f, 'VariableSelectors', '/name'); T3 = readtable(f, opts)

🕔Version History

Version	Description
1.10.0	initial version
2.0.0	JSON files: read JSON data as a table.

Edit this page on GitHub