Package: tooltime
tooltimetooltimemakes it simple to represent and manipulate many different representations of timetooltimeoperates on 4 abstract time datatypes:meaningexampleTimestampa moment in timetoday at 3:03 PMTimelengtha length of timefour minutesTimeperioda period with a start and an endfrom 3:03 PM to 3:07 PM todayTimefrequencya rateevery four minutesEach datatype has multiple interconvertible representations using native python typesInstallpip install tooltimeContentsExample UsageDatatype RepresentationsFunction ReferenceFrequently Asked QuestionsExample UsageConvert Timelength Representationsimporttooltimetooltime.timelength_to_seconds('10m')>600tooltime.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'))>TrueIntrospect Time Data# load datatimestamps=load_data(...)# summarize sequencetooltime.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 TimeperiodsCreate timeperiods whose boundaries are integer multiples of someblock_unit. These useful for placing erratically distributed timestamps into regular binstimestamp=1600000000block_size=3print('timestamp:',tooltime.timestamp_to_label(timestamp))print()print('standardized timeperiods containing timestamp:')forblock_unitin['day','hour','minute']:timeperiod=tooltime.get_standard_timeperiod(timestamp=timestamp,block_size=block_size,block_unit=block_unit,)block_str=str(block_size)+' '+block_unittimeperiod_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 Representationseach of the 4 time datatypes has multiple interconvertible representations, and each representation is assembled from native python types:TimestampRepresentationspython typeexampleTimestampSecondsintseconds since UTC epoch1600000000TimestampSecondsPrecisefloatseconds since UTC epoch1600000000.0TimestampLabelstrin format'%Y%m%d_%H%M%SZ''20200913_122640Z'TimestampISOstrin ISO 8601 format'2020-09-13T12:26:40Z'TimestampISOPrettystrin ISO 8601 format, prettier'2020-09-13 12:26:40Z'TimestampDatetimedatetime.datetimeobjectdatetime.datetime.now()TimestampYearstrof year2020TimestampMonthstrof dashed year and month2020-09TimestampMonthCompactstrof plain year and month202009TimestampDatestrof dashed date2020-09-13TimestampDateCompactstrof plain date20200913TimelengthRepresentationspython typeexampleTimelengthSecondsintseconds310TimelengthSecondsPrecisefloatseconds310.0TimelengthLabelstrof'{number}{time_unit}''310s'TimelengthClockstrof'{hours}:{minutes}:{seconds}''0:05:10'TimelengthPhrasestrof comma-separated list of English amounts'5 minutes, 10 seconds'TimelengthClockPhrasestrofTimelengthPhrasemodulo 1 day, remainder inTimelengthClock'3 days, 0:05:10'TimelengthTimedeltadatetime.timedeltaobjectdatetime.timedelta(3, 310)valid time units are's','m','h','d','w','M', and'y', indicating seconds, minutes, hours, days, weeks, months, and yearsTimeperiodRepresentationspython typeexampleTimeperiodMapdictin form{'start': 'Timestamp', 'end': 'Timestamp'}{'start': 1600000000, 'end': 1600000001}TimeperiodPairlistin form[start, end][1600000000, 1600000001]TimefrequencyRepresentationspython typeexampleTimefrequencyFrequencyintorfloatof cycles per second5.0TimefrequencyCountPerdictin form{'count': ['int', 'float'], 'per': 'Timelength'}{'count': 5, 'per': '1s'}TimefrequencyIntervaldictin form{'interval': 'Timelength'}{'interval': 0.2}Function Referenceall functions can be accessed using syntaxtooltime.<function_name>(...)tooltimecontains many functions, but most derive from one of the following patterns:operation typetemplate(functions that are more specific will have better performance)descriptionidentificationis_<datatype>()returnboolof whether input is instance of datatypeidentificationis_<datatype>_<representation>()returnboolof whether input is instance of specific datatype representationidentificationdetect_<datatype>_representation()returnstrof datatype representation namecreationcreate_<datatype>()create datatypecreationcreate_<datatype>_<representation>()create datatype with specific representationconversionconvert_<datatype>()convert datattype representationconversionconvert_<datatype>_to_<representation>()convert datatype to specific representationconversionconvert_<datatype>_<representation>_to _<representation>()convert datatype with known representation to specific representationAll functions for each datatype are listed belowIdentfication FunctionsCreation FunctionsConversion FunctionsSpecialized FunctionsIdentification Functionsexample callexample outputis_timestamp()is_timestamp('hello')Falseis_timestamp_seconds()is_timestamp_seconds(610)Trueis_timestamp_label()is_timestamp_label(610)Falseis_timestamp_iso()is_timestamp_iso( '2020-09-13T12:26:40Z')Trueis_timestamp_datetime()is_timestamp_datetime(610)Falsedetect_timestamp _representation()detect_timestamp_representation( 610)'TimestampSeconds'is_timelength()is_timelength('10m')Trueis_timelength_seconds()is_timelength_seconds('10m')Falseis_timelength_label()is_timelength_label('10m')Trueis_timelength_clock()is_timelength_clock('10m)Falseis_timelength_phrase()is_timelength_phrase('10 minutes')Trueis_timelength_clock_phrase()is_timelength_clock_phrase('10m')Falseis_timelength_timedelta()is_timelength_timedelta('10 minutes')Falsedetect_timelength _representation()detect_timelength_representation( '10m')'TimelengthLabel'is_timeperiod()is_timeperiod({'start': 1600000000, 'end': 1600000001'})Trueis_timeperiod_map()is_timeperiod_map({'start': 1600000000, 'end': 1600000001'})Trueis_timeperiod_pair()is_timeperiod_length({'start': 1600000000, 'end': 1600000001'})Falsedetect_timeperiod _representation()detect_timeperiod_representation( {'start': 1600000000, 'end': 1600000001'})'TimeperiodMap'is_timefrequency()is_timefrequency({'interval': 0.2})Trueis_timefrequency_frequency()is_timefrequency_frequency( {'interval': 0.2})Falseis_timefrequency_count_per()is_timefrequency_count_per( {'interval': 0.2})Falseis_timefrequency_interval()is_timefrequency_interval( {'interval': 0.2})Truedetect_timefrequency _representation()detect_timefrequency _representation({'interval': 0.2})'TimefrequencyInterval'Creation Functionsexample callexample outputcreate_timestamp_seconds()create_timestamp_seconds()1600000000create_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)310create_timelength_seconds_precise()create_timelength_seconds _precise(seconds=310)310.0create_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.0create_timefrequency_frequency()create_timefrequency_frequency( count=5, per=1)5.0create_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 FunctionsTimestamp Conversion Functionsexample callexample outputconvert_timestamp()convert_timestamp(1600000000, 'TimestampLabel')'20200913_122640Z'timestamp_to_seconds()timestamp_to_seconds( '20200913_122640Z')1600000000timestamp_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')1600000000timestamp_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')1600000000Timelength Conversion Functionsexample callexample outputconvert_timelength()convert_timelength(1600000000, 'TimestampLabel')'20200913_122640Z'timelength_to_seconds()timelength_to_seconds(610)610timelength_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')600timelength_clock_to_seconds()timelength_clock_to_seconds( '0:10:10')610timelength_phrase_to_seconds()timelength_phrase_to_seconds('10 minutes')610timelength_clock_phrase_to_seconds()timelength_clock_phrase_to _seconds( '3 days, 0:05:10')259510timelength_timedelta_to_seconds()timelength_timedelta_to_seconds( timedelta)259510Timeperiod Conversion Functionsexample callexample outputconvert_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 Functionsexample callexample outputconvert_timefrequency()convert_timefrequency({'count': 5, 'per': '1s'}, 'TimeInterval'){'interval': 0.5}convert_timefrequency_to_frequency()convert_timefrequency_to_frequency( {'interval': 0.2})5.0convert_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 Functionsthese are functions that are specific to each datatypedatatypefunctiondescriptionTimestampfloor_datetime()return floor ofdatetimeto specified unit of precisionTimestampget_unit_lowest_value()return int of lowest possible for value for a given time unitTimestampiterableprint_timestamp_summary()print a variety of summary statistics aboutTimestampsTimeperiodtimeperiods_overlap()returnboolof whetherTimeperiods have any overlapTimeperiodtimeperiod_contains()returnboolof whetherTimeperiodcontains otherTimeperiodTimeperiodcreate_superset_timeperiod()createTimeperiodthat contains all inputTimeperiodsTimeperiodcreate_overlapping_timeperiod()create copy ofTimeperiodwith start or end trimmed or extended by relative or absolute amountsTimeperiodget_standard_timeperiod()get standardizedTimeperiodwhose boundaries are integer multiples of some block_unitTimefrequencydetect_resolution()detect resolution of iterable ofTimestampFrequently Asked QuestionsHow are timezones handled?AllTimestamprepresentations exceptTimestampDatetimeare linked to specific timezone, which in most cases is GMT (UTC). Counts of seconds since epoch (as inTimestampSecondsandTimestampSecondsPrecise) are conventionally always GMT (UTC).TimestampLabelandTimestampISOuse amilitary time zone abbreviationas their last characters. Thedatetimeobject ofTimestampDatetimeinternally represents a count of seconds since epoch, butdatetimeobjects can have implicit or explicit timezones depending on how they are instantiated.Why not just usedatetime?datetimedoes not handle timezones in a simple or explicit way.datetimedoes not make it easy to ingest, output, or convert representations of time using primitive python types.tooltimecontains different convenience functions thandatetimethat 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 morehere.