Time Series

Time series is in Beta. Contact your Encord support representative to enable the feature for your Organization.

Time series data lets you import a CSV file and view its columns as charted channels in the Label Editor timeline.

This page explains the CSV format Encord expects, how to register time series files, and how to view and label them in the Label Editor. To upload time series files from your machine and set how channels are displayed using the SDK, see Time-series Data (SDK).

Supported Files

Time series data currently supports CSV files with a MIME type of text/csv or application/csv.

Each file must contain a header row, one timestamp column, and at least one channel column. See Timestamp column for how Encord picks and interprets the timestamp column.

Example

time_ms,acc_x,acc_y,acc_z
0,0.12,0.02,0.98
100,0.18,0.03,1.01
200,0.15,0.01,0.99

This example uses millisecond timestamps, which work well for standalone time series files. If you pair the file with a video, use frame indices instead. See Align Time Series with Video.

Column Structure

Timestamp column

Encord does not validate time series CSVs on upload. The Label Editor validates and parses the file when you open it, so a CSV that uploads without errors can still display incorrectly. Check your file against the rules below before you upload it.

Encord picks the timestamp column as follows:

• The timestamp column is the first column whose header is t, time, or timestamp, or starts with one of these followed by _ or - (for example time_ms or timestamp-utc). Matching is case-insensitive.
• If no header matches, Encord uses the first column as the timestamp column.
• Every other column is treated as a channel and plotted in the timeline. Channel headers must be unique.
• Empty, NaN, null, or otherwise non-numeric channel values are treated as gaps.
• Rows without a valid timestamp are skipped.

Timestamp units

Encord infers the timestamp unit from the suffix of the timestamp column header:

Header suffix	Unit	Example header	Example values
_ns, _nanosecond(s)	Nanoseconds	time_ns	0, 33333333
_us, _microsecond(s)	Microseconds	time_us	0, 33333
_ms, _millisecond(s)	Milliseconds	time_ms	0, 100, 200
_s, _sec, _second(s)	Seconds	time_s	0, 1, 2
_iso	ISO 8601 date-time	time_iso	2026-09-30T10:00:00.000Z
No recognized suffix	Frame index (see below)	frame, timestamp	0, 1, 2

If the header has no recognized suffix, Encord looks at the values. Clock values such as 00:01:23.500 are read as elapsed time, and ISO 8601 date-times are read as ISO timestamps. Any other numeric values are treated as frame indices on the timeline.

Nanosecond, microsecond, millisecond, and second timestamps must be whole numbers. Rows with decimal values, such as 33.333 in a time_ms column or 0.5 in a time_s column, are skipped without an error. To keep sub-unit precision, use a smaller unit (for example time_us instead of time_ms) or use frame indices.

Unit-based timestamps (nanoseconds through ISO) are measured relative to the first valid row of the CSV. The first row always lines up with the start of the timeline, whatever its absolute value. ISO timestamps are read with millisecond precision.

Align Time Series with Video

When a time series file shares a timeline with a video, for example in a Data Group, index the time series by video frame rather than by time:

1. Make the frame column the first column of the CSV and give it a header without a unit suffix, such as frame.
2. Set each value to the video frame the sample belongs to, starting at 0 for the first video frame.

Frame index values are placed directly on the matching video frames, so the chart stays synchronized with the frame cursor. Values do not need to be whole numbers. A value of 1.5 sits halfway between frames 1 and 2, so data sampled faster than the video frame rate keeps its position.

To convert timestamps to frame indices, multiply the time in seconds since the start of the video by the video frame rate:

frame = (sample_time_seconds - video_start_seconds) * video_fps

For example, 60 Hz sensor data paired with a 30 fps video produces two samples per video frame:

Frame-indexed time series for a 30 fps video

frame,acc_x,acc_y,acc_z
0,0.12,0.02,0.98
0.5,0.14,0.02,0.99
1,0.18,0.03,1.01
1.5,0.16,0.02,1.00
2,0.15,0.01,0.99

If the time series starts later than the video, start the frame column at the matching frame (for example 45 for a sample taken 1.5 seconds into a 30 fps video). Unit-based timestamps always start at the first row, so they cannot express this offset.

Common Issues

Symptom	Likely cause	Fix
The chart drifts away from the video or does not line up with the frame cursor	The CSV uses unit-based timestamps (for example time_ms) in a Data Group with a video	Use a frame index column, as described in Align Time Series with Video
Rows or samples are missing from the chart	Decimal values in a _ns, _us, _ms, or _s timestamp column	Use whole numbers, a smaller unit, or frame indices
The chart is offset from the start of the video	The first CSV row is not at the start of the video	Remove leading rows, or use frame indices that start at the matching video frame
Timestamps are plotted as frames instead of time	The header has no recognized unit suffix, for example Time (ms)	Rename the header, for example to time_ms
A timestamp column is plotted as a channel	The timestamp header does not start with t, time, or timestamp, and it is not the first column	Move the timestamp column to the first position or rename it
The file fails to open with “Time series CSV channel headers must be unique”	Two channel columns share a header	Give every channel a unique header

These assumptions are temporary. In a future release, you will be able to specify them at upload time.

Register Time Series Data

Register time series CSV files with the time_series top-level key in your upload JSON.

Time series upload JSON

{
  "time_series": [
    {
      "objectUrl": "s3://my-bucket/sensors/session-001.csv",
      "title": "Session 001 telemetry",
      "clientMetadata": {
        "vehicle": "A-17",
        "route": "north-loop"
      }
    }
  ]
}

Then register the JSON file through the existing data registration flow:

• UI: Manual Data Registration
• SDK: Import/Register Data

To upload a local CSV file instead of registering one from cloud storage, use upload_time_series() in the SDK. See Time-series Data (SDK).

Annotating Time Series Data

Open a time series task in the Label Editor. The timeline displays the channels above the annotation rows. Annotators can use the chart as context while creating and reviewing time range labels.

For Composite Scenes, the timeline also displays each non-timestamp column from attached time series CSV streams. For MCAP Scenes with a configured layout, it displays the selected numeric time-series sub-channels.

To label intervals on a time series file, add a Time range object to your Ontology. Time range labels appear on the timeline and can be used to mark events, anomalies, or segments of interest.

The chart supports multiple channels. Channels are color-coded, and the timeline view can show time range labels below the chart. Time series uses the same timeline annotation interactions as other temporal modalities:

1. Select the Time range class.
2. Create a range on the timeline for the event or segment you want to label.
3. Adjust the range boundaries as needed.
4. Submit the task when all required labels are complete.

To display channel values when you hover over a chart, open Visualization and select Show tooltip. Encord saves this selection as a Label Editor preference. You can also toggle it from the Actions menu with Show time-series tooltip.

Time Series in Data Groups

When a Data Group layout assigns a time series file to a tile, the Label Editor displays its channels in that tile instead of repeating them in the shared timeline. The chart stays synchronized with the group’s frame navigation and displays the current frame cursor. Scroll to pan the chart. To zoom, hold Ctrl (Windows) or Command (macOS) while scrolling, or pinch on a trackpad. You can also create and edit time range labels directly in the tile.

Use Time series style settings in the tile toolbar to display each channel as a line or points and adjust its line width or point size. Encord assigns different default colors to channels across time series tiles so that you can distinguish them.

Customize Time Series Channels

Use the channel controls in the timeline to adjust how each CSV channel appears in the chart.

You can:

• Hide or show individual channels.
• Set a custom channel color.
• Change the channel style between line and points.
• Resize the channel by changing line width or point size.

You can also set channel appearance when you upload a time series file, or update it on existing files, using the SDK. See Time-series Data (SDK).