Main Content

varfun

Apply function to table or timetable variables

collapse all in page

Syntax

B = varfun(func,A)
B = varfun(func,A,Name,Value)

Description

example

B= varfun(func,A)applies the functionfuncseparately to each variable of the table or timetableAand returns the results in the table or timetableB.

The functionfuncmust take one input argument and return arrays with the same number of rows each time it is called. Theith variable in the output argument,B{:,i}, is equal tofunc(A{:,i}).

IfAis a timetable andfuncaggregates data over groups of rows, thenvarfunassigns the first row time from each group of rows inAas the corresponding row time inB. To returnBas a table without row times, specify'OutputFormat'as'table'.

example

B= varfun(func,A,Name,Value)applies the functionfuncseparately to each variable of the table or timetableAwith additional options specified by one or moreName,Valuepair arguments.

For example, you can specify which variables to pass to the function.

Examples

collapse all

Open Live Script

Define and apply an element-wise function to the variables of a table to square all the elements.

定义一个表包含数值变量。

A = table([0.71;-2.05;-0.35;-0.82;1.57],[0.23;0.12;-0.18;0.23;0.41])
A=5×2 tableVar1 Var2  _____ _____ 0.71 0.23 -2.05 0.12 -0.35 -0.18 -0.82 0.23 1.57 0.41

Define the anonymous function to find the square of an input.

func = @(x) x.^2;

Apply the function to all the variables of tableA.

B = varfun(func,A)
B=5×2 tableFun_Var1 Fun_Var2 ________ ________ 0.5041 0.0529 4.2025 0.0144 0.1225 0.0324 0.6724 0.0529 2.4649 0.1681

The variables ofBhave names based on the function and the variable names fromA.

Open Live Script

Compute the mean of each variable in a 5-by-2 table.

定义一个表包含数值变量。

A = table([0.71;-2.05;-0.35;-0.82;1.57],[0.23;0.12;-0.18;0.23;0.41])
A=5×2 tableVar1 Var2  _____ _____ 0.71 0.23 -2.05 0.12 -0.35 -0.18 -0.82 0.23 1.57 0.41

Define the anonymous function to find the mean of an input.

func = @mean;

func使用现有的MATLAB®函数定义operation.

Apply the function to all the variables of tableA.

B = varfun(func,A)
B=1×2 tablemean_Var1 mean_Var2 _________ _________ -0.188 0.162

Bis a table containing the average value from each variable. To return a numeric vector instead of a table, you can useB = varfun(func,A,'OutputFormat','uniform').

Open Live Script

Compute the group-wise means of variables in a table,A, and return them as rows in a table,B.

Create a table where one variable defines groups.

A = table({'test2';'test1';'test2';'test3';'test1'},...[0.71;-2.05;-0.35;-0.82;1.57],[0.23;0.12;-0.18;0.23;0.41])
A=5×3 tableVar1 Var2 Var3 _________ _____ _____ {'test2'} 0.71 0.23 {'test1'} -2.05 0.12 {'test2'} -0.35 -0.18 {'test3'} -0.82 0.23 {'test1'} 1.57 0.41

Define the anonymous function to find the mean of an input.

func = @mean;

func使用现有的MATLAB®函数定义operation.

Apply the function to each group of data defined byVar1.

B = varfun(func,A,'GroupingVariables','Var1')
B=3×4 tableVar1 GroupCount mean_Var2 mean_Var3 _________ __________ _________ _________ {'test1'} 2 -0.24 0.265 {'test2'} 2 0.18 0.025 {'test3'} 1 -0.82 0.23

Bcontains a variable calledGroupCountto indicate the number of entries from tableAin that group.

Open Live Script

Create a timetable containing sample data. The row times of the timetable also define groups.

dt = datetime(2016,1,1)+days([0 1 1 2 3 3])'; A = timetable(dt,[0.71;-2.05;-0.35;-0.82;1.57;0.09],...[0.23;0.12;-0.18;0.23;0.41;0.02],...'VariableNames',{'x''y'})
A=6×2 timetabledt x y ___________ _____ _____ 01-Jan-2016 0.71 0.23 02-Jan-2016 -2.05 0.12 02-Jan-2016 -0.35 -0.18 03-Jan-2016 -0.82 0.23 04-Jan-2016 1.57 0.41 04-Jan-2016 0.09 0.02

Compute the group-wise means of the variables in the timetable.varfunreturnsBas a timetable becauseAis a timetable. When you specify the row times as the grouping variable, you cannot specify any variable as another grouping variable.

B = varfun(@mean,A,'GroupingVariables',“dt”)
B=4×3 timetabledt GroupCount mean_x mean_y ___________ __________ ______ ______ 01-Jan-2016 1 0.71 0.23 02-Jan-2016 2 -1.2 -0.03 03-Jan-2016 1 -0.82 0.23 04-Jan-2016 2 0.83 0.215

Input Arguments

collapse all

Function, specified as a function handle. You can define the function in a file or as an anonymous function. Iffunccorresponds to more than one function file (that is, iffuncrepresents a set of overloaded functions), MATLAB®determines which function to call based on the class of the input arguments.

Use the'OutputFormat','cell'name-value pair argument, if the functionfunctake one input argument and returns arrays with a different numbers of rows each time it is called. Otherwise,funcmust return arrays with the same number of rows.

Example:func = @(x) x.^2;computes the square of each element of an input.

Input table, specified as a table or a timetable.

Name-Value Arguments

Specify optional pairs of arguments asName1=Value1,...,NameN=ValueN, whereNameis the argument name andValueis the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and encloseNamein quotes.

Example:'InputVariables',2uses only the second variable inAas an input tofunc.

Specifiers for selecting variables ofAto pass tofunc, specified as the comma-separated pair consisting of'InputVariables'and a positive integer, vector of positive integers, string array, character vector, cell array of character vectors,patternscalar, logical vector, or a function handle.

If you specify'InputVariables'as a function handle, then it must return a logical scalar, andvarfunpasses only the variables inAwhere the function returns1(true).

One or more variables inAthat define groups of rows, specified as the comma-separated pair consisting of'GroupingVariables'and a positive integer, vector of positive integers, string array, character vector, cell array of character vectors,patternscalar, or logical vector.

The value of'GroupingVariables'specifies which table variables are the grouping variables, not their data types. A grouping variable can be numeric, or have data typecategorical,calendarDuration,datetime,duration,logical, orstring.

Rows inAthat have the same grouping variable values belong to the same group.varfunappliesfuncto each group of rows within each of the variables ofA, rather than to each entire variable.

If any grouping variable containsNaNs or missing values (such asNaTs, undefined categorical values, or missing strings), then the corresponding rows do not belong to any group, and are excluded from the output.

Row labels can be grouping variables. You can group on row labels alone, on one or more variables inA, or on row labels and variables together.

  • IfAis a table, then the labels are row names.

  • IfAis a timetable, then the labels are row times.

The output,B, has one row for each group when you specify'OutputFormat','uniform'or'OutputFormat','cell'. When you specify'OutputFormat','table'or'OutputFormat','timetable', the sizes of the outputs fromfuncdetermine how many rows ofBcorrespond to each group.

Format ofB, specified as the comma-separated pair consisting of'OutputFormat'and either the value'uniform','table','timetable', or'cell'.

'table'

varfunreturns a table with one variable for each variable inA(or each variable specified with'InputVariables'). For grouped computation,B, also contains the grouping variables.

'table'allows you to use a function that returns values of different sizes or data types for the different variables inA. However, for ungrouped computation,funcmust return arrays with the same number of rows each time it is called. For grouped computation,funcmust return values with the same number of rows each time it is called for a given group.

IfAis a table, then this is the default output format.

'timetable'

varfunreturns a timetable with one variable for each variable inA(or each variable specified with'InputVariables'). For grouped computation,Balso contains the grouping variables.

varfuncreates the row times ofBfrom the row times ofA. If the row times assigned toBdo not make sense in the context of the calculations performed usingfunc, then specify the output format as'OutputFormat','table'.

IfAis a timetable, then this is the default output format.

'uniform'

varfunconcatenates the values into a vector.funcmust return a scalar with the same data type each time it is called.

'cell'

varfunreturnsBas a cell array.'cell'allows you to use a function that returns values of different sizes or data types.

Function to call iffuncfails, specified as the comma-separated pair consisting of'ErrorHandler'and a function handle. Define this function so that it rethrows the error or returns valid outputs for functionfunc.

MATLAB calls the specified error-handling function with two input arguments:

  • A structure with these fields:

    identifier

    Error identifier.

    message

    Error message text.

    index

    Index of the variable for which the error occurred.

    name

    Name of the variable for which the error occurred.

  • The set of input arguments to functionfuncat the time of the error.

For example,

function[A, B] = errorFunc(S, varargin) warning(S.identifier, S.message) A = NaN; B = NaN;

Output Arguments

collapse all

Output table, returned as a table or a timetable.Bcan store metadata such as descriptions, variable units, variable names, and row names. For more information, see the Properties sections oftableortimetable.

Extended Capabilities

Version History

Introduced in R2013b

See Also

||||||||

Topics