help mata _somdtransf

Title

_somdtransf() -- Transformations used by somersd

Syntax

void
_somdtransf(transf,
theta,
zeta [ ,
dzeta ])

where

transf: string scalar
theta: real matrix
zeta: real matrix
dzeta: real matrix

Description

This function is used by somersd to perform the
transformations specified by the transf() option and described in the
file somersd.pdf, which is distributed with the somersd package.

_somdtransf(transf, theta, zeta,
dzeta) inputs a string scalar in transf, which specifies one
of the transformations used by the transf() option of somersd, and
a matrix theta, containing values for Somers' D or Kendall's tau-a.
It outputs a matrix zeta, with the same dimensions as theta,
containing the transformed values, and, optionally, a matrix dzeta, with
the same dimensions, containing the derivatives of the transformed values with
respect to the untransformed values. Either zeta or dzeta, but not
both, may be the same matrix as theta, which is then overwritten. Some
transformations, or their derivatives, are undefined for untransformed values
of 1 and -1 and may be too large to be calculated at values close to 1 or -1.
In these cases, somdtransf() uses a maximum value thetamax, slightly
less than one, and sets the transformed values and their derivatives to the
transformed value and derivative for thetamax for untransformed values
above thetamax and sets the transformed values and their derivatives
to the transformed value and derivative for -thetamax for untransformed
values below -thetamax.
The value of thetamax depends on the
transformation specified by the string scalar transf.
If the string scalar transf
contains a value other than one of the transformation names recognized by the
transf() option of somersd, then all the transformed values and
their derivatives are set to missing.

Remarks

The value of the maximum untransformed value thetamax depends on the
value of transf, which specifies a transformation recognized by the
transf() option of somersd. The recognized values, and
corresponding maximum untransformed values, are as follows:

transf

thetamax

iden 1
z 0.999999999999999
asin 0.999999999999999
rho 1
zrho 0.99999999
c 1

These values ensure that any value of Somers' D or Kendall's tau-a from
-1 to 1 will have a nonmissing transformed value and derivative. These values
will not be strictly correct for untransformed values of magnitude greater
than thetamax. However, confidence intervals generated by somersd
for such untransformed values should probably not be taken seriously, because
these confidence intervals are calculated by the delta-jackknife
method and work by the Central Limit Theorem, which does not work well
for such extreme population values of Somers' D and Kendall's tau-a. The
formulas for all these transformations, and for their derivatives and
inverses, are given in the manual somersd.pdf, distributed with the
somersd package.

Conformability

_somdtransf(transf, theta, zeta, dzeta):
transf: 1 x 1
theta: M x N
zeta: M x N
dzeta: M x N

Diagnostics

_somdtransf(transf, theta, zeta,
dzeta) returns missing values of zeta and dzeta for
values of theta greater than 1, or less than -1, or for unrecognized
values of transf.

Source code

_somdtransf.mata

Author

Roger Newson, Imperial College London, UK.

Email: r.newson@imperial.ac.uk

Also see

Manual: [M-0] intro

Online: mata,

somersd (if installed)