Aggregated parameters

Basic usage

An aggregated parameter returns the values of its child parameters aggregated using an aggregation function. The following aggregation functions are available: sum, minimum, maximum, mean (value only), median (value only), product (value only), any (index only), all (index only), custom.

There are two kinds of aggregated parameter: AggregatedParameter and AggregatedIndexParameter, referred to as “value” and “index” in this document. A value aggregated parameter aggregates the values of it’s children, while the index aggregated parameter does the same for the index of IndexParameter.

An example of creating an AggregatedParameter in Python is given below. The value of the aggregated parameter is the product of the baseline and profile values, e.g. in January the value is 5.0 * 0.8 = 4.0.

baseline = ConstantParameter(5.0)
profile = MonthlyParameter(
    [0.8, 0.8, 0.8, 0.8, 1.1, 1.1, 1.1, 1.1, 0.8, 0.8, 0.8, 0.8]
)
agg = AggregatedParameter(
    parameters=[baseline, profile],
    agg_func="product"
)

An example of creating an AggregatedParameter in JSON is given below. This parameter aggregates three parameters, one of which is a constant while the other two are references to parameters named in the "parameters" section.

{
    "type": "aggregated",
    "agg_func": "product",
    "parameters": [
        104.7
        "monthly_demand_profile",
        "demand_saving_factor"
    ]
}

Aggregated parameters can be used to build up complex functions. A more detailed explanation of the above example can be found in Demand restrictions.

Sum, Min, Max, Product

The "sum", "min", "max" and "product" aggregation functions are available to both aggregated value and aggregated index parameters.

Mean and Median

The "mean" and "median" aggregation functions are only available for aggregated value parameters, as they could return non-integer values.

Any and All

The any and all aggregation functions behave like their NumPy equivalents, numpy.any and numpy.all , returning 0 or 1 depending on whether any or all of the child values are truthy (i.e. non-zero).

An example use is an index parameter which is “on” when any reservoir in a group is below its control curve.

Custom aggregation functions

Custom aggregation functions can be used via the Python API only. The function is called with the values of the individual parameters and should return the aggregated value. For example, the following aggregation function returns the 25th percentile of the values:

func = lambda x: np.percentile(x, 25)
parameter = AggregatedParameter(parameters, agg_func=func)

MaxParameter, MinParameter and NegativeParameter, NegativeMaxParameter

The Max/Min/Negative parameters are optimised aggregation functions for some common operations, which aggregate a single parameter and a constant.

The examples below compare the “max” aggregation function in AggregatedParameter to the MaxParameter. The JSON required is shorter, arguably more readable and quicker to evaluate.

{
    "type": "aggregated",
    "agg_func": "max",
    "parameters": [
        "another_parameter",
        0.0
    ]
}

{
    "type": "max",
    "parameter": "another_parameter",
    "threshold": 0.0
}

An example use of these functions is to handle the net inflow timeseries for a reservoir, which includes both positive flows (net gain) and negative flows (net evaporation / leakage). If the original parameter is given as X, the positive component can be achieved using max(X, 0) and attached to an Input node. The negative component needs to be made positive, as Outputs require positive flows, using max(negative(X)). This setup is shown in JSON below.

"original": ...

"inflow": {
    "type": "max",
    "parameter": "original",
    "threshold": 0.0
}

"evaporation": {
    "type": "max",
    "parameter": {
        "type": "negative",
        "parameter": "original"
    }
    "threshold": 0.0
}

The pattern above was common enough to warrant the creation of the NegativeMaxParameter.

"evaporation": {
    "type": "negativemax",
    "parameter": "original",
    "threshold": 0.0
}