---
title: "Getting Started with OdysseusSurvivalModule"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with OdysseusSurvivalModule}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)
```

## 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 `:::`.

```{r setup}
library(OdysseusSurvivalModule)
library(DatabaseConnector)
library(Eunomia)
```

## Connect to Eunomia

```{r eunomia-setup}
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

```{r build-survival}
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

```{r km-fit}
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

```{r inspect-output}
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.

```{r plot-km}
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"`.

```{r other-models}
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

```{r 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.