Skip to contents

Function time_to_event

time_to_event.Rd

The time_to_event function quickly generates serial times and serial dates for all patients in a cohort. These calculations can then be used for survival analyses and Kaplan-Meier graphs.

Usage

time_to_event(
  database,
  tables,
  code_list,
  index_date,
  index_days_start,
  index_days_end,
  exclude_prior_outcome = FALSE,
  allow_subset = FALSE
)

Arguments

database

name to use

tables

names of tables to use in a dataset that is a list c("diagnosis"), c("diagnosis", "procedure")

  • supported tables: encounter, diagnosis, procedure, medication_ingredient, medication_drug, lab_result, vitals_signs

code_list

user defined table with 3 mandatory columns:

  • mandatory columns

    • feature - the feature the exact code will roll up to and name of the matrix column in the output (letters, numbers, underscores only, no spaces, not case sensitive)

    • code - exact code

    • code_system - RxNorm, LOINC, etc

      • if a user is using the encounter table, code_system must equal "Encounter Type" and code maps to the "type" field in the encounter table

      • if a user enters the value month_year_death in code column and patient in code_system column, the function will use the value in the patient.month_year_death column for all calculations

index_date

user defined table with two columns

  • patient_id

  • index_date

index_days_start

start period relative to index date in days

  • must be great than or equal to 0

  • positive means after

index_days_end

end period relative to index date in days

  • must be after index_days_start

exclude_prior_outcome

(optional) - defaults to FALSE

  • if set to TRUE, excludes any patients with any codes within the feature of the code_list input that are present before the the start of the defined time window (index_days_start)

  • looks at one feature at a time

  • if a user has a code_list with multiple features, the function only looks for the prior outcome of the codes within a single feature to determine exclusion

  • a patient_id can appear within one feature and not another in the output if set to TRUE

allow_subset

(optional argument) - checks whether the number of patients in the index event input table is the same as the dataset cohort number - would default to FALSE, but if set to TRUE would warn and continue

Value

returns a 6 column dataframe with the following columns:

  • patient_id

  • feature

  • serial_time

    • if any codes within the feature of the code_list input are present in the time window, the row is populated with the difference in days between the index date and the first occurrence of a code within the feature

    • if no codes within the feature of the code_list input are present and the patient’s last fact falls within the time window, the row is populated with the difference in days between in the index date and the last code

    • last fact is the most recent fact of a patient across all tables in the dataset database

      • populate the date that is one day after the last fact

    • if last fact is a death date in patient.month_year_death , use the last day of the month

    • if there are facts for the patient after their death date, use the death date (earliest of death date, end of study, last fact)

    • if no codes within the feature of the code_list input are present and the patient’s last fact falls after the time window, the row is populated with the difference in days between the index date and the last date of the time window

  • status

    • 1 if any codes within the feature of the code_list input are present in the time window

    • 0 if

      • no codes within the feature of the code_list input are present and the patient’s last fact falls within the time window

      • no codes within the feature of the code_list input are present and the patient’s last fact falls after the time window

  • serial_date

    • the date (YYYY-MM-DD) used for the time_to_event field calculation that is not the index date

  • index_date

Details

outcomes = time_to_event(database=db,
                         tables=['diagnosis','procedure'],
                         code_list=code_list,
                         index_date=index_date,
                         index_days_start=1,
                         index_days_end=1825,
                         )

display(outcomes)

| patient_id |     feature     | serial_time | status | serial_date | index_date |
|------------|-----------------|-------------|--------|-------------|------------|
| 1          | type_1_diabetes |     123     |    0   |   2/29/16   |  10/29/15  |
| 1          | type_2_diabetes |     123     |    0   |   2/29/16   |  10/29/15  |
| 2          | type_1_diabetes |     1825    |    0   |   7/15/14   |   7/16/09  |
| 2          | type_2_diabetes |     1825    |    0   |   7/15/14   |   7/16/09  |
| 3          | type_1_diabetes |     1825    |    0   |   12/13/14  |  12/14/09  |
| 3          | type_2_diabetes |     1825    |    0   |   12/13/14  |  12/14/09  |
| 4          | type_1_diabetes |     1825    |    0   |   7/15/14   |   7/16/09  |
| 4          | type_2_diabetes |     1825    |    0   |   7/15/14   |   7/16/09  |
| 5          | type_1_diabetes |     386     |    0   |    9/6/14   |   8/16/13  |
| 5          | type_2_diabetes |     386     |    0   |    9/6/14   |   8/16/13  |
| 6          | type_1_diabetes |     386     |    0   |    9/6/14   |   8/16/13  |
| 6          | type_2_diabetes |     386     |    0   |    9/6/14   |   8/16/13  |