convertvars

Convert table or timetable variables to specified data type

Syntax

T2 = convertvars(T1,vars,dataType)

Description

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

Convert Table Variables

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)

       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)

     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 Variable Types Without Specifying Names

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)

       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)

       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

T1 — Input table

table | timetable

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.

vars — Variables in input table or timetable

string array | character vector | cell array of character vectors | pattern scalar | numeric array | logical array | function handle

Variables in the input table or timetable, specified as a string array, character vector, cell array of character vectors, pattern scalar, 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.

dataType — Data type of converted variables

character vector | string scalar | function handle

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.

Alternative Functionality

You can also convert table and timetable variables by using the VariableTypes property. Unlike convertvars, the property enables you to convert different variables to different data types. (since R2024b)

For example, assign new data types to the variables of table T so that the first variable is a categorical array and the last variable is a string array.

T = readtable('outages.csv');
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'   }
    {'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'   }

T.Properties.VariableTypes = ["categorical" "datetime" "double" "double" "datetime" "string"];
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"
    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"

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• Function handles are not supported.

• The second and third input arguments (vars and dataType) must be constant.

• The vars input argument does not support pattern expressions.

• You cannot specify dataType as 'cell', 'cellstr', or 'char'.

For more information, see Code Generation for Tables (MATLAB Coder) and Table Limitations for Code Generation (MATLAB Coder).

Thread-Based Environment
Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

Version History

Introduced in R2018b