Constructing Multi-State Life Tables

The first step to using METER is to have your data in the correct format. The data should have one subject per row, and have columns containing each of the transition times. Transition times can be specified as calendar dates or time from study entry, as the wide_format function will convert everything into the latter format.

To obtain the transition matrices of the multi-state model you should do the following:

  1. Use wide_format() to obtain the data in wide format.

  2. Use atrisk_and_transitions() to obtain the risk sets and number of transitions made at each time point.

  3. Use transitionprobs_and_samplesizes() to obtain the transition matrices for each time point, and the associated sample sizes.

If you don’t need the transition probabilities directly, and just want associated life expectancies or other survival estimates, you can just do step one and then skip forward to the section on generating estimates.

Note

You should still be running wide_format even if your data already has transition times specified as time from study entry. This is because the wide_format function creates status columns that indicate whether each transition ever occured for a given subject, and ensures that there is only one transition per year.

METER also allows you to censor data at a given state. This is often useful for reasons mentioned in Life Expectancies. If you want to censor your data, you should do this immediately after step 1 above, using censor().

METER.wrangler.wide_format(data, transition_names, exit)

Take data with transitions as calendar dates and expand for life table construction. If multiple transitions occur at the same time (i.e. in the same year or day) then only the final transition is counted as occuring.

Parameters

  • data (pandas dataframe) – the data, with dates of all transitions, with one subject per line

  • transition_names (list) – a list of the names of the columns that contain the transition times

  • exit (string) – the name of the column indicating final follow-up date for each subject

Returns

a dataframe with additional columns for:

  • transitions as time from study entry

  • transition status columns indicating whether such a transition ever occurred

  • a column final_age, for age at study close-out

Return type

pandas dataframe

METER.table.atrisk_and_transitions(data, transition_names, states)

Get the number of individuals in a given state at a each time, and number of transitions at each time.

Parameters

  • data (pandas dataframe) – the data in wide format as generated by wide_format()

  • transition_names (list) – a list of the names of the columns that contain the transition times

  • states (list) – the names of the states in the model, the entry into each of which will correspond to the columns in transition_names

Returns

a two element list with:

  • first element a dataframe containing the risk sets for each time point

  • second element a dataframe containing the number of transitions of each type at each time point

Return type

list

METER.table.transitionprobs_and_samplesizes(riskdf, transdf, states)

Obtain transition matrices governing transitions from each time point, and associated sample sizes.

Parameters

  • riskdf (pandas dataframe) – a dataframe with the number of individuals in each state, indexed at each time point. This is the first output from atrisk_and_transitions()

  • transdf (pandas dataframe) – a dataframe containing the number of transitions of each type at each time point. The second output from atrisk_and_transitions()

  • states (list) – the names of the states in the model

Returns

a two element list with:

  • first element a list containing the transition matrix (as a numpy array) for each time point

  • second element a list containing a matrix of the associated sample sizes

Return type

list

METER.wrangler.censor(data, transition, transition_names)

censor all individuals in a dataframe at a given state

Parameters

  • data (pandas dataframe) – the dataframe in wide format as created by wide_format()

  • transition (string) – the column name in the original dataset that represents transitions into the state you want to censor at

  • transition_names (list) – a list of the names of the columns that contain the transition times

Returns

a new dataframe where all individuals have been censored at the desired state

Return type

pandas dataframe