atomscale.timeseries.provider

Provider classes for accessing timeseries data.

Functions

extend_with_statistics(rename_map)	Add suffix-based statistical labels to a rename map.
properties_payload_to_dataframe(properties)	Merge a property-centric payload into a wide DataFrame.
series_payload_to_dataframe(series)	Parse the legacy row-oriented series payload into a wide DataFrame.

Classes

TimeseriesProvider()

Strategy interface for parsing timeseries by domain.

atomscale.timeseries.provider.extend_with_statistics(rename_map: Mapping[str, str]) → dict[str, str]

Add suffix-based statistical labels to a rename map.

Parameters:

rename_map (Mapping[str, str])

Return type:

dict[str, str]

atomscale.timeseries.provider.properties_payload_to_dataframe(properties: Mapping[str, Mapping[str, Any]]) → DataFrame

Merge a property-centric payload into a wide DataFrame.

The payload shape is:

{
  "<property_name>": {
    "relative_time_seconds": [...],
    "unix_timestamp_ms":     [...],
    "values":                [...],
    "units": "..."
  },
  ...
}

Each property carries its own unix_timestamp_ms and relative_time_seconds arrays (potentially different sample rates). Values are outer-joined on the union of unix_timestamp_ms across all properties and forward-filled onto that index.

Forward-fill (rather than numerical interpolation) is correct for setpoints and shutter states, which are step functions that hold constant between samples. For dense continuous sensors (pyrometers etc.) the error between samples is bounded. Forward-fill preserves real measurements rather than manufacturing synthetic values.

Returned columns:

• UNIX Timestamp (int64, milliseconds)

• Time (float64, relative seconds; anchored to the longest property’s t=0 via piecewise-linear extrapolation)

• one column per property keyed by its API name (case preserved — these are setpoint/shutter/etc. names users grep for)

Index is row number. Empty input → empty DataFrame.

Unix timestamps are accepted as Decimal, float, int, or numeric strings; they are cast to int64 for the DataFrame column.

Parameters:

properties (Mapping[str, Mapping[str, Any]])

Return type:

DataFrame

atomscale.timeseries.provider.series_payload_to_dataframe(series: Sequence[Mapping[str, Any]]) → DataFrame

Parse the legacy row-oriented series payload into a wide DataFrame.

Each row carries unix_timestamp_ms, relative_time_seconds, and one key per property. This shape predates the property-centric payload and is still emitted by un-migrated API deployments. Output schema mirrors properties_payload_to_dataframe() so downstream code is shape-stable across both API versions.

Parameters:

series (Sequence[Mapping[str, Any]])

Return type:

DataFrame

class atomscale.timeseries.provider.TimeseriesProvider

Bases: ABC, Generic[R]

Strategy interface for parsing timeseries by domain.

abstractmethod fetch_raw(client: BaseClient, data_id: str) → Any

Perform the HTTP GET(s) to retrieve raw payload(s).

Parameters:

• client (BaseClient)

• data_id (str)

Return type:

Any

abstractmethod to_dataframe(raw: Any) → DataFrame

Convert raw payload to a tidy DataFrame with domain-specific renames/index.

Parameters:

raw (Any)

Return type:

DataFrame

abstractmethod build_result(client: BaseClient, data_id: str, data_type: str, ts_df: DataFrame) → R

Build time series result object

Parameters:

• client (BaseClient)

• data_id (str)

• data_type (str)

• ts_df (DataFrame)

Return type:

TypeVar(R)

snapshot_url(data_id: str) → str

API endpoint that exposes extracted/snapshot frames.

Parameters:

data_id (str)

Return type:

str

snapshot_image_uuids(frames_payload: dict[str, Any]) → list[dict]

Extract requests from frames payload. Default: no snapshots.

Parameters:

frames_payload (dict[str, Any])

Return type:

list[dict]

fetch_snapshot(client: BaseClient, req: dict) → Any | None

Resolve one snapshot request → domain-specific ImageResult (or None).

Parameters:

• client (BaseClient)

• req (dict)

Return type:

Any | None