Stata 15 help for mf_sort

[M-5] sort() -- Reorder rows of matrix

Syntax

transmorphic matrix sort(transmorphic matrix X, real rowvector idx)

void _sort(transmorphic matrix X, real rowvector idx)

transmorphic matrix jumble(transmorphic matrix X)

void _jumble(transmorphic matrix X)

real colvector order(transmorphic matrix X, real rowvector idx)

real colvector unorder(real scalar n)

void _collate(transmorphic matrix X, real colvector p)

where

1. X may not be a pointer matrix.

2. p must be a permutation column vector, a 1 x c vector containing the integers 1, 2, ..., c in some order.

Description

sort(X, idx) returns X with rows in ascending or descending order of the columns specified by idx. For instance, sort(X, 1) sorts X on its first column; sort(X, (1,2)) sorts X on its first and second columns (meaning rows with equal values in their first column are ordered on their second column). In general, the ith sort key is column abs(idx[i]). Order is ascending if idx[i]>0 and descending otherwise. Ascending and descending are defined in terms of [M-5] abs() (length of elements) for complex.

_sort(X, idx) does the same as sort(X, idx), except that X is sorted in place.

jumble(X) returns X with rows in random order. For instance, to shuffle a deck of cards numbered 1 to 52, one could code jumble(1::52). See rseed() in [M-5] runiform() for information on setting the random-number seed.

_jumble(X) does the same as jumble(X), except that X is jumbled in place.

order(X, idx) returns the permutation vector -- see [M-1] permutation -- that would put X in ascending (descending) order of the columns specified by idx. A row-permutation vector is a 1 x c column vector containing the integers 1, 2, ..., c in some order. Vectors (1\2\3), (1\3\2), (2\1\3), (2\3\1), (3\1\2), and (3\2\1) are examples. Row-permutation vectors are used to specify the order in which the rows of a matrix X are to appear. If p is a row-permutation vector, X[p, .] returns X with its rows in the order of p; p=(3\2\1) would reverse the rows of X. order(X, idx) returns the row-permutation vector that would sort X and, as a matter of fact, sort(X, idx) is implemented as X[order(X, idx), .].

unorder(n) returns a 1 x n permutation vector for placing the rows in random order. Random numbers are calculated by runiform(); see rseed() in [M-5] runiform() for information on setting the random-number seed. jumble() is implemented in terms of unorder(): jumble(X) is equivalent to X[unorder(rows(X)), .].

_collate(X, p) is equivalent to X = X[p, .]; it changes the order of the rows of X. _collate() is used by _sort() and _jumble() and has the advantage over subscripting in that no extra memory is required when the result is to be assigned back to itself. Consider

X = X[p, .]

There will be an instant after X[p, .] has been calculated but before the result has been assigned back to X when two copies of X exist. _collate(X, p) avoids that. _collate() is not a substitute for subscripting in all cases; _collate() requires p be a permutation vector.

Remarks

If X is complex, the ordering is defined in terms of [M-5] abs() of its elements.

Also see invorder() and revorder() in [M-5] invorder(). Let p be the permutation vector returned by order():

p = order(X, ...)

Then X[p,.] are the sorted rows of X. revorder() can be used to reverse sort order: X[revorder(p),.] are the rows of X in the reverse of the order of X[p,.]. invorder() provides the inverse transform: If Y = X[p,.], then X = Y[invorder(p),.].

Conformability

sort(X, idx), jumble(X): X: r1 x c1 idx: 1 x c2, c2 <= c1 result: r1 x c1

_sort(X, idx), _jumble(X): X: r1 x c1 idx: 1 x c2, c2 <= c1 result: void; X row order modified

order(X, idx): X: r1 x c1 idx: 1 x c2, c2 <= c1 result: r1 x 1

unorder(n): n: 1 x 1 result: n x 1

_collate(X, p): X: r x c p: r x 1 result: void; X row order modified

Diagnostics

sort(X, idx) aborts with error if any element of abs(idx) is less than 1 or greater than rows(X).

_sort(X, idx) aborts with error if any element of abs(idx) is less than 1 or greater than rows(X), or if X is a view.

_jumble(X) aborts with error if X is a view.

order(X, idx) aborts with error if any element of abs(idx) is less than 1 or greater than rows(X).

unorder(n) aborts with error if n<1.

_collate(X, p) aborts with error if p is not a permutation vector or if X is a view.

Source code

sort.mata, _sort.mata, jumble.mata, _jumble.mata, unorder.mata

order() and _collate() are built in.


© Copyright 1996–2018 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index