# varfun

Apply function to table or timetable variables

## Syntax

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

## Description

example

````B = varfun(func,A)` applies the function `func` separately to each variable of the table or timetable `A` and returns the results in the table or timetable `B`.The function `func` must take one input argument and return arrays with the same number of rows each time it is called. The `i`th variable in the output argument, `B{:,i}`, is equal to `func(A{:,i})`.If `A` is a timetable and `func` aggregates data over groups of rows, then `varfun` assigns the first row time from each group of rows in `A` as the corresponding row time in `B`. To return `B` as a table without row times, specify `'OutputFormat'` as `'table'`.```

example

````B = varfun(func,A,Name,Value)` applies the function `func` separately to each variable of the table or timetable `A` with additional options specified by one or more `Name,Value` pair arguments.For example, you can specify which variables to pass to the function.```

## Examples

collapse all

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

Define a table containing numeric variables.

`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 table Var1 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 table `A`.

`B = varfun(func,A)`
```B=5×2 table Fun_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 of `B` have names based on the function and the variable names from `A`.

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

Define a table containing numeric variables.

`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 table Var1 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` uses an existing MATLAB® function to define the operation.

Apply the function to all the variables of table `A`.

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

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

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 table Var1 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` uses an existing MATLAB® function to define the operation.

Apply the function to each group of data defined by `Var1`.

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

`B` contains a variable called `GroupCount` to indicate the number of entries from table `A` in that group.

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 timetable dt 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. `varfun` returns `B` as a timetable because `A` is 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 timetable dt 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. If `func` corresponds to more than one function file (that is, if `func` represents 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 function `func` take one input argument and returns arrays with a different numbers of rows each time it is called. Otherwise, `func` must 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 as `Name1=Value1,...,NameN=ValueN`, where `Name` is the argument name and `Value` is 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 enclose `Name` in quotes.

Example: `'InputVariables',2` uses only the second variable in `A` as an input to `func`.

Specifiers for selecting variables of `A` to pass to `func`, 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, `pattern` scalar, logical vector, or a function handle.

If you specify `'InputVariables'` as a function handle, then it must return a logical scalar, and `varfun` passes only the variables in `A` where the function returns `1` (`true`).

One or more variables in `A` that 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, `pattern` scalar, 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 type `categorical`, `calendarDuration`, `datetime`, `duration`, `logical`, or `string`.

Rows in `A` that have the same grouping variable values belong to the same group. `varfun` applies `func` to each group of rows within each of the variables of `A`, rather than to each entire variable.

If any grouping variable contains `NaN`s or missing values (such as `NaT`s, 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 in `A`, or on row labels and variables together.

• If `A` is a table, then the labels are row names.

• If `A` is 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 from `func` determine how many rows of `B` correspond to each group.

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

 `'table'` `varfun` returns a table with one variable for each variable in `A` (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 in `A`. However, for ungrouped computation, `func` must return arrays with the same number of rows each time it is called. For grouped computation, `func` must return values with the same number of rows each time it is called for a given group.If `A` is a table, then this is the default output format. `'timetable'` `varfun` returns a timetable with one variable for each variable in `A` (or each variable specified with `'InputVariables'`). For grouped computation, `B` also contains the grouping variables.`varfun` creates the row times of `B` from the row times of `A`. If the row times assigned to `B` do not make sense in the context of the calculations performed using `func`, then specify the output format as `'OutputFormat','table'`.If `A` is a timetable, then this is the default output format. `'uniform'` `varfun` concatenates the values into a vector. `func` must return a scalar with the same data type each time it is called. `'cell'` `varfun` returns `B` as a cell array. `'cell'` allows you to use a function that returns values of different sizes or data types.

Function to call if `func` fails, 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 function `func`.

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 function `func` at 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. `B` can store metadata such as descriptions, variable units, variable names, and row names. For more information, see the Properties sections of `table` or `timetable`.

## Version History

Introduced in R2013b