matlab.tall.transform

tA = matlab.tall.transform(fcn,tX) は、関数ハンドル fcn を配列 tX の各ブロックに適用し、変換された配列 tA を返します。

tA = matlab.tall.transform(fcn,tX,tY,...) は、fcn への入力である複数の配列 tX,tY,... を指定します。各配列の同じ行は、fcn(tX(n:m,:),tY(n:m,:)) など、fcn によって演算されます。高さ 1 の入力はすべての fcn の呼び出しに渡されます。

[tA,tB,...] = matlab.tall.transform(fcn,tX,tY,...)。ここで fcn は、複数の出力を返し、それぞれが fcn の出力引数のいずれかに対応する配列 tA,tB,... を返す関数です。fcn のすべての出力の高さは同じでなければなりません。また出力数は、matlab.tall.transform から要求された数と同じでなければなりません。

[tA,tB,...] = matlab.tall.transform(___,'OutputsLike',{PA,PB,...}) は出力 tA,tB,... にプロトタイプ配列 PA,PB,... と同じデータ型をそれぞれ指定します。前述の構文にある任意の入力引数の組み合わせが使用できます。

例

tall ベクトルへの関数の適用

matlab.tall.transform を使用して、別の配列と同様の属性をもつゼロの tall 配列を作成します。

airlinesmall.csv データセットの tall table を作成します。このデータには米国のフライトの到着時刻と出発時刻に関する情報が含まれています。変数 ArrDelay を抽出します。これは到着遅延のベクトルです。

ds = tabularTextDatastore('airlinesmall.csv','TreatAsMissing','NA');
ds.SelectedVariableNames = {'ArrDelay' 'DepDelay'};
tt = tall(ds);
tX = tt.ArrDelay

tX =

  Mx1 tall double column vector

     8
     8
    21
    13
     4
    59
     3
    11
    :
    :

入力と同じサイズと同じデータ型をもつゼロの配列を作成する無名関数を書き込みます。

zerosLike = @(in) zeros(size(in),'like',in);

matlab.tall.transform を使用して関数 zerosLike を到着遅延時間のベクトルに適用します。結果は、同じサイズの tall ベクトルになりますが、その値はすべて 0 です。

s = matlab.tall.transform(zerosLike, tX)

s =

  Mx1 tall double column vector

     0
     0
     0
     0
     0
     0
     0
     0
     :
     :

2 つのベクトルの変換

到着遅延時間と出発遅延時間のベクトルから平均の合計フライト遅延時間を計算します。

airlinesmall.csv データセットの tall table を作成します。このデータには米国のフライトの到着時刻と出発時刻に関する情報が含まれています。変数 ArrDelay と DepDelay を抽出します。これらは到着遅延時間と出発遅延時間のベクトルです。

ds = tabularTextDatastore('airlinesmall.csv','TreatAsMissing','NA');
ds.SelectedVariableNames = {'ArrDelay' 'DepDelay'};
tt = tall(ds);
tX = tt.ArrDelay;
tY = tt.DepDelay;

関数 meanDelay は入力ベクトルを 1 つの行列に連結して、各行の値 (NaN は無視する) を合計した後、平均を計算します。その関数ファイルの内容を表示します。

type meanDelay

function D = meanDelay(a,b)
X = [a b];
Y = sum(X,2,'omitnan');
D = mean(Y);
end

matlab.tall.transform を使用して関数 meanDelay を tX および tY 内の各データブロックに適用します。結果は、各データブロックの平均合計遅延時間になります。

d = matlab.tall.transform(@meanDelay, tX, tY)

d =

  7x1 tall double column vector

   14.0621
   11.1639
   17.2311
   15.1852
   12.5860
   19.8596
   14.4036

この演算は、各データブロックをスカラー値まで削減した結果がメモリに収まるものと仮定しています。極端に大きいデータセットや小さなブロックサイズを使用するデータセットの場合、この仮定が当てはまらない場合があります。

複数の出力をもつ関数の適用

データの各行の最大値とその値のインデックスを求めます。

ds = tabularTextDatastore('airlinesmall.csv','TreatAsMissing','NA');
ds.SelectedVariableNames = {'ArrDelay' 'DepDelay'};
tt = tall(ds);
tX = tt.ArrDelay;
tY = tt.DepDelay;

関数 maxDelay は入力ベクトルを連結した後に、最大到着遅延時間または最大出発遅延時間とその列インデックスを求めます。そのファイルの内容を表示します。

type maxDelay

function [M,I] = maxDelay(A,B)
X = [A B];
[M,I] = max(X,[],2);
end

matlab.tall.transform を使用して関数 maxDelay を tX および tY 内の各データブロックに適用します。結果は、データの各行の最大到着遅延時間または最大出発遅延時間、および最大値が取得された列を示すインデックスベクトルになります。インデックス 1 はその行の到着遅延時間の方が長いことを示し、インデックス 2 は出発遅延時間の方が長いことを示します。

[M, idx] = matlab.tall.transform(@maxDelay, tX, tY)

M =

  Mx1 tall double column vector

    12
     8
    21
    13
     4
    63
     3
    11
    :
    :


idx =

  Mx1 tall double column vector

     2
     1
     1
     1
     1
     2
     1
     1
     :
     :

異なる変数をもつ出力 table

'OutputsLike' オプションを使用して、入力 table と変数が異なる matlab.tall.transform から table を返します。

乱数値の 2 つの変数をもつ tall table を作成します。

T = tall(table(rand(1e6,1),rand(1e6,1)))

T =

  1,000,000x2 tall table

     Var1       Var2  
    _______    _______

    0.81472    0.90399
    0.90579    0.94095
    0.12699    0.80252
    0.91338    0.24205
    0.63236    0.97566
    0.09754    0.31723
     0.2785    0.81279
    0.54688    0.69743
       :          :
       :          :

関数 tableDiff は、2 つの入力 table 変数の差を計算し、結果を table の新しい変数として追加します。ファイルの内容を表示します。

type tableDiff

function Tout = tableDiff(Tin)
d = Tin.Var2 - Tin.Var1;
Tin.Var3 = abs(d);
Tout = Tin;
end

matlab.tall.transform を使用して関数 tableDiff を T 内の各データブロックに適用します。出力 table には入力 table からのさまざまな変数があるため、'OutputsLike' の名前と値のペアを使用して類似した変数をもつプロトタイプの table を出力として指定します (既定の名前が Var1、Var2、および Var3 の 3 つの変数)。

Z = matlab.tall.transform(@tableDiff, T, 'OutputsLike', {table(1,1,1)})

Z =

  Mx3 tall table

     Var1       Var2        Var3  
    _______    _______    ________

    0.81472    0.90399    0.089267
    0.90579    0.94095    0.035156
    0.12699    0.80252     0.67553
    0.91338    0.24205     0.67133
    0.63236    0.97566      0.3433
    0.09754    0.31723     0.21969
     0.2785    0.81279     0.53429
    0.54688    0.69743     0.15054
       :          :          :
       :          :          :

入力引数

`fcn` — 適用する変換関数
関数ハンドル | 無名関数

適用する変換関数。関数ハンドルまたは無名関数として指定します。fcn の各出力は最初の入力 tX と同じタイプでなければなりません。'OutputsLike' オプションを使用してさまざまなデータ型の出力を返すことができます。fcn が複数の出力を返す場合、それらの出力はすべて同じ高さをもたなければなりません。

fcn の一般的な関数シグネチャは、次のとおりです。

[a, b, c, ...] = fcn(x, y, z, ...)

fcn は以下の要件を満たさなければなりません。

入力引数 — 入力 [x, y, z, ...] は、メモリに収まるデータのブロックです。ブロックは、tall 配列の入力 [tX, tY, tZ, ...] それぞれからデータを抽出することによって生成されます。入力 [x, y, z, ...] は次の特性を満たします。
- [x, y, z, ...] はすべて、任意の可能な拡張後の最初の次元が同じサイズをもつ。
- [x, y, z, ...] のデータブロックは、tall 配列の tall 次元が 1 ではないと仮定した場合、tall 次元の同じインデックスから得られる。たとえば、tX と tY の tall 次元が 1 ではない場合、ブロックの最初のセットは x = tX(1:20000,:) および y = tY(1:20000,:) になる可能性があります。
- [tX, tY, tZ, ...] のいずれかの最初の次元がサイズ 1 である場合、対応するブロック [x, y, z, ...] は、その tall 配列内のすべてのデータで構成される。
出力引数 — 出力 [a, b, c, ...] はメモリに収まるブロックで、それぞれの出力 [tA, tB, tC, ...] に送信されます。出力 [a, b, c, ...] は以下の特性を満たします。
- [a, b, c, ...] はすべて、最初の次元が同じサイズでなければならない。
- [a, b, c, ...] はすべて、fcn の以前の呼び出しの結果とそれぞれ垂直方向に連結される。
- [a, b, c, ...] はすべて、それぞれの出力先で、出力配列の最初の次元にある同じインデックスに送信される。
関数ルール — fcn は関数ルールを満たさなければなりません。
- F([inputs1; inputs2]) == [F(inputs1); F(inputs2)]:入力の連結に関数を適用することは、入力に関数を個別に適用してから結果を連結する場合と同じでなければならない。
空の入力 — fcn が高さ 0 の入力を処理できることを確認します。空の入力は、ファイルが空の場合や、データに対して数多くのフィルター処理を行った場合に発生することがあります。

たとえば、この関数は 2 つの入力配列を受け入れて、二乗し、2 つの出力配列を返します。

function [xx,yy] = sqInputs(x,y)
xx = x.^2;
yy = y.^2;
end

この関数をアクセス可能なフォルダーに保存した後、この関数を呼び出して tX と tY を次のコマンドで二乗できます。

[tA,tB] = matlab.tall.transform(@sqInputs,tX,tY)

例: tA = matlab.tall.transform(@(x) x .* 2, tX) は tX の値を 2 で乗算する無名関数を指定します。

例: tC = matlab.tall.transform(@plus,tX,tY) は 2 つの配列を同時に追加する関数ハンドル @plus を指定します。

データ型: function_handle

`tX`, `tY` — 入力配列
スカラー | ベクトル | 行列 | 多次元配列

入力配列。スカラー、ベクトル、行列または多次元配列として指定します。入力配列は、指定した関数 fcn への入力として使用されます。各入力配列 tX,tY,... の高さに互換性がなければなりません。高さが同じであるか、一方の入力が高さ 1 である場合、2 つの入力の高さは互換性があります。

`PA`, `PB` — 出力配列のプロトタイプ
配列

出力配列のプロトタイプ。配列として指定します。'OutputsLike' を指定する場合、matlab.tall.transform で返される出力配列 tA,tB,... は、指定した配列 {PA,PB,...} と同じデータ型をもちます。

例: tA = matlab.tall.transform(fcn,tX,'OutputsLike',{int8(1)}); の場合、tX は倍精度配列であり、A を double ではなく int8 として返します。

出力引数

`tA`, `tB` — 出力配列
スカラー | ベクトル | 行列 | 多次元配列

出力配列。スカラー、ベクトル、行列、または多次元配列として返されます。matlab.tall.transform へのいずれかの入力が tall の場合、すべての出力引数も tall となります。それ以外の場合、すべての出力引数はインメモリ配列になります。

出力配列のサイズとデータ型は指定した関数 fcn によって異なります。一般的に、出力 tA,tB,... はすべて、最初の入力 X と同じデータ型をもたなければなりません。ただし、'OutputsLike' を指定して異なるデータ型を返すことができます。出力配列 tA,tB,... はすべて同じ高さをもちます。

詳細