# varfun

Apply function to table variables

## Syntax

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

## Description

example

````B = varfun(func,A)` applies the function `func` separately to each variable of the table `A` and returns the results in the table `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 table, `B{:,i}`, is equal to `func(A{:,i})`.```

example

````B = varfun(func,A,Name,Value)` applies the function `func` separately to each variable of the table `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

### Apply Element-wise Function

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 = 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 = 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`.

### Apply Function that Returns Scalar From Vector

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 = 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 = 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')`.

### Apply Function to Groups Within Variables

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 = 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 = Var1 GroupCount mean_Var2 mean_Var3 _______ __________ _________ _________ test1 'test1' 2 -0.24 0.265 test2 'test2' 2 0.18 0.025 test3 'test3' 1 -0.82 0.23 ```

`B` contains row names based on the grouping variables and a variable called `GroupCount` to indicate the number of entries from table `A` in that group.

## Input Arguments

collapse all

### `func` — Functionfunction handle

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;` conputes the square of each element of an input.

### `A` — Input tabletable

Input table, specified as a table.

### Name-Value Pair Arguments

Specify optional comma-separated pairs of `Name,Value` arguments. `Name` is the argument name and `Value` is the corresponding value. `Name` must appear inside single quotes (`' '`). You can specify several name and value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

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

### `'InputVariables'` — Variables of `A` to pass to `func`positive integer | vector of positive integers | variable name | cell array of variable names | logical vector | ...

Variables of `A` to pass to `func`, specified as the comma-separated pair consisting of `'InputVariables'` and a positive integer, vector of positive integers, variable name, cell array of variable names, or logical vector, or an anonymous function that returns a logical scalar. If you specify `'InputVariables'` as an anonymous function that returns a logical scalar, `varfun` only passes the variables in `A` where the specified function returns `1` (`true`).

### `'GroupingVariables'` — One or more variables in `A` that define groups of rowspositive integer | vector of positive integers | variable name | cell array of variable names | logical vector

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, variable name, cell array of variable names, or logical vector.

A grouping variable can be a numeric vector, logical vector, string (or character array), cell array of strings, or a categorical vector. 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.

The output, `B`, has one row for each group when you specify `'OutputFormat','uniform'` or `'OutputFormat','cell'`. When you specify `'OutputFormat','table'`, the sizes of the outputs from `func` determine how many rows of `B` correspond to each group. When multiple rows of `B` correspond to a group, `varfun` appends a unique identifier to the row names.

### `'OutputFormat'` — Format of `B``'table'` (default) | `'uniform'` | `'cell'`

Format of `B`, specified as the comma-separated pair consisting of `'OutputFormat'` and either the string `'uniform'`, `'table'`, 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.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.

### `'ErrorHandler'` — Function to call if `func` failsfunction handle

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

### `B` — Output tabletable

Output table, returned as a table. The table can store metadata such as descriptions, variable units, variable names, and row names. For more information, see `Table Properties`.