Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

table

Table array with named variables that can contain different types

Description

table arrays store column-oriented or tabular data, such as columns from a text file or spreadsheet. Tables store each piece of column-oriented data in a variable. Table variables can have different data types and sizes so long as each variable has the same number of rows. Use the summary function to get information about a table.

To index into a table, use smooth parentheses () to return a subtable or curly braces {} to extract the contents, such as a numeric array. You can reference variables and rows using names. For more information on indexing, see Access Data in a Table.

Creation

You can read data from a file into a table using either the Import Tool or the readtable function. Alternatively, use the table function described below to create a table from existing workspace variables.

Syntax

T = table(var1,...,varN)
T = table(var1,...,varN,Name,Value)
T = table

Description

T = table(var1,...,varN) creates a table from the input variables, var1,...,varN. Variables can be of different sizes and data types, but all variables must have the same number of rows.

example

T = table(var1,...,varN,Name,Value) includes 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.

T = table creates an empty 0-by-0 table.

Input Arguments

expand all

Input variables, specified as arrays with the same number of rows. The input variables can be of different sizes and different data types.

Common input variables are numeric arrays, logical arrays, character arrays, structure arrays, or cell arrays. Input variables also can be objects that are arrays. Such an array must support indexing of the form var(index1,...,indexN), where index1 is a numeric or logical vector that corresponds to rows of the variable var. In addition, the array must implement both a vertcat method and a size method with a dim argument.

Example: table([1:4]',ones(4,3,2),eye(4,2)) creates a table from variables with four rows, but different sizes.

Example: table([1:3]',{'one';'two';'three'},categorical({'A';'B';'C'})) creates a table from variables with three rows, but different data types.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is a property name and Value is the corresponding value. You can set one or both of these properties in any order:

Example: T = table([10;20],{'M';'F'},'VariableNames',{'Age','Gender'},'RowNames',{'P1','P2'})

Properties

expand all

Access properties using the form tableName.Properties.PropertyName. For example, create a table and rename its variables using the VariableNames property.

T = table([10;20],{'M';'F'});
T.Properties.VariableNames = {'Age','Gender'}

Return a summary of all properties using tableName.Properties.

T.Properties

You also can concatenate all the timetable variables into an array using tableName.Variables. This syntax returns the same array as the tableName{:,:} syntax.

Table Metadata

Variable names, specified as a cell array of character vectors that are nonempty and distinct. Variable names must be valid MATLAB® identifiers. The number of character vectors must equal the number of variables. MATLAB removes any leading or trailing white space from the character vectors.

If valid identifiers are not available for use as variable names, MATLAB uses a cell array of N character vectors of the form {'Var1' ... 'VarN'} where N is the number of variables. You can determine valid MATLAB variable names using the function isvarname.

The variable names are visible when viewing the table and when using the summary function. Furthermore, you can use the variable names within parentheses, within curly braces, or with dot indexing to access table data.

Example

Create a table with default variable names. Then modify the names using the Properties.VariableNames property.

T = table({'M';'M';'F';'F';'F'},[38;43;38;40;49],...
          [71;69;64;67;64],[176;163;131;133;119])
T =

  5x4 table

    Var1    Var2    Var3    Var4
    ____    ____    ____    ____

    'M'     38      71      176 
    'M'     43      69      163 
    'F'     38      64      131 
    'F'     40      67      133 
    'F'     49      64      119 

T.Properties.VariableNames = {'Gender' 'Age' 'Height' 'Weight'}
T =

  5x4 table

    Gender    Age    Height    Weight
    ______    ___    ______    ______

    'M'       38     71        176   
    'M'       43     69        163   
    'F'       38     64        131   
    'F'       40     67        133   
    'F'       49     64        119   

Row names, specified as a cell array of character vectors that are nonempty and distinct. This property can be empty, but if not empty, the number of character vectors must equal the number of rows in the table. MATLAB removes any leading or trailing white space from the character vectors. The default property value is an empty cell array.

The row names are visible when you view the table. Furthermore, you can use the row names within parentheses or curly braces to access the table data.

Example

Create a table. Then add row names and access rows by their names.

load patients
T = table(Gender,Age,Height,Weight,Smoker,Systolic,Diastolic);

Add row names using the Properties.RowNames property. By default, tables do not have row names, but you can add them at any time.

T.Properties.RowNames = LastName;
head(T,4)
ans =

  4x7 table

                 Gender     Age    Height    Weight    Smoker    Systolic    Diastolic
                ________    ___    ______    ______    ______    ________    _________

    Smith       'Male'      38     71        176       true      124         93       
    Johnson     'Male'      43     69        163       false     109         77       
    Williams    'Female'    38     64        131       false     125         83       
    Jones       'Female'    40     67        133       false     117         75       

Index into the table by row names.

T({'Smith','Williams'},:)
ans =

  2x7 table

                 Gender     Age    Height    Weight    Smoker    Systolic    Diastolic
                ________    ___    ______    ______    ______    ________    _________

    Smith       'Male'      38     71        176       true      124         93       
    Williams    'Female'    38     64        131       false     125         83       

Dimension names, specified as a two-element cell array of character vectors.

Example

Create a table. Modify the names of its dimensions using the Properties.DimensionNames property.

load patients
T = table(Gender,Age,Height,Weight,Smoker,Systolic,Diastolic,...
          'RowNames',LastName);
T.Properties.DimensionNames = {'Patient' 'Data'};
T.Properties
ans = 

  struct with fields:

             Description: ''
                UserData: []
          DimensionNames: {'Patient'  'Data'}
           VariableNames: {1x7 cell}
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowNames: {100x1 cell}

Table description, specified as a character vector. This description is visible when using the summary function.

Example

Create a table. Modify the description of the table. Display a summary of the result.

load patients
T = table(Gender,Age,Height,Weight);
T.Properties.Description = 'Simulated patient data';
summary(T)
Description:  Simulated patient data

Variables:

    Gender: 100x1 cell array of character vectors

    Age: 100x1 double

        Values:

            Min       25   
            Median    39   
            Max       50   

    Height: 100x1 double

        Values:

            Min       60      
            Median    67      
            Max       72      

    Weight: 100x1 double

        Values:

            Min         111   
            Median    142.5   
            Max         202   

Variable descriptions, specified as a cell array of character vectors. This property can be an empty cell array, which is the default. If the cell array is not empty, the number of character vectors must equal the number of variables. You can specify an individual empty character vector within the cell array for a variable that does not have a description.

The variable descriptions are visible when using the summary function.

Example

Create a table. Modify the variable descriptions. Display a summary of the result.

load patients
T = table(Gender,Age,Height,Weight,Smoker,Systolic,Diastolic);
T.Properties.VariableDescriptions = {'' '' '' '' ...
                                     'Has the patient ever been a smoker' ...
                                     'Systolic Pressure' 'Diastolic Pressure'};
summary(T)
Variables:

    Gender: 100x1 cell array of character vectors

    Age: 100x1 double

        Values:

            Min       25   
            Median    39   
            Max       50   

    Height: 100x1 double

        Values:

            Min       60      
            Median    67      
            Max       72      

    Weight: 100x1 double

        Values:

            Min         111   
            Median    142.5   
            Max         202   

    Smoker: 100x1 logical

        Description:  Has the patient ever been a smoker
        Values:

            True     34      
            False    66      

    Systolic: 100x1 double

        Description:  Systolic Pressure
        Values:

            Min       109       
            Median    122       
            Max       138       

    Diastolic: 100x1 double

        Description:  Diastolic Pressure
        Values:

            Min         68       
            Median    81.5       
            Max         99       

Variable units, specified as a cell array of character vectors. This property can be an empty cell array, which is the default. If the cell array is not empty, the number of character vectors must equal the number of variables. You can specify an individual empty character vector within the cell array for a variable that does not have units.

The variable units are visible when using the summary function.

Example

Create a table. Modify the variable units. Display a summary of the result.

load patients
T = table(Gender,Age,Height,Weight,Smoker,Systolic,Diastolic);
T.Properties.VariableUnits = {'' 'Yrs' 'In' 'Lbs' '' 'mm Hg' 'mm Hg'};
summary(T)
Variables:

    Gender: 100x1 cell array of character vectors

    Age: 100x1 double

        Units:  Yrs
        Values:

            Min       25   
            Median    39   
            Max       50   

    Height: 100x1 double

        Units:  In
        Values:

            Min       60      
            Median    67      
            Max       72      

    Weight: 100x1 double

        Units:  Lbs
        Values:

            Min         111   
            Median    142.5   
            Max         202   

    Smoker: 100x1 logical

        Values:

            True     34      
            False    66      

    Systolic: 100x1 double

        Units:  mm Hg
        Values:

            Min       109       
            Median    122       
            Max       138       

    Diastolic: 100x1 double

        Units:  mm Hg
        Values:

            Min         68       
            Median    81.5       
            Max         99       

Additional table information, specified as a variable containing information in any data type.

Example

Create a table. Attach an anonymous function as a piece of user data that is associated with the table.

load patients
T = table(Gender,Age,Height,Weight,Smoker,Systolic,Diastolic);
formula = @(x) x.^2;
T.Properties.UserData = formula;
T.Properties
ans = 

  struct with fields:

             Description: ''
                UserData: @(x)x.^2
          DimensionNames: {'Row'  'Variables'}
           VariableNames: {1x7 cell}
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowNames: {}

Examples

expand all

Define workspace variables with the same number of rows.

LastName = {'Smith';'Johnson';'Williams';'Jones';'Brown'};
Age = [38;43;38;40;49];
Height = [71;69;64;67;64];
Weight = [176;163;131;133;119];
BloodPressure = [124 93; 109 77; 125 83; 117 75; 122 80];

Create a table, T, as a container for the workspace variables.

T = table(Age,Height,Weight,BloodPressure,...
    'RowNames',LastName)
T=5x4 table
                Age    Height    Weight    BloodPressure
                ___    ______    ______    _____________

    Smith       38     71        176       124     93   
    Johnson     43     69        163       109     77   
    Williams    38     64        131       125     83   
    Jones       40     67        133       117     75   
    Brown       49     64        119       122     80   

table names the variables with the workspace variable names.

Create a table from arrays with different data types where each variable contains three rows.

T = table(categorical({'M';'F';'M'}),[45;32;34],...
    {'NY';'CA';'MA'},logical([1;0;0]),...
    'VariableNames',{'Gender' 'Age' 'State' 'Vote'})
T=3x4 table
    Gender    Age    State    Vote 
    ______    ___    _____    _____

    M         45     'NY'     true 
    F         32     'CA'     false
    M         34     'MA'     false

Gender is a categorical array, Age is a double-precision array, State is a cell array of character vectors, and Vote is a logical array. You can use the function summary to print the data type and other information about the variables in the table.

Starting in R2016b, you can create string arrays with the string function, and add string arrays as table variables.

FlightNum = [1261;547;3489];
Customer = string({'Jones';'Brown';'Smith'});
Date = datetime(2016,12,20:22)';
Rating = categorical({'Good';'Poor';'Fair'});
Comment = string({'Flight left on time, not crowded';...
                  'Late departure, ran out of dinner options';...
                  'Late, but only by half an hour. Otherwise fine.'});
T = table(FlightNum,Customer,Date,Rating,Comment)
T=3x5 table
    FlightNum    Customer       Date        Rating                         Comment                     
    _________    ________    ___________    ______    _________________________________________________

    1261         "Jones"     20-Dec-2016    Good      "Flight left on time, not crowded"               
     547         "Brown"     21-Dec-2016    Poor      "Late departure, ran out of dinner options"      
    3489         "Smith"     22-Dec-2016    Fair      "Late, but only by half an hour. Otherwise fine."

To use the text in a string array as row names, convert the string array to a cell array of character vectors. Then create a table with row names.

Customer = cellstr(Customer);
T = table(FlightNum,Date,Rating,Comment,'RowNames',Customer)
T=3x4 table
             FlightNum       Date        Rating                         Comment                     
             _________    ___________    ______    _________________________________________________

    Jones    1261         20-Dec-2016    Good      "Flight left on time, not crowded"               
    Brown     547         21-Dec-2016    Poor      "Late departure, ran out of dinner options"      
    Smith    3489         22-Dec-2016    Fair      "Late, but only by half an hour. Otherwise fine."

Create workspace variables containing snowfall totals on different dates at three locations. These variables are row vectors.

Date = {'12/25/11','1/2/12','1/23/12','2/7/12','2/15/12'};
location1 = [20 5 13 0 17];
location2 = [18 9 21 5 12];
location3 = [26 10 16 3 15];

One way to create a table from these variables is to call the table function with the syntax T = table(Date',location1',location2',location3'). Because the workspace variables are row vectors, you must transpose them to put them into the table as column-oriented data. Therefore, the input arguments are expressions, not simple variables. As a result, table creates T with the default variable names Var1, Var2, Var3, and Var4. You can assign more meaningful names to T.Properties.VariableNames after you create T. But, it might be more convenient to create an empty table, and then add variables one at a time with new names.

Create an empty table. Transpose the workspace variables and add them to the table as column vectors. As part of assigning each workspace variable into T, provide a meaningful name for the table variable.

T = table;
T.Date = Date';
T.Natick = location1';
T.Boston = location2';
T.Worcester = location3'
T=5x4 table
       Date       Natick    Boston    Worcester
    __________    ______    ______    _________

    '12/25/11'    20        18        26       
    '1/2/12'       5         9        10       
    '1/23/12'     13        21        16       
    '2/7/12'       0         5         3       
    '2/15/12'     17        12        15       

Tips

  • For a list of functions that accept or return tables, see Tables.

Extended Capabilities

Introduced in R2013b

Was this topic helpful?