Package ‘gems’ Generalized Multistate Simulation Model - PDF document

Package`gems'March26,2017TypePackageTitleGeneralizedMultistateSimulationModelVersion1.1.1Date2017-03-26AuthorLuisaSalazarVizcaya,NelloBlaser,ThomasGsponerMaintainerLuisaSalazarVizcaya&#xluis; pao;&#xla.s; laz; rvi;&#xzcay; @in;&#xsel.;h00;ImportsMASS,methods,msm,plyr,graphics,stats,utils,data.tableSuggestsmuhazDescriptionSimulateandanalyzemultistatemodelswithgeneralhazardfunctions.gemsprovidesfunctionalityforthepreparationofhazardfunctionsandparameters,simulationfromageneralmultistatemodelandpredictingfutureevents.ThemultistatemodelisnotrequiredtobeaMarkovmodelandmaytakethehistoryofpreviouseventsintoaccount.Inthebasicversion,itallowstosimulatefromtransition-specichazardfunction,whoseparametersaremultivariablenormallydistributed.LicenseGPL-2RoxygenNote5.0.1NeedsCompilationnoRepositoryCRANDate/Publication2017-03-2616:02:51UTCRtopicsdocumented:ArtCohort..........................................2cumulativeIncidence....................................3gems.............................................4generateHazardMatrix...................................4generateParameterCovarianceMatrix............................5generateParameterMatrix..................................6PosteriorProbabilities....................................7simulateCohort.......................................81 2ArtCohorttavi.............................................11transition.structure.....................................11transitionProbabilities....................................13Index14 ArtCohortClass"ArtCohort" DescriptionIsaS4classforthearticialcohortgeneratedbysimulateCohort.Usage##S4methodforsignature'ArtCohort,ANY,ANY,ANY'x[i,j,...,drop=TRUE]##S4methodforsignature'ArtCohort'update(object,newsize,addbaseline=matrix(NA,nrow=newsize-object@size),newInitialStates=rep(1,newsize-object@size))##S4methodforsignature'ArtCohort'head(x,...)##S4methodforsignature'ArtCohort'tail(x,...)##S4methodforsignature'ArtCohort'summary(object)Argumentsx,objectanArtCohorti,j,dropsameasfordata.frame...passedontodata.framemethodnewsizesizeoftheupdatedcohortaddbaselinebaselinefornewpartofcohortnewInitialStatesinitialstatesfornewpartofcohortSlotsstates.numberObjectofclass"numeric":numberofstatessizeObjectofclass"numeric":cohortsizebaselineObjectofclass"matrix":baselinematrix cumulativeIncidence3follow.upObjectofclass"numeric":maximumfollow-uptimeparametersObjectofclass"transition.structure":inputparametersparametersCovariancesObjectofclass"transition.structure":inputcovariancematricestimeToTransitionObjectofclass"matrix":inputtimeToTransitionmatrix.logicalcomponentstransitionFunctionsObjectofclass"transition.structure":inputhazardfunctionstime.to.stateObjectofclass"data.frame":entrytimesforeachpatientintoeachofthestatesObjectsfromtheClassObjectsarecreatedbycallstothefunctionsimulateCohort.Author(s)LuisaSalazarVizcaya,NelloBlaser,ThomasGsponerSeeAlsosimulateCohort,transition.structure,transitionProbabilities,cumulativeIncidenceExamplesshowClass("ArtCohort") cumulativeIncidencetransitionprobabilities DescriptionCalculatesthecumulativeincidenceandpredictionintervalsafterrststateUsagecumulativeIncidence(object,times,M=100,stateNames=paste("State",as.list(1:dim(cohorts)[1])))ArgumentsobjecteithertheoutputofsimulateCohortorthematrixwiththeprobabilitiesslotofthatoutput.timesatimevector.Mnumberofgroupsforcalculatingcondenceintervals.stateNamesalistwiththenamesofstates. 4generateHazardMatrixValueanobjectofclass"PosteriorProbabilities",containingthestatenames,timepointsandthecu-mulativeincidencewithpointwisepredictionintervalsovertime.Author(s)LuisaSalazarVizcaya,NelloBlaser,ThomasGsponerReferencesNelloBlaser,LuisaSalazarVizcaya,JanneEstill,CindyZahnd,BinduKalesan,MatthiasEgger,OliviaKeiser,ThomasGsponer(2015).gems:AnRPackageforSimulatingfromDiseaseProgres-sionModels.JournalofStatisticalSoftware,64(10),1-22.URLhttp://www.jstatsoft.org/v64/i10/.SeeAlsoPosteriorProbabilities,ArtCohort,simulateCohort gemsgems:GeneralizedMultistateSimulationModel DescriptionSimulateandanalyzemultistatemodelswithgeneralhazardfunctions.gemsprovidesfunctionalityforthepreparationofhazardfunctionsandparameters,simulationfromageneralmultistatemodelandpredictingfutureevents.ThemultistatemodelisnotrequiredtobeaMarkovmodelandmaytakethehistoryofpreviouseventsintoaccount.Inthebasicversion,itallowstosimulatefromtransition-specichazardfunction,whoseparametersaremultivariablenormallydistributed.ReferencesNelloBlaser,LuisaSalazarVizcaya,JanneEstill,CindyZahnd,BinduKalesan,MatthiasEgger,OliviaKeiser,ThomasGsponer(2015).gems:AnRPackageforSimulatingfromDiseaseProgres-sionModels.JournalofStatisticalSoftware,64(10),1-22.URLhttp://www.jstatsoft.org/v64/i10/. generateHazardMatrixgeneratetemplatefortransitionfunctions DescriptionThisfunctionsimpliesgeneratingthematrixoftransitionfunctions.UsagegenerateHazardMatrix(statesNumber) generateParameterCovarianceMatrix5ArgumentsstatesNumberthenumberofstatestobeconsidered.Valueatransition.structureofdimensionNN,whereNisthenumberofstatesandwithvalue"impossible"forallpotentialtransitions.Author(s)LuisaSalazarVizcaya,NelloBlaser,ThomasGsponerReferencesNelloBlaser,LuisaSalazarVizcaya,JanneEstill,CindyZahnd,BinduKalesan,MatthiasEgger,OliviaKeiser,ThomasGsponer(2015).gems:AnRPackageforSimulatingfromDiseaseProgres-sionModels.JournalofStatisticalSoftware,64(10),1-22.URLhttp://www.jstatsoft.org/v64/i10/.SeeAlsotransition.structure,simulateCohort generateParameterCovarianceMatrixgenerateatemplateforparametercovariances DescriptionThisfunctionsimpliesgeneratingthematrixofparametercovariancesfromamatrixofmeanparameters.UsagegenerateParameterCovarianceMatrix(mu)Argumentsmuatransition.structureofdimensionNN,whosecomponentslistthemeanvaluesfortheparametersinthetransitionFunction.Valueatransition.structureofdimensionNNofcovariancematricesfortheparameters.Author(s)LuisaSalazarVizcaya,NelloBlaser,ThomasGsponer 6generateParameterMatrixReferencesNelloBlaser,LuisaSalazarVizcaya,JanneEstill,CindyZahnd,BinduKalesan,MatthiasEgger,OliviaKeiser,ThomasGsponer(2015).gems:AnRPackageforSimulatingfromDiseaseProgres-sionModels.JournalofStatisticalSoftware,64(10),1-22.URLhttp://www.jstatsoft.org/v64/i10/.SeeAlsotransition.structure,generateParameterMatrix,simulateCohort generateParameterMatrixgenerateatemplateformeanparameters DescriptionThisfunctionsimpliesgeneratingthematrixofmeanparametersfromamatrixoftransitionfunc-tions.UsagegenerateParameterMatrix(hf)Argumentshfatransition.structureofdimensionNN,whereNisthenumberofstates.Valueatransition.structureofdimensionNN,whosecomponentsarelistsoftherightlengthfortheparametersinthecorrespondinghazardfunctionhf.Author(s)LuisaSalazarVizcaya,NelloBlaser,ThomasGsponerReferencesNelloBlaser,LuisaSalazarVizcaya,JanneEstill,CindyZahnd,BinduKalesan,MatthiasEgger,OliviaKeiser,ThomasGsponer(2015).gems:AnRPackageforSimulatingfromDiseaseProgres-sionModels.JournalofStatisticalSoftware,64(10),1-22.URLhttp://www.jstatsoft.org/v64/i10/.SeeAlsotransition.structure,simulateCohort PosteriorProbabilities7 PosteriorProbabilitiesClass"PosteriorProbabilities" DescriptionThisS4classsummarizestheposteriorprobabilitiesovertimeforobjectsofclass"ArtCohort"Usage##S4methodforsignature'PosteriorProbabilities,ANY,ANY,ANY'x[i,j,...,drop=TRUE]##S4methodforsignature'PosteriorProbabilities'plot(x,ci=FALSE,main=paste(x@type,"afterstartinginState",x@states[1],"attime0"),states=1:dim(x@probabilities)[2],lwd=c(2,2),col=c("blue","green3"),lty=c(1,2),xlab="Time",ylab="Probability",...)##S4methodforsignature'PosteriorProbabilities'head(x,...)##S4methodforsignature'PosteriorProbabilities'tail(x,...)ArgumentsxthePosteriorProbabilitiesobjecti,j,dropsameasfora"data.frame"...argumentspassedontomainmethodcishouldcondenceintervalsbedisplayedmain,xlab,ylabsameasanyplotstateswhichstatestodisplaylwd,col,ltyvectorsoflentht2,withrstcomponentforthepointestimateandsecondcom-ponentforthecondenceintervalSlotsstatesObjectofclass"character":namesofstatestimesObjectofclass"numeric":timepointsatwhichprobabilitiesareevaluatedprobabilitiesObjectofclass"matrix":posteriorProbabilitiestobeineachstateateachtimelowerObjectofclass"matrix":lowerpredictionboundtobeineachstateateachtimeupperObjectofclass"matrix":upperpredictionboundtobeineachstateateachtimetypeObjectofclass"character":describestypeofprobability 8simulateCohortObjectsfromtheClassObjectsarecreatedbycallstothefunctionsimulateCohort.Author(s)LuisaSalazarVizcaya,NelloBlaser,ThomasGsponerSeeAlsotransitionProbabilities,cumulativeIncidence,ArtCohortExamplesshowClass("PosteriorProbabilities") simulateCohortSimulatecohort DescriptionSimulatesacohortofpatientsfromasetoffunctionsassociatedtoeachpossibletransitioninamultistatemodel.ThemultistatemodelisnotrequiredtobeaMarkovmodelandmaytakethehistoryofpreviouseventsintoaccount.Inthebasicversion,itallowstosimulatefromtransition-specichazardfunction,whoseparametersaremultivariablenormallydistributed.Foreachstate,alltransition-specichazardfunctionsandtheirparametersneedtobespecied.Forsimulatingonetransition,allpossibleeventtimesaresimulatedandtheminimumischosen.Thensimulationcontinuesfromthecorrespondingstateuntilanabsorbingstateoftimetoisreached.UsagesimulateCohort(transitionFunctions,parameters,cohortSize=1000,parameterCovariances=FALSE,timeToTransition=array(FALSE,dim=dim(transitionFunctions@list.matrix)),baseline=matrix(NA,nrow=cohortSize),initialState=rep(1,cohortSize),absorbing=transitionFunctions@states.number,to=100,report.every=100,sampler.steps=1000)ArgumentstransitionFunctionsatransition.structureofdimensionNNthatcontainsthehazardfunc-tionsparametersatransition.structureofdimensionNNthatcontainstheparameterscohortSizeanumericindicatingthenumberofpatientstobesimulated. simulateCohort9parameterCovariancesatransition.structureofdimensionNNofcovariancematricesfortheparameters.timeToTransitionalogicalmatrix;TRUEforalltransitionswhosetransitionFunctionisspeciedasthetimeuntiltransitioninsteadofasahazardfunctionorasacharacter.baselineamatrixordata.frameofdimensioncohortSizeMwithMbaselinechar-acteristicsofsubjectstobesimulated.initialStateanumericoflengthcohortSizewiththeinitialstateforeachsubjectsimulated.absorbinganumericcontainingallabsorbingstates.tonaltimeofthesimulation.report.everyanumerictocheckprogressofsimulation.sampler.stepsanumericindicatingnumberofstepsfordiscretizationofhazardfunctionsDetailsThetransitionFunctionscontainshazardfunctionsortimetoeventfunctionassociatedtoeachpossibletransition.TheelementsofthislistcanbeeitherexpressedasanexplicitRfunctionorasacharacter("impossible","Weibull","multWeibull","exponential")inordertoexpressimpos-sibletransitionsorparametricformsforthedistributionsoftimetoevent.Ifthefunctionsshoulddependontime,baselinecharacteristicsorbehistory-dependent,thefunctionargumentst,blorhistorycanbeused.Timetreferstothetimesinceentryintothecurrentstate.Forthetimesincetheinitialstate,uset+sum(history).ThecomponentsoftheparametersargumentlistthemeanvaluesfortheparametersinthetransitionFunction.IfthecorrespondingtransitionFunctionisafunction,theparametersshouldappearinthesameorderasinthefunction,leavingoutt,blandhistory.Ifthecorre-spondingtransitionFunctionisthecharacter"Weibull",therstargumentistheshapeandthesecondonethescale.IfthecorrespondingtransitionFunctionisthecharacter"multWeibull",specifyweights,shapes,scalesinthisorder.NotethatwhenusingtheparameterCovariancesargumentitistheusersresponsibilitytoen-surethatthefunctionsareparametrizedsuchthatparametersforeachtransitionaremultivariatenormallydistributedandmutuallyindependent.Valueanobjectofclass"ArtCohort"withtime.to.stateslotofdimensioncohortSizeNwithentrytimesforeachpatientintoeachofthestates.Author(s)LuisaSalazarVizcaya,NelloBlaser,ThomasGsponerReferencesNelloBlaser,LuisaSalazarVizcaya,JanneEstill,CindyZahnd,BinduKalesan,MatthiasEgger,OliviaKeiser,ThomasGsponer(2015).gems:AnRPackageforSimulatingfromDiseaseProgres-sionModels.JournalofStatisticalSoftware,64(10),1-22.URLhttp://www.jstatsoft.org/v64/i10/. 10simulateCohortSeeAlsogenerateHazardMatrix,generateParameterMatrix,generateParameterCovarianceMatrix,ArtCohort,transitionProbabilities,cumulativeIncidenceExamples#Hereisanexamplemodelwith3statesand2possibletransitions.#numberofstatesinthemodelstatesNumber3#cohortsizecohortSize100#specificationofhazardfunctionshazardfgenerateHazardMatrix(statesNumber)hazardf[[1,2]]function(t,r1,r2){ifelse(tr1,r2)}hazardf[[2,3]]"Weibull"#listofparametersforthehazardfunctionsmugenerateParameterMatrix(hazardf)mu[[1,2]]list(0.33,0.03)#r1,r2mu[[2,3]]list(1,0.84)#shape,scale#timemaxTime10#simulatethecohortcohortsimulateCohort(transitionFunctions=hazardf,parameters=mu,cohortSize=cohortSize,to=maxTime)#outputhead(cohort)#transitionprobabilitytrtransitionProbabilities(cohort,times=seq(0,4,.1))plot(tr,ci=FALSE)#cumulativeincidenceinccumulativeIncidence(cohort,times=seq(0,4,.1))plot(inc,ci=FALSE,states=c(2,3)) tavi11 tavitavidataset DescriptionThesimulateddatasetforeachpatientcontainsdataforkidneyinjuries,bleedingcomplicationsandthecombinedendpointofstrokeordeath.Thedatawassimulatedfromtheoriginaldatafollowingthestepsdescribedinthepackagevignette.FormatAdataframewith194observationsonthefollowing7variables.idacharactervectorthatcontainsthepatientid'skidneyanumericvector;indicatorvariablethatshowifaneventhasoccurredkidney.duranumericvector;timesatwhichtheeventsoccurredorthepatientswerecensoredbleedinganumericvector;indicatorvariablethatshowifaneventhasoccurredbleeding.duranumericvector;timesatwhichtheeventsoccurredorthepatientswerecensoreddeathanumericvector;indicatorvariablethatshowifaneventhasoccurreddeath.duranumericvector;timesatwhichtheeventsoccurredorthepatientswerecensoredReferencesNelloBlaser,LuisaSalazarVizcaya,JanneEstill,CindyZahnd,BinduKalesan,MatthiasEgger,OliviaKeiser,ThomasGsponer(2015).gems:AnRPackageforSimulatingfromDiseaseProgres-sionModels.JournalofStatisticalSoftware,64(10),1-22.URLhttp://www.jstatsoft.org/v64/i10/.Exampleshead(data(tavi)) transition.structureClass"transition.structure" DescriptionThisS4classprovidesastructuretospecifydifferentcharacteristicsoftransitions,suchastransitionfunctionsfunctions,parametersorparametercovariances. 12transition.structureUsage##S4methodforsignature'transition.structure'x[[i,j,...,exact=TRUE]]##S4replacementmethodforsignature'transition.structure'x[[i,j]]valuepossibleTransitions(object)##S4methodforsignature'transition.structure'possibleTransitions(object)##S4methodforsignature'transition.structure'print(x)Argumentsx,objectthetransition.structurei,jsameasformatrixexact,value,...passedontolistmethodSlotsstates.numberObjectofclass"numeric":numberofstateslist.matrixObjectofclass"matrix":alistwithtwodimensions,wherelistelement[i,j]correspondtotransitionsfromitojObjectsfromtheClassObjectsarecreatedbycallstothefunctionsgenerateHazardMatrix,generateParameterMatrix,generateParameterCovarianceMatrix.Author(s)LuisaSalazarVizcaya,NelloBlaser,ThomasGsponerSeeAlsogenerateHazardMatrix,generateParameterMatrix,generateParameterCovarianceMatrixExamplesshowClass("transition.structure") transitionProbabilities13 transitionProbabilitiestransitionprobabilities DescriptionCalculatestheprobabilitiesandpredictionintervalsafterrststateUsagetransitionProbabilities(object,times,M=100,stateNames=paste("State",as.list(1:dim(cohorts)[1])))ArgumentsobjecteithertheoutputofsimulateCohortorthematrixwiththeprobabilitiesslotofthatoutput.timesatimevector.Mnumberofgroupsforcalculatingcondenceintervals.stateNamesalistwiththenamesofstates.Valueanobjectofclass"PosteriorProbabilities",containingthestatenames,timepointsandthetran-sitionprobabilitieswithpointwisepredictionintervalsovertime.Author(s)LuisaSalazarVizcaya,NelloBlaser,ThomasGsponerReferencesNelloBlaser,LuisaSalazarVizcaya,JanneEstill,CindyZahnd,BinduKalesan,MatthiasEgger,OliviaKeiser,ThomasGsponer(2015).gems:AnRPackageforSimulatingfromDiseaseProgres-sionModels.JournalofStatisticalSoftware,64(10),1-22.URLhttp://www.jstatsoft.org/v64/i10/.SeeAlsoPosteriorProbabilities,ArtCohort,simulateCohort IndexTopicclassesArtCohort,2PosteriorProbabilities,7transition.structure,11Topicdatasetstavi,11TopicfunctionsimulateCohort,8TopicmainsimulateCohort,8TopicutilitiescumulativeIncidence,3generateHazardMatrix,4generateParameterCovarianceMatrix,5generateParameterMatrix,6transitionProbabilities,13[,ArtCohort,ANY,ANY,ANY-method(ArtCohort),2[,ArtCohort-method(ArtCohort),2[,PosteriorProbabilities,ANY,ANY,ANY-method(PosteriorProbabilities),7[,PosteriorProbabilities-method(PosteriorProbabilities),7[.ArtCohort(ArtCohort),2[.PosteriorProbabilities(PosteriorProbabilities),7[[,transition.structure-method(transition.structure),11[[.transition.structure(transition.structure),11[[(transition.structure),11[[(transition.structure),11ArtCohort,2,4,8,10,13ArtCohort-class(ArtCohort),2cumulativeIncidence,3,3,8,10gems,4gems-package(gems),4generateHazardMatrix,4,10,12generateParameterCovarianceMatrix,5,10,12generateParameterMatrix,6,6,10,12head,ArtCohort-method(ArtCohort),2head,PosteriorProbabilities-method(PosteriorProbabilities),7head.ArtCohort(ArtCohort),2head.PosteriorProbabilities(PosteriorProbabilities),7plot,PosteriorProbabilities-method(PosteriorProbabilities),7plot.PosteriorProbabilities(PosteriorProbabilities),7possibleTransitions(transition.structure),11possibleTransitions,transition.structure-method(transition.structure),11PosteriorProbabilities,4,7,13PosteriorProbabilities-class(PosteriorProbabilities),7print,transition.structure-method(transition.structure),11print.transition.structure(transition.structure),11simulateCohort,3–6,8,13summary,ArtCohort-method(ArtCohort),2summary.ArtCohort(ArtCohort),2tail,ArtCohort-method(ArtCohort),2tail,PosteriorProbabilities-method(PosteriorProbabilities),7tail.ArtCohort(ArtCohort),2tail.PosteriorProbabilities(PosteriorProbabilities),714 INDEX15tavi,11transition.structure,3,5,6,11transition.structure-class(transition.structure),11transitionProbabilities,3,8,10,13update,ArtCohort-method(ArtCohort),2update.ArtCohort(ArtCohort),2