Timestamps#
The nominal.ts module provides timestamp format specifications and utilities.
When you upload a dataset to nominal, the dataset may have timestamps in a variety of formats. For example:
ISO 8601 strings like ‘2021-01-31T19:00:00Z’
Epoch timestamps in floating-point seconds since epoch like 1612137600.123
Epoch timestamps in integer nanoseconds since epoch like 1612137600123000000
Relative timestamps like 12.123 for 12 seconds and 123 milliseconds after some start time
Various other string timestamp formats, e.g. ‘Sun Jan 31 19:00:00 2021’
All of these may also have different interpretations of the units, epoch, time zone, etc.
To simplify common usages while allowing for the full flexibility of the Nominal platform, the client library allows you to specify timestamp formats with simple strings and more complex typeful representations.
Wherever you can specify a timestamp format (typically the timestamp_type parameter), these are all examples of
valid formats:
"iso_8601"
"epoch_nanoseconds"
"epoch_microseconds"
"epoch_milliseconds"
"epoch_seconds"
"epoch_minutes"
"epoch_hours"
nominal.ts.Iso8601()
nominal.ts.Epoch("microseconds")
nominal.ts.Epoch("seconds")
nominal.ts.Epoch("hours")
nominal.ts.Relative("nanoseconds", start=datetime.fromisoformat("2021-01-31T19:00:00Z"))
nominal.ts.Relative("milliseconds", start=datetime.fromisoformat("2021-01-31T19:00:00Z"))
nominal.ts.Relative("seconds", start=datetime.fromisoformat("2021-01-31T19:00:00Z"))
nominal.ts.Relative("minutes", start=datetime.fromisoformat("2021-01-31T19:00:00Z"))
nominal.ts.Custom(r"yyyy-MM-dd[T]hh:mm:ss")
nominal.ts.Custom(r"DDD:HH:mm:ss.SSSSSS", default_year=2024)
The strings "iso_8601" and "epoch_{unit}" are equivalent to using the types nominal.ts.Iso8601() and
nominal.ts.Epoch("{unit}").
Relative and custom formats require additional parameters, so they can’t be specified with a string.
Relative timestamps require a start time that they are relative to, e.g.
nominal.ts.Relative("{unit}", start=start_time). Custom timestamp formats require a format string compatible with the
DateTimeFormatter class in Java: see java
docs.
Timestamp examples#
All of the examples use the same data (timestamp and value) expressed with different timestamp formats, and showcase how to upload them to Nominal.
ISO 8601#
Nominal requires ISO 8601 timestamps to include the time zone, e.g. '2021-01-31T19:00:00Z' or
'2021-01-31T19:00:00.123+00:00'. For example:
temperature,timestamp
20,2024-09-30T16:37:36.891349Z
21,2024-09-30T16:37:36.990262Z
22,2024-09-30T16:37:37.089310Z
19,2024-09-30T16:37:37.190015Z
23,2024-09-30T16:37:37.289585Z
22,2024-09-30T16:37:37.388941Z
28,2024-09-30T16:37:37.491115Z
24,2024-09-30T16:37:37.590826Z
dataset.add_tabular_data(
"temperature.csv",
timestamp_column="timestamp",
timestamp_type="iso_8601", # or nominal.ts.Iso8601()
)
Epoch timestamps#
Nominal supports epoch timestamps in different units: hours, minutes, seconds, milliseconds, microseconds, and nanoseconds. The values can be integers or floating-point numbers.
Floating-point seconds since epoch#
temperature,timestamp
20,1727728656.891349
21,1727728656.990262
22,1727728657.08931
19,1727728657.190015
23,1727728657.289585
22,1727728657.388941
28,1727728657.491115
24,1727728657.590826
dataset.add_tabular_data(
"temperature.csv",
timestamp_column="timestamp",
timestamp_type="epoch_seconds", # or nominal.ts.Epoch("seconds")
)
Integer nanoseconds since epoch#
temperature,timestamp
20,1727728656891349000
21,1727728656990262000
22,1727728657089310000
19,1727728657190015000
23,1727728657289585000
22,1727728657388941000
28,1727728657491115000
24,1727728657590826000
dataset.add_tabular_data(
"temperature.csv",
timestamp_column="timestamp",
timestamp_type="epoch_nanoseconds", # or nominal.ts.Epoch("nanoseconds")
)
Relative timestamps#
Similar to epoch timestamps, Nominal supports relative timestamps in the same units: hours, minutes, seconds, milliseconds, microseconds, and nanoseconds, and can be integer or floating-point values. Relative timestamps are relative to a specified start time.
temperature,timestamp
20,0
21,98913
22,197961
19,298666
23,398236
22,497592
28,599766
24,699477
dataset.add_tabular_data(
"temperature.csv",
timestamp_column="timestamp",
timestamp_type=nominal.ts.Relative(
"microseconds",
start=datetime.fromisoformat("2024-09-30T16:37:36.891349+00:00")
),
)
Custom Format#
Nominal supports custom timestamp formats. The format string should be in the format of the DateTimeFormatter
class in Java: see java
docs.
Customized ctime#
This time format is similar to the string format from ctime(), except with microsecond precision added.
temperature,timestamp
20,Mon Sep 30 16:37:36.891349 2024
21,Mon Sep 30 16:37:36.990262 2024
22,Mon Sep 30 16:37:37.089310 2024
19,Mon Sep 30 16:37:37.190015 2024
23,Mon Sep 30 16:37:37.289585 2024
22,Mon Sep 30 16:37:37.388941 2024
28,Mon Sep 30 16:37:37.491115 2024
24,Mon Sep 30 16:37:37.590826 2024
dataset.add_tabular_data(
"temperature.csv",
timestamp_column="timestamp",
timestamp_type=nominal.ts.Custom("EEE MMM dd HH:mm:ss.SSSSSS yyyy"),
)
IRIG time code#
IRIG time codes come in a variety of formats. A common IRIG format specifies a relative timestamp from the
beginning of the year, expressed in days:hours:minutes:seconds.ms.
temperature,timestamp
20,274:16:37:36.891349
21,274:16:37:36.990262
22,274:16:37:37.089310
19,274:16:37:37.190015
23,274:16:37:37.289585
22,274:16:37:37.388941
28,274:16:37:37.491115
24,274:16:37:37.590826
dataset.add_tabular_data(
"temperature.csv",
timestamp_column="timestamp",
timestamp_type=nominal.ts.Custom(r"DDD:HH:mm:ss.SSSSSS", default_year=2024),
)
Timestamp values#
IntegralNanosecondsUTC is an integer number of nanoseconds since
the Unix epoch in UTC. IntegralNanosecondsDuration is a duration
measured in nanoseconds.
API Reference#
Module: nominal.ts.
Classes
A custom timestamp format. |
|
An absolute timestamp in numeric format representing time since some epoch. |
|
ISO 8601 timestamp format, e.g. '2021-01-31T19:00:00Z' or '2021-01-31T19:00:00.123+00:00'. |
|
A relative timestamp in numeric format representing time since some start time. |
Constants
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Type aliases
|
|