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
.
func
accepts size(A,2)
inputs.
If A
is a timetable and func
aggregates
data over groups of rows, then rowfun
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'
.
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
pair
arguments.
For example, you can specify which variables to pass to the
function func
and how to call func
.
Examples
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.
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, hypot
, to each row of A
. The function hypot
takes two inputs and returns one output.
B = rowfun(@hypot,A,'OutputVariableNames','z')
B=5×1 table
z
______
9.0554
10.44
6.3246
14.142
12.207
B
is a table.
Append the function output, B
, to the input table, A
.
[A B]
ans=5×3 table
x y z
__ __ ______
9 1 9.0554
10 3 10.44
2 6 6.3246
10 10 14.142
7 10 12.207
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.
% Copyright 2015 The MathWorks, Inc. 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); end
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 = 5x2 table 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 = 5x4 table 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 four variable names specified by the 'OutputVariableNames'
name-value pair argument indicate that rowfun
should obtain four 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 = 5x6 table 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.
rng('default')
g = randi(3,[15,1]);
x = rand([15,1]);
y = rand([15,1]);
A = table(g,x,y)
A=15×3 table
g x y
_ ________ ________
3 0.14189 0.70605
3 0.42176 0.031833
1 0.91574 0.27692
3 0.79221 0.046171
2 0.95949 0.097132
1 0.65574 0.82346
1 0.035712 0.69483
2 0.84913 0.3171
3 0.93399 0.95022
3 0.67874 0.034446
1 0.75774 0.43874
3 0.74313 0.38156
3 0.39223 0.76552
2 0.65548 0.7952
3 0.17119 0.18687
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=3×3 table
g GroupCount MeanDiff
_ __________ ________
1 4 0.032744
2 3 0.41822
3 8 0.14656
The variable GroupCount
indicates the number of rows in A
for each group.
Input Arguments
func
— Function
function 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 table
table | timetable
Input table, specified as a table or a 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.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: 'InputVariables',2
uses only the
second variable in A
as an input 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 the comma-separated pair consisting of
'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
— One or more variables in A
that define groups of rows
positive integer | vector of positive integers | string array | character vector | cell array of character vectors | pattern
scalar | 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, string array, character vector, cell array
of character vectors, pattern
scalar, or logical vector.
The value of 'GroupingVariables'
specifies which
table variables are the grouping variables, not their data types. A
grouping variable can be numeric, or have data type
categorical
, calendarDuration
,
datetime
, duration
,
logical
, or string
.
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.
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 you specify
'OutputFormat','uniform'
or'OutputFormat','cell'
, then the output has one or more columns corresponding to the input table variables thatfunc
was applied to.If you specify
'OutputFormat','table'
or'OutputFormat','timetable'
, then the output has:One or more 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.
SeparateInputs
— Indicator for calling func
with separate inputs
true
(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
.
|
This is the default behavior. |
|
|
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 the comma-separated pair consisting of 'ExtractCellContents'
and
either false
, true
, 0
,
or 1
.
|
For grouped computation, 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 the comma-separated pair
consisting of '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
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
'auto'
(default) | 'table'
| 'timetable'
| 'uniform'
| 'cell'
Format of B
, specified as the comma-separated pair
consisting of '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 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
Version History
Introduced in R2013bR2023a: 'OutputFormat'
name-value argument can take 'auto'
as a value
The 'OutputFormat'
name-value 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
Apri esempio
Si dispone di una versione modificata di questo esempio. Desideri aprire questo esempio con le tue modifiche?
Comando MATLAB
Hai fatto clic su un collegamento che corrisponde a questo comando MATLAB:
Esegui il comando inserendolo nella finestra di comando MATLAB. I browser web non supportano i comandi MATLAB.
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)