ValueStream

Module: thinkiq.history.value_stream

Contains all logic and classes regarding Value Streams.

A time series data storage object with units of measure. The core of the ValueStream class is a list of Vsts associated with a MeasurementUnit.

Class Listings

ValueStream

ValueStream

class thinkiq.history.value_stream.ValueStream(dataframe=None, start_datetime=None, end_datetime=None, measurement_unit=None)

A list of Vsts with an associated Measurement Unit.

Properties:

vsts: pandas.DataFrame
measurement_unit: thinkiq.model.measurement_unit.MeasurementUnit
start_timestamp: datetime.datetime
end_timestamp: datetime.datetime
values: List[bool, int, float, str, datetime.datetime]
statuses: List[int]
timestamps: List[datetime.datetime]

Methods

__init__(dataframe=None, start_datetime=None, end_datetime=None, measurement_unit=None)

Construct a value stream object which contains a list of Vsts and their MeasurementUnit.

Parameters:

  • dataframe (pandas.DataFrame) – A dataframe with values, status, timestamp rows. Indexed by timestamp.

  • start_datetime (datetime.datetime, optional) – Start datetime to load into value_stream property, by default None

  • end_datetime (datetime.datetime, optional) – End datetime to load into value_stream property, by default None

  • measurement_unit (MeasurementUnit, optional) – The value_stream’s MeasurementUnit, by default None

find_index_value(timestamp, direction=None)

Find the index value

FORWARD: (i) where vsts[i].timestamp <= timestamp < vsts[i+1].timestamp REVERSE: (i) where (vsts[::-1])[i].timestamp => timestamp > (vsts[::-1])[i-1].timestamp

Parameters:

  • timestamp (datetime.datetime) – The timestamp index value to find.

  • direction (common.Directions, optional) – Deprecated

Returns:

The index value closest to the timestamp provided, without exceeding in the direction of search Index value returned is from beginning of the array for FORWARD, from end of array for REVERSE

Return type:

int

add_vst(vst)

Add a single vst, in time order, to the vsts property of the ValueStream.

Parameters:

vst (Vst) – The Vst object to be added in time order to the ValueStream.

Return type:

Series

get_last_value_point()

Create a ValuePoint from the last Vst in the vsts property.

Returns:

The final Vst object with measurement unit.

Return type:

ValuePoint

get_definite_integral(integral_start_timestamp, integral_end_timestamp, direction=Directions.FORWARD)

Calculate the definite integral between start and end datetimes.

Returns a scalar value that represents the definite integral between integral_start_timestamp and integral_end_timestamp.

Parameters:

  • integral_start_timestamp (datetime.datetime)

  • integral_end_timestamp (datetime.datetime)

  • direction (common.Directions, optional) – The direction to step while producing the integral, by default common.Directions.FORWARD

Returns:

The integral value between the datetimes.

Return type:

None, float

get_time_to_accumulated_value(accumulation_target, direction, timestamp, max_duration=datetime.timedelta(seconds=3600))

Calculate the amount of time it takes to accumulate a value over time.

Calculates and sums the integral of a measured value that varies with time and compares it to a target value. Once the target value is reached, the amount of time to accumulate is returned.

Parameters:

  • accumulation_target (int, float) – Accumulation sum target threshold.

  • direction (common.Directions) – Denotes the direction of time. ie. Forward/Backward.

  • timestamp (datetime.datetime) – The datetime to begin accumulation sum.

  • max_duration (datetime.timedelta, optional) – Maximum time allowed to sum accumulation, by default datetime.timedelta(hours=1)

Returns:

The time it took to accumulate the integral of the value to the accumulation target.

Return type:

Union[None, int, float]

convert_to_unit(measurement_unit)

Conver the current value stream into a new value stream of different unit

Requires the same quantity kind of the value streams measurement unit with the passed measurement unit

Parameters:

measurement_unit (MeasurementUnit) – Desired measurement unit for returned value stream.

Returns:

Value stream with disred measurement unit.

Return type:

ValueStream

Raises:

TypeError – If desired measurement unit does not have the same quantity kind this error is raised.

static get_timestamp_union(*args)

Returns the full union of all value stream timestamps.

Takes any number of value streams as args. Returns the total union of all timestamps that make up their timeseries data points.

Parameters:

*args (ValueStream) – ValueStreams whose timestamps will be unioned together.

Returns:

A pandas.Series of the unioned datetime objects

Return type:

Series

static get_overlap_time_period(*args)

Returns the beginning and end intersection datetimes of value streams.

Takes any number of value streams as args. If there is a cummulative intersection of the value streams, the start and end of the timestamp intersection is returned as a tuple.

If no cummulative intersection is found, returns None.

Parameters:

*args (ValueStream) – ValueStreams with which to find the cummulative intersection

Returns:

If intersection exists returns (start, end), else None

Return type:

Optional[Tuple[datetime, datetime]]

static create_with_ones(start_timestamp, end_timestamp=datetime.datetime(2025, 11, 12, 21, 16, 55, 453498), interval=datetime.timedelta(seconds=1), measurement_unit=None)

Return a ValueStream with evenly spaced ones (1)

Parameters:

  • start_timestamp (datetime.datetime)

  • end_timestamp (datetime.datetime, optional) – By default datetime.datetime.now()

  • interval (datetime.timedelta, optional) – Time delta between Vst’s, by default datetime.timedelta(seconds=1)

  • measurement_unit (Optional[MeasurementUnit], optional) – MeasurementUnit of the created ValueStream, by default None

Returns:

ValueStream with ‘1.0’ as all values in vsts.

Return type:

ValueStream

static create_with_zeros(start_timestamp, end_timestamp=datetime.datetime(2025, 11, 12, 21, 16, 55, 453505), interval=datetime.timedelta(seconds=1), measurement_unit=None)

Return a ValueStream with evenly spaced zeros (0)

Parameters:

  • start_timestamp (datetime.datetime)

  • end_timestamp (datetime.datetime, optional) – By default datetime.datetime.now()

  • interval (datetime.timedelta, optional) – Time delta between Vst’s, by default datetime.timedelta(seconds=1)

  • measurement_unit (Optional[MeasurementUnit], optional) – MeasurementUnit of the created ValueStream, by default None

Returns:

ValueStream with ‘0.0’ as all values in vsts.

Return type:

ValueStream

classmethod create_with_value(value, start_timestamp, end_timestamp=datetime.datetime(2025, 11, 12, 21, 16, 55, 453508), interval=datetime.timedelta(seconds=1), measurement_unit=None)

Return a ValueStream with evenly spaced values

Parameters:

  • value (int, float, str, datetime.datetime) – The value for all Vst’s in vsts of ValueStream

  • start_timestamp (datetime.datetime)

  • end_timestamp (datetime.datetime, optional) – By default datetime.datetime.now()

  • interval (datetime.timedelta, optional) – Time delta between Vst’s, by default datetime.timedelta(seconds=1)

  • measurement_unit (Optional[MeasurementUnit], optional) – MeasurementUnit of the created ValueStream, by default None

Returns:

ValueStream with specified value in all vsts.

Return type:

ValueStream