Quantcast

Documentation Center

  • Trial Software
  • Product Updates

varfun

Apply function to table variables

Syntax

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 ith 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

expand 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

expand 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 funcpositive 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

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

See Also

| | |

Was this topic helpful?