This is machine translation

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

Note: This page has been translated by MathWorks. Click here to see
To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

Add Custom Properties to Tables and Timetables

This example shows how to add custom properties to tables and timetables, set and access their values, and remove them.

All tables and timetables have properties that contain metadata about them or their variables. You can access these properties through the T.Properties object, where T is the name of the table or timetable. For example, T.Properties.VariableNames returns a cell array containing the names of the variables of T.

The properties you access through T.Properties are part of the definitions of the table and timetable data types. You cannot add or remove these predefined properties. But starting in R2018b, you can add and remove your own custom properties, by modifying the T.Properties.CustomProperties object of a table or timetable.

Add Properties

Read power outage data into a table. Sort it using the first variable that contains dates and times, OutageTime. Then display the first three rows.

T = readtable('outages.csv');
T = sortrows(T,'OutageTime');
head(T,3)
ans=3×6 table
      Region          OutageTime        Loss     Customers     RestorationTime         Cause     
    ___________    ________________    ______    __________    ________________    ______________

    'SouthWest'    2002-02-01 12:18    458.98    1.8202e+06    2002-02-07 16:50    'winter storm'
    'MidWest'      2002-03-05 17:53    96.563    2.8666e+05    2002-03-10 14:41    'wind'        
    'MidWest'      2002-03-16 06:18    186.44    2.1275e+05    2002-03-18 23:23    'severe storm'

Display its properties. These are the properties that all tables have in common. Note that there is also a CustomProperties object, but that by default it has no properties.

T.Properties
ans = 
  TableProperties with properties:

             Description: ''
                UserData: []
          DimensionNames: {'Row'  'Variables'}
           VariableNames: {1x6 cell}
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowNames: {}
        CustomProperties: No custom properties are set.
      Use addprop and rmprop to modify CustomProperties.

To add custom properties, use the addprop function. Specify the names of the properties. For each property, also specify whether it has metadata for the whole table (similar to the Description property) or for its variables (similar to the VariableNames property). If the property has variable metadata, then its value must be a vector whose length is equal to the number of variables.

Add custom properties that contain an output file name, file type, and indicators of which variables to plot. Best practice is to assign the input table as the output argument of addprop, so that the custom properties are part of the same table. Specify that the output file name and file type are table metadata using the 'table' option. Specify that the plot indicators are variable metadata using the 'variable' option.

T = addprop(T,{'OutputFileName','OutputFileType','ToPlot'}, ...
              {'table','table','variable'});
T.Properties
ans = 
  TableProperties with properties:

             Description: ''
                UserData: []
          DimensionNames: {'Row'  'Variables'}
           VariableNames: {1x6 cell}
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowNames: {}

   Custom Properties (access using t.Properties.CustomProperties.<name>):
          OutputFileName: []
          OutputFileType: []
                  ToPlot: []

Set and Access Values of Custom Properties

When you add custom properties using addprop, their values are empty arrays by default. You can set and access the values of the custom properties using dot syntax.

Set the output file name and type. These properties contain metadata for the table. Then assign a logical array to the ToPlot property. This property contains metadata for the variables. In this example, the elements of the value of the ToPlot property are true for each variable to be included in a plot, and false for each variable to be excluded.

T.Properties.CustomProperties.OutputFileName = 'outageResults';
T.Properties.CustomProperties.OutputFileType = '.mat';
T.Properties.CustomProperties.ToPlot = [false false true true true false];
T.Properties
ans = 
  TableProperties with properties:

             Description: ''
                UserData: []
          DimensionNames: {'Row'  'Variables'}
           VariableNames: {1x6 cell}
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowNames: {}

   Custom Properties (access using t.Properties.CustomProperties.<name>):
          OutputFileName: 'outageResults'
          OutputFileType: '.mat'
                  ToPlot: [0 0 1 1 1 0]

Plot variables from T in a stacked plot using the stackedplot function. To plot only the Loss, Customers, and RestorationTime values, use the ToPlot custom property as the second input argument.

stackedplot(T,T.Properties.CustomProperties.ToPlot);

When you move or delete table variables, both the predefined and custom properties are reordered so that their values correspond to the same variables. In this example, the values of the ToPlot custom property stay aligned with the variables marked for plotting, just as the values of the VariableNames predefined property stay aligned.

Remove the Customers variable and display the properties.

T.Customers = [];
T.Properties
ans = 
  TableProperties with properties:

             Description: ''
                UserData: []
          DimensionNames: {'Row'  'Variables'}
           VariableNames: {1x5 cell}
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowNames: {}

   Custom Properties (access using t.Properties.CustomProperties.<name>):
          OutputFileName: 'outageResults'
          OutputFileType: '.mat'
                  ToPlot: [0 0 1 1 0]

Convert the table to a timetable, using the outage times as row times. Move Region to the end of the table, and RestorationTime before the first variable, using the movevars function. Note that the properties are reordered appropriately. The RestorationTime and Loss variables still have indicators for inclusion in a plot.

T = table2timetable(T);
T = movevars(T,'Region','After','Cause');
T = movevars(T,'RestorationTime','Before',1);
T.Properties
ans = 
  TimetableProperties with properties:

             Description: ''
                UserData: []
          DimensionNames: {'OutageTime'  'Variables'}
           VariableNames: {'RestorationTime'  'Loss'  'Cause'  'Region'}
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [1468x1 datetime]
               StartTime: 2002-02-01 12:18
              SampleRate: NaN
                TimeStep: NaN

   Custom Properties (access using t.Properties.CustomProperties.<name>):
          OutputFileName: 'outageResults'
          OutputFileType: '.mat'
                  ToPlot: [1 1 0 0]

Remove Properties

You can remove any or all of the custom properties of a table using the rmprop function. However, you cannot use it to remove predefined properties from T.Properties, because those properties are part of the definition of the table data type.

Remove the OutputFileName and OutputFileType custom properties. Display the remaining table properties.

T = rmprop(T,{'OutputFileName','OutputFileType'});
T.Properties
ans = 
  TimetableProperties with properties:

             Description: ''
                UserData: []
          DimensionNames: {'OutageTime'  'Variables'}
           VariableNames: {'RestorationTime'  'Loss'  'Cause'  'Region'}
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [1468x1 datetime]
               StartTime: 2002-02-01 12:18
              SampleRate: NaN
                TimeStep: NaN

   Custom Properties (access using t.Properties.CustomProperties.<name>):
                  ToPlot: [1 1 0 0]

See Also

| | | | | | | |

Related Topics