grouptransform

グループごとの変換

構文

G = grouptransform(T,groupvars,method)

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

G = grouptransform(___,datavars)

G = grouptransform(___,Name,Value)

B = grouptransform(A,groupvars,method)

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

B = grouptransform(___,Name,Value)

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

説明

テーブル データ

G = grouptransform(T,groupvars,method) は、table または timetable T の非グループ化変数の代わりに変換後のデータを返します。method のグループ単位の計算がそれぞれの非グループ化変数に適用されます。グループは、同じ一意の値の組み合わせをもつ groupvars の変数の行により定義されます。たとえば、G = grouptransform(T,"HealthStatus","norm") は 2 ノルムを使用して、T のデータを健康状態を基準として正規化します。

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

G = grouptransform(T,groupvars,groupbins,method) は、グループ化の前にビン化スキーム groupbins に従って groupvars の行をビン化するよう指定し、そのビンを出力 table に追加変数として追加します。たとえば、G = grouptransform(T,"SaleDate","year","rescale") は販売年を基準にビン化し、T のデータを [0, 1] の範囲でスケーリングします。

G = grouptransform(___,datavars) は、前述の構文のいずれかについて、方法を適用する table 変数を指定します。

G = grouptransform(___,Name,Value) は、前述の任意の構文について名前と値の引数を 1 つ以上使用して、追加のプロパティを指定します。たとえば、G = grouptransform(T,"Temp","linearfill","ReplaceValues",false) は、非グループ化変数を置き換えず、埋め込みデータを T の追加変数として追加します。

配列データ

B = grouptransform(A,groupvars,method) は、入力ベクトルまたは行列 A の列ベクトルの代わりに変換後のデータを返します。method のグループ単位の計算が A のすべての列ベクトルに適用されます。グループは、同じ一意の値の組み合わせをもつ groupvars の列ベクトルの行により定義されます。

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

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

B = grouptransform(___,Name,Value) は、入力配列についての前述の構文のいずれかについて、名前と値の引数を 1 つ以上使用して、追加のプロパティを指定します。

[B,BG] = grouptransform(A,___) は、B の行に対応するグループ化ベクトルまたはビン化されたグループ化ベクトルの値も返します。

例

グループ別に欠損データを埋める

3 チームの進捗ステータスが含まれる timetable を作成します。

timeStamp = days([1 1 1 2 2 2 3 3 3]');
teamNumber = [1 2 3 1 2 3 1 2 3]';
percentComplete = [14.2 28.1 11.5 NaN NaN 19.3 46.1 51.2 30.3]';
T = timetable(timeStamp,teamNumber,percentComplete)

T=9×2 timetable
    timeStamp    teamNumber    percentComplete
    _________    __________    _______________

    1 day            1              14.2      
    1 day            2              28.1      
    1 day            3              11.5      
    2 days           1               NaN      
    2 days           2               NaN      
    2 days           3              19.3      
    3 days           1              46.1      
    3 days           2              51.2      
    3 days           3              30.3      

線形内挿を使用して、各チームの欠損したステータスのパーセンテージ (NaN で示される) を埋めます。

G = grouptransform(T,"teamNumber","linearfill","percentComplete")

G=9×2 timetable
    timeStamp    teamNumber    percentComplete
    _________    __________    _______________

    1 day            1               14.2     
    1 day            2               28.1     
    1 day            3               11.5     
    2 days           1              30.15     
    2 days           2              39.65     
    2 days           3               19.3     
    3 days           1               46.1     
    3 days           2               51.2     
    3 days           3               30.3     

変数 percentComplete を置き換えずに元の table に埋め込みデータを追加するには、ReplaceValues を使用します。

Gappend = grouptransform(T,"teamNumber","linearfill","percentComplete","ReplaceValues",false)

Gappend=9×3 timetable
    timeStamp    teamNumber    percentComplete    linearfill_percentComplete
    _________    __________    _______________    __________________________

    1 day            1              14.2                     14.2           
    1 day            2              28.1                     28.1           
    1 day            3              11.5                     11.5           
    2 days           1               NaN                    30.15           
    2 days           2               NaN                    39.65           
    2 days           3              19.3                     19.3           
    3 days           1              46.1                     46.1           
    3 days           2              51.2                     51.2           
    3 days           3              30.3                     30.3           

曜日別のデータの正規化

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

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]';
T = table(timeStamps,profit)

T=10×2 table
    timeStamps     profit
    ___________    ______

    04-Mar-2017     2032 
    02-Mar-2017     3071 
    15-Mar-2017     1185 
    10-Mar-2017     2587 
    14-Mar-2017     1998 
    31-Mar-2017     2899 
    25-Mar-2017     3112 
    29-Mar-2017      909 
    21-Mar-2017     2619 
    18-Mar-2017     3085 

曜日別にビン化し、2 ノルムを使用して利益を正規化します。

G = grouptransform(T,"timeStamps","dayname","norm")

G=10×3 table
    timeStamps     profit     dayname_timeStamps
    ___________    _______    __________________

    04-Mar-2017    0.42069        Saturday      
    02-Mar-2017          1        Thursday      
    15-Mar-2017    0.79344        Wednesday     
    10-Mar-2017    0.66582        Friday        
    14-Mar-2017    0.60654        Tuesday       
    31-Mar-2017    0.74612        Friday        
    25-Mar-2017    0.64428        Saturday      
    29-Mar-2017    0.60864        Wednesday     
    21-Mar-2017    0.79506        Tuesday       
    18-Mar-2017    0.63869        Saturday      

ベクトル データによるグループ操作

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

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]';

曜日別にビン化し、2 ノルムを使用して利益を正規化します。変換後のデータと、それに対応するグループを表示します。

[normDailyProfit,dayName] = grouptransform(profit,timeStamps,"dayname","norm")

normDailyProfit = 10×1

    0.4207
    1.0000
    0.7934
    0.6658
    0.6065
    0.7461
    0.6443
    0.6086
    0.7951
    0.6387

dayName = 10×1 categorical
     Saturday 
     Thursday 
     Wednesday 
     Friday 
     Tuesday 
     Friday 
     Saturday 
     Wednesday 
     Tuesday 
     Saturday 

入力引数

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") — 数値を含んでいるすべての変数

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

method — 変換メソッド

"zscore" | "norm" | "meancenter" | "rescale" | "meanfill" | "linearfill" | 関数ハンドル

変換メソッド。次の値のいずれかとして指定します。

メソッド	説明
"zscore"	平均が 0、標準偏差が 1 となるようにデータを正規化
"norm"	2 ノルムでデータを正規化
"meancenter"	平均が 0 となるようにデータを正規化
"rescale"	範囲を [0,1] に再スケーリング
"meanfill"	グループ データの平均値で欠損値を埋める
"linearfill"	欠損していないグループ データの線形内挿で欠損値を埋める

最初の次元の長さが 1、または入力データと同じ行数をもつ 1 つの配列を返す関数ハンドルも指定できます。関数が、最初の次元の長さが 1 の配列を返す場合、grouptransform はその値を繰り返して、出力と入力の行数を同じにします。

データ型: char | string | function_handle

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 で指定されていないその他の変数は、演算されずに出力に渡されます。datavars が指定されない場合、grouptransform はそれぞれの非グループ化変数を処理します。

インデックス方式	指定する値	例
変数名	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") — 数値を含んでいるすべての変数

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

名前と値の引数

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

例: G = grouptransform(T,groupvars,groupbins,"zscore",IncludedEdge="right")

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

例: G = grouptransform(T,groupvars,groupbins,"zscore","IncludedEdge","right")

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

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

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

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

ReplaceValues — 値を置き換えるオプション

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

値を置き換えるオプション。次の値のいずれかとして指定します。

• true または 1 — 入力データ内の非グループ化 table 変数または列ベクトルを、変換後のデータを含む table 変数または列ベクトルに置き換えます。

• false または 0 — 入力データに、変換後のデータを含む table 変数または列ベクトルを追加します。

出力引数

G — 出力テーブル

table | timetable

table または timetable 入力データの出力 table。table または timetable として返されます。G には各グループの変換後のデータが含まれます。

B — 出力配列

ベクトル | 行列

配列の入力データの出力配列。ベクトルまたは行列として返されます。B には非グループ化ベクトルの代わりに変換後のデータが含まれます。

BG — グループ化ベクトル

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

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

ヒント

• grouptransform を何度も呼び出す場合、可能であればパフォーマンス向上のためグループ変数を categorical 型または logical 型に変換することを検討してください。たとえば、string 配列のグループ化変数 (要素が "Poor"、"Fair"、"Good"、"Excellent" である HealthStatus など) がある場合、categorical(HealthStatus) コマンドを使用してこれを categorical 変数に変換することができます。

代替機能

ライブ エディター タスク

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

拡張機能

tall 配列

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

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

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

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

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

• 引数 method が関数ハンドルの場合は、tall 配列を扱う splitapply の有効な入力でなければなりません。

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

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

C/C++ コード生成

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

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

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

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

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

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

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

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

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

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

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

スレッドベースの環境

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

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

バージョン履歴

R2018b で導入

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

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

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

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

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

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

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

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

tic
for k = 1:290
   G = grouptransform(data,groups,"norm");
end
toc
end

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

R2021b: 6.26 秒

R2022a: 1.01 秒

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

参考

関数

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

ライブ エディター タスク

• グループ別に計算

トピック

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