reddooranalytics/survsim

Simulating time-to-event data from parametric distributions, custom distributions, competing risk models and general multi-state models in Stata

survsim

Simulating time-to-event data from parametric distributions, custom distributions, competing risk models and general multi-state models

For an introductory seminar, see Simulating time-to-event data from parametric distributions, custom distributions, competing risk models and general multi-state models.

Installation

The current stable version of survsim can be installed from the SSC archive by typing:

ssc install survsim

To install directly from this GitHub repository, use:

net install survsim, from("https://raw.githubusercontent.com/RedDoorAnalytics/survsim/main/")

References

Bender R, Augustin T and Blettner M. Generating survival times to simulate Cox proportional hazards models. Statistics in Medicine 2005;24:1713-1723.

Beyersmann J, Latouche A, Buchholz A and Schumacher M. Simulating competing risks data in survival analysis. Statistics in Medicine 2009;28:956-971.

Crowther MJ and Lambert PC. Simulating complex survival data. The Stata Journal 2012;12(4):674-687.

Crowther MJ and Lambert PC. Simulating biologically plausible complex survival data. Statistics in Medicine 2013;32(23):4118-4134.

Crowther MJ. Simulating time-to-event data from parametric distributions, custom distributions, competings risk models and general multi-state models. Pre-print 2020.

Jann, B. 2005. moremata: Stata module (Mata) to provide various functions. Available from http://ideas.repec.org/c/boc/bocode/s455001.html.

survsim's Issues

`survsim_msm`: Informative Error Message Needed (`tdefunc()`)

Win11, Stata 17.0 MP6, survsim 4.0.10

I was jumping back and forth between stcox and survsim and accidentally used the former's texp() syntax for the latter--I typed tdefunc("ln(_t)") instead of tdefunc("ln({t})"). However, the error message I received when simulating via survsim msm didn't pinpoint this as the issue:

              totalhf1():  3200  conformability error
       survsim_msm_sim():     -  function returned error
            _mm_callf1():     -  function returned error
              mm_callf():     -  function returned error
       survsim_mm_root():     -  function returned error
           survsim_msm():     -  function returned error
                 <istmt>:     -  function returned error

A more informative error message would help, especially because Mata kicking the error means set trace-ing won't easily reveal the true problem.

(As an aside: running the same code via survsim parametric doesn't throw an error at all, which obfuscated matters. Only after rereading the survsim parametric help file again, after I'd found the issue, made me realize that tdefunc() isn't a parsed option for that survsim variant.)

MWE

clear *
set seed 1283169888
set obs 8000

gen double x1 = rnormal()
gen double x2 = rnormal()

//****************************************************************************** 
global opts = "dist(w) lambda(0.5) gamma(1.25)"
global tvc1 = "tde(x2 -0.1) tdefunction(ln(_t))"

* msm - throws error
cap noi survsim t type fail, ///    
    hazard1($opts covariate(x1 -0.65 x2 0.4) $tvc1) ///
    hazard2($opts covariate(x1 0.3   x2 0.5)) ///
    maxtime(100)
    
mata mata clear // to ensure starting from clean slate [GH issue #2]
    
* parametric - no error    
survsim t fail, ///    
    $opts covariate(x1 -0.65 x2 0.4) $tvc1 

`simsurv_msm`: Missing Start Stage Value Behavior

Win10, Stata 17.0 MP6, survsim 4.0.9

Problem
If any observation has a missing value for the startstate variable, survsim goes off the rails and repeatedly creates yObsv, state, and fail variables until the dataset in memory hits c(max_k_theory).

In the MWE below, the error gets thrown while survsim_msm's executing mata: survsim_msm(Phfs,Ptotalhfs).

MWE

clear *
set obs 2000
set seed 57

matrix tMat = (., 1, ., . \ ., ., ., . \., ., ., 2\., ., ., .)

gen grp = .
replace grp = 1 in 1/200
replace grp = 2 in 201/1800  // NOTE: 200 observations 'accidentally' left without a value for starting stage

survsim yObsv state fail, ///
    hazard1(d(w) gamma(1.25) lambda(.05))  ///
    hazard2(d(w) gamma(1.05) lambda(.1) ) ///
    maxtime(100) startstate(grp) transmatrix(tMat) 

Error-Out Behavior

Win10, Stata 17.0 MP6, survsim 4.0.9

Problem
If survsim throws an unexpected error and exits out, it doesn't tidy up Mata memory. If you try to rerun the command after an unexpected exit, you get:

. hf1() already exists
(4 lines skipped)
r(3000);

Checking Mata memory confirms the issue:

. mata mata desc

      # bytes   type                        name and extent
-------------------------------------------------------------------------------
          240   transmorphic matrix         hf1()
          256   transmorphic matrix         hf2()
          400   transmorphic matrix         totalhf1()
          408   transmorphic matrix         totalhf3()
           16   pointer colvector           Phfs[2]
           32   pointer colvector           Ptotalhfs[4]
-------------------------------------------------------------------------------

MWE
Run the MWE from #1, then without clearing session memory: keep grp, then recode grp (.=2), then try rerunning #1's survsim call.