> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracebloc.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Survival analysis (time-to-event)

> Dataset template for survival analysis: one CSV with covariates, a duration column and an event indicator, the required label policy, ingest.yaml and the checks the data ingestor runs.

Predict how long until an event happens, allowing for cases where it has not happened yet (censoring). The dataset is a single CSV where every row is one subject: covariate columns, a **duration** column and an **event indicator** column (1 = event observed, 0 = censored).

## Folder layout

```text theme={null}
/data/shared/survival/
└── survival.csv
```

## Data CSV

```csv theme={null}
age,anaemia,creatinine_phosphokinase,diabetes,ejection_fraction,high_blood_pressure,platelets,serum_creatinine,serum_sodium,sex,smoking,time,DEATH_EVENT
48,0,315,0,40,1,275841,1.6,131,0,1,225,0
78,0,3964,1,62,0,315081,0.9,135,0,0,5,1
64,0,2656,0,45,0,372021,3.0,142,0,1,13,1
```

| Column                               | Meaning                                                                                                                                                                    |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| covariate columns                    | Declared in `schema` with their SQL type.                                                                                                                                  |
| duration column (`time` here)        | Numeric and non-negative; declared in `schema` like any other column. Its name is `time` unless you set `time_column`. Empty values produce a warning.                     |
| event indicator (`DEATH_EVENT` here) | The label column, named by `label.column` and **not** declared in `schema`. Integer codes; declare which code means event and which means censored with `event_indicator`. |

## ingest.yaml

```yaml theme={null}
apiVersion: tracebloc.io/v1
kind: IngestConfig
category: time_to_event_prediction
table: heart_failure_survival_train
intent: train
csv: /data/shared/survival/survival.csv
time_column: time          # the default; set it when your duration column has another name
time_unit: days
event_indicator:
  event: 1
  censored: 0
schema:
  age: INT
  anaemia: INT
  creatinine_phosphokinase: INT
  diabetes: INT
  ejection_fraction: INT
  high_blood_pressure: INT
  platelets: FLOAT
  serum_creatinine: FLOAT
  serum_sodium: INT
  sex: INT
  smoking: INT
  time: INT                # the duration column is declared like any other
label:
  column: DEATH_EVENT
  policy: bucket
```

| Field                         | Required             | Meaning                                                                                                                                                                                                                                                      |
| ----------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `csv`                         | yes                  | Path to the data CSV.                                                                                                                                                                                                                                        |
| `schema`                      | **yes**              | Covariates plus the duration column, with SQL types. Every schema column must exist in the CSV.                                                                                                                                                              |
| `label`                       | **yes, object form** | `column` names the event indicator; `policy` is required. `bucket` makes the platform receive hash buckets, not raw values — stored rows keep the raw indicator that training reads. `passthrough` sends raw values; use it only with a compliance sign-off. |
| `time_column`                 | no                   | Name of the duration column. Default `time`. Matched exactly as written.                                                                                                                                                                                     |
| `time_unit`                   | no                   | `days`, `weeks`, `months` or `years`. Recorded so combined datasets are not compared across units.                                                                                                                                                           |
| `event_indicator`             | no                   | `{event: <int>, censored: <int>}` — the codes used in the label column. Recorded so a flipped convention across combined datasets is caught.                                                                                                                 |
| `columns`                     | no                   | Per-column `unit` and `ordinal` facts.                                                                                                                                                                                                                       |
| `data_id`, `spec.csv_options` | no                   | See [the contract](/create-use-case/templates#the-ingestyaml-contract).                                                                                                                                                                                      |

## What the ingestor checks

| Check         | Rejects                                                                                                                             |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Time to event | A CSV without the duration column (exact name); non-numeric duration values; negative durations. Empty durations produce a warning. |
| Data types    | Duplicate headers, schema columns missing from the CSV, values that do not match their declared type, unknown SQL types.            |

Plus the [checks every ingest runs](/create-use-case/templates#checks-every-ingest-runs). There is no label-diversity check.

## Sample dataset

The template ships 30 synthetic rows shaped like a heart-failure clinical dataset (no real patients): eleven covariates (`age`, `anaemia`, `creatinine_phosphokinase`, `diabetes`, `ejection_fraction`, `high_blood_pressure`, `platelets`, `serum_creatinine`, `serum_sodium`, `sex`, `smoking`), the duration `time` in days and the event indicator `DEATH_EVENT`. The covariates are linearly independent on purpose — a Cox proportional-hazards fit needs that. The rows shown above are its first rows, and the `ingest.yaml` above ingests it as is; only `csv:` changes to wherever you staged the file.

## Next steps

* Stage the data and run the ingest: [Prepare Data](/create-use-case/prepare-dataset)
* Shared rules for every template: [Dataset templates](/create-use-case/templates)