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,Gender,Height,SelfAssessedHealthStatus);

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

如果年龄相同，则按 Gender 变量继续排序。
如果性别相同，则按 Height 变量继续排序。
如果身高相同，则按 SelfAssessedHealthStatus 变量继续排序。

TA = topkrows(T,10)

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

    50     {'Male'  }      72             Excellent        
    50     {'Male'  }      68             Good             
    49     {'Male'  }      70             Fair             
    49     {'Male'  }      68             Poor             
    49     {'Female'}      64             Good             
    49     {'Female'}      63             Good             
    48     {'Male'  }      71             Good             
    48     {'Male'  }      71             Good             
    48     {'Male'  }      66             Fair             
    48     {'Female'}      66             Excellent

通过按 Gender 变量排序，再按 Age 变量排序，获取包含最年轻女性患者的前 10 行。

TB = topkrows(T,10,{'Gender','Age'},'ascend')

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

    25     {'Female'}      63             Good             
    25     {'Female'}      64             Excellent        
    27     {'Female'}      69             Fair             
    28     {'Female'}      65             Good             
    28     {'Female'}      65             Good             
    28     {'Female'}      66             Good             
    29     {'Female'}      63             Excellent        
    29     {'Female'}      68             Excellent        
    29     {'Female'}      64             Good             
    30     {'Female'}      67             Excellent

通过将 Age 变量的排序方向更改为 'descend'，获取年龄最大的前 10 名女性患者。

TB = topkrows(T,10,{'Gender','Age'},{'ascend','descend'})

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

    49     {'Female'}      64             Good             
    49     {'Female'}      63             Good             
    48     {'Female'}      65             Excellent        
    48     {'Female'}      66             Excellent        
    48     {'Female'}      64             Excellent        
    48     {'Female'}      64             Good             
    48     {'Female'}      66             Excellent        
    47     {'Female'}      66             Excellent        
    46     {'Female'}      68             Good             
    45     {'Female'}      68             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 输入参量不支持模式表达式。

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

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

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

此函数完全支持分布式数组。有关详细信息，请参阅使用分布式数组运行 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++ 代码。

基于线程的环境 使用 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++ 代码。

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

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