{smcl} {* 23oct2020}{...} {cmd:help mata mm_relrank()} {hline} {title:Title} {p 4 17 2} {bf:mm_relrank() -- Relative ranks (grade transformation)} {title:Syntax} {p 8 24 2} {it:real matrix}{bind: } {cmd:mm_relrank(}{it:X}{cmd:,} {it:w}{cmd:,} {it:Y} [{cmd:,} {it:mid}{cmd:,} {it:nonorm}{cmd:,} {it:break}{cmd:,} {it:w2}]{cmd:)} {p 8 24 2} {it:real colvector}{bind: } {cmd:_mm_relrank(}{it:x}{cmd:,} {it:w}{cmd:,} {it:y} [{cmd:,} {it:mid}{cmd:,} {it:nonorm}{cmd:,} {it:break}{cmd:,} {it:w2}]{cmd:)} {p 4 8 2} where {p 14 18 2}{it:X}: {it:real matrix} containing reference data (rows are observations, columns variables) {p_end} {p 14 18 2}{it:x}: {it:real colvector} containing reference data (single variable) {p_end} {p 14 18 2}{it:w}: {it:real colvector} containing weights associated with {it:X} {p_end} {p 14 18 2}{it:Y}: {it:real matrix} containing comparison data (rows are observations, columns variables) {p_end} {p 14 18 2}{it:y}: {it:real colvector} containing comparison data (single variable) {p_end} {p 12 18 2}{it:mid}: {it:real scalar} requesting midpoint adjustment {p_end} {p 9 18 2}{it:nonorm}: {it:real scalar} requesting the absolute ranks {p_end} {p 10 18 2}{it:break}: {it:real scalar} requesting that ties be broken {p_end} {p 13 18 2}{it:w2}: {it:real colvector} containing weights associated with {it:Y} {p_end} {title:Description} {pstd} {cmd:mm_relrank()} evaluates the relative ranks of {it:Y} in the distribution {it:X} (so called grade transformation). {pstd} Results will be obtained column by column. If {it:Y} has one column and {it:X} has several columns, then the relative ranks of {it:Y} are computed in each column of {it:X}. If {it:X} has one column and {it:Y} has several columns, then the relative ranks in {it:X} are computed for each column of {it:Y}. If {it:X} and {it:Y} both have several columns, then the number of columns is required to be the same and relative ranks are computed column by column. {pstd} Argument {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. {pstd} Argument {it:mid}!=0 applies midpoint adjustment. In this case, if a comparison value from {it:Y} has ties in the distribution of {it:X}, the midpoint of the corresponding step in the cumulative distribution of {it:X} is used as the relative rank. {it:mid}!=0 has no effect on relative ranks for values from {it:Y} that do not have ties in {it:X}. {pstd} Argument {it:nonorm}!=0 returns absolute ranks, that is, ranks expressed in frequency units. The default is return normalized ranks (i.e., ranks divided by the number of observations or sum of weights of {it:X}). {pstd} Argument {it:break}!=0 causes ties to be broken. Let {it:p} be the step size in the cumulative distribution at a particular value of {it:X} and let {it:y_i}, {it:i} = 1, ..., {it:k}, be the (randomly ordered) set of observations from {it:Y} that are equal to this particular value of {it:X}. The relative rank of {it:y_i} will then be obtained as the value of the cumulative distribution at the relevant point minus ({it:k}-{it:i})*({it:p}/{it:k}). If weights {it:w2} are specified, the set of tied values will be ordered by the size of {it:w2} (using random order within ties of {it:w2}) and the formula will be adjusted such that the increments in the relative ranks within ties are proportional to the size of {it:w2}. {pstd} Argument {it:w2} specifies weights associated with {it:Y}. These weights are only relevant if argument {it:break}!=0 is specified. {pstd} {cmd:_mm_relrank()} is like {cmd:mm_relrank()}, but assumes that both the reference data and the comparison data have already been sorted (and, consequently, only accepts single data columns as input). If {it:break}!=0 is specified, ties will be split in order of their appearance. That is, {cmd:_mm_relrank()} takes the order of {it:y} as given and does not rerandomize the order of ties or reorder the ties by {it:w2}. {title:Examples} {com}: x = jumble(1::10) {res} {com}: mm_ecdf2(x) {res} {txt} 1 2 {c TLC}{hline 11}{c TRC} 1 {c |} {res} 1 .1{txt} {c |} 2 {c |} {res} 2 .2{txt} {c |} 3 {c |} {res} 3 .3{txt} {c |} 4 {c |} {res} 4 .4{txt} {c |} 5 {c |} {res} 5 .5{txt} {c |} 6 {c |} {res} 6 .6{txt} {c |} 7 {c |} {res} 7 .7{txt} {c |} 8 {c |} {res} 8 .8{txt} {c |} 9 {c |} {res} 9 .9{txt} {c |} 10 {c |} {res}10 1{txt} {c |} {c BLC}{hline 11}{c BRC} {com}: y = (3,5.2,7,7,2.1)' {res} {com}: // default vs. mid!=0 : y, mm_relrank(x, 1, y), mm_relrank(x, 1, y, 1) {res} {txt} 1 2 3 {c TLC}{hline 19}{c TRC} 1 {c |} {res} 3 .3 .25{txt} {c |} 2 {c |} {res}5.2 .5 .5{txt} {c |} 3 {c |} {res} 7 .7 .65{txt} {c |} 4 {c |} {res} 7 .7 .65{txt} {c |} 5 {c |} {res}2.1 .2 .2{txt} {c |} {c BLC}{hline 19}{c BRC} {com}: // default vs. break!=0 : y, mm_relrank(x, 1, y), mm_relrank(x, 1, y, 0, 0, 1) {res} {txt} 1 2 3 {c TLC}{hline 19}{c TRC} 1 {c |} {res} 3 .3 .3{txt} {c |} 2 {c |} {res}5.2 .5 .5{txt} {c |} 3 {c |} {res} 7 .7 .7{txt} {c |} 4 {c |} {res} 7 .7 .65{txt} {c |} 5 {c |} {res}2.1 .2 .2{txt} {c |} {c BLC}{hline 19}{c BRC} {com}: // default vs. mid!=0 & break!=0 : y, mm_relrank(x, 1, y), mm_relrank(x, 1, y, 1, 0, 1) {res} {txt} 1 2 3 {c TLC}{hline 22}{c TRC} 1 {c |} {res} 3 .3 .25{txt} {c |} 2 {c |} {res} 5.2 .5 .5{txt} {c |} 3 {c |} {res} 7 .7 .625{txt} {c |} 4 {c |} {res} 7 .7 .675{txt} {c |} 5 {c |} {res} 2.1 .2 .2{txt} {c |} {c BLC}{hline 22}{c BRC} {com}: // default vs. nonorm!=0 : y, mm_relrank(x, 1, y), mm_relrank(x, 1, y, 0, 1) {res} {txt} 1 2 3 {c TLC}{hline 19}{c TRC} 1 {c |} {res} 3 .3 3{txt} {c |} 2 {c |} {res}5.2 .5 5{txt} {c |} 3 {c |} {res} 7 .7 7{txt} {c |} 4 {c |} {res} 7 .7 7{txt} {c |} 5 {c |} {res}2.1 .2 2{txt} {c |} {c BLC}{hline 19}{c BRC}{txt} {title:Conformability} {cmd:mm_relrank(}{it:X}{cmd:,} {it:w}{cmd:,} {it:Y}{cmd:,} {it:mid}{cmd:,} {it:nonorm}{cmd:,} {it:break}{cmd:,} {it:w2}]{cmd:)} {it:X}: {it:r1 x c1} {it:w}: {it:r1 x} 1 or 1 {it:x} 1 {it:Y}: {it:r2 x c2} {it:mid}: 1 {it:x} 1 {it:nonorm}: 1 {it:x} 1 {it:break}: 1 {it:x} 1 {it:w2}: {it:r2 x} 1 or 1 {it:x} 1 {it:result}: {it:r2 x c2} or {it:r2 x c1} {cmd:_mm_relrank(}{it:x}{cmd:,} {it:w}{cmd:,} {it:x}{cmd:,} {it:mid}{cmd:,} {it:nonorm}{cmd:,} {it:break}{cmd:,} {it:w2}]{cmd:)} {it:x}: {it:r1 x} 1 {it:w}: {it:r1 x} 1 or 1 {it:x} 1 {it:y}: {it:r2 x} 1 {it:mid}: 1 {it:x} 1 {it:nonorm}: 1 {it:x} 1 {it:break}: 1 {it:x} 1 {it:w2}: {it:r2 x} 1 or 1 {it:x} 1 {it:result}: {it:r2 x 1} {title:Diagnostics} {pstd} The functions return missing values for the relative ranks if {it:w} contains missing values. Missing values in {it:X} and {it:Y} are ordered last. {title:Source code} {pstd} {help moremata_source##mm_relrank:mm_relrank.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 mf_mm_ecdf:mm_ecdf()}, {helpb mf_mm_ranks:mm_ranks()}, {helpb moremata}