# Getting Started with OdysseusSurvivalModule

## Introduction

OdysseusSurvivalModule supports a two-step workflow:

1. Build a subject-level survival dataset from OMOP CDM cohorts.
2. Estimate survival curves from that dataset with `singleEventSurvival()`.

This vignette uses Eunomia as the example CDM and focuses on the package API as it exists today.

## Package Surface

The exported function is `singleEventSurvival()`. The cohort-to-survival-data helper, `addCohortSurvival()`, is currently internal, so vignette examples call it with `:::`.

    library(OdysseusSurvivalModule)
    library(DatabaseConnector)
    library(Eunomia)

## Connect to Eunomia

    connectionDetails <- Eunomia::getEunomiaConnectionDetails()
    connection <- DatabaseConnector::connect(connectionDetails)

    cdmDatabaseSchema <- Eunomia::getEunomiaCdmDatabaseSchema()
    cohortDatabaseSchema <- Eunomia::getEunomiaResultsSchema()

## Prerequisite: Target and Outcome Cohorts

`addCohortSurvival()` does not create cohorts from concept IDs. It expects existing target and outcome cohort tables. In a typical OHDSI workflow, those cohorts are created ahead of time with ATLAS, Circe, or custom SQL and stored in the cohort results schema.

For the examples below, assume a table named `cohort` exists in the Eunomia results schema and contains:

- target cohort definition `1`
- outcome cohort definition `2`

## Build Survival Data

    survivalData <- OdysseusSurvivalModule:::addCohortSurvival(
      connection = connection,
      cdmDatabaseSchema = cdmDatabaseSchema,
      cohortDatabaseSchema = cohortDatabaseSchema,
      targetCohortTable = "cohort",
      targetCohortId = 1,
      outcomeCohortTable = "cohort",
      outcomeCohortId = 2,
      outcomeDateVariable = "cohort_start_date",
      followUpDays = 365,
      includeAge = TRUE,
      includeGender = TRUE
    )

    head(survivalData)

The resulting data frame contains `subject_id`, `time`, and `status`, with optional `age_years` and `gender` columns when requested.

## Fit a Kaplan-Meier Model

    kmFit <- singleEventSurvival(
      survivalData = survivalData,
      timeScale = "days",
      model = "km",
      strata = "gender",
      confInt = 0.95
    )

    names(kmFit)
    kmFit[["overall"]]$summary
    kmFit[["gender=Female"]]$summary
    kmFit$logrank_test_gender

The returned object is a named list. Each stratum entry contains:

- `data`: survival step data
- `summary`: aggregate statistics such as median and mean survival

When `strata = "gender"`, the list includes entries such as `gender=Female` and `gender=Male`, plus `overall`.

## Inspect the Returned Data

    overall_curve <- kmFit[["overall"]]$data
    female_curve <- kmFit[["gender=Female"]]$data

    head(overall_curve)
    head(female_curve)

Each `data` table contains stepwise survival information, including `time`, `n_risk`, `n_event`, `survival`, `hazard`, and cumulative event counts.

## Plot a Returned Curve

`singleEventSurvival()` returns tabular survival output rather than a `survfit` object, so plotting is done from the returned `data` frame.

    plot(
      kmFit[["overall"]]$data$time,
      kmFit[["overall"]]$data$survival,
      type = "s",
      xlab = "Time (days)",
      ylab = "Survival probability",
      main = "Overall Kaplan-Meier curve"
    )

## Fit Cox and Parametric Models

The `model` argument supports `"km"`, `"cox"`, `"weibull"`, `"exponential"`, `"lognormal"`, and `"loglogistic"`.

    coxFit <- singleEventSurvival(
      survivalData = survivalData,
      timeScale = "days",
      model = "cox",
      covariates = c("age_years"),
      confInt = 0.95
    )

    weibullFit <- singleEventSurvival(
      survivalData = survivalData,
      timeScale = "days",
      model = "weibull",
      covariates = c("age_years")
    )

    coxFit[["overall"]]$summary
    weibullFit[["overall"]]$summary

For Cox and parametric models, the function still returns survival summaries and step data. It does not return a coefficient table or hazard-ratio table.

## Cleanup

    DatabaseConnector::disconnect(connection)

## Summary

The core workflow is:

1. Prepare target and outcome cohorts in Eunomia.
2. Build subject-level survival data with `OdysseusSurvivalModule:::addCohortSurvival()`.
3. Fit survival models with `singleEventSurvival()`.
4. Work with the returned `data` and `summary` components directly.