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 は最初の列の要素を基準として並べ替えます。1 列目に等しい値の要素が複数存在する場合、topkrows は 2 列目の要素を基準として並べ替え、その後の等しい値についても同じ動作を繰り返します。

B = topkrows(X,k,col) は、col で指定された列に基づいて結果を並べ替えます。この構文を使用して、列の並べ替えを連続して複数回実行します。たとえば、topkrows(X,k,5) は、X の行を 5 列目の要素に基づいて降順で並べ替えます。topkrows(X,k,[4 6]) は、まず行を 4 列目の要素に基づいて降順で並べ替え、次に 6 列目の要素に基づいて同順位のものを並べ替えます。

B = topkrows(X,___,direction) は、前述の構文のいずれかを使って並べ替えの方向を指定します。

たとえば、topkrows(A,2,[2 3],{'ascend' 'descend'}) は、まず 2 列目の要素に基づいて昇順で行を並べ替えることにより、上位 2 行を取得します。次に、2 列目の等しいエントリがある行を、3 列目の要素に基づいて降順で並べ替えます。

B = topkrows(X,___,'ComparisonMethod',method) は X 内の複素数の比較方法を指定します。比較方法は、'auto'、'real'、'abs' のいずれかにすることができます。

[B,I] = topkrows(X,___) はインデックス ベクトル I も返します。これは選択した行の順序を B = X(I,:) のように示します。

テーブル データ

B = topkrows(T,k) は、table または timetable T の最初の k 行を、順序を並べ替えて返します。table の行はすべての変数の降順で並べ替えられ、timetable の行は時間の降順で並べ替えられます。

B = topkrows(T,k,vars) は vars によって指定された変数で結果を並べ替えます。この構文を使用して、複数の変数による連続した並べ替えを行います。たとえば、topkrows(T,k,{'Var1','Var2'}) は T の行をまず Var1 の要素に基づいて並べ替え、次に Var2 の要素に基づいて並べ替えます。

B = topkrows(T,k,vars,direction) は並べ替えの方向を指定します。たとえば、T を昇順に並べ替えるには 'ascend' を使用します。

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

入力引数を 3 つ使用して topkrows を呼び出した場合、3 番目の引数で指定された列のみに基づいて並べ替えます。つまり、指定された列の等しい値がある行は、元の順序のままとなります。3 列目の値を使用して 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

3 列目と 4 列目の両方を使用して 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);

最初の 3 列を使用して X を並べ替え、上位 10 行を返します。cell 配列を使用して各列の並べ替え方向を指定します。

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

テーブルの行の並べ替え

table の異種混合データの行を並べ替えます。

patients.mat データ セットから table を作成します。これには、患者グループの基本的な健康情報が含まれています。table には患者の年齢、性別、身長、自己申告の健康状態が含まれます。変数 SelfAssessedHealthStatus を順序 categorical 配列にします。

load patients
vals = {'Poor','Fair','Good','Excellent'};
SelfAssessedHealthStatus = categorical(SelfAssessedHealthStatus,vals,'Ordinal',true);
T = table(Age,Gender,Height,SelfAssessedHealthStatus);

table を降順に並べ替えて上位 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 — 入力配列

配列

入力配列。数値配列、logical 配列、文字配列、string 配列、categorical 配列、datetime 配列、duration 配列として指定します。

• X が非順序 categorical 配列である場合、topkrows は categories(X) によって返されたカテゴリの順序に基づいて要素を降順に並べ替えます。

• X に NaN、NaT、またはその他の欠損値が含まれる場合、topkrows はその欠損値を降順の並べ替えの最後に配置します。

データ型: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | string | categorical | datetime | duration
複素数のサポート: あり

T — 入力 table

table | timetable

入力 table。table または timetable として指定します。

データ型: table | timetable

k — 返す行数

非負のスカラー整数

返す行数。非負のスカラー整数として指定します。k が X の行数より多い場合、topkrows は X のすべての行を返します。

col — 並べ替えの基準となる列

正のスカラー整数 | 正の整数のベクトル

並べ替えの基準となる列。正のスカラー整数または正の整数のベクトルとして指定します。

例: B = topkrows(X,100,[1 3]) は、1 列目と 3 列目を基準として並べ替えてから、上位 100 行を返します。

vars — 並べ替えの基準となる変数

スカラー | ベクトル | 変数名 | string 配列 | 文字ベクトルの cell 配列 | pattern スカラー | 'RowNames'

並べ替えの基準となる変数。次の表のオプションのいずれかとして指定します。

オプション	例	説明
正の整数	topkrows(T,k,3)	整数 n は並べ替えの基準となる変数のインデックスを指定します。T.Properties.VariableNames{n} によって返されます。
正の整数のベクトル	topkrows(T,k,[1 3])	ベクトル [n1 n2 …] は並べ替えの基準となる複数の変数のインデックスを指定します。T.Properties.VariableNames{[n1 n2 …]} によって返されます。
logical ベクトル	topkrows(T,k,[true false true])	値 true または false を使用して、並べ替えの基準となる変数を 1 つ以上指定します。
変数名	topkrows(T,k,"Var3")	並べ替え変数を T.Properties.VariableNames にリストされた変数名のいずれかとして指定します。
string 配列	topkrows(T,k,["Var1","Var3"])	T.Properties.VariableNames から選択した複数の並べ替え変数を指定します。
文字ベクトルの cell 配列	topkrows(T,k,{'Var1','Var3'})	T.Properties.VariableNames から選択した複数の並べ替え変数を指定します。
pattern スカラー	topkrows(T,k,"V" + wildcardPattern)	T.Properties.VariableNames から選択した複数の並べ替え変数を指定します。
'RowNames'	topkrows(T,k,'RowNames')	table のみ。このオプションは、行名を基準として結果を並べ替えます。

例: B = topkrows(X,k,[1 3]) は 1 列目と 3 列目を基準として並べ替えます。

例: B = topkrows(X,k,"Year") は変数 Year を使用して並べ替えます。

direction — 並べ替える方向

'descend' (既定値) | 'ascend' | string 配列 | 文字ベクトルの cell 配列

並べ替えの方向。'descend'、'ascend'、あるいはこれらの値の組み合わせを指定する string 配列または文字ベクトルの cell 配列として指定します。

direction が cell 配列の場合、col または vars によって指定される各並べ替え列に対して、'descend' または 'ascend' が含まれなければなりません。col または vars を指定しない場合は、X の各列または T の変数に対して、cell 配列に 'descend' または 'ascend' が含まれなければなりません。

method — 数値入力の比較方法

'auto' (既定値) | 'real' | 'abs'

数値入力の比較方法。次の値のいずれかとして指定します。

• 'auto' — (既定) 'real' に従って実数を比較、'abs' に従って複素数を比較。

• 'real' — 実数部 real(A) によって数値を比較。実数部が等しい数値は、虚数部 imag(A) でサブソート。

• 'abs' — 絶対値 abs(A) によって数値を比較。振幅が等しい数値は、位相角 angle(A) でサブソート。

出力引数

B — 要求した行

配列 | table | timetable

要求した行は、配列、table、または timetable として返されます。B は入力データと同じ型です。

I — 行インデックス

列ベクトル

行インデックス。列ベクトルとして返されます。I は選択した行の順序を B = X(I,:) または B = T(I,:) のように示します。

ヒント

• topkrows は入力データ全体の並べ替えは行わないため、要求した行数が少ない場合は通常 sort と sortrows より高速です。

拡張機能

tall 配列

メモリの許容量を超えるような多数の行を含む配列を計算します。

topkrows 関数は tall 配列をサポートしていますが、以下の使用上の注意および制限があります。

• 名前と値の引数 ComparisonMethod はサポートされていません。

• RowNames オプションは table ではサポートされていません。

詳細については、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: 数値データまたは logical データの大量の行を返す場合のパフォーマンスが向上

topkrows 関数は、複素数データを含む数値データおよび logical データに対してパフォーマンスが向上しています。これは、k が 2048 以上かつ総行数の 20% 以上である場合に有効です。

たとえば、次のコードは、10,000 行をもつ数値行列から最初の列を第一の基準として降順に並べた上位 5,000 行を返します。以前のリリースと比較して、このコードは約 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 配列の動作の変更

tall 配列の操作を行う topkrows の一部の動作が変更されています。

• topkrows は降順の並べ替えの末尾に NaN、NaT、およびその他の欠損値を配置します。以前のリリースでは、topkrows は、降順の並べ替えの先頭に欠落した値を配置していました。

• topkrows は、入力にスカラー数値のみを含む tall cell 配列を受け入れなくなりました。topkrows を使用する前に、cell2mat を使用してスカラー数値の tall cell 配列を tall 行列に変換してください。

参考

head | tail | sortrows | sort | mink | maxk