> For the complete documentation index, see [llms.txt](https://cgps.gitbook.io/data-flo/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cgps.gitbook.io/data-flo/reference-guide/calculate-time-difference.md).

# 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#:~:text=Accepted%20format%20string%20patterns%3A>). 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#:~:text=Accepted%20format%20string%20patterns%3A). 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cgps.gitbook.io/data-flo/reference-guide/calculate-time-difference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.