# Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

# 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=5x2 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=5x2 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=5x2 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=1x2 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=5x3 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=3x4 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=6x2 timetable dt x y ____________________ _____ _____ 01-Jan-2016 00:00:00 0.71 0.23 02-Jan-2016 00:00:00 -2.05 0.12 02-Jan-2016 00:00:00 -0.35 -0.18 03-Jan-2016 00:00:00 -0.82 0.23 04-Jan-2016 00:00:00 1.57 0.41 04-Jan-2016 00:00:00 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=4x3 timetable dt GroupCount mean_x mean_y ____________________ __________ ______ ______ 01-Jan-2016 00:00:00 1 0.71 0.23 02-Jan-2016 00:00:00 2 -1.2 -0.03 03-Jan-2016 00:00:00 1 -0.82 0.23 04-Jan-2016 00:00:00 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 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`.

collapse all

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, character vector, cell array of character vectors, 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, character vector, cell array of character vectors, logical vector, categorical vector, datetime vector, or duration 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.

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

## See Also

### Topics

#### Introduced in R2013b

Was this topic helpful?

#### The Manager's Guide to Solving the Big Data Conundrum

Download white paper