Documentation

This is machine translation

Translated by Microsoft
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

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

    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.

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

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'    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 = 

            Time              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','Time')
B = 

            Time            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 

Related Examples

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.

If A is a timetable, then 'GroupingVariables' can specify either the row times or a subset of the data variables from the timetable, but not both.

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 Table Properties or Timetable Properties.

Introduced in R2013b

Was this topic helpful?