groupfilter

グループによるフィルター処理

構文

G = groupfilter(T,groupvars,method)

G = groupfilter(T,groupvars,groupbins,method)

G = groupfilter(___,datavars)

G = groupfilter(___,"IncludedEdge",LR)

B = groupfilter(A,groupvars,method)

B = groupfilter(A,groupvars,groupbins,method)

B = groupfilter(A,groupvars,groupbins,method,"IncludedEdge",LR)

[B,BG] = groupfilter(A,___)

説明

テーブル データ

G = groupfilter(T,groupvars,method) は、method で指定されたグループ単位のフィルター処理条件を満たす table または timetable T の行を返します。フィルター処理条件 method は、それぞれの非グループ化変数に適用される関数ハンドルです。グループは、同じ一意の値の組み合わせをもつ groupvars の変数の行により定義されます。たとえば、G = groupfilter(T,"Trial",@(x) numel(x) > 5) は、T のデータを Trial 別にグループ化し、試行数が 5 を超えるグループに属する行を保持します。

groupfilter の機能を対話的に使用するには、ライブ スクリプトに [グループ別に計算] タスクを追加します。

G = groupfilter(T,groupvars,groupbins,method) は、グループ化の前にビン化スキーム groupbins に従って groupvars の行をビン化するよう指定します。たとえば、G = groupfilter(T,"SaleDate","year",@(x) numel(x) > 5) は、SaleDate のデータを年別にビン化し、要素数が 5 を超えるビンの行を保持します。

G = groupfilter(___,datavars) は、前述の構文のいずれかについて、フィルター方法を適用する table 変数を指定します。たとえば、G = groupfilter(T,"Trial",@(x) x == max(x),"Height") は、各試行の最大高さに対応する T の行を保持します。

G = groupfilter(___,"IncludedEdge",LR) は、ビンのエッジを "left" または "right" として指定し、ビン区間のいずれの端が含まれるかを示します。groupbins を指定する前述のどの構文でも IncludeEdge を使用できます。

配列データ

B = groupfilter(A,groupvars,method) は、method で指定されたグループ単位のフィルター処理条件を満たすベクトルまたは行列 A の行を返します。フィルター処理条件 method は、すべての列ベクトルに適用される関数ハンドルです。グループは、同じ一意の値の組み合わせをもつ groupvars の列ベクトルの行により定義されます。

groupfilter の機能を対話的に使用するには、ライブ スクリプトに [グループ別に計算] タスクを追加します。

B = groupfilter(A,groupvars,groupbins,method) は、グループ化の前にビン化スキーム groupbins に従って groupvars の行をビン化するよう指定します。

B = groupfilter(A,groupvars,groupbins,method,"IncludedEdge",LR) は、groupbins が指定された場合に各ビンに左右のエッジのいずれを含めるかを指定します。

[B,BG] = groupfilter(A,___) は、B の行に対応する一意のグループ化ベクトルの組み合わせも返します。

例

2 変数テーブルのフィルター処理

2 変数を含む table を作成します。

groupID = [1 1 1 2 2 3]';
sample = [3 1 2 9 8 5]';
T = table(groupID,sample)

T=6×2 table
    groupID    sample
    _______    ______

       1         3   
       1         1   
       1         2   
       2         9   
       2         8   
       3         5   

ID 番号でグループ化し、サンプル数が 2 を超えるグループに対応する行を返します。

Gnumel = groupfilter(T,"groupID",@(x) numel(x) > 2)

Gnumel=3×2 table
    groupID    sample
    _______    ______

       1         3   
       1         1   
       1         2   

グループのサンプル数が 0 ～ 6 である行を返します。

Gvals = groupfilter(T,"groupID",@(x) min(x) > 0 && max(x) < 6)

Gvals=4×2 table
    groupID    sample
    _______    ______

       1         3   
       1         1   
       1         2   
       3         5   

最大値でのグループ化

日番号と温度を表す 2 変数を含む table を作成します。

daynum = [1 1 1 1 2 2 2 2]';
temp = [67 65 71 55 61 79 58 78]';
T = table(daynum,temp)

T=8×2 table
    daynum    temp
    ______    ____

      1        67 
      1        65 
      1        71 
      1        55 
      2        61 
      2        79 
      2        58 
      2        78 

日番号でグループ化し、それぞれの日の最も高い温度 2 値を返します。

G = groupfilter(T,"daynum",@(x) ismember(x,maxk(x,2)))

G=4×2 table
    daynum    temp
    ______    ____

      1        67 
      1        71 
      2        79 
      2        78 

月でのグループ化

日付と、それに対応する利益の table を作成します。

timeStamps = datetime([2017 3 4; 2017 3 2; 2017 3 15; 2017 4 10; ...
                       2017 4 14; 2017 4 30; 2017 5 25; ...
                       2017 5 29; 2017 5 21]);
profit = [2032 3071 1185 2587 1998 2899 3112 909 2619]';
T = table(timeStamps,profit)

T=9×2 table
    timeStamps     profit
    ___________    ______

    04-Mar-2017     2032 
    02-Mar-2017     3071 
    15-Mar-2017     1185 
    10-Apr-2017     2587 
    14-Apr-2017     1998 
    30-Apr-2017     2899 
    25-May-2017     3112 
    29-May-2017      909 
    21-May-2017     2619 

日付を月でグループ化し、その月の最大利益に対応する行を返します。

Gmax = groupfilter(T,"timeStamps","month",@(x) x == max(x))

Gmax=3×3 table
    timeStamps     profit    month_timeStamps
    ___________    ______    ________________

    02-Mar-2017     3071         Mar-2017    
    30-Apr-2017     2899         Apr-2017    
    25-May-2017     3112         May-2017    

平均利益が $2300 を超える月を含む行を返します。

Gavg = groupfilter(T,"timeStamps","month",@(x) mean(x) > 2300)

Gavg=3×3 table
    timeStamps     profit    month_timeStamps
    ___________    ______    ________________

    10-Apr-2017     2587         Apr-2017    
    14-Apr-2017     1998         Apr-2017    
    30-Apr-2017     2899         Apr-2017    

3 変数テーブルのフィルター処理

9 人の個人に関する情報を含む table T を作成します。

groupID = [1 2 3 1 2 3 1 2 3]';
Height = [62 61 59 66 70 72 57 67 71]';
HealthStatus = categorical(["Poor"; "Good"; "Fair"; "Poor"; "Fair"; "Excellent"; "Poor"; "Excellent"; "Fair"]);
T = table(groupID,Height,HealthStatus)

T=9×3 table
    groupID    Height    HealthStatus
    _______    ______    ____________

       1         62       Poor       
       2         61       Good       
       3         59       Fair       
       1         66       Poor       
       2         70       Fair       
       3         72       Excellent  
       1         57       Poor       
       2         67       Excellent  
       3         71       Fair       

ID 番号でグループ化し、身長が 60 以上のメンバーのみを含むグループの行を返します。

G1 = groupfilter(T,"groupID",@(x) min(x) >= 60,"Height")

G1=3×3 table
    groupID    Height    HealthStatus
    _______    ______    ____________

       2         61       Good       
       2         70       Fair       
       2         67       Excellent  

ID 番号でグループ化し、健康状態が Poor のメンバーのみを含むグループの行を返します。

G2 = groupfilter(T,"groupID",@(x) all(x == "Poor"),"HealthStatus")

G2=3×3 table
    groupID    Height    HealthStatus
    _______    ______    ____________

       1         62          Poor    
       1         66          Poor    
       1         57          Poor    

ベクトル データを使用するフィルター処理

日付のベクトルと、対応する利益額のベクトルを作成します。

timeStamps = datetime([2017 3 4; 2017 3 2; 2017 3 15; 2017 3 10; ...
                       2017 3 14; 2017 3 31; 2017 3 25; ...
                       2017 3 29; 2017 3 21; 2017 3 18]);
profit = [2032 3071 1185 2587 1998 2899 3112 909 2619 3085]';

曜日でグループ化し、各グループの最大利益を計算します。最大利益とその対応するグループを表示します。

[maxDailyProfit,dayOfWeek] = groupfilter(profit,timeStamps, ...
    "dayname",@(x) x == max(x))

maxDailyProfit = 5×1

        3071
        1185
        2899
        3112
        2619

dayOfWeek = 5×1 categorical
     Thursday 
     Wednesday 
     Friday 
     Saturday 
     Tuesday 

入力引数

T — 入力 table

table | timetable

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

A — 入力配列

列ベクトル | 行列

入力配列。列ベクトル、または行列として保存された列ベクトルのグループとして指定します。

groupvars — グループ化変数またはベクトル

スカラー | ベクトル | 行列 | cell 配列 | パターン | 関数ハンドル | table vartype 添字

グループ化変数またはベクトル。次のオプションのいずれかとして指定します。

• 配列の入力データの場合、groupvars は A と同じ行数をもつ列ベクトルか、行列内あるいは cell 配列内に配置した列ベクトルのグループのいずれかにすることができます。

• 入力データが table または timetable の場合、groupvars はデータ内のグループの計算にどの変数を使用するかを表します。グループ化変数は、次の表のオプションのいずれかを使用して指定できます。

  インデックス方式	指定する値	例
  変数名	string スカラーまたは文字ベクトル 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 番目の変数
  関数ハンドル	入力として table 変数を取り、logical スカラーを返す関数ハンドル	@isnumeric — 数値を含んでいるすべての変数
  変数の型	指定した型の変数を選択する vartype 添字	vartype("numeric") — 数値を含んでいるすべての変数

例: groupfilter(T,"Var3",method)

method — フィルター方法

関数ハンドル

フィルター方法。関数ハンドルとして指定します。

method は、各グループからメンバーをフィルターで除外するために使用される関数を定義します。この関数は、logical スカラーを返すか、入力データと同じ行数をもち、選択するグループ メンバーを示す logical 列ベクトルを返さなければなりません。

• 関数が logical スカラーを返す場合、グループのすべてのメンバーがフィルターで除外されるか (値が false のとき)、何も除外されません (値が true のとき)。

• 関数が logical ベクトルを返す場合、対応する要素が false であるグループ メンバーがフィルターで除外され、対応する要素が true であるメンバーが保持されます。

関数ハンドルを定義するには、@(inputargs) mymethod の形式の構文を使用します。ここで mymethod は inputargs に依存します。

• 関数は、条件を満たすグループに対応する行でフィルター処理を行うことができます。たとえば、@(x) mean(x) > 10 は、グループ平均が 10 を超えるグループに対応する行のみを出力に渡します。

• 関数は、対応するグループ内で条件を満たす行でフィルター処理を行うことができます。たとえば、@(x) x == max(x) は、グループ内の行の最大値に対応する行のみを出力に渡します。

詳細については、関数ハンドルの作成と無名関数を参照してください。

groupfilter が一度に複数の非グループ化変数にメソッドを適用する場合、メソッドは各変数について logical スカラーまたはベクトルを返します。行を出力に渡すには、各行で、返されるすべてのスカラーまたはベクトルの対応する値が true である必要があります。

groupbins — グループ化変数またはベクトルのビン化スキーム

"none" (既定値) | ビンのエッジのベクトル | ビンの数 | 時間の長さ (ビンの幅) | 時間単位の名前 (ビンの幅) | ビン化方法の cell 配列

グループ化変数またはベクトルのビン化スキーム。以下の 1 つ以上のビン化方法として指定します。グループ化変数またはベクトルとビン化スキーム引数は同じサイズでなければなりませんが、いずれかをスカラーにすることもできます。

• "none" — ビン化なし。

• ビンのエッジのベクトル — ビンのエッジはビンを定義します。エッジは、数値として指定するか、datetime グループ化変数またはベクトルの datetime 値として指定できます。

• ビンの数 — この数字は、作成する等間隔のビンの数を決定します。ビンの数を正の整数スカラーとして指定できます。

• 時間の長さ (ビンの幅) — この時間の長さは各ビンの幅を決定します。ビンの幅は、datetime または duration グループ化変数またはベクトルの duration または calendarDuration スカラーとして指定できます。

• 時間単位の名前 (ビンの幅) — この時間単位の名前は各ビンの幅を決定します。ビンの幅は、datetime または duration グループ化変数またはベクトルについての以下の表のいずれかのオプションとして指定できます。

  値	説明	データ型
  "second"	各ビンは 1 秒です。	datetime と duration
  "minute"	各ビンは 1 分です。	datetime と duration
  "hour"	各ビンは 1 時間です。	datetime と duration
  "day"	各ビンは 1 カレンダー日です。この値には、夏時間のシフトが考慮されます。	datetime と duration
  "week"	各ビンは 1 カレンダー週です。	datetime のみ
  "month"	各ビンは 1 カレンダー月です。	datetime のみ
  "quarter"	各ビンは 1 カレンダー四半期です。	datetime のみ
  "year"	各ビンは 1 カレンダー年です。この値には、うるう日が考慮されます。	datetime と duration
  "decade"	各ビンは 10 年 (10 カレンダー年) です。	datetime のみ
  "century"	各ビンは 1 世紀 (100 カレンダー年) です。	datetime のみ
  "secondofminute"	ビンは 0 から 59 までの秒です。	datetime のみ
  "minuteofhour"	ビンは 0 から 59 までの分です。	datetime のみ
  "hourofday"	ビンは 0 から 23 までの時間です。	datetime のみ
  "dayofweek"	ビンは 1 から 7 までの曜日です。週の始まりは日曜日です。	datetime のみ
  "dayname"	ビンは "Sunday" などの完全な曜日名です。	datetime のみ
  "dayofmonth"	ビンは 1 から 31 までの日です。	datetime のみ
  "dayofyear"	ビンは 1 から 366 までの日です。	datetime のみ
  "weekofmonth"	ビンは 1 から 6 までの週です。	datetime のみ
  "weekofyear"	ビンは 1 から 54 までの週です。	datetime のみ
  "monthname"	ビンは "January" などの完全な月名です。	datetime のみ
  "monthofyear"	ビンは 1 から 12 までの月です。	datetime のみ
  "quarterofyear"	ビンは 1 から 4 までの四半期です。	datetime のみ

datavars — 演算の対象とする table 変数

スカラー | ベクトル | cell 配列 | パターン | 関数ハンドル | table vartype 添字

演算の対象とする table 変数。次の表のオプションのいずれかとして指定します。datavars は、フィルター方法を適用する入力 table または timetable の変数を示します。datavars で指定されていないその他の変数は、演算されずに出力に渡されます。groupfilter はフィルター方法を指定した変数に適用し、その結果を使用してすべての変数から行を削除します。datavars が指定されない場合、groupfilter はそれぞれの非グループ化変数を処理します。

インデックス方式	指定する値	例
変数名	string スカラーまたは文字ベクトル 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 番目の変数
関数ハンドル	入力として table 変数を取り、logical スカラーを返す関数ハンドル	@isnumeric — 数値を含んでいるすべての変数
変数の型	指定した型の変数を選択する vartype 添字	vartype("numeric") — 数値を含んでいるすべての変数

例: groupfilter(T,groupvars,method,["Var1" "Var2" "Var4"])

LR — ビン化スキームに含めるビン エッジ

"left" (既定値) | "right"

ビン化スキームに含めるビン エッジ。"left" または "right" のいずれかとして指定し、ビン区間のどちらの端が含まれるかを示します。

LR を指定できるのは、groupbins も指定し、かつその値がすべてのグループ化変数またはベクトルのすべてのビン化方法に適用される場合のみです。

出力引数

G — 出力テーブル

table | timetable

table または timetable 入力データの出力 table。table または timetable として返されます。G には、グループ単位のフィルター方法を満たす T の行が含まれます。

B — 出力配列

ベクトル | 行列

配列の入力データの出力配列。ベクトルまたは行列として返されます。B には、グループ単位のフィルター方法を満たす A の行が含まれます。

BG — グループ化ベクトル

列ベクトル | 列ベクトルの cell 配列

配列の入力データのグループ化ベクトル。列ベクトル、または列ベクトルの cell 配列として返されます。BG には、B の行に対応する一意のグループ化ベクトルまたはビン化されたグループ化ベクトルの組み合わせが含まれます。

代替機能

ライブ エディター タスク

groupfilter の機能を対話的に使用するには、ライブ スクリプトに [グループ別に計算] タスクを追加します。

拡張機能

tall 配列

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

groupfilter 関数は tall 配列をサポートしていますが、以下の使用上の注意および制限があります。

• A と groupvars が両方とも tall 行列の場合、その行数は同じでなければなりません。

• 最初の入力が tall 行列の場合、groupvars を tall グループ化ベクトルを含む cell 配列にすることができます。

• 引数 groupvars と引数 datavars は関数ハンドルをサポートしていません。

• 引数 method は、tall 配列を扱う splitapply の有効な入力でなければなりません。

• 離散化された datetime 配列によってグループ化する場合、カテゴリのグループ名はインメモリ groupfilter 計算と比べ異なっています。

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

C/C++ コード生成

MATLAB® Coder™ を使用して C および C++ コードを生成します。

使用上の注意および制限:

• スパース入力はサポートされません。

• datetime データと duration データの場合、ビン化スキームはサポートされません。

• 多次元配列が含まれる入力 table はサポートされません。

• 計算メソッドは定数でなければなりません。

• 最初の入力引数が table である場合、グループ化変数は定数でなければなりません。

• データ変数は定数でなければなりません。

• 文字ベクトルまたは string として指定するビン化スキームは定数でなければなりません。

• 名前と値の引数は定数でなければなりません。

• 計算メソッドはスパースまたは多次元の結果を返すことはできません。

スレッドベースの環境

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

この関数はスレッドベースの環境を完全にサポートしています。詳細については、スレッドベースの環境での MATLAB 関数の実行を参照してください。

バージョン履歴

R2019b で導入

R2024a: グループ化変数に複数のビン化方法を適用

ビン化方法の cell 配列を指定して、1 つのグループ化変数またはベクトルに複数のビン化方法を適用します。

R2022b: コード生成のサポート

関数 groupfilter の C または C++ コードを生成します。使用上の注意事項および制限事項については、C/C++ コード生成を参照してください。

R2022a: グループ サイズが小さい場合のパフォーマンスが向上

関数 groupfilter は、特に各グループのデータ数が少ない場合に、パフォーマンスが向上しています。

たとえば、次のコードでは、それぞれ 10 カウントの 500 のグループをもつ行列をグループ別にフィルター処理しています。直前のリリースと比較して、このコードは約 2.32 倍速くなっています。

function timingGroupfilter
data = (1:5000)';
groups = repelem(1:length(data)/10,10)';
p = randperm(length(data));
data = data(p);
groups = groups(p);

tic
for k = 1:600
   G = groupfilter(data,groups,@(x) x == max(x));
end
toc
end

おおよその実行時間は以下のとおりです。

R2021b: 2.32 秒

R2022a: 1.00 秒

このコードの時間測定では、Windows^® 10、Intel^® Xeon^® CPU E5-1650 v4 @ 3.60 GHz を使用するテスト システムで、関数 timingGroupfilter を呼び出しました。

参考

関数

• groupsummary | groupcounts | grouptransform | findgroups | splitapply | discretize | varfun | rowfun

ライブ エディター タスク

• グループ別に計算

トピック

• table でのグループ別の計算の実行
• table でのデータの整理と計算
• table と timetable でのグループ化された計算