 Institut de Santé Publique,
d'Épidémiologie et de Développement Centre Inserm U897
Equipe Biostatistique

MKVPCI 1.0 : USER GUIDE
Computer program for Markov models with piecewise constant intensities and covariates.

Programme pour l’estimation des modèles de Markov avec intensités de transition constantes par morceaux et covariables.

MKVPCI requires two input files : the data file (in ASCII format) and the control parameters file. The records in data file must contain the following variables in the order shown:      (j=0,1,… ; i=1,2,…,n),

where identify the ith subject (i=1,2,…,n), , ,…, represent the observed covariates at the observation time ; (j=0,1,… ), and is the state occupied by the ith subject at time .  It is required that records of the same subject be placed consecutively in an increasing order of . The data file must contain a total of lines; its name must be specified in the control file.

The following table gives a description of the input parameters required for running MKVPCI. The way of numbering the transition and the regression coefficients is very important for the use of the program and is explained in the first part of this table.

Input parameters

The following table gives a description of the input parameters required for running MKVPCI. The way of numbering the transition and the regression coefficients is very important for the use of the program and is explained in the first part of this table.

 Parameter Type Description FILENAME Character Name of the data file NOBS Integer Number of observations (lines) in the data file NOBS = NSTATE Integer Number of states in the model NTRANS Integer Number of transitions in the model MXTRANS Integer NSTATE NSTATE matrix with entries (h,j) equal to 1 if a transition from h to j is allowed, and 0 otherwise; entries (h,h) are all equal to 0. Important : the running numbers of transition from h to j with MXTRANS(h,j) 0 are : , if h=1 if h >1 R Integer Dimension of the vector of artificial covariates Important : R=0 corresponds to the time-homogeneous Markov model TAU(1,2,…,R) Real Use only if R 0Cut points which define the time intervals ; and need not to be specified INTRZ-m(1,2,…,NTRANS) Integer Use only if R 0 INTRZ-m(j)  is equal to the running number of the regression coefficient associated with the mth artificial covariate and the jth transition, if this coefficient is to be estimated   INTRZ-m(j) = 0, otherwise Important : the regression coefficients to be estimated must be numbered consecutively in an increasing running numbers of transition IEXACT Integer = 1 if the last state of the model is an absorbing state and if the transition times to this state are observed exactly   = 0, otherwise NCOV Integer Number of covariates in data file (observed covariates) NAMECVm Character Name of the mth observed covariate INMODm Integer = 1 if the mth observed covariate is to be included in the model   = 0, otherwise INTRZm(1,2,…,NTRANS) Integer INTRZm(j) is equal to the running number of the regression coefficient associated with the mth observed covariate and the jth transition, if this coefficient is to be estimated INTRZm(j)=0 if there is no effect of the mth observed covariate on the jth transition Note that the values of INTRZm(j) can be also used to constrain the effect of the mth observed covariate on different transitions VINIT Integer = 1 if the initial values of the parameters are to be calculated by the program   = 0 if the user wants to specify the initial values of the parameters NPAR Integer Use only if VINIT=0 :   Total number of parameters to be estimated VPARm Real Use only if VINIT=0 :   Initial value of the mth parameter IEST Integer = 1 if the parameters are to be estimated by the program   = 0 otherwise (in this case, only the covariance matrix of the parameters is calculated by the program) NHYP Integer Total number of multivariate hypotheses to be tested on the regression coefficients associated with the observed covariates(= 0 if there is no multivariate hypothesis to test) NMCOVm Character Use only if NHYP 0 :    Name of the observed covariate involved in the mth multivariate hypothesis NCONTm Integer Use only if NHYP 0 :    Dimension of the mth multivariate hypothesis MCONTm Integer Use only if NHYP 0 :   NCONTm NTRANS contrast matrix for the mth multivariate hypothesis

Parameter file

MKVPCI runs batch mode by reading a control parameters file, named imperatively FINPUT, which contains a set of required and optional input parameters in the order shown in following:

FILENAME
NOBS
NSTATE
NTRANS
MXTRANS(1,1)    MXTRANS(1,2) … MXTRANS(1,NSTATE)
MXTRANS(2,1)    MXTRANS(2,2) … MXTRANS(2,NSTATE).
...
MXTRANS(NSTATE,1)     MXTRANS(NSTATE,2) … MXTRANS(NSTATE,NSTATE)
R

The following sets of lines are required only if R 0

TAU(1)    TAU(2) … TAU(R)
INTRZ-1(1)           INTRZ-1(2) … INTRZ-1(NTRANS)
INTRZ-2(1)           INTRZ-2(2) … INTRZ-2(NTRANS)

...

INTRZ-R(1)           INTRZ-R(2) … INTRZ-R(NTRANS)

The following sets of lines are not optional and must be specified

IEXACT
NCOV
NAMECV1           INMOD1            INTRZ1(1)          INTRZ1(2) … INTRZ1(NTRANS
NAMECV2           INMOD2            INTRZ2(1)          INTRZ2(2) … INTRZ2(NTRANS
NAMECVNCOV      INMODNCOV       INTRZNCOV(1)     INTRZNCOV(2) …
INTRZNCOV(NTRANS)
VINIT

The following sets of lines are required only if the user wants to specify the initial values of the parameters (VINIT=0)

NPAR
VPAR1
VPAR2
...

VPARNPAR

The following two sets of lines are not optional and must be specified (put NHYP=0 if there is no hypothesis to test)

IEST
NHYP

The following sets of lines are required only if NHYP 0, which means that the user wants to test at least one multivariate hypothesis

NMCOV1
NCONT1
MCONT1(1,1)       MCONT1(1,2) … MCONT1(1,NTRANS)
...

MCONT1(NCONT1,1)        MCONT1(NCONT1,2) … MCONT1(NCONT1,NTRANS)
NMCOV2
NCONT2
MCONT2(1,1)       MCONT2(1,2) … MCONT2(1,NTRANS)
...

MCONT2(NCONT2,1)        MCONT2(NCONT2,2) … MCONT2(NCONT2,NTRANS)
...

NMCOVNHYP
NCONTNHYP
MCONTNHYP(1,1)  MCONTNHYP(1,2) … MCONTNHYP(1,NTRANS)
...

MCONTNHYP(NCONTNHYP,1)     MCONTNHYP(NCONTNHYP,2) … MCONTNHYP(NCONTNHYP,NTRANS)

Example

This is an example of running MKVPCI using data from a study of smoking behavior of school children taken from Kalbfleisch and Lawless (1985). The data concerned 125 children who were included in the study at their entry in sixth grade (t0=0), and were surveyed at times (in year) t1=0.15, t2=0.75, t3=1.10, and t4=1.19. There must be a total of 625 observations in the data file SMOKE.DAT (five lines for each children). At each follow-up time, children were classified in one of the following categories : (i) has never smoked (state 1), (ii) is currently a smoker (state 2), (iii) has smoked, but now quit (state 3). The Markov model was defined as follows:

state 1 state 2 state 3

A single observed covariate, coded HRISK=1 for children in the “high risk” group and HRISK=0 for the others, was considered. The control file FINPUT needed to fit a Markov model in which the transition intensities are two-step functions of time (R=1), and a single observed covariate HRISK (NCOV=1) is:

 smoke.dat 625 3  3 0   1   0  0   0   1 0   1   0 1 0.25 1   2   3 0 1 HRISK   1     1   2   3  1 1  1 HRISK 2 1   -1   0 1   0   -1

The meaning of the input parameters in this file are as follows:

 Parameters Signification smoke.dat name of the data file 625 total number of observations 3 three states in the model 3 number of transitions in the model 0  1  00  0  10  1  0 the transition matrix indicates that only transitions from state 1 to state 2, from state 2 to state 3, and from state 3 to state 2 are allowed in the model 1 there is two time intervals in which transition intensities may take different values 0.25 first interval: [0,0.25) ; second interval: [0.25, ) 0 the transition times to state 3 are not observed exactly ; in fact, state 3 is not an  absorbing state in this example 1 there is one observed covariate in the data file HRISK  1  1  2  3 the observed covariate  HRISK must be included in the model with different effect on each transition, so that three regression coefficients are to be estimated for HRISK 1 the program must calculate the initial values of the parameters 1 the program must estimate the model parameters 1 the user wants to test one multivariate hypothesis on the regression coefficients HRISK the multivariate hypothesis concerns the coefficients of HRISK 2 number of lines of the contrast matrix ; the number of columns of this matrix is always equal to the number of transition in the model 1   -1   01   0   -1 contrast matrix ; this indicates that the null hypothesis to be tested is defined as: , which means that HRISK has the same effect on all transitions

Output

Computational results are written in an output, named imperatively FOUTPUT. The input parameters, the type of model fitted, the maximum likelihood estimates of the model parameters, the estimated baseline transition intensities and their estimated standard errors in each interval , l=1,2,…,r+1, and the results of the multivariate hypotheses tests are included

How to use MKVPCI ?

. PC station

mkvpci-pc.f                  FORTRAN source file
mkvpci-pc.exe              executable file
smoke.dat                    span style="font-size: 10pt; ">data file for the example on children smoking behavior

finput                            example of control parameters file
foutput                          output file obtained using FINPUT

or

. Unix station

mkvpci-ux.f                   FORTRAN source file
mkvpci-ux                     executable file
smoke.dat                    data file for the example on children smoking behavior
finput                            example of control parameters file
foutput                          output file obtained using FINPUT

-  Compile, if necessary, the source file using a FORTRAN-77 compiler

-  Run the program (mkvpci-pc or mkvpci-ux) in a directory which contains the executable file, the data file and the control parameters file FINPUT