NAG Toolbox: nag_surviv_coxmodel_risksets (g12za)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{ns}$ – int64int32nag_int scalar

The number of strata. If $\mathbf{ns}>0$ then the stratum for each observation must be supplied in isi.

Constraint: $\mathbf{ns}\ge 0$.

2:     $\mathrm{z}\left(\mathit{ldz},\mathbf{m}\right)$ – double array

ldz, the first dimension of the array, must satisfy the constraint $\mathit{ldz}\ge \mathbf{n}$.

The $i$th row must contain the covariates which are associated with the $i$th failure time given in t.

3:     $\mathrm{isz}\left(\mathbf{m}\right)$ – int64int32nag_int array

Indicates which subset of covariates are to be included in the model.

$\mathbf{isz}\left(j\right)\ge 1$

The $j$th covariate is included in the model.

$\mathbf{isz}\left(j\right)=0$

The $j$th covariate is excluded from the model and not referenced.

Constraint: $\mathbf{isz}\left(j\right)\ge 0$ and at least one value must be nonzero.

4:     $\mathrm{ip}$ – int64int32nag_int scalar

$p$, the number of covariates included in the model as indicated by isz.

Constraint: $\mathbf{ip}=$ the number of nonzero values of isz.

5:     $\mathrm{t}\left(\mathbf{n}\right)$ – double array

The vector of $n$ failure censoring times.

6:     $\mathrm{ic}\left(\mathbf{n}\right)$ – int64int32nag_int array

The status of the individual at time $t$ given in t.

$\mathbf{ic}\left(i\right)=0$

Indicates that the $i$th individual has failed at time $\mathbf{t}\left(i\right)$.

$\mathbf{ic}\left(i\right)=1$

Indicates that the $i$th individual has been censored at time $\mathbf{t}\left(i\right)$.

Constraint: $\mathbf{ic}\left(\mathit{i}\right)=0$ or $1$, for $\mathit{i}=1,2,\dots ,\mathbf{n}$.

7:     $\mathrm{isi}\left(:\right)$ – int64int32nag_int array

The dimension of the array isi must be at least $\mathbf{n}$ if $\mathbf{ns}>0$, and at least $1$ otherwise

If $\mathbf{ns}>0$, the stratum indicators which also allow data points to be excluded from the analysis.

If $\mathbf{ns}=0$, isi is not referenced.

$\mathbf{isi}\left(i\right)=k$

Indicates that the $i$th data point is in the $k$th stratum, where $k=1,2,\dots ,\mathbf{ns}$.

$\mathbf{isi}\left(i\right)=0$

Indicates that the $i$th data point is omitted from the analysis.

Constraint: if $\mathbf{ns}>0$, $0\le \mathbf{isi}\left(\mathit{i}\right)\le \mathbf{ns}$, for $\mathit{i}=1,2,\dots ,\mathbf{n}$.

8:     $\mathrm{mxn}$ – int64int32nag_int scalar

The first dimension of the array x and the dimension of the arrays ixs and id.

Constraint: mxn must be sufficiently large for the arrays to contain the expanded risk sets. The size will depend on the pattern of failures times and censored times. The minimum value will be returned in num unless the function exits with $\mathbf{ifail}=\mathbf{1}$ or $\mathbf{2}$.

Optional Input Parameters

1:     $\mathrm{n}$ – int64int32nag_int scalar

Default: the dimension of the arrays t, ic and the first dimension of the array z. (An error is raised if these dimensions are not equal.)

$n$, the number of data points.

Constraint: $\mathbf{n}\ge 2$.

2:     $\mathrm{m}$ – int64int32nag_int scalar

Default: the dimension of the array isz and the second dimension of the array z. (An error is raised if these dimensions are not equal.)

The number of covariates in array z.

Constraint: $\mathbf{m}\ge 1$.

Output Parameters

1:     $\mathrm{num}$ – int64int32nag_int scalar

The number of values in the combined risk sets.

2:     $\mathrm{ixs}\left(\mathbf{mxn}\right)$ – int64int32nag_int array

The factor giving the risk sets/strata for the data in x and id.

If $\mathbf{ns}=0$ or $1$, $\mathbf{ixs}\left(i\right)=l$ for members of the $l$th risk set.

If $\mathbf{ns}>1$, $\mathbf{ixs}\left(i\right)=\left(j-1\right)\times \mathbf{nd}+l$ for the observations in the $l$th risk set for the $j$th strata.

3:     $\mathrm{nxs}$ – int64int32nag_int scalar

The number of levels for the risk sets/strata factor given in ixs.

4:     $\mathrm{x}\left(\mathbf{mxn},\mathbf{ip}\right)$ – double array

The dimension of the array x will be $\mathbf{num}$

The first num rows contain the values of the covariates for the members of the risk sets.

5:     $\mathrm{id}\left(\mathbf{mxn}\right)$ – int64int32nag_int array

Indicates if the member of the risk set given in x failed.

$\mathbf{id}\left(i\right)=1$ if the member of the risk set failed at the time defining the risk set and $\mathbf{id}\left(i\right)=0$ otherwise.

6:     $\mathrm{nd}$ – int64int32nag_int scalar

The number of distinct failure times, i.e., the number of risk sets.

7:     $\mathrm{tp}\left(\mathbf{n}\right)$ – double array

$\mathbf{tp}\left(\mathit{i}\right)$ contains the $\mathit{i}$th distinct failure time, for $\mathit{i}=1,2,\dots ,\mathbf{nd}$.

8:     $\mathrm{irs}\left(\mathbf{n}\right)$ – int64int32nag_int array

Indicates rows in x and elements in ixs and id corresponding to the risk sets. The first risk set corresponding to failure time $\mathbf{tp}\left(1\right)$ is given by rows $1$ to $\mathbf{irs}\left(1\right)$. The $\mathit{l}$th risk set is given by rows $\mathbf{irs}\left(\mathit{l}-1\right)+1$ to $\mathbf{irs}\left(\mathit{l}\right)$, for $\mathit{l}=1,2,\dots ,\mathbf{nd}$.

9:     $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

   $\mathbf{ifail}=1$

On entry,	$\mathbf{m}<1$,
or	$\mathbf{n}<2$,
or	$\mathbf{ns}<0$,
or	$\mathit{ldz}<\mathbf{n}$.

   $\mathbf{ifail}=2$

On entry,	$\mathbf{isz}\left(i\right)<0$ for some $i$,
or	the value of ip is incompatible with isz,
or	$\mathbf{ic}\left(i\right)\ne 1$ or $0$.
or	$\mathbf{ns}>0$ and $\mathbf{isi}\left(i\right)<0$,
or	$\mathbf{ns}>1$ and $\mathbf{isi}\left(i\right)>\mathbf{ns}$.

   $\mathbf{ifail}=3$

mxn is too small, the minimum value is returned in num.

   $\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

   $\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: g12za_example

function g12za_example


fprintf('g12za example results\n\n');

% Data
n = 42;
m = 1;
z          = zeros(n,m);
ic         = zeros(n,1,'int64');
ic(31:end) = 1;
z(22:end)  = 1;
isz        = [int64(1)];

t = [ 1;      1;      2;      2;      3;      4;      4;
      5;      5;      8;      8;      8;      8;     11;
     11;     12;     12;     15;     17;     22;     23;
      6;      6;      6;      7;     10;     13;     16;
     22;     23;      6;      9;     10;     11;     17;
     19;     20;     25;     32;     32;     34;     35];

% Parameters
ns  = int64(0);
ip  = int64(m);
isi = [int64(0)];
mxn = int64(1000);

% Create risk set
[num, ixs, nxs, x, id, nd, tp, irs, ifail] = ...
  g12za(...
        ns, z, isz, ip, t, ic, isi, mxn);

% Parameters for conditional logistic analysis
tol = 1e-05;
maxit = int64(10);

% initial estimate
b   = zeros(m,1);
% Calculate parameter estimates
[dev, b, se, sc, covar, nca, nct, ifail] = ...
g11ca( ...
       nxs, x, isz, id, ixs, b, tol, maxit, 'n', num);

% Display results
ns = max(ns,1);
fprintf(' Parameter      Estimate       Standard Error\n\n');
ivar = [1:m]';
fprintf('%6d%18.4f%18.4f\n',[ivar b se]');

g12za example results

 Parameter      Estimate       Standard Error

     1            1.6282            0.4331