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 0
Cut 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 


0   1  
0   0  
0   1  

0.25 
1   2  


HRISK   1     1   2  



HRISK 

1   -1  
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  0
0  0  1
0  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   0
1   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 ? 

Download the following files : 

. 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