```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, tidottree() 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 from thetamax to 1 and sets the transformed values
and their derivatives to the transformed value and derivative for
-thetamax for untransformed values from -1 to -thetamax.  The value of
thetamax depends on the transformation specified by the string scalar
transf.  If the untransformed value is greater than 1, or less than -1,
then the transformed value and its derivative are set to missing.  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
infinitesimal 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)
```