Categories &

Functions List

Function Reference: csv2table

datatypes: tbl = csv2table (filename)
datatypes: tbl = csv2table (filename, Name, Value)

Load a CSV file into a table.

tbl = csv2table (filename) creates a table tbl by reading the data in CSV file specified by filename, which can be either character vector or a string scalar. If the CSV file was saved by the table2csv method, then it reads the custom comment line in the first element of the CSV file and reconstructs the table as specified including variable types, variable names, and possibly any nested tables or structures it may contain. If no such special comment is found, then it treats the CSV file as simple columnar data and loads with the following default options.

  1. The first column is considered as RowNames and it is converted to cell array of character vectors and it is subsequently removed from the remaining data contained in the CSV file. To change the default behavior, you need to specify the ReadRowNames and RowNamesColumn paired arguments accordingly.
  2. The first line is treated as a header containing the variable names of the table. Any numeric values in the header line are converted to character vectors and all variable names are automatically modified to valid Octave variable names. To change the default behavior, you need to specify the ReadVariableNames, VariableNamingRule, and VariableNamesRow paired arguments accordingly.
  3. The data type of each column in the remaining data is automatically detected according to its contents. Consequently, text is converted to character vectors, datetime and duration strings are converted to datetime and duration arrays, respectively, and hexadecimal strings are converted to the smallest integer type that can represent all variable values. To change the default behavior, you need to specify the TextType, DatetimeType, DurationType, and HexType accordingly.

tbl = csv2table (filename, Name, Value) specifies optional parameters for creating the table tbl with the following Name-Value paired arguments.

NameValue
'NumHeaderLines'A positive integer scalar value specifying the number of rows to omit reading from the CSV file. If the CSV contains the custom comment line in its first element, then the 'NumHeaderLines' applies to the top number of rows to remove from the created table. If CSV is a generic case, then 'NumHeaderLines' specifies the number of lines to omit parsing from the CSV file itself.
'VariableNames'A cell array of character vectors or a string array specifying the names of the variables of the created table. The names must be unique but not necessarily valid variable names. If not empty, it overrides any variable names extracted from the CSV file. This applies both to custom and generic CSV files.
'ReadVariableNames'A logical scalar specifying whether to parse or not the CSV files for variable names. If your CSV file only contains data, set 'ReadVariableNames' to false so that csv2table parses all lines as data rows in the returned table. Variable names will be automatically generated to the default style as done by table, unless otherwise specified by the 'VariableNames' paired argument. The default value is true.
'VariableNamingRule'A character vector or a string scalar specifying whether the variable names should be modified to valid Octave variable names or the original names should be preserved. Valid options are "modify" and "preserve". By default, csv2table modifies the parsed variable names.
'VariableNamesRow'A nonnegative integer scalar value specifying the line number in the CSV file, which should be parsed for variable names. This only applies if the 'ReadVariableNames' option is true. The specified line is subsequently removed from the remaining data contained in the CSV file. If 'VariableNamesRow' is set to zero, then it is equivalent to setting 'ReadVariableNames' to false.
'VariableNamesLine'MATLAB’s spelling of 'VariableNamesRow' for a text file, and an exact alias of it. Passing both names raises an error rather than one silently winning.
'VariableTypes'A cell array of character vectors or a string array specifying the data type of the variables of the created table. The number of elements must much the number of variable in the table. This optional argument only has an effect on generic CSV files. When specified, it overrides any other data type specification or automatic detection by the csv2table function.
'VariableUnitsLine'A nonnegative integer scalar value specifying the line number in the CSV file, which should be parsed for variable units. The specified line is subsequently removed from the remaining data contained in the CSV file.
'VariableDescriptionsLine'A nonnegative integer scalar value specifying the line number in the CSV file, which should be parsed for variable descriptions. The specified line is subsequently removed from the remaining data contained in the CSV file.
'ReadRowNames'A logical scalar specifying whether to parse or not the CSV files for row names. If your CSV file only contains data, set 'ReadRowNames' to false so that csv2table parses all columns as data columms in the returned table. The default value is true.
'RowNamesColumn'A nonnegative integer scalar value specifying the column number in the CSV file, which should be parsed for row names. This only applies if the 'ReadRowNames' option is true. The specified column is subsequently removed from the remaining data contained in the CSV file. If 'RowNamesColumn' is set to zero, then it is equivalent to setting 'ReadRowNames' to false. Note that the values in the column specified by 'RowNamesColumn' must be unique, otherwise csv2table will return an error. The default value is 0: a file that does not say which column holds its row names is read as data throughout, and a file written by table2csv records the column itself. A leading column headed Row, which is what writetable writes for the row names, is taken as the row names without being named here.
'TextType'A character vector or a string scalar specifying whether the text data in the CSV file should be stored in the table as character vectors or string arrays. Valid options are "char" and "string". By default, csv2table stores text data as character vectors.
'DatetimeType'A character vector or a string scalar specifying whether the datetime strings found in the CSV file should be stored in the table as datetime arrays or as text data. Valid options are "datetime" and "text". By default, csv2table stores datetime strings as datetime arrays. If "text" is specified, then the data type depends on the 'TextType' option.
'DurationType'A character vector or a string scalar specifying whether the duration strings found in the CSV file should be stored in the table as duration arrays or as text data. Valid options are "duration" and "text". By default, csv2table stores duration strings as duration arrays. If "text" is specified, then the data type depends on the 'TextType' option.
'HexType'A character vector or a string scalar specifying whether the hexadecimal text found in the CSV file should be stored as a suitable integer type, "auto", as unaltered input text, "text" (the default, in which case the data type depends on the 'TextType' option), or as any of the integer types supported by Octave. Valid options are "auto", "text", "int8", "int16", "int32", "int64", "uint8", "uint16", "uint32", and "uint64". Detection is off by default because MATLAB does not perform it, so a file carrying no header of ours is read the way MATLAB reads it. It never applies to a file written by table2csv, which declares every variable’s type.

Source Code: csv2table

A datetime or duration variable written by table2csv is restored exactly, along with its Format and, for a zone-aware datetime, its TimeZone. Where the column’s type is declared, either by the file or by "VariableTypes", a field that is empty and unquoted carries no value and is read as a missing entry, where an empty quoted field ("") is read as an empty string; a column whose type is guessed is unaffected. The following round-trip limitation applies when reading a file written by table2csv: calendarDuration and categorical variables are returned as cell arrays of character vectors and their values are not reconstructed.

See also: array2table, struct2table, table

Source Code: csv2table

csv2table reads a CSV back into a table. When the file was written by table2csv, the typed header lets it restore each variable's type exactly.

 T = table ([38; 43], [71.5; 69.0], 'VariableNames', {'Age', 'Height'});
 filename = fullfile (tempdir (), 'patients.csv');
 table2csv (T, filename);
 csv2table (filename)
ans =
  2x2 table

    Age    Height    
    ___    ______    

     38      71.5    
     43        69

For a plain CSV that has no type header, the first line is taken as the variable names and each column's type is detected automatically. Use 'ReadRowNames' to turn the first column into row names instead of data.

 filename = fullfile (tempdir (), 'plain.csv');
 fid = fopen (filename, 'w');
 fputs (fid, "Patient,Age,Height\nLi,38,64\nDiaz,40,67\n");
 fclose (fid);
 csv2table (filename, 'ReadRowNames', true)
ans =
  2x3 table

    Patient     Age    Height    
    ________    ___    ______    

    {'Li'  }     38        64    
    {'Diaz'}     40        67
 delete (filename);