cell2table

Convert cell array to table

Syntax

T = cell2table(C)

T = cell2table(C,Name=Value)

Description

T = cell2table(C) converts the contents of an m-by-n cell array to an m-by-n table. Each column of the input cell array provides the data contained in a variable of the output table.

To create variable names in the output table, cell2table appends column numbers to the input array name. If the input array has no name, then cell2table creates variable names of the form "Var1",...,"VarN", where N is the number of columns in the cell array.

T = cell2table(C,Name=Value) specifies options using one or more name-value arguments in addition to the input argument in the previous syntax. For example, you can specify variable names by setting VariableNames to a string array of variable names.

Examples

Convert Cell Array to Table

Create a cell array that contains strings and numeric data. (Cell arrays of strings are not recommended. But in this case, it is appropriate to include strings in a cell array that contains both strings and numbers. This cell array is not a container for text, but for values that are grouped together though they have different data types.)

C = { 5 "cereal"  110 "C+"; ...
     12 "pizza"   140 "B"; ...
     23 "salmon"  367 "A"; ...
      2 "cookies" 160 "D"}

C=4×4 cell array
    {[ 5]}    {["cereal" ]}    {[110]}    {["C+"]}
    {[12]}    {["pizza"  ]}    {[140]}    {["B" ]}
    {[23]}    {["salmon" ]}    {[367]}    {["A" ]}
    {[ 2]}    {["cookies"]}    {[160]}    {["D" ]}

Convert the cell array to a table and specify variable names. The variables T.Age and T.Calories are numeric arrays while the variables T.FavoriteFood and T.NutritionGrade are string arrays.

T = cell2table(C,VariableNames=["Age" "FavoriteFood" "Calories" "NutritionGrade"])

T=4×4 table
    Age    FavoriteFood    Calories    NutritionGrade
    ___    ____________    ________    ______________

     5      "cereal"         110            "C+"     
    12      "pizza"          140            "B"      
    23      "salmon"         367            "A"      
     2      "cookies"        160            "D"      

Convert Column Headings to Variable Names

Convert a cell array to a table. Use the first row from the cell array to provide variable names for the table.

Create a cell array where the first row contains strings that identify column headings. (Cell arrays of strings are not recommended. But in this case, it is appropriate to include strings in a cell array that contains strings, numbers, and logical values. This cell array is not a container for text, but for values that are grouped together though they have different data types.)

Patients = {"LastName" "Age" "Height" "Weight" "Smoker"; ...
            "Chang"     38    71       176     true; ...
            "Brown"     43    69       163     false; ...
            "Ruiz"      38    64       131     false; ...
            "Lee"       38    64       131     false; ...
            "Smith"     40    67       133     false; ...
            "Garcia"    49    64       119     false}

Patients=7×5 cell array
    {["LastName"]}    {["Age"]}    {["Height"]}    {["Weight"]}    {["Smoker"]}
    {["Chang"   ]}    {[   38]}    {[      71]}    {[     176]}    {[       1]}
    {["Brown"   ]}    {[   43]}    {[      69]}    {[     163]}    {[       0]}
    {["Ruiz"    ]}    {[   38]}    {[      64]}    {[     131]}    {[       0]}
    {["Lee"     ]}    {[   38]}    {[      64]}    {[     131]}    {[       0]}
    {["Smith"   ]}    {[   40]}    {[      67]}    {[     133]}    {[       0]}
    {["Garcia"  ]}    {[   49]}    {[      64]}    {[     119]}    {[       0]}

Exclude the column headings from the first row of the cell array. The remaining rows contain data.

C = Patients(2:end,:)

C=6×5 cell array
    {["Chang" ]}    {[38]}    {[71]}    {[176]}    {[1]}
    {["Brown" ]}    {[43]}    {[69]}    {[163]}    {[0]}
    {["Ruiz"  ]}    {[38]}    {[64]}    {[131]}    {[0]}
    {["Lee"   ]}    {[38]}    {[64]}    {[131]}    {[0]}
    {["Smith" ]}    {[40]}    {[67]}    {[133]}    {[0]}
    {["Garcia"]}    {[49]}    {[64]}    {[119]}    {[0]}

Convert C to a table. The table has the data from Patients. But the variable names are C1,...,C5.

T = cell2table(C)

T=6×5 table
       C1       C2    C3    C4      C5  
    ________    __    __    ___    _____

    "Chang"     38    71    176    true 
    "Brown"     43    69    163    false
    "Ruiz"      38    64    131    false
    "Lee"       38    64    131    false
    "Smith"     40    67    133    false
    "Garcia"    49    64    119    false

Change the variable names by setting the table property, T.Properties.VariableNames, to include the names from the first row of the cell array. To extract the names from the first row, use curly braces. Then concatenate the names into a string array. Assign the string array to T.Properties.VariableNames.

ColumnHeadings = [Patients{1,:}]

ColumnHeadings = 1×5 string
    "LastName"    "Age"    "Height"    "Weight"    "Smoker"

T.Properties.VariableNames = ColumnHeadings

T=6×5 table
    LastName    Age    Height    Weight    Smoker
    ________    ___    ______    ______    ______

    "Chang"     38       71       176      true  
    "Brown"     43       69       163      false 
    "Ruiz"      38       64       131      false 
    "Lee"       38       64       131      false 
    "Smith"     40       67       133      false 
    "Garcia"    49       64       119      false 

Input Arguments

C — Input cell array

2-D cell array

Input cell array, specified as a 2-D cell array. Each column of C provides data for a table variable.

If the contents of the cells in a column of C have:

• Compatible sizes and data types, and each cell has an array with one row, then the corresponding table variable is a homogeneous array.

  Example:

  C = {[1 2] 3; [4 5] 6}
  T = cell2table(C)
  

  T =
    2×2 table
        C1      C2
      ______    __
      1    2    3 
      4    5    6 
  

• Different sizes, incompatible data types, or any cell has either an object that must be a scalar or an array with more than one row, then the corresponding table variable is a cell array.

  (For example, dictionaries and function handles are always scalars. Objects that must be scalars cannot be concatenated into a homogenous array. Therefore, cell2table must collect them into a cell array.)

  Example:

  C = {[1 2] 3; 4 5}
  T = cell2table(C)
  

  T =
    2×2 table
        C1       C2
      _______    __
      {[1 2]}    3 
      {[  4]}    5 
  

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.

Example: RowNames=["row1" "row2" "row3"] uses the row names, row1, row2, and row3 for a table that has three rows.

RowNames — Row names

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

Row names, specified as a string array or cell array of character vectors, 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 the colon character, :.

If you specify row names that have leading or trailing white space characters, then cell2table removes them from the row names.

VariableNames — Variable names

string array | cell array of character vectors

Variable names, specified as a string array or cell array of character vectors, 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 the colon character, :.

DimensionNames — Dimension names

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

Dimension names, specified as a two-element string array or two-element cell array of character vectors 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 the colon character, :.

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.

Extended Capabilities

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 argument when using this function. For more information, see Code Generation for Tables (MATLAB Coder) and Table Limitations for Code Generation (MATLAB Coder).

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Refer to the usage notes and limitations in the C/C++ Code Generation section. The same usage notes and limitations apply to GPU code generation.

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 white space characters

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

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

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