finam.adapters.SumOverTime#

class finam.adapters.SumOverTime(step=0.0, per_time=True, initial_interval=datetime.timedelta(0))[source]#

Bases: TimeIntegrationAdapter

Aggregates data over time to form the temporal sum (area under curve) over the last pull time step.

Output is the Area under Curve (AuC) between the last and the current pull (vertical lines):

../../../_images/integration-methods.svg — Illustration of time integration.#

Can use step-wise or linear interpolation between push time steps.

../../../_images/interpolation-methods.svg — Illustration of interpolation methods.#

Parameters:

step (float, optional) – Value in range [0, 1] that determines the relative step position. Defaults to 0.0, which means values are interpreted as constant over each time step.

Linear interpolation is used if set to None.
- For a value of 0.0, the new value is returned for any dt > 0.0.
- For a value of 1.0, the old value is returned for any dt <= 1.0.
- Values between 0.0 and 1.0 shift the step between the first and the second time.
- A value of 0.5 results in nearest interpolation.
per_time (bool, optional) – Whether the input data is time-normalized.

Use True for input units like mm/d, e.g. for precipitation. Data per step is multiplied with step length, with time cancelling out: mm/d becomes mm.

Use False for absolute amount, e.g. mm for the precipitation of the last time step. Output units will be the same as input units. Duration of time steps is not explicitly taken into account.

Examples:
- per_time=True, value=1mm/d, step=2x5d –> 10 mm
- per_time=True, value=1mm, step=2x5d –> 10mm*d
- per_time=False, value=1mm/d, step=2x5d –> 2mm/d
- per_time=False, value=1mm, step=2x5d –> 2mm
initial_interval (datetime, optional) – Time scaling duration for the initial data, if per_time=True. Defaults to 0 days.

See also

adapters.LinearTime: Linear time interpolation.
adapters.StepTime: Step-wise time interpolation.
adapters.AvgOverTime: Average aggregation over time.

Examples

import finam as fm

adapter = fm.adapters.SumOverTime()

Attributes:

has_source: Flag if this input instance has a source.
has_targets: Flag if this output instance has any targets.
info: Info: The input’s data info.
is_static: Whether the input is static
logger: Logger for this component.
logger_name: Logger name derived from source logger name and class name.
memory_limit: The memory limit for this slot
memory_location: The memory-mapping location for this slot
metadata: The adapter’s metadata.
name: Input name.
needs_pull: bool: if the adapter needs pull.
needs_push: bool: if the adapter needs push.
source: Get the input’s source output or adapter
targets: Get target inputs and adapters for this output.
time: The output’s time of the latest available data
uses_base_logger_name: Whether this class has a base_logger_name attribute.

Methods

`add_target`(target)	Add a target input or adapter for this output.
`chain`(other)	Chain outputs and adapters.
`exchange_info`([info])	Exchange the data info with the input's source.
`finalize`()	Called at the end of each run.
`get_data`(time, target)	Get the transformed data of this adapter.
`get_info`(info)	Exchange and get the output's data info.
`has_info`()	Returns if the output has a data info.
`notify_targets`(time)	Notify all targets by calling their `source_updated(time)` method.
`ping`()	Pings upstream to inform outputs about the number of connected inputs.
`pinged`(source)	Called when receiving a ping from a downstream input.
`pull_data`(time[, target])	Retrieve the data from the input's source.
`push_data`(data, time)	Push data into the output.
`push_info`(info)	Push data info into the output.
`source_updated`(time)	Informs the input that a new output is available.
`with_name`(name)	Renames the adapter and returns self.

_get_info(info)[source]#

Exchange and get the output’s data info.

Adapters can overwrite this method to manipulate the metadata for the output.

Parameters:: info (Info) – Requested data info
Returns:: Delivered data info
Return type:: Info

_finalize()#: Called at the end of each run. Overwrite this for cleanup.

_get_data(time, _target)#

Get the output’s data-set for the given time.

Parameters:: time (datetime) – simulation time to get the data for.
Returns:: data-set for the requested time.
Return type:: array_like

_source_updated(time)#

Informs the input that a new output is available.

Parameters:: time (datetime) – Simulation time of the notification.

add_target(target)#

Add a target input or adapter for this output.

Parameters:: target (IInput) – The target to add.

chain(other)#

Chain outputs and adapters.

Parameters:: other (IInput or IAdapter) – The adapter or input to add as target to this output.
Returns:: The last element of the chain.
Return type:: IOutput

exchange_info(info=None)#

Exchange the data info with the input’s source.

Parameters:: info (Info) – request parameters
Returns:: delivered parameters
Return type:: Info

finalize()#: Called at the end of each run. Calls _finalize().

get_data(time, target)#

Get the transformed data of this adapter.

Internally calls _get_data().

Parameters:

time (datetime) – Simulation time to get the data for.
target (IInput) – Requesting end point of this pull.

Returns:

Transformed data-set for the requested time.

Return type:

pint.Quantity

get_info(info)#

Exchange and get the output’s data info.

Parameters:: info (Info) – Requested data info
Returns:: Delivered data info
Return type:: Info
Raises:: FinamNoDataError – Raises the error if no info is available

has_info()#

Returns if the output has a data info.

The info is not required to be validly exchanged.

property has_source#: Flag if this input instance has a source.

property has_targets#: Flag if this output instance has any targets.

property info#

The input’s data info.

Type:: Info

property is_static#: Whether the input is static

property logger#: Logger for this component.

property logger_name#: Logger name derived from source logger name and class name.

property memory_limit#: The memory limit for this slot

property memory_location#: The memory-mapping location for this slot

property metadata#

The adapter’s metadata. Will only be called after the connect phase from Composition.metadata.

Adapters can overwrite this property to add their own specific metadata:

import finam as fm

class MyAdapter(fm.Adapter):

    @property
    def metadata(self):
        # Get the default metadata
        md = super().metadata

        # Add your own metadata
        md["my_field"] = "some value"

        # Return the dictionary
        return md

Returns:

A dict with the following default metadata:

name - the component’s name
class - the component’s class

Return type:

dict

property name#: Input name.

property needs_pull#

if the adapter needs pull.

Type:: bool

property needs_push#

if the adapter needs push.

Type:: bool

notify_targets(time)#

Notify all targets by calling their source_updated(time) method.

Parameters:: time (datetime) – Simulation time of the simulation.

ping()#

Pings upstream to inform outputs about the number of connected inputs.

Must be called after linking and before the connect phase.

pinged(source)#: Called when receiving a ping from a downstream input.

pull_data(time, target=None)#

Retrieve the data from the input’s source.

Parameters:

time (datetime) – Simulation time to get the data for.
target (IInput or None) – Requesting end point of this pull. Should be None for normal input pulls in components. Simple adapters should forward the source in Adapter._get_data(). Push-based adapters should use self in Adapter._source_updated().

Returns:

Data set for the given simulation time.

Return type:

pint.Quantity

push_data(data, time)#

Push data into the output.

Should notify targets, and can handle the provided date.

Parameters:

data (array_like) – Data set to push.
time (datetime) – Simulation time of the data set.

push_info(info)#

Push data info into the output.

Parameters:: info (Info) – Delivered data info

property source#

Get the input’s source output or adapter

Returns:: The input’s source.
Return type:: IOutput

source_updated(time)#

Informs the input that a new output is available.

Parameters:: time (datetime) – Simulation time of the notification.

property targets#

Get target inputs and adapters for this output.

Returns:: List of targets.
Return type:: list

property time#: The output’s time of the latest available data

property uses_base_logger_name#: Whether this class has a base_logger_name attribute. True.

with_name(name)#: Renames the adapter and returns self.