SROWR

Sorts rows of a real rectangular matrix using keys in columns.

Required Arguments

X — NROW by NCOL matrix. (Input, if IRET = 1; input/output if IRET = 0)
On input, X contains the matrix to be sorted. If IRET = 0, the output X contains the sorted matrix.

INDKEY — Vector of length NKEY giving the column numbers of X which are to be used in the sort. (Input)

IPERM — Permutation vector of length NROW specifying the rearrangement of the rows. (Output)
IPERM(I) = J means row I of the sorted X is row J of the unsorted X.

NGROUP — Number of groups. (Output, if IRET ≤ 1)
The rows of the sorted X are partitioned into groups. A group contains rows that are equal with respect to the method of comparison. NGROUP is the number of groups of different rows.

NI — Vector of length NGROUP containing the number of rows in each group. (Output, if IRET ≤ 1)

The first NI(1) rows of the sorted X are group number 1. The next NI(2) rows of the sorted X are group number 2. … The last NI(NGROUP) rows of the sorted X are group number NGROUP. If NGROUP is not known prior to the invocation of this routine, NROW(an upper bound for NGROUP) can be used as the dimension of NI. If IRET ≥ 2, NI is not referenced and can be a vector of length one.

Optional Arguments

NROW — Number of rows of X. (Input)
Default: NROW = size (X,1).

NCOL — Number of columns of X. (Input)
Default: NCOL = size (X,2).

LDX — Leading dimension of X exactly as specified in the dimension statement of the calling program. (Input)
Default: LDX = size (X,1).

ICOMP — Option giving the method of comparison of the row vectors. (Input)
Default: ICOMP = 0.

ICOMP	Action
0	Elementwise, by algebraic values
1	Elementwise, by absolute values

IORDR — Option giving the sorting order. (Input)
Default: IORDR = 0.

IORDR	Action
0	Ascending
1	Descending

IRET — Option to indicate information returned. (Input)
Default: IRET = 0.

IRET	Action
0	The sorted X is returned along with NGROUP and NI.
1	X is unchanged (detached key sort) and NGROUP and NI are returned.
2	The sorted X is returned, but NGROUP and NI are not returned.
3	X is unchanged (detached key sort) and NGROUP and NI are not returned.

NKEY — Number of columns of X on which to sort. (Input)
Default: NKEY = size (INDKEY,1).

NRMISS — Number of rows that contained NaN in the columns of X used in the sort. (Output)
These rows are considered as a separate group from the other NGROUP groups and are put as the last NRMISS rows of the sorted X.

FORTRAN 90 Interface

Generic: CALL SROWR (X, INDKEY, IPERM, NGROUP, NI [, …])

Specific: The specific interface names are S_SROWR and D_SROWR.

FORTRAN 77 Interface

Single: CALL SROWR (NROW, NCOL, X, LDX, ICOMP, IORDR, IRET, NKEY, INDKEY, IPERM, NGROUP, NI, NRMISS)

Double: The double precision name is DSROWR.

Description

Routine SROWR sorts the rows of a real matrix X using particular rows in X as the keys. One of two methods for comparing the rows can be used for sorting.

1. Algebraic with the first key as the most significant, the second key next most significant and so forth.

2. Absolute values with the first key as the most significant, the second key next most significant and so forth.

The rows of X can be put in ascending or descending order.

The routine is useful for grouping data based on values of specified variables. The rows of X containing the IMSL missing value code NaN (not a number) in at least one of the specified columns are considered as an additional group of NRMISS rows. These rows are moved to the end of the sorted X. SROWR is based on a quicksort method given by Singleton (1969). Modifications by Griffin and Redish (1970) and Petro (1970) are incorporated.

Comments

1. Workspace may be explicitly provided, if desired, by use of S2OWR/DS2OWR. The reference is:

CALL S2OWR (NROW, NCOL, X, LDX, ICOMP, IORDR, IRET, NKEY, INDKEY, IPERM, NGROUP, NI, NRMISS, WK, IWK)

The additional arguments are as follows:

WK — Work vector of length 2 * m.

IWK — Work vector of length m + INT(2.8854 * ln(m)) + 2.

2. When X is sorted by algebraic values (ICOMP = 0), in ascending order, the resulting array X is such that:
For i = 1, 2, …, NROW – 1, X(i, INDKEY(1)) ≤ X(i + 1, INDKEY(1)).
For k = 2, …, NKEY, if X(i, INDKEY(j)) = X(i + 1, INDKEY(j)) for j = 1, 2, …, k – 1; then X(i, INDKEY(k)) ≤ X(i + 1, INDKEY(k)).
When ICOMP = 1, the absolute values are compared instead.

Example

The rows of a 10 x 3 matrix X are sorted in ascending order by algebraic value using columns 2 and 3 as the keys. The permutations to put the rows of the input X into sorted order are returned along with the sorted X.

USE IMSL_LIBRARIES

IMPLICIT NONE

INTEGER LDX, NCOL, NKEY, NROW, J

PARAMETER (NCOL=3, NKEY=2, NROW=10, LDX=NROW)

INTEGER ICOMP, INDKEY(NKEY), IORDR, IPERM(NROW), IRET, &

NGROUP, NI(NROW), NOUT, NRMISS

REAL X(LDX,NCOL)

DATA (X(1,J),J=1,3)/1.0, 1., 1./

DATA (X(2,J),J=1,3)/2.0, 2., 1./

DATA (X(3,J),J=1,3)/3.0, 1., 1./

DATA (X(4,J),J=1,3)/4.0, 1., 1./

DATA (X(5,J),J=1,3)/5.0, 2., 2./

DATA (X(6,J),J=1,3)/6.0, 1., 2./

DATA (X(7,J),J=1,3)/7.0, 1., 2./

DATA (X(8,J),J=1,3)/8.0, 1., 1./

DATA (X(9,J),J=1,3)/9.0, 2., 2./

DATA (X(10,J),J=1,3)/9.0, 1., 1./

DATA INDKEY/2, 3/

X(5,3) = AMACH(6)

X(7,2) = AMACH(6)

CALL SROWR (X, INDKEY, IPERM, NGROUP, NI, NRMISS=NRMISS)

CALL WRRRN ('X', X)

CALL WRIRN ('IPERM', IPERM)

CALL WRIRN ('NI', NI, NGROUP, 1, NGROUP)

CALL UMACH (2, NOUT)

WRITE (NOUT,*) ' '

WRITE (NOUT,*) 'NRMISS = ', NRMISS

END

Output

1 2 3

1 1.000 1.000 1.000

2 9.000 1.000 1.000

3 3.000 1.000 1.000

4 4.000 1.000 1.000

5 8.000 1.000 1.000

6 6.000 1.000 2.000

7 2.000 2.000 1.000

8 9.000 2.000 2.000

9 7.000 NaN 2.000

10 5.000 2.000 NaN

IPERM

1 1

2 10

3 3

4 4

5 8

6 6

7 2

8 9

9 7

10 5

1 5

2 1

3 1

4 1

NRMISS = 2