tooltime

tooltime makes it simple to represent and manipulate many different representations of time

tooltime operates on 4 abstract time datatypes:

Each datatype has multiple interconvertible representations using native python types

Install

pip install tooltime

Contents

• Example Usage
• Datatype Representations
• Function Reference
• Frequently Asked Questions

Example Usage

Convert Timelength Representations

import tooltime

tooltime.timelength_to_seconds('10m')
> 600
tooltime.timelength_to_label(600)
> '10m'
tooltime.timelength_to_clock('10m')
> '0:10:00'
tooltime.timelength_to_phrase('10m')
> '10 minutes'

(
    tooltime.timelength_to_seconds(600)
    == tooltime.timelength_to_seconds('10m')
    == tooltime.timelength_to_seconds('0:10:00')
    == tooltime.timelength_to_seconds('10 minutes')
)
> True

Introspect Time Data

# load data
timestamps = load_data(...)

# summarize sequence
tooltime.print_timestamp_summary(timestamps)

n_t: 216
n_unique: 216
extent:
    start: 20210117_201840Z (1610914720.757)
    end:   20210118_235708Z (1611014228.542)
    duration: 1 days, 3:38:27.785000 (99507.785000086 s)
resolution:
    median_dt: 4m
    mean_dt: 462s
    missing timestamps: 200 (if median_dt maintained)
    outlier_dts: 20
        small: 8        dt < median_dt / (1 + outlier_rtol)
        large: 12        dt > median_dt * (1 + outlier_rtol)
        (outlier_rtol = 0.5)

Create Standardized Timeperiods

Create timeperiods whose boundaries are integer multiples of some block_unit. These useful for placing erratically distributed timestamps into regular bins

timestamp = 1600000000
block_size = 3
print('timestamp:', tooltime.timestamp_to_label(timestamp))
print()
print('standardized timeperiods containing timestamp:')
for block_unit in ['day', 'hour', 'minute']:
    timeperiod = tooltime.get_standard_timeperiod(
        timestamp=timestamp,
        block_size=block_size,
        block_unit=block_unit,
    )    
    block_str = str(block_size) + ' ' + block_unit
    timeperiod_str = tooltime.timeperiod_to_str(timeperiod)
    print('   %8s' % block_str + ':', timeperiod_str)

timestamp: 20200913_122640Z

standardized timeperiods containing timestamp:
      3 day: [20200913_000000Z, 20200915_235959Z]
     3 hour: [20200913_120000Z, 20200913_145959Z]
   3 minute: [20200913_122400Z, 20200913_122659Z]

Datatype Representations

each of the 4 time datatypes has multiple interconvertible representations, and each representation is assembled from native python types:

Timestamp Representations

Timelength Representations

valid time units are 's', 'm', 'h', 'd', 'w', 'M', and 'y', indicating seconds, minutes, hours, days, weeks, months, and years

Timeperiod Representations

Timefrequency Representations

Function Reference

• all functions can be accessed using syntax tooltime.<function_name>(...)
• tooltime contains many functions, but most derive from one of the following patterns:

All functions for each datatype are listed below

• Identfication Functions
• Creation Functions
• Conversion Functions
• Specialized Functions

Identification Functions

Creation Functions

Conversion Functions

Timestamp Conversion Functions

Timelength Conversion Functions

Timeperiod Conversion Functions

Timefrequency Conversion Functions

Specialized Functions

these are functions that are specific to each datatype

Frequently Asked Questions

How are timezones handled?

All Timestamp representations except TimestampDatetime are linked to specific timezone, which in most cases is GMT (UTC). Counts of seconds since epoch (as in TimestampSeconds and TimestampSecondsPrecise) are conventionally always GMT (UTC). TimestampLabel and TimestampISO use a military time zone abbreviation as their last characters. The datetime object of TimestampDatetime internally represents a count of seconds since epoch, but datetime objects can have implicit or explicit timezones depending on how they are instantiated.

Why not just use datetime?

• datetime does not handle timezones in a simple or explicit way.
• datetime does not make it easy to ingest, output, or convert representations of time using primitive python types.
• tooltime contains different convenience functions than datetime that are better suited for different workloads.

What do the T and Z mean in an ISO 8601 timestamp, such as "2020-09-13T12:26:40Z"?

The T character separates the date portion of the timestamp from the time portion. The Z character indicates the GMT (UTC) timezone. Each timezone has its own letter. Read more here.