rowfun

Apply function to table rows

Syntax

  • B = rowfun(func,A)
  • B = rowfun(func,A,Name,Value) example

Description

B = rowfun(func,A) applies the function func to each row of the table A and returns the results in the table B.

func accepts size(A,2) inputs.

example

B = rowfun(func,A,Name,Value) applies the function func to each row 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 func and how to call func.

Examples

expand all

Apply Function with Single Output to Rows

Apply the function hypot to each row of the 5-by-2 table A to find the shortest distance between the variables x and y.

Create a table, A, with two variables of numeric data.

x = gallery('integerdata',10,[5,1],2);
y = gallery('integerdata',10,[5,1],8);

A = table(x,y)
A = 

    x    y 
    _    __

    9     1
    4     5
    3     2
    7     3
    1    10

Apply the function, hypot to each row of A. The function hypot takes two inputs and returns one output.

B = rowfun(@hypot,A,'OutputVariableNames','z')
B = 

      z   
    ______

    9.0554
    6.4031
    3.6056
    7.6158
     10.05

B is a table.

Append the function output, B, to the input table, A.

[A B]
ans = 

    x    y       z   
    _    __    ______

    9     1    9.0554
    4     5    6.4031
    3     2    3.6056
    7     3    7.6158
    1    10     10.05

Apply Function with Multiple Outputs to Rows

Define and apply a geometric Brownian motion model to a range of parameters.

Create a function in a file named gbmSim.m that contains the following code.

function [m,mtrue,s,strue] = gbmSim(mu,sigma)
% Discrete approximation to geometric Brownian motion
%
% [m,mtrue,s,strue] = gbmSim(mu,sigma) computes the 
% simulated mean, true mean, simulated standard deviation, 
% and true standard deviation based on the parameters mu and sigma.

numReplicates = 1000; numSteps = 100;
y0 = 1;
t1 = 1;
dt = t1 / numSteps;
y1 = y0*prod(1 + mu*dt + sigma*sqrt(dt)*randn(numSteps,numReplicates));
m = mean(y1); s = std(y1);
% Theoretical values
mtrue = y0 * exp(mu*t1); strue = mtrue * sqrt(exp(sigma^2*t1) - 1);

gbmSim accepts two inputs, mu and sigma, and returns four outputs, m, mtrue, s, and strue.

Define the table, params, containing the parameters to input to the Brownian Motion Model.

mu = [-.5; -.25; 0; .25; .5];
sigma = [.1; .2; .3; .2; .1];

params = table(mu,sigma)
params = 

     mu      sigma
    -----    -----
     -0.5    0.1  
    -0.25    0.2  
        0    0.3  
     0.25    0.2  
      0.5    0.1  

Apply the function, gbmSim to the rows of the table, params.

stats = rowfun(@gbmSim,params,...
    'OutputVariableNames',...
    {'simulatedMean' 'trueMean' 'simulatedStd' 'trueStd'})
stats = 

    simulatedMean    trueMean    simulatedStd    trueStd 
    _____________    ________    ____________    ________

    0.60501          0.60653     0.05808         0.060805
    0.77916           0.7788       0.161          0.15733
     1.0024                1      0.3048          0.30688
     1.2795            1.284     0.25851          0.25939
     1.6498           1.6487     0.16285          0.16529

The 4 strings specified by the 'OutputVariableNames' name-value pair argument indicate that rowfun should obtain 4 outputs from gbmSim. You can specify fewer output variable names to return fewer outputs from gbmSim.

Append the function output, stats, to the input, params.

[params stats]
ans = 

     mu      sigma    simulatedMean    trueMean    simulatedStd    trueStd 
    _____    _____    _____________    ________    ____________    ________

     -0.5    0.1      0.60501          0.60653     0.05808         0.060805
    -0.25    0.2      0.77916           0.7788       0.161          0.15733
        0    0.3       1.0024                1      0.3048          0.30688
     0.25    0.2       1.2795            1.284     0.25851          0.25939
      0.5    0.1       1.6498           1.6487     0.16285          0.16529

Apply Function to Groups of Rows

Create a table, A, where g is a grouping variable.

g = gallery('integerdata',3,[15,1],1);
x = gallery('uniformdata',[15,1],9);
y = gallery('uniformdata',[15,1],2);

A = table(g,x,y)
A = 

    g       x          y    
    _    _______    ________

    3    0.24756     0.87516
    3     0.4358      0.3179
    3    0.97755     0.27323
    2    0.85995      0.6765
    3    0.30063    0.071171
    2    0.26589     0.19659
    3    0.13338     0.52908
    2     0.7425     0.17176
    1    0.85692     0.86996
    2    0.24286     0.24369
    3    0.19492     0.84291
    2    0.39076     0.55766
    1    0.29683     0.35681
    1    0.39031      0.2324
    2    0.18726      0.6476

Define the anonymous function, func, to compute the average difference between x and y.

func = @(x,y) mean(x-y);

Find the average difference between variables in groups 1, 2, and 3 defined by the grouping variable, g.

B = rowfun(func,A,...
    'GroupingVariable','g',...
    'OutputVariableName','MeanDiff')
B = 

         g    GroupCount    MeanDiff
         _    __________    ________

    1    1    3             0.028298
    2    2    6             0.032569
    3    3    6             -0.10327

The variable GroupCount indicates the number of rows in A for each 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.

func can accept no more than size(A,2) inputs. By default, rowfun returns the first output of func. To return more than one output from func, use the 'NumOutputs' or 'OutputVariableNames' name-value pair arguments.

Example: func = @(x,y) x.^2+y.^2; takes two inputs and finds the sum of the squares.

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, logical vector, or an anonymous function that returns a logical scalar. If you specify 'InputVariables' as an anonymous function that returns a logical scalar, rowfun 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. rowfun applies func to each group of rows, rather than separately to each row of A. The output, B, contains one row for each group.

'SeparateInputs' — Indicator for calling func with separate inputstrue (default) | false | 1 | 0

Indicator for calling func with separate inputs, specified as the comma-separated pair consisting of 'SeparateInputs' and either true, false, 1, or 0.

true

func expects separate inputs. rowfun calls func with size(A,2) inputs, one argument for each data variable.

This is the default behavior.

false

func expects one vector containing all inputs. rowfun creates the input vector to func by concatenating the values in each row of A.

'ExtractCellContents' — Indicator to pass values from cell variables to funcfalse (default) | true | 0 | 1

Indicator to pass values from cell variables to func, specified as the comma-separated pair consisting of 'ExtractCellContents' and either false, true, 0, or 1.

true

rowfun extracts the contents of a variable in A whose data type is cell and passes the values, rather than the cells, to func

For grouped computation, the values within each group in a cell variable must allow vertical concatenation.

false

rowfun passes the cells of a variable in A whose data type is cell to func.

This is the default behavior.

'OutputVariableNames' — Variable names for outputs of funcstring | cell array of nonempty, distinct strings

Variable names for outputs of func, specified as the comma-separated pair consisting of 'OutputVariableNames' and a string or a cell array of nonempty, distinct strings. The number of strings must equal the number of outputs desired from func.

Furthermore, the strings must be valid MATLAB identifiers. If valid MATLAB identifiers are not available for use as variable names, MATLAB uses a cell array of N strings of the form {'Var1' ... 'VarN'} where N is the number of variables. You can determine valid MATLAB variable names using the function isvarname.

'NumOutputs' — Number of outputs from func0 | positive integer

Number of outputs from func, specified as the comma-separated pair consisting of 'NumOutputs' and 0 or a positive integer. The integer must be less than or equal to the possible number of outputs from func.

Example: 'NumOutputs',2 causes rowfun to call func with two outputs.

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

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

'table'

rowfun returns a table with one variable for each output of func. 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. However, for ungrouped computation, all of the outputs from func must have one row each time it is called. For grouped computation, all of the outputs from func must have the same number of rows.

This is the default output format.

'uniform'

rowfun concatenates the values returned by func into a vector. All of the outputs from func must be scalars with the same data type.

'cell'

rowfun 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

    Row or group index at 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.

Was this topic helpful?