# Duration


A time argument computed as the elapsed time between two date or datetime columns.


Usage

``` python
Duration(
    start,
    end,
    unit="days",
)
```


A [Duration](Duration.md#greenwood.Duration) is a frozen specification that names two date or datetime columns and a time unit. When passed to an [Outcome](Outcome.md#greenwood.Outcome) constructor as the `time` (or `time2`) argument, Greenwood computes the elapsed time automatically when the data is read. Inside a formula, write the same thing as `duration(start, end, unit="days")`.

Create a [Duration](Duration.md#greenwood.Duration) with the [duration()](duration.md#greenwood.duration) helper rather than constructing it directly.


## Parameters


`start: str`  
Column name holding the origin date or datetime (e.g., enrollment date).

`end: str`  
Column name holding the exit date or datetime (e.g., date of event or last contact).

`unit: str = ``"days"`  
Time unit for the elapsed duration: `"days"` (default), `"weeks"`, `"months"`, `"years"`, `"hours"`, `"minutes"`, or `"seconds"`. Months and years use average Gregorian lengths (30.4375 and 365.25 days).


## Examples

Create a [Duration](Duration.md#greenwood.Duration) that computes follow-up time in days between two date columns, and use it as the time argument of an [Outcome](Outcome.md#greenwood.Outcome):


``` python
import greenwood as gw
import polars as pl

df = pl.DataFrame({
    "enroll": ["2020-01-01", "2020-03-15", "2020-06-01"],
    "last_contact": ["2021-06-15", "2020-12-01", "2022-01-10"],
    "event": [1, 0, 1],
}).with_columns(
    pl.col("enroll").str.to_date(),
    pl.col("last_contact").str.to_date(),
)

d = gw.duration(start="enroll", end="last_contact", unit="days")
d
```


    duration(start='enroll', end='last_contact', unit='days')


``` python
y = gw.Outcome.surv(time=d, event="event").bind(df)
y
```


    Surv(type=right, n=3, events=2)


## Attributes

| Name | Description |
|----|----|
| [columns](#columns) | The two columns the duration reads. |

------------------------------------------------------------------------


### columns


The two columns the duration reads.


`columns: tuple[str, str]`


## Methods

| Name | Description |
|----|----|
| [compute()](#compute) | The elapsed time from [start](Surv.md#greenwood.Surv.start) to `end` in `unit` (`NaN` where either is missing). |

------------------------------------------------------------------------


### compute()


The elapsed time from [start](Surv.md#greenwood.Surv.start) to `end` in `unit` (`NaN` where either is missing).


Usage

``` python
compute(
    start,
    end,
)
```