# format-time-column

## Description

<mark style="color:purple;">`format-time-column`</mark> *adaptor formats date/time values in a datatable column.*

Define the format of a date/time column and either replace the original column values or add a new column with the reformatted date-time.

## Inputs

**`data`**\
Type: `datatable`\
Required: Yes\
The datatable containing the column to be formatted.

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

**`original unit`**\
Type: `text`\
Required: No\
The unit of time measurement of the original values. If unspecified, defaults to `milliseconds`.

**`new unit`**\
Type: `text`\
Required: No\
The unit of time measurement of the new values. If unspecified, defaults to `minutes`.

**`new column`**\
Type: `text`\
Required: No\
The name of the column to which the new values will be added. If unspecified, the new values will added to the original column (specified by `original column`), overwriting the original values.

## Outputs

**`data`**\
Type: `datatable`\
A datatable with formatted values.

## Examples

### Example 1: Default behaviour.

#### Inputs:

`data`:

| id | time |
| -- | ---- |
| 1  | 1    |
| 2  | 4    |
| 3  | 5    |
| 4  | 2    |

`original column`: time

`original unit`: hours

`new unit`: minutes

`new column` : *null (empty)*

#### Outputs:

`data`:

| id | time |
| -- | ---- |
| 1  | 60   |
| 2  | 240  |
| 3  | 300  |
| 4  | 120  |

-> Overwrote the data in the `time` column with the time in `minutes`instead of `hours`

### Example 2: Time reformatted in new column.

#### Inputs:

`data`:

| id | time (hours) |
| -- | ------------ |
| 1  | 1            |
| 2  | 4            |
| 3  | 5            |
| 4  | 2            |

`original column`: time (hours)

`original unit`: hours

`new unit`: seconds

`new column` : time (seconds)

#### Outputs:

`data`:

| id | time (hours) | time (seconds) |
| -- | ------------ | -------------- |
| 1  | 1            | 3600           |
| 2  | 4            | 14400          |
| 3  | 5            | 18000          |
| 4  | 2            | 7200           |

-> Created a `time (seconds)` column with the time in `seconds`, derived from `time (hours)` column.

## Use Cases

* Standardize temporal data elements across different data sources where temportal data are stored in different formats&#x20;
* Simplify temporal data formats
* Reformat temporal data elements to a format more useful for visualisation&#x20;