tooltime

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

tooltime operates on 4 abstract time datatypes:

	meaning	example
`Timestamp`	a moment in time	today at 3:03 PM
`Timelength`	a length of time	four minutes
`Timeperiod`	a period with a start and an end	from 3:03 PM to 3:07 PM today
`Timefrequency`	a rate	every four minutes

Each datatype has multiple interconvertible representations using native python types

Install

pip install tooltime

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

	python type	example
`TimestampSeconds`	`int` seconds since UTC epoch	`1600000000`
`TimestampSecondsPrecise`	`float` seconds since UTC epoch	`1600000000.0`
`TimestampLabel`	`str` in format `'%Y%m%d_%H%M%SZ'`	`'20200913_122640Z'`
`TimestampISO`	`str` in ISO 8601 format	`'2020-09-13T12:26:40Z'`
`TimestampISOPretty`	`str` in ISO 8601 format, prettier	`'2020-09-13 12:26:40Z'`
`TimestampDatetime`	`datetime.datetime` object	`datetime.datetime.now()`
`TimestampYear`	`str` of year	`2020`
`TimestampMonth`	`str` of dashed year and month	`2020-09`
`TimestampMonthCompact`	`str` of plain year and month	`202009`
`TimestampDate`	`str` of dashed date	`2020-09-13`
`TimestampDateCompact`	`str` of plain date	`20200913`

`Timelength` Representations

	python type	example
`TimelengthSeconds`	`int` seconds	`310`
`TimelengthSecondsPrecise`	`float` seconds	`310.0`
`TimelengthLabel`	`str` of `'{number}{time_unit}'`	`'310s'`
`TimelengthClock`	`str` of `'{hours}:{minutes}:{seconds}'`	`'0:05:10'`
`TimelengthPhrase`	`str` of comma-separated list of English amounts	`'5 minutes, 10 seconds'`
`TimelengthClockPhrase`	`str` of `TimelengthPhrase` modulo 1 day, remainder in `TimelengthClock`	`'3 days, 0:05:10'`
`TimelengthTimedelta`	`datetime.timedelta` object	`datetime.timedelta(3, 310)`

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

`Timeperiod` Representations

	python type	example
`TimeperiodMap`	`dict` in form `{'start': 'Timestamp', 'end': 'Timestamp'}`	`{'start': 1600000000, 'end': 1600000001}`
`TimeperiodPair`	`list` in form `[start, end]`	`[1600000000, 1600000001]`

`Timefrequency` Representations

	python type	example
`TimefrequencyFrequency`	`int` or `float` of cycles per second	`5.0`
`TimefrequencyCountPer`	`dict` in form `{'count': ['int', 'float'], 'per': 'Timelength'}`	`{'count': 5, 'per': '1s'}`
`TimefrequencyInterval`	`dict` in form `{'interval': 'Timelength'}`	`{'interval': 0.2}`

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:

operation type	template (functions that are more specific will have better performance)	description
identification	`is_<datatype>()`	return `bool` of whether input is instance of datatype
identification	`is_<datatype>_<representation>()`	return `bool` of whether input is instance of specific datatype representation
identification	`detect_<datatype>_representation()`	return `str` of datatype representation name
creation	`create_<datatype>()`	create datatype
creation	`create_<datatype>_<representation>()`	create datatype with specific representation
conversion	`convert_<datatype>()`	convert datattype representation
conversion	`convert_<datatype>_to_<representation>()`	convert datatype to specific representation
conversion	`convert_<datatype>_<representation>_to _<representation>()`	convert datatype with known representation to specific representation

All functions for each datatype are listed below

Identfication Functions
Creation Functions
Conversion Functions
Specialized Functions

Identification Functions

	example call	example output
`is_timestamp()`	`is_timestamp('hello')`	`False`
`is_timestamp_seconds()`	`is_timestamp_seconds(610)`	`True`
`is_timestamp_label()`	`is_timestamp_label(610)`	`False`
`is_timestamp_iso()`	`is_timestamp_iso( '2020-09-13T12:26:40Z')`	`True`
`is_timestamp_datetime()`	`is_timestamp_datetime(610)`	`False`
`detect_timestamp _representation()`	`detect_timestamp_representation( 610)`	`'TimestampSeconds'`
`is_timelength()`	`is_timelength('10m')`	`True`
`is_timelength_seconds()`	`is_timelength_seconds('10m')`	`False`
`is_timelength_label()`	`is_timelength_label('10m')`	`True`
`is_timelength_clock()`	`is_timelength_clock('10m)`	`False`
`is_timelength_phrase()`	`is_timelength_phrase('10 minutes')`	`True`
`is_timelength_clock_phrase()`	`is_timelength_clock_phrase('10m')`	`False`
`is_timelength_timedelta()`	`is_timelength_timedelta('10 minutes')`	`False`
`detect_timelength _representation()`	`detect_timelength_representation( '10m')`	`'TimelengthLabel'`
`is_timeperiod()`	`is_timeperiod({'start': 1600000000, 'end': 1600000001'})`	`True`
`is_timeperiod_map()`	`is_timeperiod_map({'start': 1600000000, 'end': 1600000001'})`	`True`
`is_timeperiod_pair()`	`is_timeperiod_length({'start': 1600000000, 'end': 1600000001'})`	`False`
`detect_timeperiod _representation()`	`detect_timeperiod_representation( {'start': 1600000000, 'end': 1600000001'})`	`'TimeperiodMap'`
`is_timefrequency()`	`is_timefrequency({'interval': 0.2})`	`True`
`is_timefrequency_frequency()`	`is_timefrequency_frequency( {'interval': 0.2})`	`False`
`is_timefrequency_count_per()`	`is_timefrequency_count_per( {'interval': 0.2})`	`False`
`is_timefrequency_interval()`	`is_timefrequency_interval( {'interval': 0.2})`	`True`
`detect_timefrequency _representation()`	`detect_timefrequency _representation({'interval': 0.2})`	`'TimefrequencyInterval'`

Creation Functions

	example call	example output
`create_timestamp_seconds()`	`create_timestamp_seconds()`	`1600000000`
`create_timestamp_label()`	`create_timestamp_label()`	`'20200913_122640Z'`
`create_timestamp_iso()`	`create_timestamp_iso()`	`'2020-09-13T12:26:40Z'`
`create_timestamp_datetime()`	`create_timestamp_datetime()`	`'2020-09-13T12:26:40Z'`
`create_timelength()`	`create_timelength(seconds=310, to_representation= 'TimelengthLabel')`	`'310s'`
`create_timelength_seconds()`	`create_timelength_seconds( seconds=310)`	`310`
`create_timelength_seconds_precise()`	`create_timelength_seconds _precise(seconds=310)`	`310.0`
`create_timelength_label()`	`create_timelength_label( seconds=310)`	`'310s'`
`create_timelength_clock()`	`create_timelength_clock( seconds=310)`	`'0:05:10'`
`create_timelength_phrase()`	`create_timelength_phrase( seconds=310)`	`'5 minutes, 10 seconds'`
`create_timelength_clock_phrase()`	`create_timelength_clock_phrase( seconds=310)`	`'0:05:10'`
`create_timelength_timedelta()`	`create_timelength_timedelta( seconds=310)`	`datetime.timedelta(0, 310)`
`create_timeperiod()`	`create_timeperiod( start=1600000000, length=1)`	`{'start': 1600000000, 'end': 1600000001}`
`create_timeperiod_map()`	`create_timeperiod_map( start=1600000000, length=1)`	`{'start': 1600000000, 'end': 1600000001}`
`create_timeperiod_pair()`	`create_timeperiod_pair( start=1600000000, length=1)`	`[1600000000, 1600000001]`
`create_timefrequency()`	`create_timefrequency(count=5, per=1)`	`5.0`
`create_timefrequency_frequency()`	`create_timefrequency_frequency( count=5, per=1)`	`5.0`
`create_timefrequency_count_per()`	`create_timefrequency_count_per( count=5, per=1)`	`{'count': 5, 'per': 1}`
`create_timefrequency_interval()`	`create_timefrequency_interval( interval=0.2)`	`{'interval': 0.2}`

Conversion Functions

Timestamp Conversion Functions

	example call	example output
`convert_timestamp()`	`convert_timestamp(1600000000, 'TimestampLabel')`	`'20200913_122640Z'`
`timestamp_to_seconds()`	`timestamp_to_seconds( '20200913_122640Z')`	`1600000000`
`timestamp_to_label()`	`timestamp_to_label(1600000000)`	`'20200913_122640Z'`
`timestamp_to_iso()`	`timestamp_to_iso(1600000000)`	`'2020-09-13T12:26:40Z'`
`timestamp_to_datetime()`	`timestamp_to_datetime(1600000000)`	`datetime.datetime(2020, 9, 13, 12, 26, 40)`
`timestamp_seconds_to_label()`	`timestamp_seconds_to_label( 1600000000)`	`'20200913_122640Z'`
`timestamp_label_to_seconds()`	`timestamp_label_to_seconds( '20200913_122640Z')`	`1600000000`
`timestamp_seconds_to_iso()`	`timestamp_seconds_to_iso(1600000000)`	`'2020-09-13T12:26:40Z'`
`timestamp_iso_to_seconds()`	`timestamp_iso_to_seconds( '2020-09-13T12:26:40Z')`	`1600000000`

Timelength Conversion Functions

	example call	example output
`convert_timelength()`	`convert_timelength(1600000000, 'TimestampLabel')`	`'20200913_122640Z'`
`timelength_to_seconds()`	`timelength_to_seconds(610)`	`610`
`timelength_to_phrase()`	`timelength_to_phrase(610)`	`'10 minutes, 10 seconds'`
`timelength_to_clock()`	`timelength_to_clock(610)`	`'0:10:10'`
`timelength_to_clock_phrase()`	`timelength_to_clock_phrase( 259810)`	`'3 days, 0:10:10'`
`timelength_seconds_to_label()`	`timelength_seconds_to_label(600)`	`'10m'`
`timelength_seconds_to_clock()`	`timelength_seconds_to_clock(610)`	`'0:10:10'`
`timelength_seconds_to_phrase()`	`timelength_seconds_to_phrase(610)`	`'10 minutes, 10 seconds'`
`timelength_seconds_to_clock_phrase()`	`timelength_seconds_to_clock _phrase(600)`	`'3 days, 0:05:10'`
`timelength_seconds_to_timedelta()`	`timelength_seconds_to_timedelta( 259810)`	`datetime.timedelta( 3, 610)`
`timelength_label_to_seconds()`	`timelength_label_to_seconds( '10m')`	`600`
`timelength_clock_to_seconds()`	`timelength_clock_to_seconds( '0:10:10')`	`610`
`timelength_phrase_to_seconds()`	`timelength_phrase_to_seconds('10 minutes')`	`610`
`timelength_clock_phrase_to_seconds()`	`timelength_clock_phrase_to _seconds( '3 days, 0:05:10')`	`259510`
`timelength_timedelta_to_seconds()`	`timelength_timedelta_to_seconds( timedelta)`	`259510`

Timeperiod Conversion Functions

	example call	example output
`convert_timeperiod()`	`convert_timeperiod({'start': 1600000000, 'end': 1600000001}, 'TimePeriodStartLength')`	`{'start': 1600000000, 'length': 1}`
`convert_timeperiod_to_start_end()`	`convert_timeperiod_to_start_end( {'start': 1600000000, 'end': 1600000001}, 'TimePeriodStartLength')`	`{'start': 1600000000, 'end': 1600000001}`
`convert_timeperiod_to_start_length()`	`convert_timeperiod_to_start_length( {'start': 1600000000, 'end': 1600000001}, 'TimePeriodStartLength')`	`{'start': 1600000000, 'length': 1}`
`convert_timeperiod_to_end_length()`	`convert_timeperiod_to_end_length( {'start': 1600000000, 'end': 1600000001}, 'TimePeriodStartLength')`	`{'end': 1600000001, 'length': 1}`

Timefrequency Conversion Functions

	example call	example output
`convert_timefrequency()`	`convert_timefrequency({'count': 5, 'per': '1s'}, 'TimeInterval')`	`{'interval': 0.5}`
`convert_timefrequency_to_frequency()`	`convert_timefrequency_to_frequency( {'interval': 0.2})`	`5.0`
`convert_timefrequency_to_count_per()`	`convert_timefrequency_to_count_per( {'interval': 0.2})`	`{'count': 5, 'per': '1s'}`
`convert_timefrequency_to_interval()`	`convert_timefrequency_to_interval( {'count': 5, 'per': '1s'})`	`{'interval': 0.2}`

Specialized Functions

these are functions that are specific to each datatype

datatype	function	description
`Timestamp`	`floor_datetime()`	return floor of `datetime` to specified unit of precision
`Timestamp`	`get_unit_lowest_value()`	return int of lowest possible for value for a given time unit
`Timestamp` iterable	`print_timestamp_summary()`	print a variety of summary statistics about `Timestamp`s
`Timeperiod`	`timeperiods_overlap()`	return `bool` of whether `Timeperiod`s have any overlap
`Timeperiod`	`timeperiod_contains()`	return `bool` of whether `Timeperiod` contains other `Timeperiod`
`Timeperiod`	`create_superset_timeperiod()`	create `Timeperiod` that contains all input `Timeperiod`s
`Timeperiod`	`create_overlapping_timeperiod()`	create copy of `Timeperiod` with start or end trimmed or extended by relative or absolute amounts
`Timeperiod`	`get_standard_timeperiod()`	get standardized `Timeperiod` whose boundaries are integer multiples of some block_unit
`Timefrequency`	`detect_resolution()`	detect resolution of iterable of `Timestamp`

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.

sslivkoff/tooltime

tooltime

Install

Contents

Example Usage

Convert Timelength Representations

Introspect Time Data

Create Standardized Timeperiods

Datatype Representations

`Timestamp` Representations

`Timelength` Representations

`Timeperiod` Representations

`Timefrequency` Representations

Function Reference

Identification Functions

Creation Functions

Conversion Functions

Timestamp Conversion Functions

Timelength Conversion Functions

Timeperiod Conversion Functions

Timefrequency Conversion Functions

Specialized Functions

Frequently Asked Questions

How are timezones handled?

Why not just use `datetime`?

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

sslivkoff/tooltime

tooltime

Install

Contents

Example Usage

Convert Timelength Representations

Introspect Time Data

Create Standardized Timeperiods

Datatype Representations

Timestamp Representations

Timelength Representations

Timeperiod Representations

Timefrequency Representations

Function Reference

Identification Functions

Creation Functions

Conversion Functions

Timestamp Conversion Functions

Timelength Conversion Functions

Timeperiod Conversion Functions

Timefrequency Conversion Functions

Specialized Functions

Frequently Asked Questions

How are timezones handled?

Why not just use datetime?

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

`Timestamp` Representations

`Timelength` Representations

`Timeperiod` Representations

`Timefrequency` Representations

Why not just use `datetime`?