Written and maintained by CASRAI Editorial Board
Last updated
A MATLAB table stores column-oriented research data (one named variable per column, one row per observation) in a single object whose columns can have different data types. This guide takes you from a CSV or Excel file to an indexed, exported table using only functions documented by MathWorks.
What a MATLAB table is used for in research
A table is a table array with named variables. Each variable is a column, so a numeric dose, a text group label and a date can sit side by side, which a plain numeric matrix cannot hold. Tables were introduced in R2013b. Typical uses are imported trial or survey data, instrument exports and results you want to label before sharing. For the wider picture of what the software does, see what MATLAB is used for.
Install or access
Tables are part of base MATLAB; no separate toolbox is named on the table reference page. MATLAB is obtained from MathWorks (mathworks.com), either through an institutional licence or a personal one; your institution’s software office can tell you which applies to you.
Step by step: import, inspect, index, export
1. Create a table from variables you already have
T = table(var1,...,varN) builds a table from workspace variables. The workspace variable names become the table’s variable names; if the inputs are not plain variable names, MATLAB uses Var1,...,VarN. To preallocate, use T = table(Size=sz,VariableTypes=varTypes). Name-value options include VariableNames, RowNames and DimensionNames. Calling T = table with no arguments creates an empty 0-by-0 table.
2. Convert an existing array or cell array
T = array2table(A) turns a matrix into a table; add VariableNames as a string array or a cell array of character vectors. The names must be nonempty and distinct, their count must equal the number of columns, and a name cannot be Properties, RowNames, VariableNames, a dimension name, or contain a colon. For a cell array use cell2table(A); table2array reverses the conversion.
3. Import a file with readtable
T = readtable('results.csv');readtable(filename) reads text files (.txt, .dat, .csv), spreadsheets (.xls, .xlsb, .xlsm, .xlsx, .xltm, .xltx, .ods) and also .json, .xml, .docx and .html/.xhtml/.htm files. If your file has an extension not on that list, pass FileType. PDF is not in the file-type list, so export the PDF’s table to CSV or Excel first. Set ReadVariableNames to false if the first row is data and you want Var1,...,VarN; left unspecified, MATLAB detects it.
4. Index the table
Three bracket styles return different things:
| Syntax | Returns |
|---|---|
T.varname |
The contents of one variable |
T{rows,vars} |
An array (braces extract the data) |
T(rows,vars) |
A smaller table (parentheses keep the table) |
For example, T(1:3,2:3) is a 3-row table, while T{1:3,2:3} is an array of the same values. Use parentheses when you want to keep variable names for later steps.
5. Export
writetable(T,'cleaned.csv');writetable(T,filename) writes .txt, .dat, .csv, .xls, .xlsm, .xlsx, .xlsb (Excel for Windows only), .json or .xml. Variable names are written by default; set WriteVariableNames to false to omit them. Sheet and Range (for example 'B2:F6') apply only to spreadsheets. Text files are overwritten by default (WriteMode is 'overwrite'; use 'append' to add), whereas spreadsheets default to 'inplace', which updates only the range of the data you write; 'replacefile' removes the file’s other sheets.
Output and how to read it
A table displays with variable names as column headers. The table reference page points to summary for a per-variable overview. If a variable has an unexpected name, that is usually the import naming rule described below, not a data error.
Troubleshooting
Why did my column headers change on import?
readtable applies VariableNamingRule. For text and spreadsheet files the default is "modify", which converts headers that are not valid MATLAB identifiers (for example headers containing spaces). For JSON, XML, Word and HTML files the default is "preserve", which keeps the original text, spaces included. Set VariableNamingRule to "preserve" to keep headers such as Patient ID unchanged.
My array2table call errors
Check the name list against the rules in step 2: the number of names must equal the number of columns, names must be distinct, and reserved names such as Properties or RowNames are not allowed.
Which MATLAB container should I use?
| You have | Use |
|---|---|
| Columns of different types with named variables | table (this guide) |
| A numeric grid with no labels | A matrix, convertible with array2table |
| A cell array | cell2table converts it to a table |
Free alternatives
| Tool | Equivalent structure | Documentation description |
|---|---|---|
| Python pandas | DataFrame |
“Two-dimensional, size-mutable, potentially heterogeneous tabular data” (pandas reference) |
| R | data.frame |
Columns “may be of differing types” (R help page) |
| Julia | DataFrames.jl | “A set of tools for working with tabular data in Julia”; CSV files are read through CSV.jl |
If you are weighing MATLAB against R, see MATLAB vs R.
FAQ
How do I read Excel data into a MATLAB table?
Call readtable('file.xlsx'); .xls, .xlsm, .xlsb, .xltm, .xltx and .ods also work.
Can I import a PDF table?
PDF is not among the file types readtable lists. Convert the table to CSV or Excel first.
What is the difference between T(…) and T{…}?
Parentheses return a table; braces return an array of the underlying values.
How do I save a table?
Use writetable(T,filename) with a supported extension such as .csv or .xlsx.
