rowfun

Apply function to table or timetable rows

Syntax

B = rowfun(func,A)

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

Description

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

The number of inputs that the function func accepts must equal the number of variables in A. For example, if func must be called with two input arguments, then A must have two variables. To find the number of variables in a table, use the width function.

B = rowfun(func,A,Name,Value) specifies options using one or more name-value arguments. For example, you can use the GroupingVariables name-value argument to carry out calculations on groups of rows. For more information about calculations on groups of data, see Calculations on Groups of Data.

Examples

Apply Function with Single Output to Rows

Create a table with two variables of numeric data.

X = randi(10,[5,1]);
Y = randi(10,[5,1]);
A = table(X,Y)

A=5×2 table
    X     Y 
    __    __

     9     1
    10     3
     2     6
    10    10
     7    10

Apply the plus function to each row of the table. The function call plus(X,Y) is equivalent to the operation X + Y. The plus function accepts two inputs and returns one output. To specify a function as an input argument to rowfun, use the @ symbol.

B = rowfun(@plus,A,"OutputVariableNames","Sum")

B=5×1 table
    Sum
    ___

    10 
    13 
     8 
    20 
    17 

Append the output table to the input table.

C = [A B]

C=5×3 table
    X     Y     Sum
    __    __    ___

     9     1    10 
    10     3    13 
     2     6     8 
    10    10    20 
     7    10    17 

Apply Function with Multiple Outputs to Rows

Apply a function that returns multiple outputs to the rows of a table. The rowfun function stores each output from the applied function in a variable of the output table.

Read data from a CSV (comma-separated values) file into a table. The sample file contains test scores for 10 students from two different schools.

scores = readtable("testScores.csv","TextType","string");
scores.School = categorical(scores.School)

scores=10×5 table
     LastName       School      Test1    Test2    Test3
    __________    __________    _____    _____    _____

    "Jeong"       XYZ School     90       87       93  
    "Collins"     XYZ School     87       85       83  
    "Torres"      XYZ School     86       85       88  
    "Phillips"    ABC School     75       80       72  
    "Ling"        ABC School     89       86       87  
    "Ramirez"     ABC School     96       92       98  
    "Lee"         XYZ School     78       75       77  
    "Walker"      ABC School     91       94       92  
    "Garcia"      ABC School     86       83       85  
    "Chang"       XYZ School     79       76       82  

To find the minimum and maximum test scores across each row, apply the bounds function. The bounds function returns two output arguments. The output of rowfun is a new table that has TestMin and TestMax variables. In this case, also specify the SeparateInputs name-value argument as false so that values across each row are combined into a vector before being passed to bounds.

vars = ["Test1","Test2","Test3"];
minmaxTest = rowfun(@bounds, ...
                    scores, ...
                    "InputVariables",vars, ...
                    "OutputVariableNames",["TestMin","TestMax"], ...
                    "SeparateInputs",false)

minmaxTest=10×2 table
    TestMin    TestMax
    _______    _______

      87         93   
      83         87   
      85         88   
      72         80   
      86         89   
      92         98   
      75         78   
      91         94   
      83         86   
      76         82   

You can append the minimum and maximum to the input table.

scores = [scores minmaxTest]

scores=10×7 table
     LastName       School      Test1    Test2    Test3    TestMin    TestMax
    __________    __________    _____    _____    _____    _______    _______

    "Jeong"       XYZ School     90       87       93        87         93   
    "Collins"     XYZ School     87       85       83        83         87   
    "Torres"      XYZ School     86       85       88        85         88   
    "Phillips"    ABC School     75       80       72        72         80   
    "Ling"        ABC School     89       86       87        86         89   
    "Ramirez"     ABC School     96       92       98        92         98   
    "Lee"         XYZ School     78       75       77        75         78   
    "Walker"      ABC School     91       94       92        91         94   
    "Garcia"      ABC School     86       83       85        83         86   
    "Chang"       XYZ School     79       76       82        76         82   

Apply Function to Groups of Rows

Apply a function to data in groups of rows of the input table. The output table has one row for each group.

Read data from a CSV file into a table. The sample file contains test scores for 10 students from two different schools.

scores = readtable("testScores.csv","TextType","string");
scores.School = categorical(scores.School)

scores=10×5 table
     LastName       School      Test1    Test2    Test3
    __________    __________    _____    _____    _____

    "Jeong"       XYZ School     90       87       93  
    "Collins"     XYZ School     87       85       83  
    "Torres"      XYZ School     86       85       88  
    "Phillips"    ABC School     75       80       72  
    "Ling"        ABC School     89       86       87  
    "Ramirez"     ABC School     96       92       98  
    "Lee"         XYZ School     78       75       77  
    "Walker"      ABC School     91       94       92  
    "Garcia"      ABC School     86       83       85  
    "Chang"       XYZ School     79       76       82  

Calculate the mean test score for each student and add it as a new table variable. You can extract the numeric test scores and calculate the means along the second dimension. The result is a column vector that you can attach to scores as a new variable.

scores.TestMean = mean(scores{:,["Test1","Test2","Test3"]},2)

scores=10×6 table
     LastName       School      Test1    Test2    Test3    TestMean
    __________    __________    _____    _____    _____    ________

    "Jeong"       XYZ School     90       87       93           90 
    "Collins"     XYZ School     87       85       83           85 
    "Torres"      XYZ School     86       85       88       86.333 
    "Phillips"    ABC School     75       80       72       75.667 
    "Ling"        ABC School     89       86       87       87.333 
    "Ramirez"     ABC School     96       92       98       95.333 
    "Lee"         XYZ School     78       75       77       76.667 
    "Walker"      ABC School     91       94       92       92.333 
    "Garcia"      ABC School     86       83       85       84.667 
    "Chang"       XYZ School     79       76       82           79 

Find the student whose mean test score is the maximum for each school. Apply the helper function, findNameAtMax, defined at the end of this example. The helper function takes multiple input arguments (last names and test scores) and returns multiple output arguments (maximum score and last name). The variable GroupCount in the output table indicates the number of rows in scores for each school.

maxScoresBySchool = rowfun(@findNameAtMax, ...
                           scores, ...
                           "InputVariables",["LastName","TestMean"], ...
                           "GroupingVariables","School", ...
                           "OutputVariableNames",["max_TestMean","LastName"])

maxScoresBySchool=2×4 table
      School      GroupCount    max_TestMean    LastName 
    __________    __________    ____________    _________

    ABC School        5            95.333       "Ramirez"
    XYZ School        5                90       "Jeong"  

Helper Function

This code defines the findNameAtMax helper function.

function [maxValue,lastName] = findNameAtMax(names,values)
    % Return maximum value and the last name 
    % from the row at which the maximum value occurs
    [maxValue,maxIndex] = max(values);
    lastName = names(maxIndex);
end

Pass Optional Arguments to Applied Function

To pass optional arguments when you apply a function, wrap the function call in an anonymous function.

Create a table with two variables that are integer arrays.

X = int32(randi(10,[5,1]));
Y = int32(randi(10,[5,1]));
A = table(X,Y)

A=5×2 table
    X     Y 
    __    __

     9     1
    10     3
     2     6
    10    10
     7    10

Perform integer division of the two table variables by applying the idivide function.

B = rowfun(@idivide,A)

B=5×1 table
    Var1
    ____

     9  
     3  
     0  
     1  
     0  

The idivide function provides several options for rounding the result. The default rounding option is "fix". To use a different rounding option with idivide, wrap a call that specifies that option in an anonymous function. For example, specify "ceil" as the rounding option.

func = @(x,y) idivide(x,y,"ceil");

Perform integer division with "ceil" by applying the anonymous function.

C = rowfun(func,A)

C=5×1 table
    Var1
    ____

     9  
     4  
     1  
     1  
     1  

Input Arguments

func — Function

function handle

Function, specified as a function handle. You can specify a handle for an existing function, define the function in a file, or specify an anonymous function. The function takes N input arguments, where N = width(A), and must have a syntax in this form:

result = f(arg1, . . . ,argN)

To call f on the rows of A, specify func as shown in this call to rowfun.

func = @f;
B = rowfun(func,A);

For every row in A, rowfun calls func on that row, and then assigns the output of func to the corresponding row in B. The output B has one variable.

Some further considerations:

• The function that func represents can have other syntaxes with additional optional arguments. But when rowfun calls the function, it calls the syntax that has the appropriate number of input arguments.

  For example, the idivide function has a syntax that specifies a third optional argument. But if you specify func as @idivide, then rowfun calls idivide using the idivide(arg1,arg2) syntax.

• To call a function with optional arguments, wrap it in an anonymous function. For example, to call idivide with the "ceil" option, specify func as @(x,y) idivide(x,y,"ceil").

• To return more than one output from func, use the NumOutputs or OutputVariableNames name-value arguments. In that case, the output B has multiple variables, one for each output of func.

• If func returns an array with a different number of rows each time it is called, then specify the OutputFormat name-value argument as "cell". Otherwise, func must return an array with the same number of rows each time it is called.

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

Example: B = rowfun(@idivide,A) performs integer division. A is a table with two variables, with both variables belonging to an integer class. B is a table with one variable.

Example: B = rowfun(@(x,y) x.^2+y.^2,A) calculates the sum of the squares of the two variables in A.

Example: B = rowfun(@(x,y) idivide(x,y,"ceil"),A) performs integer division by applying the idivide function with the "ceil" option.

A — Input table

table | timetable

Input table, specified as a table or timetable.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: B = rowfun(func,A,InputVariables=["Var2","Var3"]) uses only the variables named Var2 and Var3 in A as the inputs to func.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: B = rowfun(func,A,"InputVariables",["Var2","Var3"]) uses only the variables named Var2 and Var3 in A as the inputs to func.

InputVariables — Variables of A to pass to func

positive integer | vector of positive integers | string array | character vector | cell array of character vectors | pattern scalar | logical vector | function handle

Variables of A to pass to func, specified using one of the indexing schemes from this table.

Indexing Scheme	Examples
Variable names: A string array, character vector, or cell array of character vectors A pattern object	"A" or 'A' — A variable named A ["A","B"] or {'A','B'} — Two variables named A and B "Var"+digitsPattern(1) — Variables named "Var" followed by a single digit
Variable index: An index number that refers to the location of a variable in the table A vector of numbers A logical vector. Typically, this vector is the same length as the number of variables, but you can omit trailing 0 or false values	3 — The third variable from the table [2 3] — The second and third variables from the table [false false true] — The third variable
Function handle: A handle to a function that takes one argument as input and returns a logical scalar. The function must have a syntax in this form: tf = f(arg) If you need to apply a function that has additional optional arguments, wrap it in an anonymous function.	@isnumeric — Handle to a function that returns true for an input argument that contain numeric values

Example: B = rowfun(func,A,InputVariables=[1 3 4]) uses only the first, third, and fourth variables in A as the inputs to func.

Example: B = rowfun(func,A,InputVariables=@isnumeric) uses only the numeric variables in A as the inputs to func.

GroupingVariables — Variables of A to use as grouping variables

positive integer | vector of positive integers | string array | character vector | cell array of character vectors | pattern scalar | logical vector

Variables of A to use as grouping variables, specified using one of the indexing schemes from this table.

Indexing Scheme	Examples
Variable names: A string array, character vector, or cell array of character vectors A pattern object	"A" or 'A' — A variable named A ["A","B"] or {'A','B'} — Two variables named A and B "Var"+digitsPattern(1) — Variables named "Var" followed by a single digit
Variable index: An index number that refers to the location of a variable in the table A vector of numbers A logical vector. Typically, this vector is the same length as the number of variables, but you can omit trailing 0 or false values	3 — The third variable from the table [2 3] — The second and third variables from the table [false false true] — The third variable

The unique values in the grouping variables define groups. Rows in A where the grouping variables have the same 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. For more information on calculations using grouping variables, see Calculations on Groups of Data.

Grouping variables can have any of the data types listed in the table.

Values That Specify Groups	Data Type of Grouping Variable
Numbers	Numeric or logical vector
Text	String array or cell array of character vectors
Dates and times	datetime, duration, or calendarDuration vector
Categories	categorical vector
Bins	Vector of binned values, created by binning a continuous distribution of numeric, datetime, or duration values

Many data types have ways to represent missing values, such as NaNs, NaTs, undefined categorical values, or missing strings. If any grouping variable has a data type that can represent missing values, then rows where missing values occur in that grouping variable do not belong to any group and are excluded from the output.

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 of rows in the input A. If B is a table or timetable, then B has:

• Variables corresponding to the input table variables that func was applied to

• Variables corresponding to the grouping variables

• A new variable, GroupCount, whose values are the number of rows of the input A that are in each group

If B is a timetable, then B also has:

• Row times, where the first row time from each group of rows in A is the corresponding row time in B. To return B as a table without row times, specify OutputFormat as "table".

Example: B = rowfun(func,A,GroupingVariables="Var3") uses the variable named Var3 in A as a grouping variable.

Example: B = rowfun(func,A,GroupingVariables=["Var3","Var4"]) uses the variables named Var3 and Var4 in A as grouping variables.

Example: B = rowfun(func,A,GroupingVariables=[3 4]) uses the third and fourth variables in A as grouping variables.

SeparateInputs — Option to call func with separate inputs

true or 1 (default) | false or 0

Option to call func with separate inputs, specified as a numeric or logical 1 (true) or 0 (false).

• If SeparateInputs is true, then func expects separate inputs. rowfun calls func with width(A) inputs, one argument for each data variable.

• If SeparateInputs is false, then func expects one argument containing all inputs. rowfun creates the input argument to func by concatenating the values in each row of A.

  For example, if A is a table that has three variables, and each variable is a numeric vector, then specifying SeparateInputs as false causes rowfun to concatenate the three numeric vectors into one numeric matrix. The matrix has three columns. Then rowfun passes that matrix as one input argument to func.

Example: B = rowfun(@mean,A,SeparateInputs=false) treats N table variables as though their contents were the columns of one array, so that you can treat each row of A as a vector that is passed to mean.

ExtractCellContents — Option to pass values from cell variables to func

false or 0 (default) | true or 1

Option to pass values from cell variables to func, specified as a numeric or logical 0 (false) or 1 (true).

• If ExtractCellContents is true, then 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 calculations, the values within each group in a cell variable must allow vertical concatenation.

• If ExtractCellContents is false, then rowfun passes the cells of a variable in A whose data type is cell to func.

Example: B = rowfun(func,A,ExtractCellContents=true) extracts cell contents from variables that are cell arrays.

OutputVariableNames — Variable names for outputs of func

string array | character vector | cell array of character vectors

Variable names for outputs of func, specified as a string array, character vector, or cell array of character vectors, with names that are nonempty and distinct. The number of names must equal the number of outputs from func.

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

Example: B = rowfun(func,A,OutputVariableNames=["V1","V2"]) returns an output table with two variables named V1 and V2.

NumOutputs — Number of outputs from func

nonnegative integer

Number of outputs from func, specified as a nonnegative integer. The integer must be less than or equal to the possible number of outputs from func.

Example: B = rowfun(func,A,NumOutputs=2) returns two outputs from func.

OutputFormat — Format of B

"auto" (default) | "table" | "timetable" | "uniform" | "cell"

Format of B, specified as one of the values in this table.

"auto" (default) (since R2023a)	rowfun returns an output whose data type matches the data type of the input A.
"table"	rowfun returns a table with one variable for each output of func. For grouped calculations, B also contains the grouping variables and a new GroupCount variable. "table" allows you to use a function that returns values of different sizes or data types. However, for ungrouped calculations, all of the outputs from func must have one row each time it is called. For grouped calculations, all of the outputs from func must have the same number of rows. If A is a table, then this format is the default output format.
"timetable"	rowfun returns a timetable with one variable for each variable in A (or each variable specified with InputVariables). For grouped calculations, B also contains the grouping variables and a new GroupCount variable. rowfun 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 OutputFormat as "table". If A is a timetable, then this is the default output format.
"uniform"	rowfun concatenates the output values into a vector. func must return a scalar with the same data type each time it is called.
"cell"	rowfun returns a cell array. "cell" allows you to use a function that returns values of different sizes or data types.

Example: B = rowfun(func,A,OutputFormat="uniform") returns the output as a vector.

ErrorHandler — Function to call if func fails

function handle

Function to call if func fails, specified as a function handle. If func throws an error, then the error handler function specified by ErrorHandler catches the error and takes the action specified in the function. The error handler either must throw an error or return the same number of outputs as func.

If you do not specify ErrorHandler, then rowfun rethrows the error that it caught from func.

The first input argument of the error handler is a structure with these fields:

• cause — MException object that contains information about the error (since R2024a)

• index — Row or group index at which the error occurred

The remaining input arguments to the error handler are the input arguments for the call to func that made func throw the error.

For example, suppose that func returns two doubles as output arguments. You can specify the error handler as a function that raises a warning and returns two output arguments.

function [A,B] = errorFunc(S,varargin)
    warning(S.cause.identifier,S.cause.message);
    A = NaN;
    B = NaN;
end

In releases before R2024a, the first input argument of the error handler is a structure with these fields:

• identifier — Error identifier

• message — Error message text

• index — Row or group index at which the error occurred

Example: B = rowfun(func,A,ErrorHandler=@errorFunc) specifies errorFunc as the error handler.

Output Arguments

B — Output values

table | timetable | cell array | vector

Output values, returned as a table, timetable, cell array, or vector.

If B is a table or timetable, then it can store metadata such as descriptions, variable units, variable names, and row names. For more information, see the Properties sections of table or timetable.

To return B as a cell array or vector, specify the OutputFormat name-value argument.

More About

Calculations on Groups of Data

In data analysis, you commonly perform calculations on groups of data. For such calculations, you split one or more data variables into groups of data, perform a calculation on each group, and combine the results into one or more output variables. You can specify the groups using one or more grouping variables. The unique values in the grouping variables define the groups that the corresponding values of the data variables belong to.

For example, the diagram shows a simple grouped calculation that splits a 6-by-1 numeric vector into two groups of data, calculates the mean of each group, and then combines the outputs into a 2-by-1 numeric vector. The 6-by-1 grouping variable has two unique values, AB and XYZ.

You can specify grouping variables that have numbers, text, dates and times, categories, or bins.

Extended Capabilities

Thread-Based Environment
Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

Version History

Introduced in R2013b

R2023a: Match output data type to input data type by specifying the OutputFormat name-value argument as "auto"

To return an output whose data type matches the data type of the input, specify the OutputFormat name-value argument as "auto". This value is the default value.