{smcl}
{* 23oct2020}{...}
{cmd:help mata mm_ranks()}
{hline}

{title:Title}

{p 4 17 2}
{bf:mm_ranks() -- Compute ranks or cumulative frequencies}


{title:Syntax}

{p 8 24 2}
{it:real matrix}{bind:    }
{cmd:mm_ranks(}{it:X} [{cmd:,} {it:w}{cmd:,} {it:ties}{cmd:,} {it:mid}{cmd:,} {it:norm}]{cmd:)}

{p 8 24 2}
{it:real colvector}{bind: }
{cmd:_mm_ranks(}{it:x} [{cmd:,} {it:w}{cmd:,} {it:ties}{cmd:,} {it:mid}{cmd:,} {it:norm}]{cmd:)}


{pstd}
where

{p 14 18 2}{it:X}:  {it:real matrix} containing data (rows are observations, columns variables)

{p 14 18 2}{it:x}:  {it:real colvector} containing data (single variable)

{p 14 18 2}{it:w}:  {it:real colvector} containing weights

{p 11 18 2}{it:ties}:  {it:real scalar} determining the treatment of ties{p_end}
{p 18 18 2}{it:ties}=0: randomly split ties (default){p_end}
{p 18 18 2}{it:ties}=1: use highest rank{p_end}
{p 18 18 2}{it:ties}=2: use average rank{p_end}
{p 18 18 2}{it:ties}=3: use lowest rank{p_end}
{p 18 18 2}{it:ties}=4: order ties by {it:w}

{p 12 18 2}{it:mid}:  {it:real scalar} requesting midpoint adjustment

{p 11 18 2}{it:norm}:  {it:real scalar} requesting that the ranks be normalized


{title:Description}

{pstd}
{cmd:mm_ranks()} returns for each column of {it:X} the ranks of the values
in {it:X}, where the smallest value is ranked highest (i.e. rank 1
is returned for the smallest value, rank 2 for the second smallest,
etc.). Seen differently, {cmd:mm_ranks()} returns the absolute cumulative
frequency distribution of each column of {it:X} or, if {it:norm}!=0 is specified,
the relative cumulative distribution.

{pstd}
{it:w} specifies weights associated
with the observations (rows) in {it:X}. Omit {it:w} or specify {it:w} as 1 to
obtain unweighted results. Using {it:w}!=1 does not seem to make much sense if
the result is to be interpreted as ranks. It is useful, however, to compute the
cumulative frequency distribution from weighted data.

{pstd}
The default is to return ranks in random order where outcome values are
tied. Alternatively, specify {it:ties}==1
to assign the highest occurring rank to tied observations,
{it:ties}==2 to assign mean ranks, or
{it:ties}==3 to assign the lowest rank. Example:

        {com}: x = (1,2,2,3)'
        {res}
        {com}: x, mm_ranks(x,1,0), mm_ranks(x,1,1), mm_ranks(x,1,2),
        >    mm_ranks(x,1,3)
        {res}       {txt}  1     2     3     4     5
            {c TLC}{hline 31}{c TRC}
          1 {c |}  {res}  1     1     1     1     1{txt}  {c |}
          2 {c |}  {res}  2     2     2   2.5     3{txt}  {c |}
          3 {c |}  {res}  2     3     2   2.5     3{txt}  {c |}
          4 {c |}  {res}  3     4     4     4     4{txt}  {c |}
            {c BLC}{hline 31}{c BRC}{txt}

{pstd}Furthermore, {it:ties}==4 ranks tied observations in order of
{it:w} (observations with smallest weights are ranked highest). If
{it:w} is constant within ties, {it:ties}==4 is equivalent to {it:ties}==0.

{pstd}
Argument {it:mid}!=0 applies midpoint adjustment. In this case, at each step in the
distribution, the value of the midpoint of the step is returned. For example,
the first rank will be 0.5, not 1; the second rank will be 1.5, not 2, etc.

{pstd}
Argument {it:norm}!=0 normalizes the ranks by dividing them by the
number of observations (or sum of weights, if weights have been specified).

{pstd}
{cmd:_mm_ranks()} is like {cmd:mm_ranks()}, but assumes that the data has
already been sorted (and, consequently, only accepts a single column as data
input). Note that {cmd:_mm_ranks()} makes no distinction between {it:ties}=0 and
{it:ties}=4; in both cases, ties will be split in order of their
appearance. That is, {cmd:_mm_ranks()} takes the order of the data as given and
does not rerandomize the order of ties.


{title:Conformability}

    {cmd:mm_ranks(}{it:X}{cmd:,} {it:w}{cmd:,} {it:ties}{cmd:,} {it:mid}{cmd:,} {it:norm}{cmd:)}:
             {it:X}:  {it:r x c}
             {it:w}:  {it:r x} 1 or 1 {it:x} 1
          {it:ties}:  1 {it:x} 1
           {it:mid}:  1 {it:x} 1
          {it:norm}:  1 {it:x} 1
        {it:result}:  {it:r x c}

    {cmd:_mm_ranks(}{it:x}{cmd:,} {it:w}{cmd:,} {it:ties}{cmd:,} {it:mid}{cmd:,} {it:norm}{cmd:)}:
             {it:x}:  {it:r x} 1
             {it:w}:  {it:r x} 1 or 1 {it:x} 1
          {it:ties}:  1 {it:x} 1
           {it:mid}:  1 {it:x} 1
          {it:norm}:  1 {it:x} 1
        {it:result}:  {it:r x} 1


{title:Diagnostics}

{pstd}
The functions return all ranks as missing if the weights contain missing
values. Missing values in {it:X} are ranked lowest.


{title:Source code}

{pstd}
{help moremata_source##mm_ranks:mm_ranks.mata}


{title:Author}

{pstd}
Ben Jann, University of Bern, ben.jann@soz.unibe.ch


{title:Also see}

{p 4 13 2}
Online:  help for {helpb cumul},
{helpb egen:egen rank()},
{helpb mf_mm_ecdf:mm_ecdf()},
{helpb mf_mm_relrank:mm_relrank()},
{helpb moremata}