```help mata mm_unorder2()
-------------------------------------------------------------------------------

Title

mm_unorder2() -- Stable unorder

Syntax

real colvector       mm_unorder2(real scalar n)

transmorphic matrix  mm_jumble2(transmorphic matrix X)

void                 mm__jumble2(transmorphic matrix X)

where X may not be a pointer matrix.

Description

The results from official Stata's unorder() are not reproducible if n is
large. That is, differing results may be obtained from unorder(),
although the random-number seed has been set beforehand (see help for
[M-5] uniform()). mm_unorder2() is an improved version of official
unorder() that produces stable results.

mm_jumble2() and mm__jumble2() are stable versions of official jumble()
and _jumble().

For descriptions of unorder(), jumble(), and _jumble() see help for
[M-5] sort().

Remarks

The following example illustrates the problem:

: for (i=1;i<=10;i++) {
>         uniformseed(3)
>         p1 = unorder(100000)
>         uniformseed(3)
>         p2 = unorder(100000)
>         if (p1!=p2) {
>                 printf("round %g: unequal results\n", i)
>                 break
>         }
> }
round 2: unequal results

Explanation: uniform() may return duplicate pseudo random numbers due to
computer precision constraints. Example:

: uniformseed(3)

: rows(uniqrows(uniform(100000,1)))
99999

Since the results from unorder() rely on the sort order of uniform pseudo
random numbers and since the sort order of duplicate values is randomized
independently from the usual random-number seed, results from unorder()
may differ.

mm_unorder2() solves the problem by using two pseudo random-number
sequences instead of one.

Conformability

mm_unorder2(n):
n:  1 x 1
result:  n x  1

mm_jumble2(X):
X:  r1 x c1
result:  r1 x c1

mm__jumble2(X):
X:  r1 x c1
result:  void; X row order modified

Diagnostics

See help for [M-5] sort().

Source code

mm_unorder2.mata, mm_jumble2.mata, mm__jumble2.mata.

Author

Ben Jann, ETH Zurich, jann@soz.gess.ethz.ch

Also see

Manual:  [M-5] sort()

Online:  help for [M-5] sort(); moremata
```