topkrows

按排序顺序的前若干行

全页折叠

语法

B = topkrows(X,k)

B = topkrows(X,k,col)

B = topkrows(X,___,direction)

B = topkrows(X,___,'ComparisonMethod',method)

[B,I] = topkrows(X,___)

B = topkrows(T,k)

B = topkrows(T,k,vars)

B = topkrows(T,k,vars,direction)

B = topkrows(T,k,vars,___,'ComparisonMethod',method)

[B,I] = topkrows(T,___)

说明

数组数据

B = topkrows(X,k) 对 X 中的行进行排序并返回排序后的数据的前 k 行。行按降序（对于数值数据）或字母顺序倒序（对于文本数据）排序。topkrows 基于第一列中的元素进行排序。当第一列包含值相等的元素时，topkrows 将根据下一列中的元素进行排序，并对后续的相等值重复此行为。

示例

B = topkrows(X,k,col) 按 col 指定的列对结果进行排序。使用此语法可连续执行多列排序。例如，topkrows(X,k,5) 基于第五列中的元素按降序对 X 的行进行排序。topkrows(X,k,[4 6]) 首先基于第四列中的元素按降序对行进行排序，然后基于第六列中的元素进一步排序。

示例

B = topkrows(X,___,direction) 使用上述任一语法指定排序方向。

例如，topkrows(A,2,[2 3],{'ascend' 'descend'}) 首先基于第 2 列的元素按升序对行进行排序，从而获得前 2 行。然后基于第 3 列中的元素，对第 2 列中具有相等条目的行按降序排序。

示例

B = topkrows(X,___,'ComparisonMethod',method) 指定如何比较 X 中的复数。比较方法可以是 'auto'、'real' 或 'abs'。

示例

[B,I] = topkrows(X,___) 还返回描述选定行的顺序的索引向量 I，使得 B = X(I,:)。

表数据

B = topkrows(T,k) 按照排序顺序返回表或时间表 T 中的前 k 行。表行按其所有变量以降序排序，时间表行按时间以降序排序。

示例

B = topkrows(T,k,vars) 按 vars 指定的变量对结果进行排序。使用此语法可按多个变量依次排序。例如，topkrows(T,k,{'Var1','Var2'}) 首先基于 Var1 中的元素对 T 的行进行排序，然后基于 Var2 中的元素进行排序。

示例

B = topkrows(T,k,vars,direction) 指定排序的方向。例如，使用 'ascend' 对 T 按升序排序。

B = topkrows(T,k,vars,___,'ComparisonMethod',method) 指定如何比较 T 中的复数。

[B,I] = topkrows(T,___) 还返回描述选定行的顺序的索引向量 I，使得 B = T(I,:)。

示例

全部折叠

对矩阵行排序

打开实时脚本

按照不同的排序顺序对矩阵的行进行排序，并查看前几行。

创建一个由 1 到 10 之间的随机整数组成的 20×5 矩阵。

rng default % for reproducibility
X = randi(10,20,5);

按降序对 X 的行进行排序，并返回前 4 行。默认情况下，topkrows 使用矩阵的第一列进行排序。对于在特定列中具有相等元素的任何行，将按照右侧紧邻的列进行排序。

TA = topkrows(X,4)

TA = 4×5

    10    10     8     7     6
    10     7     8     2     4
    10     4     4     3     5
    10     3     7     9     6

通过三个输入参量调用时，topkrows 完全按照第三个参量中指定的列进行排序。这意味着指定列中具有相等值的行将保持原始顺序。使用第三列中的值按降序对 X 进行排序，并返回前 5 行。

TB = topkrows(X,5,3)

TB = 5×5

     5     7    10     2     6
     2     9     8     6     6
    10    10     8     7     6
    10     7     8     2     4
    10     2     8     3     6

同时使用第三列和第四列对 X 进行排序。在这种情况下，topkrows 先按第 3 列对行进行排序。对于第 3 列中具有相等值的任何行，再按第 4 列进行排序。

TC = topkrows(X,5,[3 4])

TC = 5×5

     5     7    10     2     6
    10    10     8     7     6
     2     9     8     6     6
    10     2     8     3     6
    10     7     8     2     4

指定矩阵列的排序方向

打开实时脚本

使用具有不同排序方向的多个列对矩阵进行排序。

创建一个由 1 到 10 之间的随机整数组成的 100×5 矩阵。

rng default % for reproducibility
X = randi(10,100,5);

使用前三列对 X 进行排序，并返回前 10 行。使用元胞数组为每一列指定排序方向。

TA = topkrows(X,10,1:3,{'descend','ascend','ascend'})

TA = 10×5

    10     1     4     6     7
    10     1     8     5     1
    10     2     3     4     7
    10     3     5    10     5
    10     4     7     2     4
    10     5     5     2     7
    10     5     5     6     7
    10     6     5     5     7
    10     6     6     1     5
    10     7     7     8     1

对表行排序

打开实时脚本

对表中的异构数据行进行排序。

基于 patients.mat 数据集（包含一组患者的基本健康信息）创建一个表。在该表中包括患者的年龄、性别、身高和自我评估的健康状况。将 SelfAssessedHealthStatus 变量指定为有序分类数组。

load patients
vals = ["Poor" "Fair" "Good" "Excellent"];
SelfAssessedHealthStatus = categorical(SelfAssessedHealthStatus,vals,Ordinal=true);
T = table(Age,Smoker,Height,SelfAssessedHealthStatus)

T=100×4 table
    Age    Smoker    Height    SelfAssessedHealthStatus
    ___    ______    ______    ________________________

    38     true        71             Excellent        
    43     false       69             Fair             
    38     false       64             Good             
    40     false       67             Fair             
    49     false       64             Good             
    46     false       68             Good             
    33     true        64             Good             
    40     false       68             Good             
    28     false       68             Excellent        
    31     false       66             Excellent        
    45     false       68             Excellent        
    42     false       66             Poor             
    25     false       71             Poor             
    39     true        72             Excellent        
    36     false       65             Good             
    48     true        71             Good             
      ⋮

按降序对表进行排序，并获取前 10 行。结果按照第一个变量 Age 以降序排列。再按照其余的列继续排序：

如果年龄相同，则按 Smoker 变量继续排序。
如果吸烟者状态相同，则按 Height 变量继续排序。
如果身高相同，则按 SelfAssessedHealthStatus 变量继续排序。

TA = topkrows(T,10)

TA=10×4 table
    Age    Smoker    Height    SelfAssessedHealthStatus
    ___    ______    ______    ________________________

    50     true        72             Excellent        
    50     false       68             Good             
    49     true        68             Poor             
    49     true        63             Good             
    49     false       70             Fair             
    49     false       64             Good             
    48     true        71             Good             
    48     true        64             Excellent        
    48     false       71             Good             
    48     false       66             Excellent

通过按 Smoker 变量排序，再按 Age 变量排序，获取包含最年轻非吸烟者的前 10 行。

TB = topkrows(T,10,["Smoker" "Age"],"ascend")

TB=10×4 table
    Age    Smoker    Height    SelfAssessedHealthStatus
    ___    ______    ______    ________________________

    25     false       71             Poor             
    25     false       70             Poor             
    25     false       63             Good             
    25     false       64             Excellent        
    25     false       66             Good             
    28     false       68             Excellent        
    28     false       65             Good             
    28     false       66             Good             
    29     false       63             Excellent        
    29     false       68             Excellent

通过将 Age 变量的排序方向更改为 "descend"，获取年龄最大的前 10 名非吸烟者。

TB = topkrows(T,10,["Smoker" "Age"],["ascend" "descend"])

TB=10×4 table
    Age    Smoker    Height    SelfAssessedHealthStatus
    ___    ______    ______    ________________________

    50     false       68             Good             
    49     false       64             Good             
    49     false       70             Fair             
    48     false       65             Excellent        
    48     false       66             Excellent        
    48     false       64             Good             
    48     false       71             Good             
    48     false       66             Excellent        
    48     false       66             Fair             
    47     false       70             Excellent

对复数排序

打开实时脚本

先按绝对值再按实部对复矩阵进行排序。

创建一个由随机复数组成的 100×2 矩阵。

valRange = [-10 10];
X = randi(valRange,100,2) + 1i*randi(valRange,100,2);

获取矩阵的前 10 行。默认情况下，topkrows 按绝对值比较复数。

TA = topkrows(X,10)

TA = 10×2 complex

 -10.0000 + 9.0000i  10.0000 - 2.0000i
  -8.0000 + 9.0000i   2.0000 - 8.0000i
   9.0000 + 8.0000i   4.0000 + 7.0000i
  -6.0000 +10.0000i  -8.0000 - 7.0000i
   6.0000 -10.0000i  -1.0000 - 5.0000i
   6.0000 -10.0000i   0.0000 + 5.0000i
  -7.0000 + 9.0000i  -2.0000 - 5.0000i
   9.0000 - 7.0000i  10.0000 + 7.0000i
   9.0000 - 7.0000i   6.0000 + 6.0000i
  -9.0000 - 7.0000i   9.0000 + 9.0000i

通过指定 'ComparisonMethod' 名称-值对组，仅使用复数的实部来获取矩阵的前 10 行。

TB = topkrows(X,10,'ComparisonMethod','real')

TB = 10×2 complex

  10.0000 + 4.0000i  -3.0000 - 7.0000i
  10.0000 + 3.0000i   4.0000 + 5.0000i
  10.0000 + 2.0000i   5.0000 - 7.0000i
  10.0000 - 1.0000i  -1.0000 - 8.0000i
  10.0000 - 1.0000i  -6.0000 +10.0000i
  10.0000 - 4.0000i  -9.0000 + 0.0000i
  10.0000 - 5.0000i  -8.0000 - 3.0000i
   9.0000 + 8.0000i   4.0000 + 7.0000i
   9.0000 + 5.0000i -10.0000 + 0.0000i
   9.0000 + 1.0000i   1.0000 - 9.0000i

输入参数

全部折叠

`X` — 输入数组
数组

输入数组，指定为数值数组、逻辑数组、字符数组、字符串数组、分类数组、日期时间数组或持续时间数组。

如果 X 是一个非有序分类数组，topkrows 将根据 categories(X) 返回的类别的顺序按降序对元素进行排序。
如果 X 包含 NaN、NaT 或其他缺失值，则 topkrows 会将缺失值放在降序排序的末尾。

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

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

数据类型: table | timetable

`k` — 要返回的行数
非负整数标量

要返回的行数，指定为非负整数标量。如果 k 大于 X 的行数，则 topkrows 返回 X 的总行数。

`col` — 要作为排序依据的列
正整数标量 | 正整数向量

要作为排序依据的列，指定为正整数标量或由正整数组成的向量。

示例: B = topkrows(X,100,[1 3]) 在返回前 100 行之前先对第一列和第三列进行排序。

`vars` — 要作为排序依据的变量
标量 | 向量 | 变量名称 | 字符串数组 | 字符向量元胞数组 | `pattern` 标量 | `'RowNames'`

要作为排序依据的变量，指定为下表中的选项之一。

选项	示例	描述
正整数	`topkrows(T,k,3)`	整数 `n` 指定 `T.Properties.VariableNames{n}` 返回的要作为排序依据的变量的索引。
正整数向量	`topkrows(T,k,[1 3])`	向量 `[n1 n2 …]` 指定 `T.Properties.VariableNames{[n1 n2 …]}` 返回的要作为排序依据的多个变量的索引。
逻辑向量	`topkrows(T,k,[true false true])`	使用 `true` 或 `false` 值指定要作为排序依据的一个或多个变量。
变量名称	`topkrows(T,k,"Var3")`	将排序变量指定为 `T.Properties.VariableNames` 中列出的变量名称之一。
字符串数组	`topkrows(T,k,["Var1","Var3"])`	指定从 `T.Properties.VariableNames` 中选择的多个排序变量。
字符向量元胞数组	`topkrows(T,k,{'Var1','Var3'})`	指定从 `T.Properties.VariableNames` 中选择的多个排序变量。
`pattern` 标量	`topkrows(T,k,"V" + wildcardPattern)`	指定从 `T.Properties.VariableNames` 中选择的多个排序变量。
`'RowNames'`	`topkrows(T,k,'RowNames')`	仅适用于表。此选项按行名称对结果进行排序。

示例: B = topkrows(X,k,[1 3]) 对第一列和第三列进行排序。

示例: B = topkrows(X,k,"Year") 使用 Year 变量进行排序。

`direction` — 排序方向
`'descend'` (默认) | `'ascend'` | 字符串数组 | 字符向量元胞数组

排序方向，指定为 'descend'、'ascend'，或指定这些值的组合的字符串数组或字符向量元胞数组。

如果 direction 是一个元胞数组，则必须包含与 col 或 vars 指定的每个排序列对应的 'descend' 或 'ascend'。如果不指定 col 或 vars，则元胞数组必须包含对应于 X 中的每一列或 T 中的每个变量的 'descend' 或 'ascend'。

`method` — 数值输入的比较方法
`'auto'` (默认) | `'real'` | `'abs'`

数值输入的比较方法，指定为以下值之一：

'auto' -（默认值）按 'real' 比较实数，按 'abs' 比较复数。
'real' - 按实部 real(A) 比较数字。实部相等的数字再按虚部 imag(A) 进行比较。
'abs' - 按绝对值 abs(A) 比较数字。模相等的数字再按相位角 angle(A) 进行比较。

输出参量

全部折叠

`B` — 请求的行
数组 | 表 | 时间表

请求的行，以数组、表或时间表形式返回。B 的类型与输入数据相同。

`I` — 行索引
列向量

行索引，以列向量形式返回。I 描述所选行的顺序，使得 B = X(I,:) 或 B = T(I,:)。

提示

topkrows 不会对输入数据进行完全排序，因此当请求的行数较少时，它通常比 sort 和 sortrows 要快。

扩展功能

全部展开

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

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

不支持 ComparisonMethod 名称-值参量。
不支持对表使用 RowNames 选项。

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

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

用法说明和限制：

不支持以下类型：cell、table、categorical、duration 和 datetime。
对于固定大小的编译，k 的值必须为常量。
vars 输入参量不支持模式表达式。

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

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

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

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

分布式数组
使用 Parallel Computing Toolbox™ 在集群的组合内存中对大型数组进行分区。

topkrows 函数完全支持分布式数组。有关详细信息，请参阅使用分布式数组运行 MATLAB 函数 (Parallel Computing Toolbox)。

版本历史记录

在 R2016b 中推出

全部展开

R2025a: 改进了返回大量数值或逻辑数据行时的性能

当 k 至少为 2048 且至少为总行数的 20% 时，topkrows 函数改进了处理数值数据（包括复数数据）和逻辑数据的性能。

例如，以下代码从包含 10000 行的数值矩阵中返回前 5000 行，主要基于第一列按降序排列。该代码比上一版本大约快 2 倍。

function timingTest
A = rand(1e4,10);
for i = 1:120
    T = topkrows(A,5000);
end
end

大致的执行时间是：

R2024b：0.14 秒

R2025a：0.07 秒

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

timeit(@timingTest)

R2017b: tall 数组的行为更改

topkrows 对 tall 数组进行操作的一些行为已发生变化：

topkrows 将 NaN、NaT 和其他缺失值放在降序排序的末尾。在以前的版本中，topkrows 将缺失值放在降序排序的开头。
topkrows 不再接受仅包含标量数值的 tall 元胞数组作为输入。在使用 topkrows 之前，请使用 cell2mat 将标量数值的 tall 元胞数组转换为 tall 矩阵。

另请参阅

topkrows

语法

说明

数组数据

表数据

示例

对矩阵行排序

指定矩阵列的排序方向

对表行排序

对复数排序

输入参数

X — 输入数组 数组

T — 输入表 表 | 时间表

k — 要返回的行数 非负整数标量

col — 要作为排序依据的列 正整数标量 | 正整数向量

vars — 要作为排序依据的变量 标量 | 向量 | 变量名称 | 字符串数组 | 字符向量元胞数组 | pattern 标量 | 'RowNames'

direction — 排序方向 'descend' (默认) | 'ascend' | 字符串数组 | 字符向量元胞数组

method — 数值输入的比较方法 'auto' (默认) | 'real' | 'abs'

输出参量

B — 请求的行 数组 | 表 | 时间表

I — 行索引 列向量

提示

扩展功能

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

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

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

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

分布式数组 使用 Parallel Computing Toolbox™ 在集群的组合内存中对大型数组进行分区。

版本历史记录

R2025a: 改进了返回大量数值或逻辑数据行时的性能

R2017b: tall 数组的行为更改

另请参阅

`X` — 输入数组
数组

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

`k` — 要返回的行数
非负整数标量

`col` — 要作为排序依据的列
正整数标量 | 正整数向量

`vars` — 要作为排序依据的变量
标量 | 向量 | 变量名称 | 字符串数组 | 字符向量元胞数组 | `pattern` 标量 | `'RowNames'`

`direction` — 排序方向
`'descend'` (默认) | `'ascend'` | 字符串数组 | 字符向量元胞数组

`method` — 数值输入的比较方法
`'auto'` (默认) | `'real'` | `'abs'`

`B` — 请求的行
数组 | 表 | 时间表

`I` — 行索引
列向量

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

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

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

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

分布式数组
使用 Parallel Computing Toolbox™ 在集群的组合内存中对大型数组进行分区。