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.

convertvars

Convert table or timetable variables to specified data type

Syntax

T2 = convertvars(T1,vars,dataType)

Description

example

T2 = convertvars(T1,vars,dataType) converts the specified variables to the specified data type. The input argument T1 can be a table or timetable.

While you can specify dataType as the name of a data type, you also can specify it as a function handle. In that case, it is a handle to a function that converts or otherwise modifies the variables specified by vars. Similarly, vars can contain variable names or positions of variables in T1, or it can be a handle to a function that identifies variables.

Examples

collapse all

Read a table from a spreadsheet containing data on electric power outages. The table has text variables showing the region and cause for each power outage, datetime variables showing the outage and restoration times, and numeric variables showing the power loss and number of customers affected. Display the first five rows.

T1 = readtable('outages.csv');
head(T1,5)
ans=5×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'   
    'SouthEast'    2003-01-23 00:49    530.14    2.1204e+05                 NaT    'winter storm'   
    'SouthEast'    2003-02-07 21:15     289.4    1.4294e+05    2003-02-17 08:14    'winter storm'   
    'West'         2004-04-06 05:44    434.81    3.4037e+05    2004-04-06 06:10    'equipment fault'
    'MidWest'      2002-03-16 06:18    186.44    2.1275e+05    2002-03-18 23:23    'severe storm'   

Convert the variables Region and Cause to categorical variables. Note that categorical values are not displayed with quotation marks.

T2 = convertvars(T1,{'Region','Cause'},'categorical');
head(T2,5)
ans=5×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   
    SouthEast    2003-01-23 00:49    530.14    2.1204e+05                 NaT    winter storm   
    SouthEast    2003-02-07 21:15     289.4    1.4294e+05    2003-02-17 08:14    winter storm   
    West         2004-04-06 05:44    434.81    3.4037e+05    2004-04-06 06:10    equipment fault
    MidWest      2002-03-16 06:18    186.44    2.1275e+05    2002-03-18 23:23    severe storm   

It can be convenient to convert variables to data types that offer different functionality. For example, now that T2.Region is a categorical variable, you can use the pie function to make a pie chart of power outages by region. But you cannot use T1.Region as the input argument to pie, because that variable contains text, not categorical data.

pie(T2.Region)

Detect which table variables are datetime arrays. Then use the datetime function as an argument to the convertvars function to specify a time zone and display format.

Read power outage data into a table and display the first three rows.

T1 = readtable('outages.csv');
head(T1,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'
    'SouthEast'    2003-01-23 00:49    530.14    2.1204e+05                 NaT    'winter storm'
    'SouthEast'    2003-02-07 21:15     289.4    1.4294e+05    2003-02-17 08:14    'winter storm'

The datetime arrays in T1 do not have their time zones set. Without specifying the names or locations of table variables, you can detect which variables are datetime arrays using a function handle to the isdatetime function. (A function handle is a variable that stores an association to a function. You can use a function handle to pass a function to another function. For example, specify @isdatetime to pass the handle to convertvars.) Then you can convert all datetime variables so that they have a time zone and a different display format. This technique is useful when converting many table variables that all have the same data type.

Call the convertvars function. To modify the time zone and format in place, specify an anonymous function that calls the datetime function with the 'TimeZone' and 'Format' name-value pair arguments. (An anonymous function is not stored in a program file. It can be useful for a function that requires only a brief definition. In this case, it also allows a call to datetime with multiple inputs, while passing convertvars a function that accepts only one input, as convertvars requires.) Display the first three rows, showing the change in format.

modifyTimeZoneAndFormat = @(x)(datetime(x,'TimeZone','UTC','Format','MMM dd, yyyy, HH:mm z'));
T2 = convertvars(T1,@isdatetime,modifyTimeZoneAndFormat);
head(T2,3)
ans=3×6 table
      Region             OutageTime            Loss     Customers         RestorationTime            Cause     
    ___________    _______________________    ______    __________    _______________________    ______________

    'SouthWest'    Feb 01, 2002, 12:18 UTC    458.98    1.8202e+06    Feb 07, 2002, 16:50 UTC    'winter storm'
    'SouthEast'    Jan 23, 2003, 00:49 UTC    530.14    2.1204e+05                        NaT    'winter storm'
    'SouthEast'    Feb 07, 2003, 21:15 UTC     289.4    1.4294e+05    Feb 17, 2003, 08:14 UTC    'winter storm'

Input Arguments

collapse all

Input table, specified as a table or timetable.

If T1 is a timetable, then you cannot use convertvars to convert its row times, because the row times are not contained in a timetable variable. The row times are timetable metadata.

Variables in the input table or timetable, specified as a character vector, cell array of character vectors, string array, numeric array, logical array, or function handle.

If vars is a function handle, then the function must accept one input argument, identify its data type, and return a logical scalar. For example, use the isnumeric function to detect which variables are numeric.

Example: T2 = convertvars(T1,'Region','categorical') converts the type of the variable Region.

Example: T2 = convertvars(T1,[1,3:6],'string') converts variables specified by position to string arrays.

Example: T2 = convertvars(T1,@isnumeric,'int32') converts all numeric variables to 32-bit integers.

Data type of the converted variables, specified as a character vector, string scalar, or function handle.

If dataType is a function handle, then the function must accept one input argument and convert it to another data type. For example, the string function converts an input argument to a string array.

The table shows the names of many common data types.

'single'Single-precision number
'double'Double-precision number
'int8'Signed 8-bit integer
'int16'Signed 16-bit integer
'int32'Signed 32-bit integer
'int64'Signed 64-bit integer
'uint8'Unsigned 8-bit integer
'uint16'Unsigned 16-bit integer
'uint32'Unsigned 32-bit integer
'uint64'Unsigned 64-bit integer
'logical'Logical 1 (true) or 0 (false)
'string'String array
'cell'Cell array
'cellstr'Cell array of character vectors
'categorical'Categorical array
'datetime'Datetime array
'duration'Duration array
'calendarDuration'Calendar duration array

If you specify 'char' as a data type, then convertvars converts variables to character arrays. Best practice is to avoid creating table or timetable variables that are character arrays. Instead, consider converting variables to string arrays, categorical arrays, or cell arrays of character vectors.

Example: T2 = convertvars(T1,'OutageTime','datetime') converts the type of the variable OutageTime.

Example: T2 = convertvars(T1,'Region',@categorical) converts a variable using a function handle to the categorical function.

Introduced in R2018b