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