# TileDB Dimensions: Date and Datetime Support

## Overview

TileDB supports a wide range of date and time types as shown in the documention for Datetimes.

The supported range of dates and times correspond to the dates and times supported by the Python extension numpy, and is described in its documentation.

    import numpy as np
    import datetime

    day = "1971-02-03 04:05:06"    # third day of second month of first year past epoch

    [np.datetime64(day, 'Y').astype('int64'),    # extract year, month, ... as an int64
    np.datetime64(day, 'M').astype('int64'),
    np.datetime64(day, 'D').astype('int64'),
    np.datetime64(day, 'h').astype('int64'),
    np.datetime64(day, 'm').astype('int64'),
    np.datetime64(day, 's').astype('int64')]
    ## [1, 13, 398, 9556, 573365, 34401906]

R has date and datetime support built-in. The `Date` supports dates using an integer count since the epoch, and matches the `D` value from the previous example. Similarly, the ‘compact’ `POSIXct` representation of a `Datetime` uses the number of seconds since the epoch and corresponds to the `s` value from the previous example.

    as.Date(398, origin="1970-01-01")  # conversion from numeric input requires 'origin'
    ## [1] "1971-02-03"
    as.POSIXct(34401906, origin="1970-01-01", tz="UTC", usetz=TRUE)
    ## [1] "1971-02-03 04:05:06 UTC"

R can reconstruct dates and times from the numpy representation using the epoch as a ‘base’ date along with time period calculations. This can be done using base R (adding to `Date` or `POSIXct` objects), by using the lubridate package for a number of intermediate formats and by using the nanotime package for higher-resolution periods and intervals.

    suppressMessages(library(lubridate))
    ymd("1970-01-01") +  c(years(1), months(13), days(398))
    ## [1] "1971-01-01" "1971-02-01" "1971-02-03"
    ymd_hms("1970-01-01 00:00:00") + c(hours(9556), minutes(573365))
    ## [1] "1971-02-03 04:00:00 UTC" "1971-02-03 04:05:00 UTC"

    suppressMessages(library(nanotime))
    nanotime("1970-01-01T00:00:00+00:00") + nanoduration(hours=2, minutes=3,
                                                         seconds=4, nanoseconds=5)
    ## [1] 1970-01-01T02:03:04.000000005+00:00

## Python and R Interoperability

### Coarsest: Year

#### Python

    import numpy as np
    import sys
    import os
    import tiledb
    uri = "/tmp/tiledb/dt_year"
    dom = tiledb.Domain(tiledb.Dim(name="rows",
                                   domain=(np.datetime64('2001-01-01'), np.datetime64('2030-12-31')),
                                   tile=np.timedelta64(10, 'Y'),
                                   dtype=np.datetime64('', 'Y')))
    schema = tiledb.ArraySchema(domain=dom,
                                sparse=True,
                                attrs=[tiledb.Attr(name="a", dtype=np.int32)])
    if (os.path.isdir(uri)):
        tiledb.VFS().remove_dir(uri)
    tiledb.SparseArray.create(uri, schema)

    with tiledb.SparseArray(uri, mode='w') as A:
        I = [np.datetime64('2001-01-01'),np.datetime64('2002-01-01'),np.datetime64('2003-01-01')]
        data = np.array(([1,2,3]))
        A[I] = data

#### R

    library(tiledb)
    uri <- "/tmp/tiledb/dt_year"
    arr <- tiledb_array(uri, return_as="data.frame")
    arr[]
    ##         rows a
    ## 1 2001-01-01 1
    ## 2 2002-01-01 2
    ## 3 2003-01-01 3
    ## we can also look at 'raw' int64 values:
    datetimes_as_int64(arr) <- TRUE
    arr[]
    ##   rows a
    ## 1   31 1
    ## 2   32 2
    ## 3   33 3

### Day

#### Python

    import numpy as np
    import sys
    import os
    import tiledb
    uri = "/tmp/tiledb/dt_day"
    dom = tiledb.Domain(tiledb.Dim(name="rows",
                                   domain=(np.datetime64('2001-01-01'), np.datetime64('2030-12-31')),
                                   tile=np.timedelta64(10, 'D'),
                                   dtype=np.datetime64('', 'D')))
    schema = tiledb.ArraySchema(domain=dom,
                                sparse=True,
                                attrs=[tiledb.Attr(name="a", dtype=np.int32)])
    if (os.path.isdir(uri)):
        tiledb.VFS().remove_dir(uri)
    tiledb.SparseArray.create(uri, schema)

    with tiledb.SparseArray(uri, mode='w') as A:
        I = [np.datetime64('2001-01-01'),np.datetime64('2001-01-02'),np.datetime64('2001-01-03')]
        data = np.array(([1,2,3]))
        A[I] = data

#### R

    library(tiledb)
    uri <- "/tmp/tiledb/dt_day"
    arr <- tiledb_array(uri, return_as="data.frame")
    arr[]
    ##         rows a
    ## 1 2001-01-01 1
    ## 2 2001-01-02 2
    ## 3 2001-01-03 3

### Minute

#### Python

    import numpy as np
    import sys
    import os
    import tiledb
    uri = "/tmp/tiledb/dt_min"
    dom = tiledb.Domain(tiledb.Dim(name="rows",
                                   domain=(np.datetime64('2001-01-01'), np.datetime64('2030-12-31')),
                                   tile=np.timedelta64(10, 'm'),
                                   dtype=np.datetime64('', 'm')))
    schema = tiledb.ArraySchema(domain=dom,
                                sparse=True,
                                attrs=[tiledb.Attr(name="a", dtype=np.int32)])
    if (os.path.isdir(uri)):
        tiledb.VFS().remove_dir(uri)
    tiledb.SparseArray.create(uri, schema)

    with tiledb.SparseArray(uri, mode='w') as A:
        I = [np.datetime64('2001-01-01 00:00'),
             np.datetime64('2001-01-02 00:01'),
             np.datetime64('2001-01-03 00:02')]
        data = np.array(([1,2,3]))
        A[I] = data

#### R

    library(tiledb)
    uri <- "/tmp/tiledb/dt_min"
    arr <- tiledb_array(uri, return_as="data.frame")
    arr[]
    ##                  rows a
    ## 1 2001-01-01 00:00:00 1
    ## 2 2001-01-02 00:01:00 2
    ## 3 2001-01-03 00:02:00 3

### Millisecond

#### Python

    import numpy as np
    import sys
    import os
    import tiledb
    uri = "/tmp/tiledb/dt_ms"
    dom = tiledb.Domain(tiledb.Dim(name="rows",
                                   domain=(np.datetime64('1969-01-01'), np.datetime64('2030-12-31')),
                                   tile=np.timedelta64(10, 'ms'),
                                   dtype=np.datetime64('', 'ms')))
    schema = tiledb.ArraySchema(domain=dom,
                                sparse=True,
                                attrs=[tiledb.Attr(name="a", dtype=np.int32)])
    if (os.path.isdir(uri)):
        tiledb.VFS().remove_dir(uri)
    tiledb.SparseArray.create(uri, schema)

    with tiledb.SparseArray(uri, mode='w') as A:
        I = [np.datetime64('1970-01-01 00:00:00.001'),
             np.datetime64('1980-01-01 00:00:00.002'),
             np.datetime64('1990-01-01 00:00:00.003'),
             np.datetime64('2000-01-01 00:00:00.004'),
             np.datetime64('2010-01-01 00:00:00.005'),
             np.datetime64('2020-01-01 00:00:00.006')]
        data = np.array(([1,2,3,4,5,6]))
        A[I] = data

#### R

    library(tiledb)
    uri <- "/tmp/tiledb/dt_ms"
    arr <- tiledb_array(uri, return_as="data.frame")
    arr[]
    ##                      rows a
    ## 1 1970-01-01 00:00:00.001 1
    ## 2 1980-01-01 00:00:00.002 2
    ## 3 1990-01-01 00:00:00.003 3
    ## 4 2000-01-01 00:00:00.004 4
    ## 5 2010-01-01 00:00:00.005 5
    ## 6 2020-01-01 00:00:00.006 6

### Microsecond

#### Python

    import numpy as np
    import sys
    import os
    import tiledb
    uri = "/tmp/tiledb/dt_us"
    dom = tiledb.Domain(tiledb.Dim(name="rows",
                                   domain=(np.datetime64('1969-01-01'), np.datetime64('2030-12-31')),
                                   tile=np.timedelta64(10, 'us'),
                                   dtype=np.datetime64('', 'us')))
    schema = tiledb.ArraySchema(domain=dom,
                                sparse=True,
                                attrs=[tiledb.Attr(name="a", dtype=np.int32)])
    if (os.path.isdir(uri)):
        tiledb.VFS().remove_dir(uri)
    tiledb.SparseArray.create(uri, schema)

    with tiledb.SparseArray(uri, mode='w') as A:
        I = [np.datetime64('1970-01-01 00:00:00.000001'),
             np.datetime64('1980-01-01 00:00:00.000002'),
             np.datetime64('1990-01-01 00:00:00.000003'),
             np.datetime64('2000-01-01 00:00:00.000004'),
             np.datetime64('2010-01-01 00:00:00.000005'),
             np.datetime64('2020-01-01 00:00:00.000006')]
        data = np.array(([1,2,3,4,5,6]))
        A[I] = data

#### R

    library(tiledb)
    uri <- "/tmp/tiledb/dt_us"
    arr <- tiledb_array(uri, return_as="data.frame")
    arr[]
    ##                         rows a
    ## 1 1970-01-01 00:00:00.000001 1
    ## 2 1980-01-01 00:00:00.000001 2
    ## 3 1990-01-01 00:00:00.000002 3
    ## 4 2000-01-01 00:00:00.000003 4
    ## 5 2010-01-01 00:00:00.000005 5
    ## 6 2020-01-01 00:00:00.000005 6

### Nanosecond

#### Python

    import numpy as np
    import sys
    import os
    import tiledb
    uri = "/tmp/tiledb/dt_ns"
    dom = tiledb.Domain(tiledb.Dim(name="rows",
                                   domain=(np.datetime64('1969-01-01'), np.datetime64('2030-12-31')),
                                   tile=np.timedelta64(10, 'ns'),
                                   dtype=np.datetime64('', 'ns')))
    schema = tiledb.ArraySchema(domain=dom,
                                sparse=True,
                                attrs=[tiledb.Attr(name="a", dtype=np.int32)])
    if (os.path.isdir(uri)):
        tiledb.VFS().remove_dir(uri)
    tiledb.SparseArray.create(uri, schema)

    with tiledb.SparseArray(uri, mode='w') as A:
        I = [np.datetime64('1970-01-01 00:00:00.000000001'),
             np.datetime64('1980-01-01 00:00:00.000000002'),
             np.datetime64('1990-01-01 00:00:00.000000003'),
             np.datetime64('2000-01-01 00:00:00.000000004'),
             np.datetime64('2010-01-01 00:00:00.000000005'),
             np.datetime64('2020-01-01 00:00:00.000000006')]
        data = np.array(([1,2,3,4,5,6]))
        A[I] = data

#### R

    library(tiledb)
    uri <- "/tmp/tiledb/dt_ns"
    arr <- tiledb_array(uri, return_as="data.frame")
    arr[]
    ##                                  rows a
    ## 1 1970-01-01T00:00:00.000000001+00:00 1
    ## 2 1980-01-01T00:00:00.000000002+00:00 2
    ## 3 1990-01-01T00:00:00.000000003+00:00 3
    ## 4 2000-01-01T00:00:00.000000004+00:00 4
    ## 5 2010-01-01T00:00:00.000000005+00:00 5
    ## 6 2020-01-01T00:00:00.000000006+00:00 6

## Use integer64 Directly

Sometimes we may want to access the date or datetimes value in their native `integer64` format. To do so, we set a toggle when opening the array as shown in the following example which uses the array from the preceding example (at resolution of nanosecond).

    library(tiledb)
    uri <- "/tmp/tiledb/dt_ns"
    arr <- tiledb_array(uri, return_as="data.frame", datetimes_as_int64=TRUE)
    arr[]
    ##                  rows a
    ## 1                   1 1
    ## 2  315532800000000002 2
    ## 3  631152000000000003 3
    ## 4  946684800000000004 4
    ## 5 1262304000000000005 5
    ## 6 1577836800000000006 6

We can also write `integer64` types. The following example adds two extra rows:

    library(tiledb)
    uri <- "/tmp/tiledb/dt_ns"
    arr <- tiledb_array(uri, return_as="data.frame", datetimes_as_int64=TRUE)
    arr[] <- data.frame( rows=bit64::as.integer64(2:3), a=102:103)
    arr[]
    ##                  rows   a
    ## 1                   1   1
    ## 2                   2 102
    ## 3                   3 103
    ## 4  315532800000000002   2
    ## 5  631152000000000003   3
    ## 6  946684800000000004   4
    ## 7 1262304000000000005   5
    ## 8 1577836800000000006   6