Time-Series Types

The time-series types are the key types in the HGraph library as they provide the ports to support connecting outputs and inputs together forming edges in the graph. It is important to note that the API’s associated to the aliased types are contractual and may not be the instance types provided when actually instantiated by the runtime. This is especially true when using an alternative runtime (such as a C++ engine). In other words do not write code that does isinstance or issubclass of these types in nodes.

The supported time-series types are:

TS

alias of TimeSeriesValueInput

TSS

alias of TimeSeriesSetInput

TSL

alias of TimeSeriesListInput

TSB

alias of TimeSeriesBundleInput

TSD

alias of TimeSeriesDictInput

There is a special type to wrap any time-series type (as an input):

SIGNAL

alias of TimeSeriesSignalInput

Then there is a reference type, which can point to any of the above standard time-series types:

REF

alias of TimeSeriesReferenceInput

Finally, there is a special buffer type that is used to define a buffered time-series.

TSW

alias of TimeSeriesWindowInput

Note

The above types are alias types, they are used when annotating the types that a function supports as inputs any may return as an output. The actual types are the inputs when using them as inputs to a function and are outputs when used as a return value, or when used as the injectable _output. There are corresponding _OUT aliases that can be used to type the _output for better IDE support.

The bases of all time-series types are:

class TimeSeries

The base of all time-series types in HGraph. The time-series types provide the ports to connect the output of a function to inputs of other functions (or nodes in the graph). The type also provides a collection of useful methods and properties that can be found in all time-series values.

abstractmethod is_reference() → bool

Return type:

bool

Returns:

True if this time-series is a reference to another time-series.

abstractmethod re_parent(parent: Node | TimeSeries)

FOR USE IN LIBRARY CODE.

Change the owning node / time-series container of this time-series. This is used when grafting a time-series input from one node / time-series container to another. For example, see use in map implementation.

abstract property all_valid: bool

Is there a valid value associated to this time-series input, or loosely, “has this property ever ticked?”. Note that it is possible for the time-series to become invalid after it has been made valid. The invalidation occurs mostly when working with REF values. :return: True if there is a valid value associated with this time-series.

abstract property delta_value

All time-series objects must support a delta_value property that returns a python object representation of the changes between the last tick and the current tick.

abstract property last_modified_time: datetime

The time that this property last modified.

Type:

return

abstract property modified: bool

Has the value of this time-series changed in this engine cycle. :return: True implies this time-series has been modified in this engine cycle.

abstract property owning_graph: Graph

The graph that owns the node that owns this time-series.

abstract property owning_node: Node

The node that owns this time-series.

abstract property valid: bool

Is there a valid value associated to this time-series input, or more generally has this property ever ticked. :return: True if there is a valid value associated to this time-series

abstract property value

All time-series objects must support a value property that returns a python object representation of the current (point-in-time) state. For strongly typed runtime engines (for example, one implemented in C++) this is effectively a type erased value.

class TimeSeriesOutput

Bases: TimeSeries

Output time-series types hold the actual value and can be set / modified. These types are also the observable implementations in the graph (as in the Observer pattern, with the exception that when the output changes it schedules subscribed input nodes instead of actually calling them).

abstractmethod apply_result(result: Any)

Apply the result of calling a python method to the output.

abstractmethod can_apply_result(result: Any) → bool

Return True if the result can be applies without overwriting any value modified in this engine cycle.

Return type:

bool

abstractmethod clear()

Clear out the output, this removes all items from collection time series.

abstractmethod copy_from_input(input: TimeSeriesInput)

Copy the value from the input provided to this output. This pattern makes it easier to implement generic behaviour relying on the copying of inputs or outputs to self, this code will require that the supplied input is of the same/compatible type as this output.

abstractmethod copy_from_output(output: TimeSeriesOutput)

Copy the value from the output provided to this output. This pattern makes it easier to implement generic behaviour relying on the copying of inputs or outputs to self, this code will require that the supplied output is of the same type as this output.

abstractmethod invalidate()

Invalidate the output, this removes all values and marks the output as invalid.

abstractmethod mark_invalid()

Marks the output as invalid, this will cause the output to be scheduled for evaluation.

abstractmethod mark_modified()

Marks the output as modified, this will cause the output to be scheduled for evaluation if it hasn’t already. This will also mark the parent output as modified if it exists.

abstractmethod subscribe(node: Node)

Add this node to receive notifications when this output changes (this is called by make_active by the bound input)

abstractmethod unsubscribe(node: Node)

Remove this node from receiving notifications when this output changes (this is called by make_passive by the bound input)

abstract property delta_value

The scalar value wrapper of the ticked_value.

abstract property has_parent_output: bool

True if this output is a child of another output, False otherwise

abstract property parent_output: TimeSeriesOutput | None

The output that this output is bound to. This will be None if this is the root output.

abstract property value

The time-series point-in-time value represented as a scalar value.

class TimeSeriesInput

Bases: TimeSeries

The time-series inputs are wrappers around an output. Inputs can either wrap a single output (when peered) or a collection of outputs (when non-peered). The inputs can be made active (subscribed to changes of the output) or passive (not subscribed to changes of the output).

abstractmethod bind_output(value: TimeSeriesOutput | None) → bool

FOR LIBRARY USE ONLY.

Binds the output provided to this input.

Return type:

bool

abstractmethod do_bind_output(value: TimeSeriesOutput) → bool

Derived classes override this to implement specific behaviours

Return type:

bool

abstractmethod do_un_bind_output(unbind_refs: bool = False)

Derived classes override this to implement specific behaviours

abstractmethod make_active()

Marks the input as being active, if the input is already active no work is done. Once marked active if the value the input is bound to will cause the input’s node to be scheduled for evaluation when the value changes.

abstractmethod make_passive()

Marks the input as being passive, if the input is already passive then no work is done. Once marked passive, the node associated to the input will not be scheduled for evaluation when the associated value is changed. Note that when accessing the value, the user will still get the most recent value. The utility to mark passive is to reduce activations in circumstances where the particular input is required, but the driver of a process is not this input.

For example, a node that processes a credit card transaction only needs to be woken up when the transaction request is received, but may depend on things such as credit history, exchange rates, transaction fees, etc. There is no need to evaluate the node if the transaction request has not ticked. Thus, all other inputs can be treated as passive.

abstractmethod un_bind_output(unbind_refs: bool = False) → None

FOR LIBRARY USE ONLY.

Unbinds the output from this input.

Return type:

None

abstract property active: bool

An active input will cause the node it is associated with to be scheduled when the value the input represents is modified.

Returns:

True if this input is active.

abstract property bound: bool

Is this time-series input bound to an output? It is possible for an input to be unbound, for example, when dealing with reference types, where the node may not have a valid reference yet, in which case no output will be bound to the input. :return: True if this is bound to an output

abstract property has_parent_input: bool

True if this input is a child of another input, False otherwise

abstract property has_peer: bool

If the input is bound directly to a single output then this input is peered, however, if the input is bound to more then one output making up the structure of this input, then the input is not peered. This is generally only going to affect collection types such as TSL, TSB, and TSD where the input may be a collection of independent time-series outputs.

Note: If the input is not bound, then it has no peer.

Returns:

True if this input is peered.

abstract property output: TimeSeriesOutput | None

The output bound to this input. If the input is not bound then this will be None.

abstract property parent_input: TimeSeriesInput | None

The input that this input is bound to. This will be None if this is the root input.

The detailed API’s of the remaining types are presented below:

class TimeSeriesDeltaValue

Bases: TimeSeries, Generic[SCALAR, DELTA_SCALAR]

A time-series that is able to express the changes between this and the last tick as a delta object. All time-series values support this, this utility class provides the ability to describe the expected type of the value and delta_value properties.

abstract property delta_value: DELTA_SCALAR | None

The delta value.

abstract property value: SCALAR | None

The current value.

class TimeSeriesSignalInput

Bases: TimeSeriesInput

An input type that be bound to any output type. The value of the output is ignored, and the signal will allow for usages where only the ticked state is required to be known. There is no equivalent to this on the output side. If only a “ticked” state is required, the convention is to use a TS[bool] for the output type.

abstract property value: bool

Will return the result of ticked.

class TimeSeriesValueOutput

Bases: TimeSeriesOutput, TimeSeriesDeltaValue[SCALAR, SCALAR], ABC, Generic[SCALAR]

The time-series output that contains a scalar value. This is the most fundamental time-series output type.

This can be represented as TS_OUT[SCALAR] when typing an _output injectable argument to a node. When returning the value from a node, use the TS[SCALAR] annotation to the return value.

abstract property value: SCALAR | None

The current value associated to this node.

class TimeSeriesValueInput

Bases: TimeSeriesInput, TimeSeriesDeltaValue[SCALAR, SCALAR], ABC, Generic[SCALAR]

The time-series input of a SCALAR value. This peers with a TimeSeriesValueOutput instance. Use TS[SCALAR] as the type annotation. Note, as this is an input, the value is not settable.

class SetDelta(*args, **kwargs)

Bases: Protocol[KEYABLE_SCALAR], Generic[KEYABLE_SCALAR]

Represent the delta value of an operation performed on the TSS type. This contains the added and removed elements of the set (those added and removed in this engine cycle). This can also be used to apply the change to a TSS output.

abstract property added: Iterable[KEYABLE_SCALAR]

The elements that were added

abstract property removed: Iterable[KEYABLE_SCALAR]

The elements that were removed

class TimeSeriesSet

Bases: TimeSeriesDeltaValue[KEYABLE_SCALAR, SetDelta[KEYABLE_SCALAR]], Generic[KEYABLE_SCALAR]

The core methods common to both input and output instances of the TSS. The time-series set represents a set of SCALAR values over time. The set will tick when an item is added or removed from the set. If an item is added that already exists, or removed when it did not exist, the set will not tick.

The set will tick if it has no elements added if the set is not yet valid. That is, the set will become valid if an empty output is set. Once valid, the set will not tick again for this condition, unless there were values already present and they are removed.

abstractmethod added() → Iterable[KEYABLE_SCALAR]

Iterator over the added values

Return type:

Iterable[TypeVar(KEYABLE_SCALAR, bound= Hashable)]

abstractmethod removed() → Iterable[KEYABLE_SCALAR]

Iterator over the removed values

Return type:

Iterable[TypeVar(KEYABLE_SCALAR, bound= Hashable)]

abstractmethod values() → Iterable[KEYABLE_SCALAR]

Iterator over all the time-series values of this collection

Return type:

Iterable[TypeVar(KEYABLE_SCALAR, bound= Hashable)]

abstractmethod was_added(item: KEYABLE_SCALAR) → bool

True if the item was added in this engine cycle.

Return type:

bool

abstractmethod was_removed(item: KEYABLE_SCALAR) → bool

True if the item was removed in this engine cycle.

Return type:

bool

class TimeSeriesSetInput

Bases: TimeSeriesInput, TimeSeriesSet[KEYABLE_SCALAR], Generic[KEYABLE_SCALAR]

The input version of the set.

class TimeSeriesSetOutput

Bases: TimeSeriesOutput, TimeSeriesSet[KEYABLE_SCALAR], Generic[KEYABLE_SCALAR]

The output version of the set

add(element: KEYABLE_SCALAR)

Add an element to the set

clear()

Removes all elements from the set

abstractmethod get_contains_output(item: KEYABLE_SCALAR, requester: object) → TimeSeriesValueInput[bool]

Returns a TS[bool] output reference that ticks True when the item value is present and False otherwise.

Return type:

TimeSeriesValueInput[bool]

abstractmethod is_empty_output() → TimeSeriesValueInput[bool]

Returns a TS[bool] output that tracks the empty state of the set.

Return type:

TimeSeriesValueInput[bool]

abstractmethod release_contains_output(item: KEYABLE_SCALAR, requester: object)

Releases the reference request

remove(element: KEYABLE_SCALAR)

Removes the element from the set

abstract property delta_value: SetDelta[KEYABLE_SCALAR]

The scalar value wrapper of the ticked_value.

abstract property value: Set[KEYABLE_SCALAR]

The time-series point-in-time value represented as a scalar value.

class TimeSeriesIterable

Bases: Generic[K, V]

All collection time-series objects support this set of methods over the elements of the collection.

abstractmethod items() → Iterable[Tuple[K, V]]

Iterator over the key value pairs in this collection.

Return type:

Iterable[Tuple[TypeVar(K, bound= Hashable), TypeVar(V, bound= TimeSeries)]]

abstractmethod keys() → Iterable[K]

Iterator over all the keys of the collection

Return type:

Iterable[TypeVar(K, bound= Hashable)]

abstractmethod modified_items() → Iterable[Tuple[K, V]]

Iterator over the keys and values of the values that have been modified in this engine cycle.

Return type:

Iterable[Tuple[TypeVar(K, bound= Hashable), TypeVar(V, bound= TimeSeries)]]

abstractmethod modified_keys() → Iterable[K]

Iterator over the keys associated to values that have been modified in this engine cycle

Return type:

Iterable[TypeVar(K, bound= Hashable)]

abstractmethod modified_values() → Iterable[V]

Iterator over the time-series values that have been modified in this engine cycle

Return type:

Iterable[TypeVar(V, bound= TimeSeries)]

abstractmethod valid_items() → Iterable[Tuple[K, V]]

Iterator over the keys and values of the values that have been deemed valid.

Return type:

Iterable[Tuple[TypeVar(K, bound= Hashable), TypeVar(V, bound= TimeSeries)]]

abstractmethod valid_keys() → Iterable[K]

Iterator over the keys associated to values that have are deemed valid.

Return type:

Iterable[TypeVar(K, bound= Hashable)]

abstractmethod valid_values() → Iterable[V]

Iterator over the time-series values that have are deemed valid.

Return type:

Iterable[TypeVar(V, bound= TimeSeries)]

abstractmethod values() → Iterable[V]

Iterator over all the time-series values of this collection

Return type:

Iterable[TypeVar(V, bound= TimeSeries)]

class TimeSeriesList(__type__: TIME_SERIES_TYPE, __size__: SIZE)

Bases: TimeSeriesIterable[int, TIME_SERIES_TYPE], TimeSeriesDeltaValue[tuple, dict[int, Any]], Generic[TIME_SERIES_TYPE, SIZE]

Represents a linear collection of time-series inputs. Think of this as a list of time-series values.

items() → Iterable[Tuple[K, V]]

Iterator over the key value pairs in this collection.

Return type:

Iterable[Tuple[TypeVar(K, bound= Hashable), TypeVar(V, bound= TimeSeries)]]

key_from_value(value: TIME_SERIES_TYPE) → int

They key for a given value.

Return type:

int

keys() → Iterable[K]

The list of indices (effectively range(len(self._ts_values))

Return type:

Iterable[TypeVar(K, bound= Hashable)]

modified_items() → Iterable[Tuple[K, V]]

The pair of index and value for the values that have been modified in this engine cycle.

Return type:

Iterable[Tuple[TypeVar(K, bound= Hashable), TypeVar(V, bound= TimeSeries)]]

modified_keys() → Iterable[K]

The indices that have been modified in this engine cycle.

Return type:

Iterable[TypeVar(K, bound= Hashable)]

modified_values() → Iterable[V]

The values that have been modified in this engine cycle.

Return type:

Iterable[TypeVar(V, bound= TimeSeries)]

valid_items() → Iterable[Tuple[K, V]]

The indices and value pairs containing valid time-series values.

Return type:

Iterable[Tuple[TypeVar(K, bound= Hashable), TypeVar(V, bound= TimeSeries)]]

valid_keys() → Iterable[K]

The indices containing valid time-series values.

Return type:

Iterable[TypeVar(K, bound= Hashable)]

valid_values() → Iterable[V]

The valid time-series values.

Return type:

Iterable[TypeVar(V, bound= TimeSeries)]

values() → Iterable[V]

Iterator over all the time-series values of this collection

Return type:

Iterable[TypeVar(V, bound= TimeSeries)]

class TimeSeriesListInput(__type__: TIME_SERIES_TYPE, __size__: SIZE)

Bases: TimeSeriesList[TIME_SERIES_TYPE, SIZE], TimeSeriesInput, ABC, Generic[TIME_SERIES_TYPE, SIZE]

The input of a time series list.

classmethod from_ts(*args, tp=~TIME_SERIES_TYPE, size=~SIZE, __type__=None) → TimeSeriesList[TIME_SERIES_TYPE, SIZE]

To force a Type (to ensure input types are as expected, then provide __type__ and / or __size__

Return type:

TimeSeriesList[TypeVar(TIME_SERIES_TYPE, bound= TimeSeries), TypeVar(SIZE, bound= Size)]

class TimeSeriesListOutput(__type__: TIME_SERIES_TYPE, __size__: SIZE)

Bases: TimeSeriesList[TIME_SERIES_TYPE, SIZE], TimeSeriesOutput, ABC, Generic[TIME_SERIES_TYPE, SIZE]

The output of the time series list

class TimeSeriesBundle(__schema__: TS_SCHEMA, **kwargs)

Bases: TimeSeriesDeltaValue[TS_SCHEMA | dict[str, Any], TS_SCHEMA | dict[str, Any]], ABC, Generic[TS_SCHEMA]

Represents a non-homogenous collection of time-series values. We call this a time-series bundle.

This contains the core methods shared between input and output types.

items() → ItemsView[str, TimeSeries]

The items of the bundle

Return type:

ItemsView[str, TimeSeries]

key_from_value(value: Any) → str

This is a linear search for the first value, in the collection of time-series values, that matches the supplied value argument. This can be very heavy, use with care.

Return type:

str

keys() → KeysView[str]

The keys of the schema defining the bundle

Return type:

KeysView[str]

modified_items() → Iterable[Tuple[str, TimeSeries]]

The key / value pairs of the time-series elements that have been modified in this engine cycle

Return type:

Iterable[Tuple[str, TimeSeries]]

modified_keys() → Iterable[str]

The keys of the time-series elements that have been modified in this engine cycle

Return type:

Iterable[str]

modified_values() → Iterable[TimeSeries]

The time-series elements that have been modified in this engine cycle

Return type:

Iterable[TimeSeries]

valid_items() → Iterable[Tuple[str, TimeSeries]]

The key / value pairs of the time-series elements that are marked as valid

Return type:

Iterable[Tuple[str, TimeSeries]]

valid_keys() → Iterable[str]

The keys of the time-series elements that are marked as valid

Return type:

Iterable[str]

valid_values() → Iterable[TimeSeries]

The time-series elements that are marked as valid

Return type:

Iterable[TimeSeries]

values() → ValuesView[TimeSeries]

The values of the bundle

Return type:

ValuesView[TimeSeries]

property as_schema: TS_SCHEMA

Exposes the TSB as the schema type. This is useful for type completion in tools such as PyCharm / VSCode. It is a convenience method, it is possible to access the properties of the schema directly from the TSB instances as well.

class TimeSeriesBundleInput(__schema__: TS_SCHEMA, **kwargs)

Bases: TimeSeriesInput, TimeSeriesBundle[TS_SCHEMA], Generic[TS_SCHEMA]

The input form of the bundle.

Note

This class is used at wiring time to implement the wiring logic of the TSB, this additionally represents the behaviours present in the TSB input type.

static from_ts(arg=None, /, **kwargs) → TimeSeriesBundleInput[TS_SCHEMA]

Create an instance of the TSB[SCHEMA] from the kwargs provided. This should be used in a graph instance only. It produces an instance of an un-bound time-series bundle with the time-series values set to the values provided. This does not require all values be present, but before wiring the bundle into an input, this will be a requirement.

Return type:

TimeSeriesBundleInput[TypeVar(TS_SCHEMA, bound= TimeSeriesSchema)]

copy_with(__init_args__: dict = None, **kwargs)

Creates a new instance of a wiring time bundle using the values of this instance combined / overridden from the kwargs provided. Can be used to clone a runtime instance of a bundle as well. # TODO: support k: REMOVE semantics to remove a value from the bundle?

do_bind_output(value: TimeSeriesOutput)

Derived classes override this to implement specific behaviours

items() → ItemsView[str, TimeSeriesInput]

The items of the bundle

Return type:

ItemsView[str, TimeSeriesInput]

make_active()

Marks the input as being active, if the input is already active no work is done. Once marked active if the value the input is bound to will cause the input’s node to be scheduled for evaluation when the value changes.

make_passive()

Marks the input as being passive, if the input is already passive then no work is done. Once marked passive, the node associated to the input will not be scheduled for evaluation when the associated value is changed. Note that when accessing the value, the user will still get the most recent value. The utility to mark passive is to reduce activations in circumstances where the particular input is required, but the driver of a process is not this input.

For example, a node that processes a credit card transaction only needs to be woken up when the transaction request is received, but may depend on things such as credit history, exchange rates, transaction fees, etc. There is no need to evaluate the node if the transaction request has not ticked. Thus, all other inputs can be treated as passive.

values() → ValuesView[TimeSeriesInput]

The values of the bundle

Return type:

ValuesView[TimeSeriesInput]

property active: bool

An active input will cause the node it is associated with to be scheduled when the value the input represents is modified.

Returns:

True if this input is active.

property all_valid: bool

Is there a valid value associated to this time-series input, or loosely, “has this property ever ticked?”. Note that it is possible for the time-series to become invalid after it has been made valid. The invalidation occurs mostly when working with REF values. :return: True if there is a valid value associated with this time-series.

property bound: bool

Is this time-series input bound to an output? It is possible for an input to be unbound, for example, when dealing with reference types, where the node may not have a valid reference yet, in which case no output will be bound to the input. :return: True if this is bound to an output

property delta_value: DELTA_SCALAR | None

All time-series objects must support a delta_value property that returns a python object representation of the changes between the last tick and the current tick.

property has_parent_input: bool

True if this input is a child of another input, False otherwise

property last_modified_time: datetime

The time that this property last modified.

Type:

return

property modified: bool

Has the value of this time-series changed in this engine cycle. :return: True implies this time-series has been modified in this engine cycle.

property output: TimeSeriesOutput | None

The output bound to this input. If the input is not bound then this will be None.

property owning_graph: Graph

The graph that owns the node that owns this time-series.

property owning_node: Node

The node that owns this time-series.

property parent_input: TimeSeriesInput | None

The input that this input is bound to. This will be None if this is the root input.

property valid: bool

Is there a valid value associated to this time-series input, or more generally has this property ever ticked. :return: True if there is a valid value associated to this time-series

property value: SCALAR | None

All time-series objects must support a value property that returns a python object representation of the current (point-in-time) state. For strongly typed runtime engines (for example, one implemented in C++) this is effectively a type erased value.

class TimeSeriesBundleOutput(__schema__: TS_SCHEMA, **kwargs)

Bases: TimeSeriesOutput, TimeSeriesBundle[TS_SCHEMA], ABC, Generic[TS_SCHEMA]

The output form of the bundle

items() → ItemsView[str, TimeSeriesOutput]

The items of the bundle

Return type:

ItemsView[str, TimeSeriesOutput]

values() → ValuesView[TimeSeriesOutput]

The values of the bundle

Return type:

ValuesView[TimeSeriesOutput]

class TimeSeriesDict(__key_set__: TimeSeriesSet, __key_tp__: HgScalarTypeMetaData, __value_tp__: HgTimeSeriesTypeMetaData)

Bases: TimeSeriesIterable[K, V], TimeSeriesDeltaValue[frozendict, frozendict], Generic[K, V]

A TSD is a dynamic collection of time-series values keyed off of a scalar key K. The dynamic nature of the TSD is very powerful, but comes with additional complexity and cost. The TSD is used to process collections where the structure is not known at wiring time. It supports the concept of a TSS key-set as well as methods to detect the addition and removal of time-series values. These tick over time as well as the elements themselves.

abstractmethod added_items() → Iterable[Tuple[K, V]]

Return type:

Iterable[Tuple[TypeVar(K, bound= Hashable), TypeVar(V, bound= TimeSeries)]]

Returns:

The items that were added since the last tick.

abstractmethod added_keys() → Iterable[K]

Return type:

Iterable[TypeVar(K, bound= Hashable)]

Returns:

The keys that were added since the last tick.

abstractmethod added_values() → Iterable[V]

Return type:

Iterable[TypeVar(V, bound= TimeSeries)]

Returns:

The values that were added since the last tick.

abstractmethod create(key: K)

Implemented by subclasses to create a new time series at this index position

get(key: K) → V | None

Return type:

Optional[TypeVar(V, bound= TimeSeries)]

get_or_create(key: K) → V

Returns the time series at this index position If the key does not yet exist, it will be created. In the case of an input, this will create a stub input that will only be bound when the corresponding output is created. In the case of an output, the output is constructed but will be in an invalid state until it is set with a value.

Return type:

TypeVar(V, bound= TimeSeries)

items() → Iterable[Tuple[K, V]]

Iterator over the key value pairs in this collection.

Return type:

Iterable[Tuple[TypeVar(K, bound= Hashable), TypeVar(V, bound= TimeSeries)]]

keys() → Iterable[K]

Iterator over all the keys of the collection

Return type:

Iterable[TypeVar(K, bound= Hashable)]

modified_items() → Iterable[Tuple[K, V]]

Iterator over the keys and values of the values that have been modified in this engine cycle.

Return type:

Iterable[Tuple[TypeVar(K, bound= Hashable), TypeVar(V, bound= TimeSeries)]]

modified_keys() → Iterable[K]

Iterator over the keys associated to values that have been modified in this engine cycle

Return type:

Iterable[TypeVar(K, bound= Hashable)]

modified_values() → Iterable[V]

Iterator over the time-series values that have been modified in this engine cycle

Return type:

Iterable[TypeVar(V, bound= TimeSeries)]

abstractmethod removed_items() → Iterable[Tuple[K, V]]

Return type:

Iterable[Tuple[TypeVar(K, bound= Hashable), TypeVar(V, bound= TimeSeries)]]

Returns:

The items that were removed since the last tick.

abstractmethod removed_keys() → Iterable[K]

Return type:

Iterable[TypeVar(K, bound= Hashable)]

Returns:

The keys that were removed since the last tick.

abstractmethod removed_values() → Iterable[V]

Return type:

Iterable[TypeVar(V, bound= TimeSeries)]

Returns:

The values that were removed since the last tick.

valid_items() → Iterable[Tuple[K, V]]

Iterator over the keys and values of the values that have been deemed valid.

Return type:

Iterable[Tuple[TypeVar(K, bound= Hashable), TypeVar(V, bound= TimeSeries)]]

valid_keys() → Iterable[K]

Iterator over the keys associated to values that have are deemed valid.

Return type:

Iterable[TypeVar(K, bound= Hashable)]

valid_values() → Iterable[V]

Iterator over the time-series values that have are deemed valid.

Return type:

Iterable[TypeVar(V, bound= TimeSeries)]

values() → Iterable[V]

Iterator over all the time-series values of this collection

Return type:

Iterable[TypeVar(V, bound= TimeSeries)]

property key_set: TimeSeriesSet

class TimeSeriesDictInput(__key_set__, __key_tp__, __value_tp__)

Bases: TimeSeriesInput, TimeSeriesDict[K, V], ABC, Generic[K, V]

The TSD input

static from_ts(arg=None, /, **kwargs) → TimeSeriesDictInput[K, V]

Create an instance of TSD from the kwargs provided.

Return type:

TimeSeriesDictInput[TypeVar(K, bound= Hashable), TypeVar(V, bound= TimeSeries)]

class TimeSeriesDictOutput(__key_set__, __key_tp__, __value_tp__)

Bases: TimeSeriesOutput, TimeSeriesDict[K, V], ABC, Generic[K, V]

The TSD output

get_ref(key: K, requester: Any) → TimeSeriesReferenceOutput

Returns a reference time-series output for the key supplied, this will not create the time-series. This is useful to subscribe to a time-series where the coming and going of the time-series can be tracked. The requester is provided to assist with tracking the reference count. Many requesters can request a key, and when they are no longer interested, they will release the reference. We need to ensure that we only remove the reference once all requesters have gone. We could just leave them dangling, but that could cause a memory leak. When requesting this from the input perspective, the reference is not provided.

Return type:

TimeSeriesReferenceOutput

pop(key: K) → V

Deletes the key (if it exists) and returns the value.

Return type:

TypeVar(V, bound= TimeSeries)

release_ref(key: K, requester: Any) → None

Releases the reference request

Return type:

None

class TimeSeriesReference

Bases: object

Contains a reference to a time-series output. This is the holder type used to tick references to outputs through the graph using the REF type.

static is_instance(obj: object) → bool

Return type:

bool

static make(ts: TimeSeriesInput | TimeSeriesOutput | None = None, from_items: Iterable[TimeSeriesReference] = None)

abstractmethod bind_input(input_: TimeSeriesInput)

Binds given input to the value of this reference

abstract property has_output: bool

Indicates if the reference has an output

abstract property is_empty: bool

Indicates if the reference is empty

abstract property is_valid: bool

Indicates if the reference is valid, this is confirmed against the output or the list of items, Flase otherwise

class TimeSeriesReferenceOutput

Bases: TimeSeriesOutput, TimeSeriesDeltaValue[TimeSeriesReference, TimeSeriesReference], Generic[TIME_SERIES_TYPE]

The time-series output of a reference type. This is very similar to the TimeSeriesValueOutput.

observe_reference(input_: TimeSeriesInput)

Registers an input as observing the reference value

stop_observing_reference(input_: TimeSeriesInput)

Unregisters an input as observing the reference value

abstract property value: TimeSeriesReference | None

The current value associated to this node.

class TimeSeriesReferenceInput

Bases: TimeSeriesInput, TimeSeriesDeltaValue[TimeSeriesReference, TimeSeriesReference], ABC, Generic[TIME_SERIES_TYPE]

The reference input. This is similar to the TimeSeriesValueInput.

abstractmethod clone_binding(other: TimeSeriesReferenceInput)

Duplicate binding of another input

class TimeSeriesWindow(__type__: SCALAR, __size__: WINDOW_SIZE, __min_size__: WINDOW_SIZE_MIN)

Bases: TimeSeriesDeltaValue[Array[SCALAR], SCALAR], Generic[SCALAR, WINDOW_SIZE, WINDOW_SIZE_MIN]

Provides a time-series buffer over a stream of scalar values. When the size is in terms of ticks, this will provide an array of length at least WINDOW_SIZE_MIN and at most WINDOW_SIZE. By default, the WINDOW_MIN_SIZE is set to WINDOW_SIZE if the min size is not set.

When the size is set to a timedelta, this will produce values with a maximum size of size.microseconds (the number of microseconds making up the time-delta set to WINDOW_SIZE) and a minimum size of 0. The WINDOW_MIN_SIZE is used to ensure that the graph has been up and running for at least the WINDOW_SIZE_MIN time. This ensures have captured at least that duration of time’s ticks. This provides no guarantee as to the number of ticks available. To ensure a sample size, use the integer-based size and min size.

abstract property first_modified_time: datetime

The time the first tick in the buffer was modified.

abstract property has_removed_value: bool

True if there is a removed value available to make use of.

property min_size: int | timedelta

The minimum size (either as integer when defined as int, or timedelta when defined as timedelta)

abstract property removed_value: SCALAR

When the window is cycled, the item/s evicted from the buffer is returned by this method. This will return None if there is no removed value.

abstract property size: int | timedelta

The size (either as integer when defined as int, or timedelta when defined as timedelta)

abstract property value_times: Array[datetime]

The times associated to the value array. These are the times when the values were updated.

class TimeSeriesWindowOutput(__type__: SCALAR, __size__: WINDOW_SIZE, __min_size__: WINDOW_SIZE_MIN)

Bases: TimeSeriesWindow[SCALAR, WINDOW_SIZE, WINDOW_SIZE_MIN], TimeSeriesOutput, ABC, Generic[SCALAR, WINDOW_SIZE, WINDOW_SIZE_MIN]

The output of the time series list

class TimeSeriesWindowInput(__type__: SCALAR, __size__: WINDOW_SIZE, __min_size__: WINDOW_SIZE_MIN)

Bases: TimeSeriesWindow[SCALAR, WINDOW_SIZE, WINDOW_SIZE_MIN], TimeSeriesInput, ABC, Generic[SCALAR, WINDOW_SIZE, WINDOW_SIZE_MIN]

The input of a time series buffer.

The input is valid if a value has been ticked into the buffer, but if a min-size has been set, the value may remain None until the min-size has been reached.

To only receive notifications when the buffer is ready, mark the input as all_valid. This will only schedule a callback when the min-buffer size has been achieved.

The delta_value will tick with the same values and at the same time as the input TS ticks into the to_window function or whichever source is generating the window.