rowfun
Apply function to table or timetable rows
Description
applies
the function B
= rowfun(func
,A
)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.
applies the function B
= rowfun(func
,A
,Name,Value
)func
to each row of the table
A
with additional options specified by one or more
Name,Value
arguments.
For example, you can use the "GroupingVariables"
namevalue 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, A
, with two variables of numeric data.
rng('default')
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 function, plus
, to each row of A
. 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, B
, to the input table, A
.
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 (commaseparated values) file, testScores.csv
, into a table by using the readtable
function. The sample file contains test scores for 10 students who attend two different schools. The output table contains variables that have numeric data and other variables that have text data. One of these variables, School
, has a fixed set of values or categories. These categories denote two groups of students within this table. Convert School
to a categorical variable.
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, use the bounds
function. The bounds
function returns two output arguments, so apply it to scores
by using rowfun
. The output of rowfun
is a new table that has TestMin
and TestMax
variables. In this case, also specify "SeparateInputs"
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 scores
.
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 taken from groups of rows of the input table. The output table has one row for each group.
Read data from a CSV (commaseparated values) file, testScores.csv
, into a table. The file has 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. One way to do that is to 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. The attached supporting function, findNameAtMax
, returns both the highest score and the name of the student who had that score. To apply findNameAtMax
to each group of students, use rowfun
. The rowfun
function is suitable because findNameAtMax
has multiple input arguments (last names and test scores) and also returns multiple output arguments. 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"
function [maxValue,lastName] = findNameAtMax(names,values) % Return maximum value and the last name % from the row at which the maximum value occurred [maxValue,maxIndex] = max(values); lastName = names(maxIndex); end
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 it 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.
The function func
must accept width(A)
inputs. By
default, rowfun
returns the first output of
func
. To return more than one output from
func
, use the "NumOutputs"
or
"OutputVariableNames"
namevalue arguments.
Example: func = @minus;
takes two inputs and subtracts
the second input from the first.
Example: func = @(x,y) x.^2+y.^2;
takes two
inputs and finds the sum of the squares.
A
— Input table
table  timetable
Input table, specified as a table or a timetable.
NameValue Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Namevalue arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: InputVariables=["Var2","Var3"]
uses only the variables named
Var2
and Var3
in A
as
the inputs to func
.
InputVariables
— Specifiers for selecting 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
Specifiers for selecting variables of A
to pass to func
,
specified as "InputVariables"
and a positive integer,
vector of positive integers, string array, character vector, cell array
of character vectors, pattern
scalar, logical vector, or a function
handle.
If you specify "InputVariables"
as a function handle, then it must return a
logical scalar, and rowfun
passes only the variables
in A
where the function returns 1
(true
).
GroupingVariables
— Specifiers for selecting variables of A
to be grouping variables
positive integer  vector of positive integers  string array  character vector  cell array of character vectors  pattern
scalar  logical vector
Specifiers for selecting variables of A
to be
grouping variables, specified as "GroupingVariables"
and a positive integer, vector of positive integers, string array,
character vector, cell array of character vectors, pattern
scalar, or logical vector.
The unique values in the grouping variables specify groups. Rows in
A
where the grouping variables have the same
values belong to the same groups. 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 

Categories 

Bins  Vector of binned values, created by binning a
continuous distribution of numeric,

If any grouping variable contains NaN
s or missing
values (such as NaT
s, undefined
categorical
values, or missing strings), then the
corresponding rows 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
from 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 inputA
that are in each group.
Note: 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 inB
. To returnB
as a table without row times, specify"OutputFormat"
as"table"
.
SeparateInputs
— Indicator for calling func
with separate inputs
true
(default)  false
 1
 0
Indicator for calling func
with separate inputs, specified as
"SeparateInputs"
and either
true
, false
,
1
, or 0
.



For example, if

ExtractCellContents
— Indicator to pass values from cell variables to func
false
(default)  true
 0
 1
Indicator to pass values from cell variables to func
, specified as
"ExtractCellContents"
and either
false
, true
,
0
, or 1
.

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

This is the default behavior. 
OutputVariableNames
— Variable names for outputs of func
character vector  cell array of character vectors  string array
Variable names for outputs of func
, specified as
"OutputVariableNames"
and a character vector,
cell array of character vectors, or string array, with names that are
nonempty and distinct. The number of names must equal the number of
outputs desired from func
.
Furthermore, 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' ... 'Var
where N
'}N
is
the number of variables. You can determine valid MATLAB variable
names using the function isvarname
.
NumOutputs
— Number of outputs from func
0
 positive integer
Number of outputs from func
, specified as "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
"auto"
(default)  "table"
 "timetable"
 "uniform"
 "cell"
Format of B
, specified as
"OutputFormat"
and either the value of
"auto"
, "table"
,
"timetable"
, "uniform"
, or
"cell"
.



If


If





ErrorHandler
— Function to call if func
fails
function handle
Function to call if func
fails, specified as
"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 errorhandling 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
B
— Output values
table  timetable  cell array  vector
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
6by1 numeric vector into two groups of data, calculates the mean of each
group, and then combines the outputs into a 2by1 numeric vector. The
6by1 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
ThreadBased Environment
Run code in the background using MATLAB® backgroundPool
or accelerate code with Parallel Computing Toolbox™ ThreadPool
.
Version History
Introduced in R2013bR2023a: "OutputFormat"
namevalue argument can take
"auto"
as a value
The "OutputFormat"
namevalue argument can take
"auto"
as a value. This value is the default value. It causes
rowfun
to return an output whose data type matches the data
type of the input A
.
See Also
varfun
 cellfun
 structfun
 arrayfun
 isvarname
 findgroups
 splitapply
 groupsummary
 convertvars
 vartype
Open Example
You have a modified version of this example. Do you want to open this example with your edits?
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
 América Latina (Español)
 Canada (English)
 United States (English)
Europe
 Belgium (English)
 Denmark (English)
 Deutschland (Deutsch)
 España (Español)
 Finland (English)
 France (Français)
 Ireland (English)
 Italia (Italiano)
 Luxembourg (English)
 Netherlands (English)
 Norway (English)
 Österreich (Deutsch)
 Portugal (English)
 Sweden (English)
 Switzerland
 United Kingdom (English)