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)

       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: {'Region'  'OutageTime'  'Loss'  'Customers'  'RestorationTime'  'Cause'}
           VariableTypes: ["cell"    "datetime"    "double"    "double"    "datetime"    "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: {'Region'  'OutageTime'  'Loss'  'Customers'  'RestorationTime'  'Cause'}
           VariableTypes: ["cell"    "datetime"    "double"    "double"    "datetime"    "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: {'Region'  'OutageTime'  'Loss'  'Customers'  'RestorationTime'  'Cause'}
           VariableTypes: ["cell"    "datetime"    "double"    "double"    "datetime"    "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: {'Region'  'OutageTime'  'Loss'  'RestorationTime'  'Cause'}
           VariableTypes: ["cell"    "datetime"    "double"    "datetime"    "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'}
           VariableTypes: ["datetime"    "double"    "cell"    "cell"]
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [1468x1 datetime]
               StartTime: 2002-02-01 12:18
              SampleRate: NaN
                TimeStep: NaN
                  Events: []

   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'}
           VariableTypes: ["datetime"    "double"    "cell"    "cell"]
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [1468x1 datetime]
               StartTime: 2002-02-01 12:18
              SampleRate: NaN
                TimeStep: NaN
                  Events: []

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