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) 返回表或时间表 T 中满足 method 指定的按组过滤条件的行。过滤条件 method 是应用于每个非分组变量的函数句柄。组基于 groupvars 中各变量的行值划分，各组包含唯一值组合。例如，G = groupfilter(T,"Trial",@(x) numel(x) > 5) 按照 Trial 对 T 中的数据进行分组，并保留具有五次以上尝试 (Trial) 的组中的各行。

您可以通过将按组计算任务添加到实时脚本中，以交互方式使用 groupfilter 函数。

示例

G = groupfilter(T,groupvars,groupbins,method) 指定在分组前根据分 bin 方案 groupbins 对 groupvars 中的行进行分 bin。例如，G = groupfilter(T,"SaleDate","year",@(x) numel(x) > 5) 按年份对 SaleDate 中的数据分 bin，并保留包含五个以上元素的 bin 的各行。

示例

G = groupfilter(___,datavars) 在上述任一语法的基础上指定要应用过滤方法的表变量。例如，G = groupfilter(T,"Trial",@(x) x == max(x),"Height") 保留 T 中对应于每次尝试 (Trial) 最大高度 (Height) 的行。

示例

G = groupfilter(___,"IncludedEdge",LR) 将包含的 bin 边界指定为 "left" 或 "right"，以指示应包含 bin 区间的哪一端。您可以将 IncludeEdge 与上述任何指定 groupbins 的语法结合使用。

数组数据

B = groupfilter(A,groupvars,method) 返回向量或矩阵 A 中满足 method 指定的按组过滤条件的行。过滤条件 method 是应用于所有列向量的函数句柄。组基于 groupvars 中各列向量的行值划分，各组均包含唯一值组合。

您可以通过将按组计算任务添加到实时脚本中，以交互方式使用 groupfilter 函数。

B = groupfilter(A,groupvars,groupbins,method) 指定在分组前根据分 bin 方案 groupbins 对 groupvars 中的行进行分 bin。

示例

当指定 groupbins 时，B = groupfilter(A,groupvars,groupbins,method,"IncludedEdge",LR) 指定是否包含每个 bin 的左边界或右边界。

[B,BG] = groupfilter(A,___) 还返回与 B 中的行对应的唯一分组向量组合。

示例

全部折叠

过滤二变量表

打开实时脚本

创建一个包含两个变量的表。

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 编号进行分组，并且返回对应于具有两个以上采样的组的行。

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

按最大值分组

打开实时脚本

创建一个包含两个变量的表，这两个变量分别表示日期和温度。

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

按日期分组，并且返回每天最高的两个温度。

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

G=4×2 table
    daynum    temp
    ______    ____

      1        67 
      1        71 
      2        79 
      2        78

按月分组

打开实时脚本

创建一个表，其中包含日期和对应的利润。

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

过滤三变量表

打开实时脚本

创建一个包含九个人信息的表 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` — 输入表
表 | 时间表

输入表，指定为表或时间表。

`A` — 输入数组
列向量 | 矩阵

输入数组，指定为列向量或一组存储为矩阵的列向量。

`groupvars` — 分组变量或向量
标量 | 向量 | 矩阵 | 元胞数组 | 模式 | 函数句柄 | 表 `vartype` 下标

分组变量或向量，指定为以下选项之一：

对于数组输入数据，groupvars 可以是一个行数与 A 相同的列向量，也可以是一组以矩阵或元胞数组形式排列的列向量。

对于表或时间表输入数据，groupvars 指示使用哪些变量来计算数据中的组。您可以使用下表中的任何选项来指定分组变量。

索引方案	要指定的值	示例
变量名称	字符串标量或字符向量字符串数组或字符向量元胞数组 `pattern` 对象	`"A"` 或 `'A'` - 名为 `A` 的变量 `["A" "B"]` 或 `{'A','B'}` - 两个名为 `A` 和 `B` 的变量 `"Var"+digitsPattern(1)` - 变量名为 `"Var"` 后跟一个数字
变量索引	引用变量在表中位置的索引编号由数字组成的向量一个 `logical` 向量。通常，此向量的长度与变量的数目相同，但可以省略尾部的 `0` (`false`) 值。	`3` - 表中的第三个变量 `[2 3]` - 表中的第二个和第三个变量 `[false false true]` - 第三个变量
函数句柄	函数句柄，以表变量作为输入并返回 `logical` 标量	`@isnumeric` - 所有包含数值的变量
变量类型：	`vartype` 下标，用于选择指定类型的变量	`vartype("numeric")` - 所有包含数值的变量

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

`method` — 过滤方法
函数句柄

过滤方法，指定为函数句柄。

method 定义用于在每个组中过滤成员的函数。该函数必须返回逻辑标量或与输入数据具有相同行数的逻辑列向量，用于指示要选择的组成员。

如果函数返回逻辑标量，则要么筛除组中的所有成员（当值为 false），要么不筛除任何成员（当值为 true）。
如果函数返回逻辑向量，则对应元素为 false 的组成员将被过滤掉并保留对应元素为 true 的成员。

要定义函数句柄，请使用形式为 @(inputargs) mymethod 的语法，其中 mymethod 取决于 inputargs。

函数可以过滤与满足条件的组对应的行。例如，@(x) mean(x) > 10 只向输出传递与组均值大于 10 的组对应的行。
函数可以过滤对应组中满足条件的行。例如，@(x) x == max(x) 只将与组中行的最大值对应的行传递给输出。

有关详细信息，请参阅创建函数句柄和匿名函数。

当 groupfilter 一次性将方法应用于多个非分组变量时，则方法将为每个变量返回一个逻辑标量或向量。对于每一行，只有返回的所有标量或向量中的对应值均为 true 时，才会将该行传递给输出。

`groupbins` — 分组变量或向量的分 bin 方案
`"none"` (默认) | 由 bin 边界组成的向量 | bin 数量 | 时间长度（bin 宽度） | 时间单位名称（bin 宽度） | 由分 bin 方法组成的元胞数组

分组变量或向量的分 bin 方案，指定为以下一种或多种分 bin 方法。分组变量或向量和分 bin 方案参量的大小必须相同，或其中之一可以为标量。

"none" - 无分 bin。
由 bin 边界组成的向量 - bin 边界定义 bin。对于 datetime 分组变量或向量，可以将边界指定为数值或 datetime 值。
bin 数目 - 该数目确定要创建多少个等间距 bin。可以将 bin 数目指定为正整数标量。
时间长度（bin 宽度）- 时间长度确定每个 bin 的宽度。对于 datetime 或 duration 分组变量或向量，可以将 bin 宽度指定为 duration 或 calendarDuration 标量。

时间单位的名称（bin 宽度）- 时间单位的名称确定每个 bin 的宽度。对于 datetime 或 duration 分组变量或向量，可以将 bin 宽度指定为下表中的选项之一。

值	描述	数据类型
`"second"`	每个 bin 是 1 秒。	`datetime` 和 `duration`
`"minute"`	每个 bin 是 1 分钟。	`datetime` 和 `duration`
`"hour"`	每个 bin 是 1 小时。	`datetime` 和 `duration`
`"day"`	每个 bin 表示 1 个日历日。此值将夏令时变化考虑在内。	`datetime` 和 `duration`
`"week"`	每个 bin 是 1 个日历周。	仅限 `datetime`
`"month"`	每个 bin 是 1 个日历月。	仅限 `datetime`
`"quarter"`	每个 bin 是 1 个日历季度。	仅限 `datetime`
`"year"`	每个 bin 表示 1 个日历年。此值将闰日考虑在内。	`datetime` 和 `duration`
`"decade"`	每个 bin 是 1 个十年（10 个日历年）。	仅限 `datetime`
`"century"`	每个 bin 是 1 个世纪（100 个日历年）。	仅限 `datetime`
`"secondofminute"`	bin 从 0 到 59 秒。	仅限 `datetime`
`"minuteofhour"`	bin 从 0 到 59 分钟。	仅限 `datetime`
`"hourofday"`	bin 从 0 到 23 小时。	仅限 `datetime`
`"dayofweek"`	bin 从 1 到 7 日。一周的第一天是星期天。	仅限 `datetime`
`"dayname"`	bin 是一周中某天的全称，例如 `"Sunday"`。	仅限 `datetime`
`"dayofmonth"`	bin 从 1 到 31 天。	仅限 `datetime`
`"dayofyear"`	bin 从 1 到 366 天。	仅限 `datetime`
`"weekofmonth"`	bin 从 1 到 6 周。	仅限 `datetime`
`"weekofyear"`	bin 从 1 到 54 周。	仅限 `datetime`
`"monthname"`	bin 是完整的月份名称，如 `"January"`。	仅限 `datetime`
`"monthofyear"`	bin 从 1 到 12 个月。	仅限 `datetime`
`"quarterofyear"`	bin 从 1 到 4 个季度。	仅限 `datetime`

`datavars` — 要对其进行操作的表变量
标量 | 向量 | 元胞数组 | 模式 | 函数句柄 | 表 `vartype` 下标

要对其进行操作的表变量，指定为下表中的选项之一。datavars 指示将过滤方法应用于输入表或时间表的哪些变量。未由 datavars 指定的其他变量会传递给输出，而不会对其进行操作。groupfilter 将过滤方法应用于指定的变量，并根据得到的结果从所有变量中删除行。当未指定 datavars 时，groupfilter 对每个非分组变量进行操作。

索引方案	要指定的值	示例
变量名称	字符串标量或字符向量字符串数组或字符向量元胞数组 `pattern` 对象	`"A"` 或 `'A'` - 名为 `A` 的变量 `["A" "B"]` 或 `{'A','B'}` - 两个名为 `A` 和 `B` 的变量 `"Var"+digitsPattern(1)` - 变量名为 `"Var"` 后跟一个数字
变量索引	引用变量在表中位置的索引编号由数字组成的向量一个 `logical` 向量。通常，此向量的长度与变量的数目相同，但可以省略尾部的 `0` (`false`) 值。	`3` - 表中的第三个变量 `[2 3]` - 表中的第二个和第三个变量 `[false false true]` - 第三个变量
函数句柄	函数句柄，以表变量作为输入并返回 `logical` 标量	`@isnumeric` - 所有包含数值的变量
变量类型：	`vartype` 下标，用于选择指定类型的变量	`vartype("numeric")` - 所有包含数值的变量

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

`LR` — 在分 bin 方案中包括 bin 边界
`"left"` (默认) | `"right"`

在分 bin 方案中包括 bin 边界，指定为 "left" 或 "right"，指示包括 bin 区间的哪一边。

仅当指定了 groupbins 时，才能指定 LR，并且该值适用于所有分组变量或向量的所有分 bin 方法。

输出参量

全部折叠

`G` — 输出表
表 | 时间表

表或时间表输入数据的输出表，以表或时间表形式返回。G 包含 T 中满足按组过滤方法的行。

`B` — 输出数组
向量 | 矩阵

数组输入数据的输出数组，以向量或矩阵形式返回。B 包含 A 中满足按组过滤方法的行。

`BG` — 分组向量
列向量 | 列向量元胞数组

数组输入数据的分组向量，以列向量或列向量元胞数组形式返回。BG 包含与 B 中的行对应的唯一分组向量或分 bin 分组向量组合。

替代功能

实时编辑器任务

您可以通过将按组计算任务添加到实时脚本中，以交互方式使用 groupfilter 函数。

Compute by Group task in the Live Editor

扩展功能

全部展开

tall 数组
对行数太多而无法放入内存的数组进行计算。

groupfilter 函数支持 tall 数组，但存在以下使用说明和限制：

如果 A 和 groupvars 均为 tall 矩阵，则它们必须具有相同的行数。
如果第一个输入是 tall 矩阵，则 groupvars 可以是包含 tall 分组向量的元胞数组。
groupvars 和 datavars 参量不支持函数句柄。
method 参量必须是对 tall 数组执行的 splitapply 的有效输入。
按照离散的日期时间数组分组时，分类组名称将不同于内存中的 groupfilter 计算结果。

有关详细信息，请参阅tall 数组。

C/C++ 代码生成
使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

用法说明和限制：

不支持稀疏输入。
日期时间或持续时间数据不支持分 bin 方案。
不支持包含多维数组的输入表。
计算方法必须为常量。
当第一个输入参量是表时，分组变量必须为常量。
数据变量必须为常量。
指定为字符向量或字符串的分 bin 方案必须为常量。
名称-值参量必须为常量。
计算方法不能返回稀疏结果或多维结果。

GPU 代码生成
使用 GPU Coder™ 为 NVIDIA® GPU 生成 CUDA® 代码。

请参阅“C/C++ 代码生成”部分中的用法说明和限制。同样的用法说明和限制也适用于 GPU 代码生成。

基于线程的环境
使用 MATLAB® `backgroundPool` 在后台运行代码或使用 Parallel Computing Toolbox™ `ThreadPool` 加快代码运行速度。

groupfilter 函数完全支持基于线程的环境。有关详细信息，请参阅在基于线程的环境中运行 MATLAB 函数。

版本历史记录

在 R2019b 中推出

全部展开

R2026a: 处理数值或字符串分组向量时性能得到改进

当分组变量或向量类型为数值或 string 时，groupfilter 函数的性能得到了改进。

如果分组变量或向量为数值，并且元素总数和每组元素数都很大，则性能改进最为明显。如果分组变量或向量类型为 string，并且元素总数很大且每组元素数很小，则性能改进最为明显。

例如，以下代码将长度为 12,500,000 的数值向量中的元素拆分为 25 个编号组，并应用过滤条件。代码执行速度比上一版本大约快 1.7 倍。

function timingTest
numberOfGroups = 25;
elementsPerGroup = 5e5;
groups = repmat(1:numberOfGroups,1,elementsPerGroup)';
data = randn(numel(groups),1);
F = @() groupfilter(data,groups,@(x) mean(x) > 0);
t = timeit(F)
end

大致的执行时间是：

R2025b：2.64 秒

R2026a：1.53 秒

此代码是在运行 Windows^® 11 的 AMD EPYC™ 74F3 24 核处理器 @ 3.19 GHz 测试系统上通过调用 timingTest 函数计时的。

R2024a: 对分组变量应用多种分 bin 方法

通过指定分 bin 方法的元胞数组将多种分 bin 方法应用于一个分组变量或向量。

R2022b: 代码生成支持

为 groupfilter 函数生成 C 或 C++ 代码。有关用法说明和限制，请参阅 C/C++ 代码生成。

R2022a: 改进了处理小型组时的性能

groupfilter 函数显示性能得到改进，尤其是在每个组中的数据量较小时。

例如，以下代码按组过滤有 500 个组（每个组的计数为 10）的矩阵。该代码比上一版本大约快 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

实时编辑器任务

按组计算

groupfilter

语法

说明

表数据

数组数据

示例

过滤二变量表

按最大值分组

按月分组

过滤三变量表

对向量数据进行过滤

输入参数

T — 输入表 表 | 时间表

A — 输入数组 列向量 | 矩阵

groupvars — 分组变量或向量 标量 | 向量 | 矩阵 | 元胞数组 | 模式 | 函数句柄 | 表 vartype 下标

method — 过滤方法 函数句柄

groupbins — 分组变量或向量的分 bin 方案 "none" (默认) | 由 bin 边界组成的向量 | bin 数量 | 时间长度（bin 宽度） | 时间单位名称（bin 宽度） | 由分 bin 方法组成的元胞数组

datavars — 要对其进行操作的表变量 标量 | 向量 | 元胞数组 | 模式 | 函数句柄 | 表 vartype 下标

LR — 在分 bin 方案中包括 bin 边界 "left" (默认) | "right"

输出参量

G — 输出表 表 | 时间表

B — 输出数组 向量 | 矩阵

BG — 分组向量 列向量 | 列向量元胞数组

替代功能

实时编辑器任务

扩展功能

tall 数组 对行数太多而无法放入内存的数组进行计算。

C/C++ 代码生成 使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

GPU 代码生成 使用 GPU Coder™ 为 NVIDIA® GPU 生成 CUDA® 代码。

基于线程的环境 使用 MATLAB® backgroundPool 在后台运行代码或使用 Parallel Computing Toolbox™ ThreadPool 加快代码运行速度。

版本历史记录

R2026a: 处理数值或字符串分组向量时性能得到改进

R2024a: 对分组变量应用多种分 bin 方法

R2022b: 代码生成支持

R2022a: 改进了处理小型组时的性能

另请参阅

函数

实时编辑器任务

主题

`T` — 输入表
表 | 时间表

`A` — 输入数组
列向量 | 矩阵

`groupvars` — 分组变量或向量
标量 | 向量 | 矩阵 | 元胞数组 | 模式 | 函数句柄 | 表 `vartype` 下标

`method` — 过滤方法
函数句柄

`groupbins` — 分组变量或向量的分 bin 方案
`"none"` (默认) | 由 bin 边界组成的向量 | bin 数量 | 时间长度（bin 宽度） | 时间单位名称（bin 宽度） | 由分 bin 方法组成的元胞数组

`datavars` — 要对其进行操作的表变量
标量 | 向量 | 元胞数组 | 模式 | 函数句柄 | 表 `vartype` 下标

`LR` — 在分 bin 方案中包括 bin 边界
`"left"` (默认) | `"right"`

`G` — 输出表
表 | 时间表

`B` — 输出数组
向量 | 矩阵

`BG` — 分组向量
列向量 | 列向量元胞数组

tall 数组
对行数太多而无法放入内存的数组进行计算。

C/C++ 代码生成
使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

GPU 代码生成
使用 GPU Coder™ 为 NVIDIA® GPU 生成 CUDA® 代码。

基于线程的环境
使用 MATLAB® `backgroundPool` 在后台运行代码或使用 Parallel Computing Toolbox™ `ThreadPool` 加快代码运行速度。