help for normalrir (Roger Newson)

Calculate ridits of inverse ridits between Normal populations

normalrir newvarname [if exp] [in range] ,
uniform(expression_1) [
mu(expression_2)
sd(expression_3)
muzero(expression_4)
sdzero(expression_5)
float
]

where expression_i (for i an integer} is a numeric expression.
The numeric expression for each
option must be in the form required by the generate command. That is to say,
each expression must be specified so that the command

gene double newvarname=(expression)

will work.

Description

normalrir inputs expressions to deliver, respectively, a uniform deviate variable,
2 means for 2 Normal populations (Population 1 and Population 0),
and 2 standard deviations for the same 2 Normal populations.
It outputs a new variable, containing, in each observation,
the ridit with respect to Population 0
of a value sampled from Population 1,
whose Normal cumulative distribution function for Population 1 has the value of the uniform deviate variable
in the same observation.
normalrir can be used with the SSC packages expgen and powercal
to perform multi-scenario power and sample size calculations for the 2-sample rank statistics
Somers' D and Harrell's c,
assuming that there exists an unspecified transformation that transforms the outcome variable
to a variable with a Normal distribution in each of the 2 populations
from which the 2 samples are sampled.

Options

uniform(expression_1) gives an expression,
whose value is interpreted as a uniform deviate from the continuous uniform distribution from 0 to 1.
This option is required.
The output variable will have a nonmissing value in and only in observations
in which the uniform() expression evaluates to a value in the closed interval
from 0 to 1 inclusive.

mu(expression_2) gives an expression, whose value is the mean of Population 1.
If absent, it is set to 0.
Note that the expression may contain variables and/or scalars and/or constants,
but defines a variable whose values are different in different observations,
because we may be comparing multiple pairs of populations in different observations,
as in a multi-scenario power calculation..

sd(expression_3) gives an expression,
whose value is the standard deviation of Population 1.
If absent, it is set to 1.

muzero(expression_4) gives an expression,
whose value is the mean of Population 0.
If absent, it is set to 0.

sdzero(expression_5) gives an expression,
whose value is the standard deviation of Population 0.
If absent, it is set to 1.

float specifies that the output variable will have a storage type no higher than float.
If float is not specified, then normalrir creates the output variable with storage type double.
Whether or not float is specified, normalrir compresses the output variable as much as possible
without loss of precision. (See help for compress.)

Methods and formulas

normalrir computes the ridits, with respect to Population 0,
of the inverse ridits, with respect to Population 1,
of the uniform deviates supplied by the uniform() option.
Ridits were introduced in Bross (1958),
and are equal, for a continuously-distributed variable,
to the cumulative distribution function (CDF)
of the population with respect to which the ridits are defined.
More precisely, the ridit with respect to Population 0
of the inverse ridit with respect to Population 1
of a value U in the closed interval from 0 to 1 inclusive
is denoted as RIR_01(U), and is defined as 0 for U=0, 1 for U=1,
and

RIR_01(U) = F_0(invF_1(U))

if 0<U<1, where F_i(.) is the CDF of Population i,
invF_i(.) is the inverse CDF of Population i,
and i can be 0 or 1.
normalrir assumes that F_1(.) belongs to a Normal distribution,
with mean and standard deviation (SD) supplied by the mu() and sd() expressions,
and that F_0() belongs to a Normal distribution,
with mean and SD supplied by the muzero() and sdzero() expressions.

The main appication of ridits of inverse ridits is in power calculations for 2-sample rank statistics,
estimating the 2-sample parameters Harrell's c(Y|X) and Somers' D(Y|X),
where X is a binary variable indicating membership of Subpopulation 1 instead of Subpopulation 0,
and Y is an outcome variable,
assumed by normalrir to be transformable, using an unidentified transformation,
to a variable with a Normal distribution
within each of the 2 subpopulations (1 and 0).
By the argument of Chapter 5 of Serfling (1980),
the asymptotic distribution of the sample estimate of Harrell's c(Y|X)
is Normal,
with a sampling variance which converges in ratio
(as the sample numbers become large and their ratio stays the same)
to

Var[RIR_01(U)]/N_1 + Var[RIR_10(U)]/N_0,

where U is a uniform deviate distributed between 0 and 1,
RIR_10() is the ridit with respect to Population 1
of the inverse ridit with respect to Population 0,
and N_1 and N_0 are the sample numbers of individuals
sampled from Population 1 and Population 0, respectively.
The 2 variances can be estimated numerically,
using normalrir with the collapse command in Stata,
and then used in power calculations,
using the SSC package powercal described in
Newson (2004).
The SSC package expgen can be very useful here,
especially if the power calculations are multi-scenario.

For more about the estimation of Somers D and Harrell's c using Stata,
see Newson (2006).
For more about the details of the maths behind normalrir,
see Newson (2017).

Examples

The following examples use a generated dataset,
with a single variable containing a uniform deviate,
with values spanning the closed interval from 0 to 1 inclusive.
We then use normalrir to define new variables,
containing the ridits with rspect to Population 0
of the inverse ridits with repect to Population 1,
and use scatter to plot the ridits of inverse ridits against the original uniform deviates.
The 3 ridits of inverse ridits assume, respectively,
that Populations 0 and 1
have the same SD and the same mean,
the same SD and different means,
and different SDs and different means.

Set-up:

. clear

. set obs 101

. gene unidev=(_n-1)/(_N-1)

. lab var unidev "Uniform deviate"

. summ unidev, detail

Simple examples:

. normalrir rir1, uniform(unidev)

. scatter rir1 unidev

. normalrir rir2, uniform(unidev) mu(2) muzero(1)

. scatter rir2 unidev

. normalrir rir3, uniform(unidev) mu(2) muzero(1) sd(1) sdzero(0.5)

. scatter rir3 unidev

Author

Roger Newson, Imperial College London, UK.
Email: r.newson@imperial.ac.uk

References

Bross, I. D. J. 1958.
How to use ridit analysis.
Biometrics 14(1): 18-38.

Newson, R. B.
2017.
Asymptotic distributions of two-sample rank statistics for continuous outcomes.
Download from
Roger Newson's website.

Newson, R.
2006.
Confidence intervals for rank statistics: Somers' D and extensions.
The Stata Journal 6(3): 309-334.
Download from
The Stata Journal website.

Newson, R.
2004.
Generalized power calculations for generalized linear models and more.
The Stata Journal 4(4): 379-401.
Download from
The Stata Journal website.

Serfling R. J. 1980. Approxination Theorems of Mathematical Statistics. New York, NY: John Wiley & Sons.

Also see

Manual: [R] collapse, [G2] graph twoway scatter

On-line: help for collapse, scatter

help for powercal, somersd, expgen (if installed)