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)