HydPy-Conv-IDW-CM (inverse distance weighted interpolation with multiplicative climatological adjustment)

conv_idw_cm extends conv_idw by taking long-term averages at the input and output nodes into account. Ratios of the current input values to their long-term averages are IDW-interpolated to the output nodes, and then multiplied by the long-term averages at the output nodes. This approach brings climatological knowledge into the interpolation results. Because of the multiplicative adjustment, it suits intermittent variables that are often zero, like precipitation.

You need to estimate the long-term averages in advance, in whatever way seems appropriate. One example is the REGNIE method of the Deutscher Wetterdienst, which Rauthe et al. (2013) use to generate the HYRAS precipitation data set. For this purpose, they preprocess monthly long-term averages using external information such as elevation. Their interpolation of daily precipitation values relies on the four closest stations, weighted with an exponent of two.

You can define the averages in arbitrary units; for example, mm/month and m/year would be equally fine, as long as you apply them consistently to the input and output locations.

Integration tests

Note

When new to HydPy, consider reading section Integration Tests first.

We begin by repeating the examples documented for application model conv_idw. We first define identical test settings (see the documentation on application model conv_idw for more information):

>>> from hydpy import Element, Node, pub
>>> pub.timegrids = "2000-01-01", "2000-01-04", "1d"

>>> from hydpy.models.conv_idw_cm import *
>>> parameterstep()

>>> in1, in2, in3 = Node("in1"), Node("in2"), Node("in3")
>>> element = Element("conv",
...                   inlets=(in1, in2, in3),
...                   outlets=["out1", "out2", "out3", "out4"])

>>> inputcoordinates(in1=(0.0, 3.0),
...                  in2=(2.0, -1.0),
...                  in3=(4.0, 2.0))
>>> outputcoordinates(out1=(0.0, 3.0),
...                   out2=(3.0, -2.0),
...                   out3=(1.0, 2.0),
...                   out4=(1.0, 1.0))
>>> power(2.0)
>>> maxnmbinputs(3)

>>> element.model = model
>>> from hydpy.core.testtools import IntegrationTest
>>> test = IntegrationTest(element)
>>> test.dateformat = "%Y-%m-%d"
>>> with pub.options.checkseries(False):
...     in1.sequences.sim.series = 1.0, nan, nan
...     in2.sequences.sim.series = 3.0, 2.0, nan
...     in3.sequences.sim.series = 4.0, nan, nan

equal averages

If all input and output nodes have the same long-term average, all adjustments cancel out, and conv_idw_cm reproduces the results of the all inputs example of application model conv_idw precisely:

>>> inputaverages(in1=800.0, in2=800.0, in3=800.0)
>>> outputaverages(out1=800.0, out2=800.0, out3=800.0, out4=800.0)

>>> test()
Click to see the table

restricted inputs

The same holds for the restricted inputs example:

>>> maxnmbinputs(2)

>>> test()
Click to see the table

different averages

Now we define different averages. Output node out1 lies at the same location as input node in1 and has the same average. Hence, it receives the original value of in1, if available. The other output nodes’ values reflect their averages:

>>> maxnmbinputs(3)
>>> inputaverages(in1=800.0, in2=1000.0, in3=600.0)
>>> outputaverages(out1=800.0, out2=900.0, out3=700.0, out4=650.0)

>>> test()
Click to see the table

shared location

If an input and an output node share the same location, their averages can still differ. We show this for inlet node in1 and outlet node out1:

>>> outputaverages(out1=1200.0, out2=900.0, out3=700.0, out4=650.0)

>>> test()
Click to see the table

other units

Only the relationships between the input and output averages matter. Hence, using other units (here, daily instead of annual values) changes the ratios but not the final results of the shared location example:

>>> inputaverages(in1=800.0 / 366.0, in2=1000.0 / 366.0, in3=600.0 / 366.0)
>>> outputaverages(out1=1200.0 / 366.0,
...                out2=900.0 / 366.0,
...                out3=700.0 / 366.0,
...                out4=650.0 / 366.0)

>>> test()
Click to see the table

zero averages

Stations with zero averages do not contribute to the interpolation (see station in2). Target points with zero averages receive zero values (see node out2):

>>> inputaverages(in1=800.0, in2=0.0, in3=600.0)
>>> outputaverages(out1=800.0, out2=0.0, out3=700.0, out4=650.0)

>>> test()
Click to see the table

nearest station

Stations with zero averages still count as one of the MaxNmbInputs nearest stations and are not replaced by more distant ones, just like stations with missing input values (see the restricted inputs example of conv_idw). If we only consider the nearest station, out2 receives nan values, despite its zero average, because station in2 is its nearest station:

>>> maxnmbinputs(1)

>>> test()
Click to see the table

monthly averages

Finally, we demonstrate the application of monthly averages. We shift the simulation period to the January-February transition and define averages for two nodes that differ between the months. The results change from the second to the third simulation step, even though the input values stay the same:

>>> pub.timegrids = "2000-01-30", "2000-02-02", "1d"
>>> element.prepare_allseries()
>>> test = IntegrationTest(element)
>>> test.dateformat = "%Y-%m-%d"
>>> inputaverages(in1=[80.0, 40.0, 80.0, 80.0, 80.0, 80.0,
...                    80.0, 80.0, 80.0, 80.0, 80.0, 80.0],
...               in2=100.0,
...               in3=60.0)
>>> outputaverages(out1=80.0,
...                out2=90.0,
...                out3=[70.0, 140.0, 70.0, 70.0, 70.0, 70.0,
...                      70.0, 70.0, 70.0, 70.0, 70.0, 70.0],
...                out4=65.0)
>>> in1.sequences.sim.series = 2.0, 2.0, 2.0
>>> in2.sequences.sim.series = 3.0, 3.0, 3.0
>>> in3.sequences.sim.series = 4.0, 4.0, 4.0

>>> test()
Click to see the table

Method features

class hydpy.models.conv_idw_cm.Model[source]

Bases: BaseModel

HydPy-Conv-IDW-CM (inverse distance weighted interpolation with multiplicative climatological adjustment).

The following “inlet update methods” are called in the given sequence at the beginning of each simulation step:
The following “run methods” are called in the given sequence during each simulation step:

  • Calc_CurrentInputAverages_V1 Take the long-term averages of the input nodes for the current month.

  • Calc_CurrentOutputAverages_V1 Take the long-term averages of the output nodes for the current month.

  • Calc_InputRatios_V1 Calculate the ratios between the values of the input nodes and their long-term averages for the current month.

  • Calc_OutputRatios_V1 Perform a simple inverse distance weighted interpolation based on the ratios previously determined for the input nodes.

  • Calc_Outputs_V4 Calculate the values of the output nodes by multiplying their long-term averages for the current month with the interpolated ratios.

The following “outlet update methods” are called in the given sequence at the end of each simulation step:
The following “additional methods” might be called by one or more of the other methods or are meant to be directly called by the user:
DOCNAME = ('Conv-IDW-CM', 'inverse distance weighted interpolation with multiplicative climatological adjustment')
REUSABLE_METHODS = ()

Parameter features

class hydpy.models.conv_idw_cm.ControlParameters(master: Parameters[TM_co], cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)

Bases: ControlParameters

Control parameters of model conv_idw_cm.

The following classes are selected:

  • InputCoordinates Coordinates of the inlet nodes [?].

  • OutputCoordinates Coordinates of the outlet nodes [?].

  • InputAverages The long-term averages of the input nodes for each month of the year [?].

  • OutputAverages The long-term averages of the output nodes for each month of the year [?].

  • MaxNmbInputs The maximum number of input locations to be taken into account for interpolating the values of a specific output location [-].

  • Power Power parameter for calculating inverse distance weights [-].

class hydpy.models.conv_idw_cm.DerivedParameters(master: Parameters[TM_co], cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)

Bases: DerivedParameters

Derived parameters of model conv_idw_cm.

The following classes are selected:

  • MOY References the “global” month of the year index array [-].

  • NmbInputs The number of inlet nodes [-]

  • NmbOutputs The number of outlet nodes [-]

  • Distances Distances of the inlet nodes to each outlet node [?].

  • ProximityOrder Indices of the inlet nodes in the order of their proximity to each outlet node [-].

  • Weights Weighting coefficients of the inlet nodes corresponding to their proximity to each outlet node and parameter Power [-].

Sequence features

class hydpy.models.conv_idw_cm.FluxSequences(master: Sequences[TM_co], cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: FluxSequences

Flux sequences of model conv_idw_cm.

The following classes are selected:

  • Inputs The (unmodified) values supplied by the input nodes [?].

  • CurrentInputAverages The long-term averages of the input nodes for the current month [?].

  • CurrentOutputAverages The long-term averages of the output nodes for the current month [?].

  • InputRatios The ratios between the current values supplied by the input nodes and their long-term averages for the current month [-].

  • OutputRatios The ratios between the final results and the long-term averages for the current month, interpolated for the output nodes [-].

  • Outputs The final interpolation results estimated for the output nodes [?].

class hydpy.models.conv_idw_cm.InletSequences(master: Sequences[TM_co], cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: InletSequences

Inlet sequences of model conv_idw_cm.

The following classes are selected:
class hydpy.models.conv_idw_cm.OutletSequences(master: Sequences[TM_co], cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: OutletSequences

Outlet sequences of model conv_idw_cm.

The following classes are selected: