{smcl}
{cmd:help mata somdtransf}
{hline}

{title:Title}

{p 4 4 2}
{bf:somdtransf() -- Transformations used by somersd}


{title:Syntax}

{p 8 8 2}
{it:void}{bind:          }
{cmd:_somdtransf(}{it:transf}{cmd:,} 
{it:theta}{cmd:,}
{it:zeta} [ {cmd:,}
{it:dzeta} ]{cmd:)}

{p 4 4 2}
where

               {it:transf}:  {it:string scalar}
                {it:theta}:  {it:real matrix}
                 {it:zeta}:  {it:real matrix}
                {it:dzeta}:  {it:real matrix}


{title:Description}

{p 4 4 2}
This function is used by {helpb somersd} to perform the
transformations specified by the {cmd:transf()} option and described in the
file {hi:somersd.pdf}, which is distributed with the {cmd:somersd} package.

{p 4 4 2}
{cmd:somdtransf(}{it:transf}{cmd:,} {it:theta}{cmd:,} {it:zeta}{cmd:,}
{it:dzeta}{cmd:)} inputs a string scalar in {it:transf}, which specifies one
of the transformations used by the {cmd:transf()} option of {cmd:somersd}, and
a matrix {it:theta}, containing values for Somers' {it:D} or Kendall's tau-a.
It outputs a matrix {it:zeta}, with the same dimensions as {it:theta},
containing the transformed values, and, optionally, a matrix {it:dzeta}, with
the same dimensions, containing the derivatives of the transformed values with
respect to the untransformed values.  Either {it:zeta} or {it:dzeta}, but not
both, may be the same matrix as {it: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, {cmd:tidottree()} uses a maximum value {it:thetamax}, slightly
less than one, and sets the transformed values and their derivatives to the
transformed value and derivative for {it:thetamax} for untransformed values
from {it:thetamax} to 1 and sets the transformed values and their derivatives
to the transformed value and derivative for {it:-thetamax} for untransformed
values from -1 to {it:-thetamax}.  The value of {it:thetamax} depends on the
transformation specified by the string scalar {it: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 {it:transf}
contains a value other than one of the transformation names recognized by the
{cmd:transf()} option of {helpb somersd}, then all the transformed values and
their derivatives are set to missing.


{title:Remarks}

{p 4 4 2}
The value of the maximum untransformed value {it:thetamax} depends on the
value of {it:transf}, which specifies a transformation recognized by the
{cmd:transf()} option of {helpb somersd}.  The recognized values, and
corresponding maximum untransformed values, are as follows:

    {title:{it:transf}}          {title:{it:thetamax}}
    {hi:iden}            1
    {hi:z}               0.999999999999999
    {hi:asin}            0.999999999999999
    {hi:rho}             1
    {hi:zrho}            0.99999999
    {hi:c}               1

{p 4 4 2}
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 {it:thetamax}.  However, confidence intervals generated by {helpb 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' {it:D} and Kendall's tau-a. The
formulas for all these transformations, and for their derivatives and
inverses, are given in the manual {hi:somersd.pdf}, distributed with the
{helpb somersd} package.


{title:Conformability}

    {cmd:_somdtransf(}{it:transf}{cmd:,} {it:theta}{cmd:,} {it:zeta}{cmd:,} {it:dzeta}{cmd:)}:
	   {it:transf}:  1 {it:x} 1
	    {it:theta}:  {it:M x N}
	     {it:zeta}:  {it:M x N}
	    {it:dzeta}:  {it:M x N}


{title:Diagnostics}

{p 4 4 2}
{cmd:_somdtransf(}{it:transf}{cmd:,} {it:theta}{cmd:,} {it:zeta}{cmd:,}
{it:dzeta}{cmd:)} returns missing values of {it:zeta} and {it:dzeta} for
values of {it:theta} greater than 1, or less than -1, or for unrecognized
values of {it:transf}.


{title:Source code}

{p 4 4 2}
{view _somdtransf.mata, adopath asis:_somdtransf.mata}


{title:Author}

{p 4 4 2}
Roger Newson, Imperial College London, UK.{break}
Email: {browse "mailto:r.newson@imperial.ac.uk":r.newson@imperial.ac.uk}


{title:Also see}

{p 4 13 2}
Manual:  {hi:[M-0] intro}

{p 4 13 2}
Online:  {helpb mata}, {break}
         {helpb somersd} (if installed)
{p_end}