array2table

Convert homogeneous array to table

Syntax

T = array2table(A)

T = array2table(A,Name,Value)

Description

T = array2table(A) converts an m-by-n array to an m-by-n table. Each column of input A becomes a variable in output T.

array2table uses the input array name appended with the column number for the variable names in the table. If these names are not valid MATLAB^® identifiers, array2table uses names of the form 'Var1',...,'VarN', where N is the number of columns in A.

T = array2table(A,Name,Value) creates a table from an array, A, with additional options specified by one or more Name,Value pair arguments.

For example, you can specify row names or variable names to include in the table.

Examples

Convert Numeric Array to Table

Create an array of numeric data.

A = [1 4 7; 2 5 8; 3 6 9]

A = 3×3

     1     4     7
     2     5     8
     3     6     9

Convert the array, A, to a table.

T = array2table(A)

T=3×3 table
    A1    A2    A3
    __    __    __

    1     4     7 
    2     5     8 
    3     6     9 

The table has variable names that append the column number to the input array name, A.

Convert Array to Table Including Variable Names

Create an array of numeric data.

A = [1 12 30.48; 2 24 60.96; 3 36 91.44]

A = 3×3

    1.0000   12.0000   30.4800
    2.0000   24.0000   60.9600
    3.0000   36.0000   91.4400

Convert the array, A, to a table and include variable names.

T = array2table(A,...
    'VariableNames',{'Feet','Inches','Centimeters'})

T=3×3 table
    Feet    Inches    Centimeters
    ____    ______    ___________

     1        12         30.48   
     2        24         60.96   
     3        36         91.44   

Input Arguments

A — Input array

matrix

Input array, specified as a matrix.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | string | struct | cell
Complex Number Support: Yes

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'RowNames',{'row1','row2','row3'} uses the row names, row1, row2, and row3 for the table, T.

RowNames — Row names

{} (default) | cell array of character vectors | string array

Row names, specified as a cell array of character vectors or string array, whose elements are nonempty and distinct. The number of row names must equal the number of rows of the input array.

Row names can have any Unicode^® characters, including spaces and non-ASCII characters, except for ':'.

If you specify row names that have leading or trailing whitespace characters, then array2table removes them from the row names.

VariableNames — Variable names

cell array of character vectors | string array

Variable names, specified as a cell array of character vectors or a string array, whose elements are nonempty and distinct. The number of variable names must equal the number of columns of the input array.

Variable names can have any Unicode characters, including spaces and non-ASCII characters. However, a variable name cannot match any table dimension name or the reserved names 'Properties', 'RowNames', 'VariableNames', or ':'.

DimensionNames — Dimension names

two-element cell array of character vectors | two-element string array

Since R2021a

Dimension names, specified as a two-element cell array of character vectors or two-element string array whose elements are nonempty and distinct.

Dimension names can have any Unicode characters, including spaces and non-ASCII characters. However, a dimension name cannot match any table variable name or the reserved names 'Properties', 'RowNames', 'VariableNames', or ':'.

As an alternative, in all releases you can specify dimension names by setting the DimensionNames property of the table.

Output Arguments

T — Output table

table

Output table, returned as a table. The table can store metadata such as descriptions, variable units, variable names, and row names. For more information, see the Properties section of table.

Tips

• If A is a cell array, use cell2table(A) to create a table from the contents of the cells in A. Each variable in the table is numeric or a cell array of character vectors. array2table(A) creates a table where each variable is a column of cells.

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

This function supports tall arrays with the limitations:

The 'RowNames' name-value pair is not supported.

For more information, see Tall Arrays.

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• In generated code, you must specify the 'VariableNames' name-value pair argument when using this function. For more information, see Code Generation for Tables (MATLAB Coder) and Table Limitations for Code Generation (MATLAB Coder).

Thread-Based Environment
Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

Version History

Introduced in R2013b

R2019b: Variable names can contain leading and trailing whitespace characters

Table and timetable variable names with leading or trailing whitespace characters are not modified.

In previous releases, leading and trailing whitespace characters were deleted from variable names when you specified them using the 'VariableNames' name-value pair argument, or assigned them to the VariableNames property.

To manually remove such characters, first use the strtrim function on the names, then assign them as variable names to the table or timetable.