matlab.tall.transform

通过将函数句柄应用于数据块来转换数组

全页折叠

语法

tA = matlab.tall.transform(fcn,tX)

tA = matlab.tall.transform(fcn,tX,tY,...)

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

[tA,tB,...] = matlab.tall.transform(___,'OutputsLike',{PA,PB,...})

说明

tA = matlab.tall.transform(fcn,tX) 将函数句柄 fcn 应用于数组 tX 的每个块并返回转换后的数组 tA。

示例

tA = matlab.tall.transform(fcn,tX,tY,...) 指定几个 tX,tY,... 数组，这些数组是 fcn 的输入。fcn 对每个数组的相同行进行运算；例如，fcn(tX(n:m,:),tY(n:m,:))。高度为 1 的输入将传递给 fcn 的每次调用。

示例

[tA,tB,...] = matlab.tall.transform(fcn,tX,tY,...) 返回 tA,tB,... 数组，每个数组对应于 fcn 的一个输出参量，fcn 是返回多个输出的函数。fcn 的所有输出必须具有相同的高度，并且输出数目必须与 matlab.tall.transform 中请求的数量相同。

示例

[tA,tB,...] = matlab.tall.transform(___,'OutputsLike',{PA,PB,...}) 指定输出 tA,tB,... 分别与原型数组 PA,PB,... 具有相同的数据类型。您可以使用上述语法中的任何输入参量组合。

示例

全部折叠

将函数应用于 tall 向量

打开实时脚本

使用 matlab.tall.transform 构建一个全零 tall 数组，其属性与另一个数组类似。

为 airlinesmall.csv 数据集创建 tall 表。该数据包含有关美国航班的到港和离港时间的信息。提取 ArrDelay 变量，该变量是到港延误的向量。

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

tX =

  M×1 tall double column vector

     8
     8
    21
    13
     4
    59
     3
    11
    :
    :

编写一个匿名函数，该函数创建一个大小和数据类型与输入相同的全零数组。

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

使用 matlab.tall.transform 将 zerosLike 函数应用于到港延误的向量。结果是相同大小的 tall 向量，但其值均为零。

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

s =

  M×1 tall double column vector

     0
     0
     0
     0
     0
     0
     0
     0
     :
     :

变换两个向量

打开实时脚本

基于到港和离港延误向量计算平均总航班延误。

为 airlinesmall.csv 数据集创建 tall 表。该数据包含有关美国航班的到港和离港时间的信息。提取 ArrDelay 和 DepDelay 变量，这些变量是到港和离港延误的向量。

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

meanDelay 函数将输入向量串联到矩阵中，对每行中的值求和（忽略 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 =

  7×1 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 =

  M×1 tall double column vector

    12
     8
    21
    13
     4
    63
     3
    11
    :
    :


idx =

  M×1 tall double column vector

     2
     1
     1
     1
     1
     2
     1
     1
     :
     :

输出包含不同变量的表

打开实时脚本

使用 'OutputsLike' 选项从 matlab.tall.transform 返回表，该表与输入表具有不同的变量。

创建包含两个随机值变量的 tall 表。

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

T =

  1,000,000×2 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 计算两个输入表变量之间的差，并将结果作为新变量添加到表中。显示文件内容。

type tableDiff

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

使用 matlab.tall.transform 将 tableDiff 函数应用于 T 中的每个数据块。由于输出表与输入表具有不同变量，因此使用 'OutputsLike' 名称-值对组来提供具有与输出类似的变量的原型表（三个变量具有默认名称 Var1、Var2 和 Var3）。

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

Z =

  M×3 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 数组的 tall 维度是非单一维度）。例如，如果 tX 和 tY 的 tall 维度为非单一维度，则第一组数据块可能是 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 的输入。当文件为空或者您对数据进行大量过滤时，可能会出现空输入。

例如，以下函数接受两个输入数组，对它们求平方，并返回两个输出数组：

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) 指定函数句柄 @plus 以将两个数组相加。

数据类型: function_handle

`tX`, `tY` — 输入数组
标量 | 向量 | 矩阵 | 多维数组

输入数组，指定为标量、向量、矩阵或多维数组。输入数组用作指定函数 fcn 的输入。每个输入数组 tX,tY,... 必须具有兼容的高度。如果两个输入具有相同的高度，或者其中一个输入的高度为 1，则它们具有兼容的高度。

`PA`, `PB` — 输出数组的原型
数组

输出数组的原型，指定为数组。当您指定 'OutputsLike' 时，matlab.tall.transform 返回的输出数组 tA,tB,... 与指定的数组 {PA,PB,...} 具有相同的数据类型。

示例: tA = matlab.tall.transform(fcn,tX,'OutputsLike',{int8(1)});（其中 tX 是双精度数组）以 int8（而不是 double）形式返回 A。

输出参量

全部折叠

`tA`, `tB` — 输出数组
标量 | 向量 | 矩阵 | 多维数组

输出数组，以标量、向量、矩阵或多维数组形式返回。如果 matlab.tall.transform 的任一输入为 tall，则所有输出参量也为 tall。否则，所有输出参量均为内存数组。

输出数组的大小和数据类型取决于指定的函数 fcn。通常，输出 tA,tB,... 必须与第一个输入 X 具有相同的数据类型。但是，您可以指定 'OutputsLike' 以返回不同数据类型。输出数组 tA,tB,... 都具有相同的高度。

详细信息

全部折叠

tall 数组块

从数据存储创建 tall 数组时，基础数据存储便于在计算过程中移动数据。数据以块或分块形式的离散片段移动，其中每个块是一组可放入内存的连续行。例如，二维数组（例如表）的一个块是 X(n:m,:)，表示下标为 n 和 m 的一些数据。每个块的大小基于数据存储的 ReadSize 属性的值，但该块不一定完全等于该大小。对于 matlab.tall.transform 来说，tall 数组被视为许多此类块的垂直串联：

Illustration of an array broken into vertical blocks.

例如，如果使用 sum 函数作为变换函数，则结果为每个块之和。因此，结果是长度等于块数的一个向量，而不是针对元素之和返回单一标量值。

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

f = @(x) sum(x,'omitnan');
s = matlab.tall.transform(f, tX);
s = gather(s)

版本历史记录

在 R2018b 中推出

另请参阅

tall | matlab.tall.reduce

主题

Develop Custom Tall Array Algorithms

matlab.tall.transform

语法

说明

示例

将函数应用于 tall 向量

变换两个向量

应用具有多个输出的函数

输出包含不同变量的表

输入参数

fcn — 要应用的变换函数 函数句柄 | 匿名函数

tX, tY — 输入数组 标量 | 向量 | 矩阵 | 多维数组

PA, PB — 输出数组的原型 数组

输出参量

tA, tB — 输出数组 标量 | 向量 | 矩阵 | 多维数组

详细信息

tall 数组块

版本历史记录

另请参阅

主题

`fcn` — 要应用的变换函数
函数句柄 | 匿名函数

`tX`, `tY` — 输入数组
标量 | 向量 | 矩阵 | 多维数组

`PA`, `PB` — 输出数组的原型
数组

`tA`, `tB` — 输出数组
标量 | 向量 | 矩阵 | 多维数组