Calculator

class saco.Calculator(input_dataset: Dataset, scenarios: List[str] = None, percentiles: List[int] = None, domain: List[str] = None, capping_method: str | None = 'cap-net-impacts', unassessed_waterbodies: List[str] = None, check_order: bool = True, bin_edges: List[float] = None, na_value: int = -999, tolerance_dp: int = 3, constants: Constants = None)

For calculating scenario flows and assessing compliance against targets.

In most use cases, the steps needed to use the Calculator are (code example below):

  • Prepare/load an input Dataset

  • Create an instance of this (the Calculator) class

  • Execute the calculations using the run method.

The run method produces an updated “Master” dataframe, which can be returned on its own or as part of a full Dataset (the latter option being the current default).

Parameters:

  • input_dataset – Instance of Dataset for which to run calculations.

  • scenarios – Names/abbreviations of artificial influences scenarios for which calculations should be performed. If None (default) then taken from input_dataset.

  • percentiles – Flow percentiles (natural) for which calculations should be performed. If None (default) then taken from input_dataset.

  • domain – List of waterbody IDs indicating domain/catchment to be optimised. If None (default) then all waterbodies in input_dataset will be included in the domain.

  • capping_method – Indicates method to use to deal with potential for “negative flows” if ups impacts exceed ups natural flow in a waterbody. Options are ‘cap-net-impacts’, ‘simple’ or None. See notes below.

  • unassessed_waterbodies – Optional list of waterbodies for which compliance should not be assessed. If None (default) then any waterbodies of types ‘Seaward Transitional’ or ‘Saline Lagoon’ will not be assessed.

  • check_order – Confirm that order of dataframe(s) matches order of nodes in input_dataset.graph before carrying out calculations (small overhead).

  • bin_edges – Bin edges defining compliance band boundaries. By default, bin edges are taken from config.Constants (see Calculator).

  • na_value – Value to use for compliance in unassessed waterbodies.

  • tolerance_dp – Number of decimal places of tolerance to use in rounding deficit divided by natural flow in compliance assessment (i.e. to avoid unfairly classing a very small negative difference as non-compliant).

  • constants – Instance of config.Constants (default) or similar.

Notes

A starting point for the input_dataset might be a Dataset comprising the WRGIS tables. Make any desired modifications to this (or some other) “base” Dataset before creating an instance of Calculator. See Dataset documentation and examples.

As discussed in Calculator, there is a potential for “negative flows” if ups impacts exceed ups natural flow in a waterbody. This is because abstraction impacts are large under some scenarios and because the calculator works as a set of elementary arithmetic/array operations, rather than as a network flow-type model. A few options are provided to deal with this issue:

  • WRGIS-like approach (capping_method=’cap-net-impacts’): loop through topological generations of waterbodies (upstream to downstream) and adjust net impacts on flows until no negatives. This is the default approach.

  • WBAT-like approach (capping_method=’simple’): set potential negative flows to zero. This approach can be slightly more conservative (resulting in lower flows) than the WRGIS-like approach. It allows for potential propagation of some impacts downstream even if they have been implicitly “capped” in a waterbody if its flow has been increased to zero.

  • Do nothing (capping_method=None): allow negative scenario flows in output.

Any long-term average abstraction columns present in the input Dataset are not updated by the Calculator when it returns a Dataset. If these fields are required a user should call Dataset.infer_mean_abstraction explicitly.

Examples

>>> from saco import Dataset, Calculator
>>>
>>> ds = Dataset(data_folder='/path/to/data/files')
>>> ds.load_data()
>>>
>>> calculator = Calculator(ds)
>>> output_dataset = calculator.run()
__init__(input_dataset: Dataset, scenarios: List[str] = None, percentiles: List[int] = None, domain: List[str] = None, capping_method: str | None = 'cap-net-impacts', unassessed_waterbodies: List[str] = None, check_order: bool = True, bin_edges: List[float] = None, na_value: int = -999, tolerance_dp: int = 3, constants: Constants = None)

Methods

run([master_only])

Run data preparation and all calculations.