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 が受け入れる入力の数は、A の変数の数と等しくなければなりません。たとえば、2 つの入力引数を指定して func を呼び出す必要がある場合、A は 2 つの変数をもつ必要があります。table 内の変数の数を確認するには、関数 width を使用します。

B = rowfun(func,A,Name,Value) は、1 つ以上の名前と値の引数を使用してオプションを指定します。たとえば、名前と値の引数 GroupingVariables を使用して、行のグループに対して計算を実行できます。データのグループに対する計算の詳細については、データ グループに対する計算を参照してください。

例

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

数値データの 2 つの変数をもつ table を作成します。

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

table の各行に関数 plus を適用します。関数呼び出し plus(X,Y) は、演算 X + Y と等価です。関数 plus は 2 つの入力を受け入れ、1 つの出力を返します。rowfun への入力引数として関数を指定するには、@ 記号を使用します。

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

B=5×1 table
    Sum
    ___

    10 
    13 
     8 
    20 
    17 

出力 table を入力 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 

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

複数の出力を返す関数を table の行に適用します。関数 rowfun は、適用された関数の各出力を出力 table の変数内に格納します。

CSV (コンマ区切り値) ファイルから table にデータを読み取ります。このサンプル ファイルには、2 つの異なる学校の生徒の 10 人分のテストの得点が含まれています。

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  

各行のテストの最低点と最高点を求めるには、関数 bounds を適用します。関数 bounds は 2 つの出力引数を返します。rowfun の出力は、変数 TestMin と変数 TestMax をもつ新しい table です。この場合、さらに名前と値の引数 SeparateInputs を false と指定して、各行の値が 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   

最小値と最大値を入力 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   

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

入力 table の行のグループのデータに関数を適用します。出力 table には、グループごとに 1 つの行が含まれます。

CSV ファイルから table にデータを読み取ります。このサンプル ファイルには、2 つの異なる学校の生徒の 10 人分のテストの得点が含まれています。

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  

各生徒のテストの平均点を計算し、新しい table 変数として追加します。テストの得点の数値を抽出し、2 番目の次元に沿って平均を計算できます。結果として、新しい変数として scores に付加できる列ベクトルが得られます。

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 

各学校でテストの平均点が最も高い生徒を求めます。この例の最後で定義されている補助関数 findNameAtMax を適用します。この補助関数は、複数の入力引数 (姓とテストの得点) を受け取り、複数の出力引数 (最高点と姓) を返します。出力 table 内の変数 GroupCount は、各学校の scores 内の行数を示しています。

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"  

補助関数

補助関数 findNameAtMax は次のコードで定義されます。

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

適用される関数にオプション引数を渡す

関数を適用するときにオプション引数を渡すには、関数呼び出しを無名関数でラップします。

整数の配列である 2 つの変数をもつ table を作成します。

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

関数 idivide を適用して、2 つの table 変数の整数の除算を実行します。

B = rowfun(@idivide,A)

B=5×1 table
    Var1
    ____

     9  
     3  
     0  
     1  
     0  

関数 idivide には、結果を丸めるためのオプションが複数あります。既定の丸めオプションは "fix" です。別の丸めオプションを idivide で使用するには、そのオプションを指定する呼び出しを無名関数でラップします。たとえば、"ceil" を丸めオプションとして指定します。

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

無名関数を適用して、"ceil" で整数の除算を実行します。

C = rowfun(func,A)

C=5×1 table
    Var1
    ____

     9  
     4  
     1  
     1  
     1  

入力引数

func — 関数

関数ハンドル

関数。関数ハンドルとして指定します。既存の関数のハンドルを指定するか、ファイルで関数を定義するか、無名関数を指定できます。関数は N 個の入力引数を受け取ります。ここで、N = width(A) であり、構文は次の形式でなければなりません。

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

A の行に対して f を呼び出すには、次のように rowfun の呼び出しで func を指定します。

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

rowfun は、A の行ごとに、その行に対して func を呼び出し、func の出力を B の対応する行に割り当てます。出力 B に含まれる変数は 1 つです。

追加の考慮事項を次にいくつか示します。

• func が表す関数には、追加のオプション引数をもつ構文がほかにも含まれる場合があります。ただし、rowfun が関数を呼び出すときは、該当する数の入力引数をもつ構文を呼び出します。

  たとえば、関数 idivide には 3 番目のオプション引数を指定する構文があります。ただし、func を @idivide として指定した場合、rowfun は idivide(arg1,arg2) 構文を使用して idivide を呼び出します。

• オプション引数をもつ関数を呼び出すには、無名関数でラップします。たとえば、"ceil" オプションを指定した idivide を呼び出すには、func を @(x,y) idivide(x,y,"ceil") として指定します。

• 複数の出力を func から返すには、名前と値の引数 NumOutputs または OutputVariableNames を使用します。その場合、func の出力ごとに 1 つずつ、複数の変数が出力 B に含まれます。

• func が呼び出されるたびに異なる行数の配列を返す場合、名前と値の引数 OutputFormat を "cell" として指定します。それ以外の場合、func は呼び出されるたびに同じ行数の配列を返さなければなりません。

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

例: B = rowfun(@idivide,A) は、整数の除算を実行します。A は 2 つの変数を含む table で、どちらの変数も整数クラスに属します。B は 1 つの変数を含む table になります。

例: B = rowfun(@(x,y) x.^2+y.^2,A) は、A の 2 つの変数の二乗和を計算します。

例: B = rowfun(@(x,y) idivide(x,y,"ceil"),A) は、"ceil" オプションを指定した関数 idivide を適用して整数の除算を実行します。

A — 入力テーブル

table | timetable

入力 table。table または timetable として指定します。

名前と値の引数

引数のオプションのペアを Name1=Value1,...,NameN=ValueN として指定します。ここで Name は引数名で、Value は対応する値です。名前と値の引数は他の引数の後になければなりませんが、ペアの順序は重要ではありません。

例: B = rowfun(func,A,InputVariables=["Var2","Var3"]) は、A の Var2 および Var3 という名前の変数のみを func への入力として使用します。

R2021a より前では、コンマを使用してそれぞれの名前と値を区切り、Name を引用符で囲みます。

例: B = rowfun(func,A,"InputVariables",["Var2","Var3"]) は、A の Var2 および Var3 という名前の変数のみを func への入力として使用します。

InputVariables — func に渡す A の変数

正の整数 | 正の整数のベクトル | string 配列 | 文字ベクトル | 文字ベクトルの cell 配列 | pattern スカラー | logical ベクトル | 関数ハンドル

func に渡す A の変数。次の表のインデックス方式のいずれかを使用して指定します。

インデックス方式	例
変数名: string 配列、文字ベクトル、または文字ベクトルの cell 配列 pattern オブジェクト	"A" または 'A' — A という名前の変数 ["A","B"] または {'A','B'} — A および B という名前の 2 つの変数 "Var"+digitsPattern(1) — "Var" の後に数字 1 桁が続く名前の変数
変数インデックス: table 内の変数の位置を参照するインデックス番号 数値のベクトル logical ベクトル。通常、このベクトルの長さは変数の数と同じですが、末尾の 0 値や false 値は省略できます。	3 — table の 3 番目の変数 [2 3] — table の 2 番目と 3 番目の変数 [false false true] — 3 番目の変数
関数ハンドル: 1 つの引数を入力として受け取り logical スカラーを返す関数のハンドル。関数の構文は次の形式でなければなりません。 tf = f(arg) 追加のオプション引数をもつ関数を適用する必要がある場合は、無名関数でラップします。	@isnumeric — 数値を含む入力引数に対して true を返す関数のハンドル

例: B = rowfun(func,A,InputVariables=[1 3 4]) は、A の 1 番目、3 番目、および 4 番目の変数のみを func への入力として使用します。

例: B = rowfun(func,A,InputVariables=@isnumeric) は、A の数値変数のみを func への入力として使用します。

GroupingVariables — グループ化変数として使用する A の変数

正の整数 | 正の整数のベクトル | string 配列 | 文字ベクトル | 文字ベクトルの cell 配列 | pattern スカラー | logical ベクトル

グループ化変数として使用する A の変数。次の表のインデックス方式のいずれかを使用して指定します。

インデックス方式	例
変数名: string 配列、文字ベクトル、または文字ベクトルの cell 配列 pattern オブジェクト	"A" または 'A' — A という名前の変数 ["A","B"] または {'A','B'} — A および B という名前の 2 つの変数 "Var"+digitsPattern(1) — "Var" の後に数字 1 桁が続く名前の変数
変数インデックス: table 内の変数の位置を参照するインデックス番号 数値のベクトル logical ベクトル。通常、このベクトルの長さは変数の数と同じですが、末尾の 0 値や false 値は省略できます。	3 — table の 3 番目の変数 [2 3] — table の 2 番目と 3 番目の変数 [false false true] — 3 番目の変数

グループ化変数の一意の値によってグループが定義されます。A 内の行は、グループ化変数の値が同じであれば、同じグループに属します。rowfun は func を A の各行に個別に適用するのではなく、行のグループごとに適用します。出力 B には、グループごとに 1 つの行が含まれます。グループ化変数を使用した計算の詳細については、データ グループに対する計算を参照してください。

グループ化変数は、表にリストされているデータ型のいずれかにすることができます。

グループを指定する値	グループ化変数のデータ型
数字	数値または logical ベクトル
テキスト	string 配列または文字ベクトルの cell 配列
日付と時刻	datetime、duration または calendarDuration ベクトル
カテゴリ	categorical ベクトル
ビン	ビン化された値のベクトル。数値、datetime または duration 値の連続分布をビン化することによって作成される

多くのデータ型には、NaN、NaT、未定義の categorical 値、欠損 string など、欠損値を表現する方法があります。いずれかのグループ化変数に欠損値を表現できるデータ型が含まれている場合、そのグループ化変数で欠損値が発生する行はどのグループにも属さず、出力から除外されます。

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

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

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

出力 B には、入力 A の行のグループごとに 1 つの行があります。B が table または timetable の場合、B は以下をもちます。

• func が適用された入力 table 変数に対応する変数

• グループ化変数に対応する変数

• 各グループ内の入力 A の行数を値とする新しい変数 GroupCount

B が timetable の場合、B は以下ももちます。

• 行時間。A の各行グループの最初の行時間が、B の対応する行時間です。B を行時間のない table として返すには、OutputFormat を "table" として指定します。

例: B = rowfun(func,A,GroupingVariables="Var3") は、A の Var3 という名前の変数をグループ化変数として使用します。

例: B = rowfun(func,A,GroupingVariables=["Var3","Var4"]) は、A の Var3 および Var4 という名前の変数をグループ化変数として使用します。

例: B = rowfun(func,A,GroupingVariables=[3 4]) は、A の 3 番目および 4 番目の変数をグループ化変数として使用します。

SeparateInputs — 個々の入力で func を呼び出すオプション

true または 1 (既定値) | false または 0

個々の入力で func を呼び出すオプション。数値または logical 1 (true) または 0 (false) として指定します。

• SeparateInputs が true の場合、func は個々の入力を必要とします。rowfun は、データ変数ごとに引数を 1 つずつ、width(A) 個の入力を指定して func を呼び出します。

• SeparateInputs が false の場合、func は、すべての入力を含む 1 つの引数を必要とします。rowfun は A の各行の値を連結して func への入力引数を作成します。

  たとえば、A が 3 つの変数をもつ table であり、各変数が数値ベクトルの場合、SeparateInputs を false として指定すると、rowfun は 3 つの数値ベクトルを 1 つの数値行列に連結します。行列には 3 つの列があります。その後、rowfun はその行列を 1 つの入力引数として func に渡します。

例: B = rowfun(@mean,A,SeparateInputs=false) は、A の各行を mean に渡すベクトルとして扱えるように、N 個の table 変数の内容を 1 つの配列の列であるかのように扱います。

ExtractCellContents — cell 変数からの値を func に渡すオプション

false または 0 (既定値) | true または 1

cell 変数からの値を func に渡すオプション。数値または logical 0 (false) または 1 (true) として指定します。

• ExtractCellContents が true の場合、rowfun は、A の中でデータ型が cell の変数の内容を抽出し、cell 自体ではなくその値を func に渡します。

  グループ化された計算の場合は、cell 変数の各グループ内の値は垂直連結を許可しなければなりません。

• ExtractCellContents が false の場合、rowfun は、A の中でデータ型が cell の変数の cell を func に渡します。

例: B = rowfun(func,A,ExtractCellContents=true) は、cell 配列の変数から cell の内容を抽出します。

OutputVariableNames — func の出力の変数名

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

func の出力の変数名。空でない一意の名前をもつ string 配列、文字ベクトル、または文字ベクトルの cell 配列として指定します。名前の数は func の出力数と等しくなければなりません。

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

例: B = rowfun(func,A,OutputVariableNames=["V1","V2"]) は、V1 および V2 という名前の 2 つの変数を含む出力 table を返します。

NumOutputs — func からの出力数

非負の整数

func からの出力数。非負の整数として指定します。整数は func からの可能な出力数以下でなければなりません。

例: B = rowfun(func,A,NumOutputs=2) は、func から 2 つの出力を返します。

OutputFormat — B の形式

"auto" (既定値) | "table" | "timetable" | "uniform" | "cell"

B の形式。次の表のいずれかの値として指定します。

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

例: B = rowfun(func,A,OutputFormat="uniform") は、出力をベクトルとして返します。

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

関数ハンドル

func が失敗した場合に呼び出す関数。関数ハンドルとして指定します。func がエラーをスローした場合、ErrorHandler で指定されたエラー ハンドラー関数がエラーをキャッチし、その関数に指定されたアクションを実行します。エラー ハンドラーはエラーをスローするか、または func と同じ出力数を返さなければなりません。

ErrorHandler を指定しない場合、rowfun は func からキャッチしたエラーを再スローします。

エラー ハンドラーの最初の入力引数は、次のフィールドをもつ構造体です。

• cause — エラーについての情報を含む MException オブジェクト (R2024a 以降)

• index — エラーが発生した行またはグループのインデックス

エラー ハンドラーの残りの入力引数は、func がエラーをスローした原因である func の呼び出しの入力引数です。

たとえば、func が出力引数として 2 つの double を返すとします。エラー ハンドラーとして、警告を発行して 2 つの出力引数を返す関数を指定できます。

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

R2024a より前のリリースでは、エラー ハンドラーの最初の入力引数は次のフィールドをもつ構造体です。

• identifier — エラー識別子

• message — エラー メッセージ テキスト

• index — エラーが発生した行またはグループのインデックス

例: B = rowfun(func,A,ErrorHandler=@errorFunc) は、errorFunc をエラー ハンドラーとして指定します。

出力引数

B — 出力値

table | timetable | cell 配列 | ベクトル

出力値。table、timetable、cell 配列、またはベクトルとして返されます。

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

B を cell 配列またはベクトルとして返すには、名前と値の引数 OutputFormat を指定します。

詳細

データ グループに対する計算

データ解析では、データ グループに対して計算を実行するのが一般的です。このような計算では、1 つ以上のデータ変数をデータ グループに分割し、各グループに対して計算を実行し、結果を 1 つ以上の出力変数に結合します。1 つ以上の "グループ化変数" を使用してグループを指定できます。グループ化変数の一意の値は、データ変数の対応する値が属するグループを定義します。

たとえばこの図は、6 行 1 列の数値ベクトルを 2 つのデータ グループに分け、各グループの平均を計算し、その出力を 2 行 1 列の数値ベクトルにまとめる単純なグループ化計算を示しています。6 行 1 列のグループ化変数には、AB と XYZ の 2 つの一意の値があります。

数値、テキスト、日時、カテゴリ、またはビンをもつグループ化変数を指定できます。

拡張機能

スレッドベースの環境
MATLAB® の backgroundPool を使用してバックグラウンドでコードを実行するか、Parallel Computing Toolbox™ の ThreadPool を使用してコードを高速化します。

バージョン履歴

R2013b で導入

R2023a: 名前と値の引数 OutputFormat を "auto" として指定して出力データ型を入力データ型と一致させる

データ型が入力のデータ型と一致する出力を返すには、名前と値の引数 OutputFormat を "auto" として指定します。この値は既定値です。

参考

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

トピック

• table に数値データと非数値データの両方が含まれている場合の計算
• 無名関数
• table でのグループ別の計算の実行
• Summarize or Pivot Data in Tables Using Groups
• table でのデータの整理と計算
• table と timetable でのグループ化された計算