RFC: Implement a new Impact Function registry system

[timlinux]

Status

Accepted, under implementation. The proposal to adopt the new IF system was agreed on at an InaSAFE workshop held in AIFDR/Jakarta, March 2014

Goals

1. Separate Impact Functions from their metadata
2. Use a more OOP based approach for Impact Functions
3. Get rid of docstring based metadata from Impact Functions
4. Make Impact Functions stateful
5. Make Impact Functions Independent
6. Make aggregation and post processing part of the IF run process

OOP

OOP (Object Orientated Programming) strives to treat conceptual models in program code as if they were real world objects. Python supports OOP programming and safe Impact Functions are implemented as classes / object instances, but they don't behave in a very OOP like way. If we think of Impact Functions like objects, we should be able to create an IF object and then ask it to do things and ask it questions about itself:

• 'are you ready to run?'
• 'run yourself!'
• ' how far through running are you?'
• 'how many people were impacted?'
• 'what date were you run?'
• 'what parameters were used in your execution?'
• 'give me your action list'
• 'which layers were used in your analysis?'
• 'who ran you?'
• 'save yourself to disk'
• 'load yourself from disk'
• 'update your parameters to look like this'
• 'rerun yourself'

In contrast the current Impact Functions are rather simple: they simply take some input layers and return a dictionary containing an impact_summary and various other bits of into, plus write their product to the disk if they have on.

Adopting a more OOP approach would allow us to formalise the roles that an Impact Function must carry out while ensuring that we have good separation of concerns: Let the Impact Function and its base class parse its internal state and provide high level data back to its clients.

Statefulness

Statefulness is the ability to remember their current state within or beyond a current session. We should be able to 'freeze' the state of an impact function and then restore it. In particular this will give the ability to do things like

• 'run the analysis I ran yesterday'
• 'here is a test case, please run it'

Impact Function Independence

Independence of impact functions means that they should have the smallest possible dependency on other parts of InaSAFE. We should be able to use impact functions in a wide range of contexts with few impediments. For example we should be able to use impact functions as simply as punching in a few lines like this into the QGIS python console:

from inasafe.impact_functions import FloodImpactFunction
if = FloodImpactFunction()
if.hazard = QGISLayerA
if.exposure = QGISLayerB
if.aggregation = QGISLayerC
if.extent = [10, 10 , 20, 20]
if.extent_crs = 4326
result_layer = if.run()

Integration of Aggregation

Currently there is a lot of indirection that takes place in order to perform aggregation on an impact layer. I would like to propose that we include aggregation as a natural feature of impact functions - simply by calling aggregate on the impact function base class which will do a noop if no aggregation layer has been defined, otherwise it will carry out the aggregation in-situ

Tracing the plugin loading process

There are many layers of indirection between the things that use an Impact Function and the Impact Function itself. e.g.

safe_qgis.widgets.dock.Dock#run -> def run(self):
safe_qgis/widgets/dock.py:1434 -> self.runner.run() 
safe_qgis.utilities.impact_calculator_thread.ImpactCalculatorThread#run -> def run(self)
safe_qgis/utilities/impact_calculator_thread.py:183 -> self._impactLayer = calculate_safe_impact
safe_qgis/safe_interface.py:514 -> def calculate_safe_impact(
        layers, function, extent=None, check_integrity=True):
safe_qgis/safe_interface.py:53 -> calculate_impact as safe_calculate_impact,
safe/engine/core.py:24  -> def calculate_impact(layers, impact_fcn, extent=None, check_integrity=True):

See also

Reference implementation here:

https://github.com/timlinux/impact_function_registry

[akbargumbira]

Just to summarize the state of this RFC regarding the goals of this RFC:

• Separate Impact Functions from their metadata
• Use a more OOP based approach for Impact Functions
• Get rid of docstring based metadata from Impact Functions
• Make Impact Functions stateful
• Make Impact Functions Independent
• Make aggregation and post processing part of the IF run process

[akbargumbira]

Related issues of this PR:

• Make the IF as independent as possible to other modules in running analysis (e.g moving clipping etc) Make the IF as independent as possible to other modules in running analysis (e.g moving clipping etc) #1916
• Update the IF's to get some parameters from Layer's keywords (Update the IF's to get some parameters from Layer's keywords #1991)
• IF Parameter Rework (https://docs.google.com/spreadsheets/d/1o8xRZ_Sa3gkt0H8sLrXwJg4OyBKKqtMjQG8h7scRkW8/edit#gid=973901724)
• Implement Interpolation Algorithm (Raster on Raster, Raster on Vector, Vector on Raster, Vector on Vector) using QGIS API Implement Interpolation Algorithm (Raster on Raster, Raster on Vector, Vector on Raster, Vector on Vector) using QGIS API #1918
• Review Raster on Vector Interpolation based on September workshop discussion Review Raster on Vector Interpolation based on September workshop discussion #1917
• Make the IF as independent as possible to other modules in running analysis (e.g moving clipping etc) Make the IF as independent as possible to other modules in running analysis (e.g moving clipping etc) #1916
• Reverse the way we treat layers in IF Reverse the way we treat layers in IF #1797
• Add some fields in base IF to reflect layers metadata Add some fields in base IF to reflect layers metadata #1788
• We need to finalise the new impact function base class We need to finalise the new impact function base class #1747
• Unified Building Classification for All IFs on Building Unified Building Classification for All IFs on Building #1665
• We need to migrate the IF archtecture We need to migrate the IF archtecture #1627
• Some overlap parameters when running analysis Some overlap parameters when running analysis #1481

[timlinux]

InaSAFE 4.0 is here - death to old style IF's!