Timeseries Operations

High-level functions for working with time series data.

get_timeseries

get_timeseries((db_path: str, component_id: int, attribute_name: str, scenario_id: Optional[int] = None, start_index: Optional[int] = None, end_index: Optional[int] = None, max_points: Optional[int] = None) -> pyconvexity.core.types.Timeseries)

Get timeseries data with efficient array-based format.

This is the main function for retrieving timeseries data. It returns a Timeseries object with values as a flat array for maximum performance.

Parameters:

• db_path: Path to the database file
• component_id: Component ID
• attribute_name: Name of the attribute (e.g., 'p', 'p_set', 'marginal_cost')
• scenario_id: Scenario ID (uses master scenario if None)
• start_index: Start index for range queries (optional)
• end_index: End index for range queries (optional)
• max_points: Maximum number of points for sampling (optional)

Returns:

Timeseries object with efficient array-based data

Example:

>>> ts = get_timeseries("model.db", component_id=123, attribute_name="p")
    >>> print(f"Length: {ts.length}, Values: {ts.values[:5]}")
    Length: 8760, Values: [100.5, 95.2, 87.3, 92.1, 88.7]

    # Get a subset of the data
    >>> ts_subset = get_timeseries("model.db", 123, "p", start_index=100, end_index=200)
    >>> print(f"Subset length: {ts_subset.length}")
    Subset length: 100

    # Sample large datasets
    >>> ts_sampled = get_timeseries("model.db", 123, "p", max_points=1000)
    >>> print(f"Sampled from {ts.length} to {ts_sampled.length} points")

set_timeseries

set_timeseries((db_path: str, component_id: int, attribute_name: str, values: Union[List[float], numpy.ndarray, pyconvexity.core.types.Timeseries], scenario_id: Optional[int] = None) -> None)

Set timeseries data using efficient array-based format.

This is the main function for storing timeseries data. It accepts various input formats and stores them efficiently in the database.

Parameters:

• db_path: Path to the database file
• component_id: Component ID
• attribute_name: Name of the attribute
• values: Timeseries values as list, numpy array, or Timeseries object
• scenario_id: Scenario ID (uses master scenario if None)

Example:

# Set from a list
    >>> values = [100.5, 95.2, 87.3, 92.1, 88.7]
    >>> set_timeseries("model.db", 123, "p_set", values)

    # Set from numpy array
    >>> import numpy as np
    >>> values = np.random.normal(100, 10, 8760)  # Hourly data for a year
    >>> set_timeseries("model.db", 123, "p_max_pu", values)

    # Set from existing Timeseries object
    >>> ts = get_timeseries("model.db", 456, "p")
    >>> set_timeseries("model.db", 123, "p_set", ts)

get_timeseries_metadata

get_timeseries_metadata((db_path: str, component_id: int, attribute_name: str, scenario_id: Optional[int] = None) -> pyconvexity.core.types.TimeseriesMetadata)

Get timeseries metadata without loading the full data.

This is useful for checking the size and properties of a timeseries before deciding whether to load the full data.

Parameters:

• db_path: Path to the database file
• component_id: Component ID
• attribute_name: Name of the attribute
• scenario_id: Scenario ID (uses master scenario if None)

Returns:

TimeseriesMetadata with length and type information

Example:

>>> meta = get_timeseries_metadata("model.db", 123, "p")
    >>> print(f"Length: {meta.length}, Type: {meta.data_type}, Unit: {meta.unit}")
    Length: 8760, Type: float, Unit: MW

get_multiple_timeseries

get_multiple_timeseries((db_path: str, requests: List[dict], max_points: Optional[int] = None) -> List[pyconvexity.core.types.Timeseries])

Get multiple timeseries efficiently in a single database connection.

This is more efficient than calling get_timeseries multiple times when you need to load many timeseries from the same database.

Parameters:

• db_path: Path to the database file
• requests: List of dicts with keys: component_id, attribute_name, scenario_id (optional)
• max_points: Maximum number of points for sampling (applied to all)

Returns:

List of Timeseries objects in the same order as requests

Example:

>>> requests = [
    ...     {"component_id": 123, "attribute_name": "p"},
    ...     {"component_id": 124, "attribute_name": "p"},
    ...     {"component_id": 125, "attribute_name": "p", "scenario_id": 2}
    ... ]
    >>> timeseries_list = get_multiple_timeseries("model.db", requests)
    >>> print(f"Loaded {len(timeseries_list)} timeseries")