integrator

integrator

DataIntegratorHybrid

A flexible utility class to integrate data from various sources, including: - API instances (e.g., DatapointAPI) - Direct raw data (e.g., UUID list, metadata, timeseries DataFrame) - Hybrid approaches (combination of instances and raw data)

Problems (an unsupported source, a missing join key, timeseries sources with different timezone handling) are reported as :class:~ts_shape.errors.DataQualityWarning.

combine_data classmethod

combine_data(
    timeseries_sources: (
        list[DataFrame | object] | None
    ) = None,
    metadata_sources: (
        list[DataFrame | object] | None
    ) = None,
    uuids: list[str] | None = None,
    join_key: str = "uuid",
    merge_how: str = "left",
) -> pd.DataFrame

Combine timeseries and metadata from various sources.

Timeseries sources are concatenated. When their time columns differ in timezone handling (some tz-aware, some naive, or different zones), every source is converted to UTC -- naive times are read as UTC -- with a :class:~ts_shape.errors.DataQualityWarning. Metadata sources are combined per join_key: several sources may describe the same uuid with different columns, but two different values for the same uuid and column raise ValueError.

Parameters:

Name	Type	Description	Default
timeseries_sources	list[DataFrame | object] | None	List of timeseries sources (DataFrame or instances with fetch_data_as_dataframe).	None
metadata_sources	list[DataFrame | object] | None	List of metadata sources (DataFrame or instances with fetch_metadata).	None
uuids	list[str] | None	Optional list of UUIDs to keep; applied whether or not metadata is given (compared as text).	None
join_key	str	Key column to use for merging, default is "uuid".	'uuid'
merge_how	str	Merge strategy ('left', 'inner', etc.), default is "left".	'left'

Returns:

Type	Description
DataFrame	A combined DataFrame. Without timeseries data, an empty frame with
DataFrame	the standard columns (systime, uuid, value_*,
DataFrame	is_delta).

Raises:

Type	Description
ValueError	When metadata sources give conflicting rows for one uuid.