# calculate-time-difference

## Description

<mark style="color:purple;">`calculate-time-difference`</mark> *adaptor calculates the time difference between two datatable columns (column one - column two), using a specified unit of measurement (defaults to `day`).*

Note that the order of columns selected is important for the output values.

## Inputs

**`data`**\
Type: `datatable`\
Required: Yes\
The datatable containing two date/time columns.

**`column one`**\
Type: `text`\
Required: Yes\
The name of the column containing reference date/time values.

**`column one format`**\
Type: `text`\
Required: No\
The format of data in column one based on [Unicode Technical Standard #35](https://date-fns.org/v2.0.1/docs/parse). If unspecified, defaults to ISO 8601 date/time.

**`column two`**\
Type: `text`\
Required: Yes\
The name of the column containing date/time values.

**`column two format`**\
Type: `text`\
Required: No\
The format of data in value column based on [Unicode Technical Standard #35](https://date-fns.org/v2.0.1/docs/parse). If unspecified, defaults to ISO 8601 date/time.

**`difference column`**\
Type: `text`\
Required: No\
The name of the new column containing time difference values. If unspecified, defaults to `difference`.

**`difference unit`**\
Type: `text`\
Required: No\
The unit of time measurement. Possible values are `years`, `quarter`, `months`, `weeks`, `days`, `hours`, `minutes`, `seconds`, or `milliseconds`. If unspecified, defaults to `days`.

## Outputs

**`data`**\
Type: `datatable`\
A datatable with the new column added.

## Examples

### Example 1: Default behaviour.

#### Inputs:

`data`:

| Sample ID | Received date | Sequence date |
| --------- | ------------- | ------------- |
| Sample A  | 2020-11-01    | 2020-11-21    |
| Sample B  | 2020-12-11    | 2020-12-19    |
| Sample C  | 2020-12-11    | 2020-12-11    |

`column one`: Sequence date

`column one`: Received date

#### Outputs:

`data`:

| Sample ID | Received date | Sequence date | Processing time |
| --------- | ------------- | ------------- | --------------- |
| Sample A  | 2020-11-01    | 2020-11-21    | 20              |
| Sample B  | 2020-12-11    | 2020-12-19    | 8               |
| Sample C  | 2020-12-11    | 2020-12-11    | 0               |

-> Calculated the time difference between the two datatable columns `Sequence date` and `Received date`.

## Use Cases

* Calculating the time between patient admission to the hospital and the sample date of the first positive sample
* Calculate a person's age
* Use pharmaceutical expiry dates to predict potential stock outs
* Sort or filter data based on time differences