atomscale.timeseries.provider.properties_payload_to_dataframe#

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

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