最新のリリースでは、このページがまだ翻訳されていません。 このページの最新版は英語でご覧になれます。

rowfun

table または timetable の行への関数の適用

構文

B = rowfun(func,A)

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

説明

B = rowfun(func,A) は、関数 func を table または timetable A の各行に適用し、結果を table または timetable B に返します。

func は、size(A,2) 入力を受け入れます。

A が timetable で、func が行グループのデータを集約する場合、rowfun は A の各行グループの最初の行時間を B の対応する行時間として割り当てます。B を行時間のないテーブルとして返すには、'OutputFormat' を 'table' として指定します。

B = rowfun(func,A,Name,Value) は、1 つ以上の Name,Value ペア引数で指定された追加のオプションを使用して、関数 func を table A の各行に適用します。

たとえば、関数 func に渡す変数と func の呼び出し方法を指定できます。

例

行に対する単出力の関数の適用

5 行 2 列のテーブル A の各行に関数 hypot を適用して、変数 x と y の間の最短距離を求めます。

数値データの 2 つの変数をもつテーブル A を作成します。

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

A = table(x,y)

A=5×2 table
    x    y 
    _    __

    9     1
    4     5
    3     2
    7     3
    1    10

A の各行に関数 hypot を適用します。関数 hypot は 2 つの入力をとり、1 つの出力を返します。

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

B=5×1 table
      z   
    ______

    9.0554
    6.4031
    3.6056
    7.6158
     10.05

B はテーブルです。

関数の出力 B を入力テーブル A に追加します。

[A B]

ans=5×3 table
    x    y       z   
    _    __    ______

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

行に対する複数出力の関数の適用

幾何ブラウン運動モデルを定義し、パラメーターの範囲に適用します。

以下のコードを含む gbmSim.m という名前のファイルに関数を作成します。

% 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 は、mu と sigma の 2 つの入力 を受け入れ、m、mtrue、s および strue の 4 つの出力を返します。

ブラウン運動モデルに入力するパラメーターを含むテーブル params を定義します。

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 

テーブル params の行に関数 gbmSim を適用します。

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

'OutputVariableNames' の名前と値のペアの引数で指定された 4 つの変数名は、rowfun が 4 つの出力を gbmSim から取得しなければならないことを示します。指定する出力変数名の数を少なくして、gbmSim から返される出力を減らすことができます。

関数の出力 stats を入力 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

行のグループへの関数の適用

テーブル A を作成します。ここで、g はグループ化変数です。

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=15×3 table
    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

無名関数 func を定義して、x と y の平均の差を計算します。

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

グループ化変数 g で定義されたグループ 1、2 および 3 の変数間で平均の差を求めます。

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

B=3×3 table
    g    GroupCount    MeanDiff
    _    __________    ________

    1        3         0.028298
    2        6         0.032569
    3        6         -0.10327

変数 GroupCount は、各グループの A の行数を示します。

入力引数

func — 関数

関数ハンドル

関数。関数ハンドルとして指定します。関数は、ファイルで定義するか、無名関数として定義できます。func が複数の関数ファイルに対応している場合 (つまり、func がオーバーロードされた関数セットを表す場合)、MATLAB^® は入力引数のクラスに基づいて呼び出す関数を決定します。

func は、size(A,2) 個の入力数まで受け入れることができます。既定の設定では、rowfun は func の最初の出力を返します。複数の出力を func から返すには、'NumOutputs' または名前と値のペアの引数 'OutputVariableNames' を使用します。

例: func = @(x,y) x.^2+y.^2; は 2 つの入力をとり、二乗和を求めます。

A — 入力テーブル

テーブル | timetable

入力テーブル。table または timetable として指定します。

名前と値のペアの引数

オプションの Name,Value の引数ペアをコンマ区切りで指定します。Name は引数名で、Value は対応する値です。Name は引用符で囲まなければなりません。Name1,Value1,...,NameN,ValueN のように、複数の名前と値のペアの引数を任意の順序で指定できます。

例: 'InputVariables',2 は、A の 2 番目の変数のみを func への入力として使用します。

'InputVariables' — func に渡す A の変数を選択する指定子

正の整数 | 正の整数のベクトル | 文字ベクトル | 文字ベクトルの cell 配列 | string 配列 | 論理ベクトル | 関数ハンドル

func に渡す A の変数を選択する指定子。'InputVariables' と、正の整数、正の整数のベクトル、文字ベクトル、文字ベクトルの cell 配列、string 配列、logical ベクトル、または関数ハンドルのいずれかで構成されるコンマ区切りのペアとして指定します。

'InputVariables' を関数ハンドルとして指定する場合、この関数ハンドルは論理スカラーを返さなければならず、rowfun は関数が 1 (true) を返した A 内の変数のみを渡します。

'GroupingVariables' — 行のグループを定義する A 内の 1 つ以上の変数

正の整数 | 正の整数のベクトル | 文字ベクトル | 文字ベクトルの cell 配列 | string 配列 | 論理ベクトル

行のグループを定義する A 内の 1 つ以上の変数。'GroupingVariables' と、正の整数、正の整数のベクトル、文字ベクトル、文字ベクトルの cell 配列、string 配列、または logical ベクトルのいずれかで構成されるコンマ区切りのペアとして指定します。

'GroupingVariables' の値はどの table 変数がグループ化変数であるかを指定するもので、そのデータ型を指定するものではありません。グループ化変数は数値として指定するか、categorical、calendarDuration、datetime、duration、logical、または string のデータ型をもつことができます。

A 内で同じグループ化変数をもつ行は同じグループに属します。rowfun は func を A の各行に個別に適用するのではなく、行のグループごとに適用します。出力 B には、グループごとに 1 つの行が含まれます。

いずれかのグループ化変数に NaN または欠損値 (NaT、未定義の categorical 値、欠損 string など) が含まれている場合、それに対応する行はどのグループにも属さず、出力から除外されます。

行ラベルはグループ化変数にすることができます。行ラベルのみ、A 内の 1 つ以上の変数、または行ラベルと変数を同じグループにすることができます。

• A が table の場合、ラベルは行名です。

• A が timetable の場合、ラベルは行時間です。

'SeparateInputs' — 個々の入力で func を呼び出すかどうかを示すインジケーター

true (既定値) | false | 1 | 0

個々の入力で func を呼び出すかどうかを示すインジケーター。'SeparateInputs' と、true、false、1 または 0 で構成されるコンマ区切りのペアとして指定します。

true	func は個々の入力を必要とします。rowfun は、size(A,2) 個の入力、データ変数ごとに 1 つの引数で func を呼び出します。 これは既定の動作です。
false	func は、すべての入力を含む 1 つのベクトルを必要とします。rowfun は A の各行の値を連結して func への入力ベクトルを作成します。

'ExtractCellContents' — セル変数からの値を func に渡すかどうかを示すインジケーター

false (既定値) | true | 0 | 1

セル変数からの値を func に渡すかどうかを示すインジケーター。'ExtractCellContents' と false、true、0 または 1 で構成されるコンマ区切りのペアとして指定します。

true	rowfun は、A の中でデータ型が cell の変数の内容を抽出し、セル自体ではなくその値を func に渡します。 グループ化された計算の場合は、セル変数の各グループ内の値は垂直連結を許可しなければなりません。
false	rowfun は、A の中でデータ型が cell の変数のセルを func に渡します。 これは既定の動作です。

'OutputVariableNames' — func の出力の変数名

文字ベクトル | 文字ベクトルの cell 配列 | string 配列

func の出力の変数名。'OutputVariableNames' と、空ではない一意の名前をもつ文字ベクトル、文字ベクトルの cell 配列、または string 配列で構成されるコンマ区切りのペアとして指定します。名前の数は、意図する func の出力数と等しくなければなりません。

さらに、変数名は有効な MATLAB 識別子でなければなりません。有効な MATLAB 識別子が変数名として使用できない場合、MATLAB は {'Var1' ... 'VarN'} の形式で N 個の文字ベクトルをもつ cell 配列を使用します。ここで、N は変数の数です。関数 isvarname を使用して有効な MATLAB 変数名を確認できます。

'NumOutputs' — func からの出力数

0 | 正の整数

func からの出力数。'NumOutputs' と 0 または正の整数で構成されるコンマ区切りのペアとして指定します。整数は func からの可能な出力数以下でなければなりません。

例: 'NumOutputs',2 によって、rowfun は 2 つの出力を使用して func を呼び出します。

'OutputFormat' — B の形式

'table' (既定値) | 'timetable' | 'uniform' | 'cell'

B の形式。'OutputFormat' と値 'table'、値 'uniform' または値 'cell' で構成されるコンマ区切りのペアとして指定します。

'table'	rowfun は func の出力ごとに 1 つの変数を含むテーブルを返します。グループ化された計算の場合、B にはグループ化変数も含まれます。 'table' では、異なるサイズまたはデータ型の値を返す関数を使用できます。ただし、グループ化が解除された計算の場合、func からの出力はすべて、1 回の呼び出しにつき 1 行ずつでなければなりません。グループ化された計算の場合、func からの出力はすべて同じ行数でなければなりません。 これは既定の出力形式です。
'timetable'	rowfun は A の各変数 (または 'InputVariables' で指定した各変数) に 1 つの変数を含む timetable を返します。グループ化された計算の場合、B にはグループ化変数も含まれます。 rowfun は、A の行時間から B の行時間を作成します。B に割り当てられた行時間が func を使用して実行される計算のコンテキストにおいて意味を成さない場合、出力形式を 'OutputFormat','table' として指定します。 A が timetable の場合、これが既定の出力形式です。
'uniform'	rowfun は、func によって返される値を連結して 1 つのベクトルにします。func からの出力はすべて、同じデータ型のスカラーでなければなりません。
'cell'	rowfun は B を cell 配列として返します。'cell' では、異なるサイズまたはデータ型の値を返す関数を使用できます。

'ErrorHandler' — func が失敗した場合に呼び出す関数

関数ハンドル

func が失敗した場合に呼び出す関数。'ErrorHandler' と関数ハンドルで構成されるコンマ区切りのペアとして指定します。この関数を定義して、エラーを再スローするか、関数 func に対して有効な出力を返すようにします。

MATLAB は、以下の 2 つの入力引数を使用して、指定されたエラー処理関数を呼び出します。

• 構造体には以下のフィールドがあります。

  identifier	エラー識別子。
  message	エラー メッセージ テキスト。
  index	エラーが発生した行またはグループ インデックス。

• エラー発生時の関数 func への入力引数の集合。

以下に例を示します。

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

出力引数

B — 出力テーブル

テーブル | timetable

出力テーブル。table または timetable として返します。B は、説明、変数の単位、変数名、行名などのメタデータを格納できます。詳細については、table または timetable のプロパティの節を参照してください。

参考

arrayfun | cellfun | findgroups | groupsummary | isvarname | splitapply | structfun | varfun

トピック

• テーブルでの計算
• テーブル データ変数の分割と関数の適用
• 無名関数

R2013b で導入