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.
specifies options using one or more name-value arguments. For example, you can use
the B
= rowfun(func
,A
,Name,Value
)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 whenrowfun
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 specifyfunc
as@idivide
, thenrowfun
callsidivide
using theidivide(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, specifyfunc
as@(x,y) idivide(x,y,"ceil")
.To return more than one output from
func
, use theNumOutputs
orOutputVariableNames
name-value arguments. In that case, the outputB
has multiple variables, one for each output offunc
.If
func
returns an array with a different number of rows each time it is called, then specify theOutputFormat
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, iffunc
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:
|
|
Variable index:
|
|
Function handle:
|
|
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:
|
|
Variable index:
|
|
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 |
|
Categories |
|
Bins | Vector of binned values, created by binning a
continuous distribution of numeric,
|
Many data types have ways to represent missing values, such as
NaN
s, NaT
s, 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.
To include rows where the grouping variables have missing values,
consider using the groupsummary
function instead.
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 toVariables corresponding to the grouping variables
A new variable,
GroupCount
, whose values are the number of rows of the inputA
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 inB
. To returnB
as a table without row times, specifyOutputFormat
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
istrue
, thenfunc
expects separate inputs.rowfun
callsfunc
withwidth(A)
inputs, one argument for each data variable.If
SeparateInputs
isfalse
, thenfunc
expects one argument containing all inputs.rowfun
creates the input argument tofunc
by concatenating the values in each row ofA
.For example, if
A
is a table that has three variables, and each variable is a numeric vector, then specifyingSeparateInputs
asfalse
causesrowfun
to concatenate the three numeric vectors into one numeric matrix. The matrix has three columns. Thenrowfun
passes that matrix as one input argument tofunc
.
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
istrue
, thenrowfun
extracts the contents of a variable inA
whose data type iscell
and passes the values, rather than the cells, tofunc
.For grouped calculations, the values within each group in a cell variable must allow vertical concatenation.
If
ExtractCellContents
isfalse
, thenrowfun
passes the cells of a variable inA
whose data type iscell
tofunc
.
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' ...
'Var
, where
N
'}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.
|
|
|
If
|
|
If
|
|
|
|
|
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 identifiermessage
— Error message textindex
— 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 R2013bR2023a: 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.
See Also
varfun
| cellfun
| structfun
| arrayfun
| isvarname
| findgroups
| splitapply
| groupsummary
| convertvars
| vartype
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)
Asia Pacific
- Australia (English)
- India (English)
- New Zealand (English)
- 中国
- 日本Japanese (日本語)
- 한국Korean (한국어)