addprop

Add custom properties to table or timetable

collapse all in page

Syntax

T2 = addprop(T1,propertyNames,propertyTypes)

Description

T2 = addprop(T1,propertyNames,propertyTypes) adds properties that contain custom metadata to a table or timetable. The input argument propertyNames specifies the names of the properties. For each custom property, propertyTypes specifies whether the metadata values contained in the property apply to the output table or timetable as a whole, or to its variables.

After you add properties using addprop, you can assign metadata values to the properties using dot syntax.

example

Examples

collapse all

Open Live Script

Read data into a table. Then add properties to contain custom metadata.

First, read measurements of humidity and air quality into a table.

T = readtable("indoors.csv")
T=60×3 table
           Time            Humidity    AirQuality
    ___________________    ________    __________

    2015-11-15 00:00:24       36           80    
    2015-11-15 01:13:35       36           80    
    2015-11-15 02:26:47       37           79    
    2015-11-15 03:39:59       37           82    
    2015-11-15 04:53:11       36           80    
    2015-11-15 06:06:23       36           80    
    2015-11-15 07:19:35       36           80    
    2015-11-15 08:32:47       37           80    
    2015-11-15 09:45:59       37           79    
    2015-11-15 10:59:11       36           80    
    2015-11-15 12:12:23       37           80    
    2015-11-15 13:25:35       37           79    
    2015-11-15 14:38:46       36           83    
    2015-11-15 15:51:58       37           80    
    2015-11-15 17:05:10       36           80    
    2015-11-15 18:18:22       37           80    
      ⋮

Display the properties of the table. The properties object, T.Properties, stores metadata such as the names of the two dimensions of the table and the names of the table variables. All tables have such objects with the same properties. (Timetables also have similar objects that include additional, time-specific properties.)

T.Properties
ans = 
  TableProperties with properties:

             Description: ''
                UserData: []
          DimensionNames: {'Row'  'Variables'}
           VariableNames: {'Time'  'Humidity'  'AirQuality'}
           VariableTypes: ["datetime"    "double"    "double"]
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowNames: {}
        CustomProperties: No custom properties are set.
      Use addprop and rmprop to modify CustomProperties.

In addition, you can specify your own properties to store custom metadata. For example, use the addprop function to add properties to the table T for the instrument name, measurement precision, and the name of the source file. For properties that have one metadata value per variable, specify "variable" as the property type. For properties that have one value that applies to the whole table, specify "table".

T = addprop(T,["Instrument" "Precision" "SourceFile"],["variable" "variable" "table"]);
T.Properties
ans = 
  TableProperties with properties:

             Description: ''
                UserData: []
          DimensionNames: {'Row'  'Variables'}
           VariableNames: {'Time'  'Humidity'  'AirQuality'}
           VariableTypes: ["datetime"    "double"    "double"]
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowNames: {}

   Custom Properties (access using t.Properties.CustomProperties.<name>):
              SourceFile: []
              Instrument: []
               Precision: []

When you create custom properties using addprop, the properties are empty. To store metadata values in the custom properties, assign them using dot syntax.

T.Properties.CustomProperties.Instrument = ["clock" "hygrometer" "air quality meter"];
T.Properties.CustomProperties.Precision = [NaN 0.5 0.1];
T.Properties.CustomProperties.SourceFile = "indoors.csv";
T.Properties
ans = 
  TableProperties with properties:

             Description: ''
                UserData: []
          DimensionNames: {'Row'  'Variables'}
           VariableNames: {'Time'  'Humidity'  'AirQuality'}
           VariableTypes: ["datetime"    "double"    "double"]
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowNames: {}

   Custom Properties (access using t.Properties.CustomProperties.<name>):
              SourceFile: "indoors.csv"
              Instrument: ["clock"    "hygrometer"    "air quality meter"]
               Precision: [NaN 0.5000 0.1000]

When you assign an array of text values to custom properties, the best practice is to use a string array, not a cell array of character vectors. If you use a cell array of character vectors, then there is no mechanism to prevent you from later assigning nontext values as elements of the cell array.

Input Arguments

collapse all

Input table, specified as a table or timetable.

Names of the custom properties, specified as a string array, character vector, or cell array of character vectors.

Property types, specified as a string array, character vector, or cell array of character vectors. For each property name specified by propertyNames, specify the corresponding property type as either "table" or "variable". The number of property types must equal the number of property names.

The table describes the two property types.

Property Type

Description

"table"

The property contains a single value of arbitrary size. The value applies as metadata to the table or timetable as a whole.

"variable"

The property contains an array that has one value for each variable in the table or timetable. The values are metadata for the variables. The number of values in the array must match the number of variables.

The values stored by the property are synchronized with the variables. They respond when you take one of these actions:

  • Move variables — The corresponding values in the property are reordered.

  • Add variables — Default values are added as corresponding values in the property.

  • Remove variables — The corresponding values are removed from the property.

Output Arguments

collapse all

Output table with added properties, returned as a table or timetable.

Version History

Introduced in R2018b

See Also

| | |

Topics