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

# observed_duration

> Calculate the duration between two dates and determine whether an event was observed before a specified observation date. 

This step calculates the duration between a start date and an end date and determines whether an event was observed.
The output consists of two columns:

* `duration`: The time interval between the start and end dates in the specified unit (default: days).
* `observed`: A boolean column indicating whether the event was observed (i.e., if the end date occurs before the observation date).

This is particularly useful for preparing input data for survival analysis, such as Kaplan-Meier curves, where the event observation (censoring) status and duration are key inputs.

* If either `start_date` or `end_date` is missing (null), `observed` will be false, and `duration` will be null.
* Otherwise, the `duration` is calculated as the interval between `start_date` and `end_date`.
* If `end_date` is not null, `observed` will be true if `end_date <= observation_end`; otherwise, it will be false.

## Usage

The following examples show how the step can be used in a recipe.

<Accordion title="Examples" icon="code" defaultOpen="true">
  <Tabs>
    <Tab title="Example 1">
      Calculate the duration and observation status between a start date and end date.

      ```stan theme={null}
      observed_duration(ds.start_date, ds.end_date, {"observation_end": "2020-01-01"}) -> (ds.duration, ds.observed)
      ```
    </Tab>

    <Tab title="Example 2">
      Calculate the duration in weeks.

      ```stan theme={null}
      observed_duration(ds.start_date, ds.end_date, {"observation_end": "2020-01-01", "unit": "weeks"}) -> (ds.duration, ds.observed)
      ```
    </Tab>

    <Tab title="Signature">
      General syntax for using the step in a recipe. Shows the inputs and outputs the step is expected to receive and will produce respectively. For futher details see sections below.

      ```stan theme={null}
      observed_duration(start_date: date, end_date: date, {
          "param": value,
          ...
      }) -> (duration: number, observed: boolean)
      ```
    </Tab>
  </Tabs>
</Accordion>

## Inputs & Outputs

The following are the inputs expected by the step and the outputs it produces. These are generally
columns (`ds.first_name`), datasets (`ds` or `ds[["first_name", "last_name"]]`) or models (referenced
by name e.g. `"churn-clf"`).

<Accordion title="Inputs" icon="right-to-bracket">
  <ParamField path="start_date" type="column[date]" required>
    The column containing the start date for each entry.
  </ParamField>

  <ParamField path="end_date" type="column[date]" required>
    The column containing the end date for each entry (can be null for ongoing cases).
  </ParamField>
</Accordion>

<Accordion title="Outputs" icon="right-from-bracket">
  <ParamField path="duration" type="column[number]" required>
    The calculated duration between the start and end dates in the specified unit.
  </ParamField>

  <ParamField path="observed" type="column[boolean]" required>
    A boolean column indicating if the event was observed before the `observation_end`.
  </ParamField>
</Accordion>

## Configuration

The following parameters can be used to configure the behaviour of the step by including them in
a json object as the last "input" to the step, i.e. `step(..., {"param": "value", ...}) -> (output)`.

<Accordion title="Parameters" defaultOpen="true" icon="sliders">
  <ParamField path="observation_end" type="string" required>
    Observation end date.
    The cutoff date to determine if the event was observed (e.g., churn or any other event).
  </ParamField>

  <ParamField path="unit" type="string" default="days">
    Unit for duration.
    The unit of measurement for the duration. Allowed values are: - "Y", "year" - "Q", "quarter" - "M", "month" - "W", "week" - "D", "day" - "h", "hour" - "m", "minute" - "s", "second" - "ms", "millisecond"
    The unit name can be spelled in singular or plural and is case-insensitive.

    Values must be one of the following:

    `Y` `year` `Year` `years` `Years` `Q` `quarter` `Quarter` `quarters` `Quarters` `M` `month` `Month` `months` `Months` `W` `week` `Week` `weeks` `Weeks` `D` `day` `Day` `days` `Days` `h` `hour` `Hour` `hours` `Hours` `m` `minute` `Minute` `minutes` `Minutes` `s` `second` `Second` `seconds` `Seconds` `ms` `millisecond` `Millisecond` `milliseconds` `Milliseconds`
  </ParamField>
</Accordion>