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

varfun

関数をテーブル変数または timetable 変数に適用

構文

B = varfun(func,A)

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

説明

B = varfun(func,A) は、関数 func を table または timetable A の各変数に個別に適用し、結果を table または timetable B で返します。

関数 func は入力引数 を 1 つ取り、この関数が呼び出されるたびに、同じ行数の配列を返さなければなりません。出力引数 B{:,i} の i 番目の変数は func(A{:,i}) と等しくなります。

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

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

たとえば、関数にどの変数を渡すかを指定できます。

例

要素単位関数の適用

すべての要素の二乗を求める要素単位関数を定義し、テーブルの変数に適用します。

数値変数を含むテーブルを定義します。

A = table([0.71;-2.05;-0.35;-0.82;1.57],[0.23;0.12;-0.18;0.23;0.41])

A=5×2 table
    Var1     Var2 
    _____    _____

     0.71     0.23
    -2.05     0.12
    -0.35    -0.18
    -0.82     0.23
     1.57     0.41

入力の二乗を求める無名関数を定義します。

func = @(x) x.^2;

テーブル A のすべての変数に関数を適用します。

B = varfun(func,A)

B=5×2 table
    Fun_Var1    Fun_Var2
    ________    ________

     0.5041      0.0529 
     4.2025      0.0144 
     0.1225      0.0324 
     0.6724      0.0529 
     2.4649      0.1681 

B の変数には、関数と A の変数名に基づいて名前が付けられます。

ベクトルからスカラーを返す関数の適用

5 行 2 列のテーブルで、各変数の平均値を計算します。

数値変数を含むテーブルを定義します。

A = table([0.71;-2.05;-0.35;-0.82;1.57],[0.23;0.12;-0.18;0.23;0.41])

A=5×2 table
    Var1     Var2 
    _____    _____

     0.71     0.23
    -2.05     0.12
    -0.35    -0.18
    -0.82     0.23
     1.57     0.41

入力の平均値を求める無名関数を定義します。

func = @mean;

func は既存の MATLAB® 関数を使用して、演算を定義します。

テーブル A のすべての変数に関数を適用します。

B = varfun(func,A)

B=1×2 table
    mean_Var1    mean_Var2
    _________    _________

     -0.188        0.162  

B は、各変数からの平均値を含むテーブルです。テーブルではなく数値ベクトルを返すには、B = varfun(func,A,'OutputFormat','uniform') を使用します。

変数内のグループへの関数の適用

テーブル A で変数のグループ単位の平均値を計算し、テーブル B の行として返します。

1 つの変数が複数のグループを定義するテーブルを作成します。

A = table({'test2';'test1';'test2';'test3';'test1'},...
    [0.71;-2.05;-0.35;-0.82;1.57],[0.23;0.12;-0.18;0.23;0.41])

A=5×3 table
     Var1      Var2     Var3 
    _______    _____    _____

    'test2'     0.71     0.23
    'test1'    -2.05     0.12
    'test2'    -0.35    -0.18
    'test3'    -0.82     0.23
    'test1'     1.57     0.41

入力の平均値を求める無名関数を定義します。

func = @mean;

func は既存の MATLAB® 関数を使用して、演算を定義します。

Var1 によって定義されるデータのグループごとに、関数を適用します。

B = varfun(func,A,'GroupingVariables','Var1')

B=3×4 table
     Var1      GroupCount    mean_Var2    mean_Var3
    _______    __________    _________    _________

    'test1'        2           -0.24        0.265  
    'test2'        2            0.18        0.025  
    'test3'        1           -0.82         0.23  

B には、そのグループに含まれるテーブル A からのエントリ数を示す GroupCount という変数が含まれます。

timetable 変数内のグループへの関数の適用

サンプル データを含む timetable を作成します。timetable の行時間はグループも定義します。

dt = datetime(2016,1,1)+days([0 1 1 2 3 3])';
A = timetable(dt,[0.71;-2.05;-0.35;-0.82;1.57;0.09],...
              [0.23;0.12;-0.18;0.23;0.41;0.02],...
              'VariableNames',{'x' 'y'})

A=6×2 timetable
             dt               x        y  
    ____________________    _____    _____

    01-Jan-2016 00:00:00     0.71     0.23
    02-Jan-2016 00:00:00    -2.05     0.12
    02-Jan-2016 00:00:00    -0.35    -0.18
    03-Jan-2016 00:00:00    -0.82     0.23
    04-Jan-2016 00:00:00     1.57     0.41
    04-Jan-2016 00:00:00     0.09     0.02

timetable 内の変数のグループ単位での平均を計算します。varfun は、A が timetable であるため、B を timetable として返します。行時間をグループ化変数として指定すると、いずれの変数も別のグループ化変数として指定できません。

B = varfun(@mean,A,'GroupingVariables','dt')

B=4×3 timetable
             dt             GroupCount    mean_x    mean_y
    ____________________    __________    ______    ______

    01-Jan-2016 00:00:00        1          0.71      0.23 
    02-Jan-2016 00:00:00        2          -1.2     -0.03 
    03-Jan-2016 00:00:00        1         -0.82      0.23 
    04-Jan-2016 00:00:00        2          0.83     0.215 

入力引数

func — 関数

関数ハンドル

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

関数 func が入力引数を 1 つ取り、この関数が呼び出されるたびに異なる行数の配列を返す場合、'OutputFormat','cell' 名前と値のペアの引数を使用します。それ以外の場合、func は、同じ行数の配列を返さなければなりません。

例: func = @(x) x.^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' を関数ハンドルとして指定する場合、この関数ハンドルは論理スカラーを返さなければならず、varfun は関数が 1 (true) を返した A 内の変数のみを渡します。

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

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

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

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

A 内でグループ化変数の値が同じ行は、同じグループに属します。varfun は func を各変数全体に適用するのではなく、A の各変数内の行グループごとに適用します。

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

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

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

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

'OutputFormat','uniform' または 'OutputFormat','cell' を指定する場合、出力 B には、グループごとに 1 つの行が存在します。'OutputFormat','table' または 'OutputFormat','timetable' を指定した場合、func からの出力サイズは、各グループに対応する B の行数を決定します。

'OutputFormat' — B の形式

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

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

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

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

関数ハンドル

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

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

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

  identifier	エラー識別子。
  message	エラー メッセージ テキスト。
  index	エラーが発生した変数のインデックス。
  name	エラーが発生した変数の名前。

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

以下に例を示します。

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

出力引数

B — 出力テーブル

テーブル | timetable

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

拡張機能

tall 配列

メモリの許容量を超えるような多数の行を含む配列を計算します。

この関数は tall 配列を制限付きでサポートしています。

• func 入力は常に tall 配列を返さなければなりません。

• 以下の名前と値のペアがサポートされます。

  • 'InputVariables' — 関数ハンドルとして指定できません。

  • 'OutputFormat' — 値は 'uniform'、'table'、'timetable' または 'cell' のみです。

• 入力配列が tall timetable で 'OutputFormat' が 'timetable' の場合、指定した関数は最初の次元のサイズが入力と同じである配列を返さなければなりません。入力関数が mean などのリダクション関数の場合、'OutputFormat' を 'table' として指定します。

詳細については、tall 配列を参照してください。

参考

arrayfun | cellfun | findgroups | groupsummary | rowfun | splitapply | structfun

トピック

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

R2013b で導入