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)