[Option Appraisal Module] [Package 1: Measures] Split 3: Adds new base Measure class

[spjuhel]

Changes proposed in this PR:

This PR brings the basis of the refactored Measure class, using closures (functions that return a function) to define the effects of a measure.

Important points:

• Effects are separated by effects on Exposures, effects on Impfset, and on Hazard
• The closures need to accept keyword arguments to enable effects that rely on something else than what the effect is applied on (i.e. year, other part of risk, etc...)
• We always pass the Exposures, Impfset and Hazard objects as kwargs to the closures by default
• We pass user-defined function through an allow_kwargs to make sure closures always accept kwargs.
• Measure instances optionally have a _config attribute that contains a MeasureConfig if the measure was defined from such an object (and is therefore serializable).

PR Author Checklist

• Read the Contribution Guide
• Correct target branch selected (if unsure, select develop)
• Descriptive pull request title added
• Source branch up-to-date with target branch
• Documentation updated
• Tests updated
• Tests passing
• No new linter issues
• Changelog updated

PR Reviewer Checklist

• Read the Contribution Guide
• CLIMADA Reviewer Checklist passed
• Tests passing
• No new linter issues

[ValentinGebhart]

This new implementation of the measures looks super cool :) I think it is much cleaner and user-friendly to before! I just commented whenever something was unclear to me. I haven't had time to check the working of the functions with actual data yet , e.g. for some consistency checks.

The only one more conceptual question I have is if you have to work with the (hidden) base_exposure, base_hazard, base_impfunc handling, but maybe I have not understood yet why these can be useful. Happy to discuss!

Note that I first read the tutorial without knowing the code to just check if I understand the usage. Some of the comments there might not be there know after I read the code :)

[spjuhel]

This new implementation of the measures looks super cool :) I think it is much cleaner and user-friendly to before! I just commented whenever something was unclear to me. I haven't had time to check the working of the functions with actual data yet , e.g. for some consistency checks.

The only one more conceptual question I have is if you have to work with the (hidden) base_exposure, base_hazard, base_impfunc handling, but maybe I have not understood yet why these can be useful. Happy to discuss!

Note that I first read the tutorial without knowing the code to just check if I understand the usage. Some of the comments there might not be there know after I read the code :)

Thanks for these comments.

Answering the conceptual question about the base_X arguments. (see also #1279 (comment)):

The idea comes from the fact that I assume there is a whole range of adaptation options effect on Hazard|Exposures|Impfset where you have to use some information in your base exposures, hazard or impfset.

But it is a bit "advanced" to write for instance (ellipsed/simplified):

def my_effect_on_exposures(exposures, req_hazard):
    indices = req_hazard > 10
    exposures.gdf.loc[indices,"value"] *= 0.98
    
measure_a = Measure(..., exposure_change=my_effect_on_exposures)

exp, impf, haz = measure.apply(exp, impf, haz, kwarg_exposures = {req_hazard: haz}) # That part is slightly scary

By always providing base_Hazard|Exposures|Impfset, you can "simplify":

def my_effect_on_exposures(exposures, base_hazard): # note that the name need to be base_hazard!
    indices = base_hazard > 10
    exposures.gdf.loc[indices,"value"] *= 0.98
    
measure_a = Measure(..., exposure_change=my_effect_on_exposures)

exp, impf, haz = measure.apply(exp, impf, haz) # Scary kwargs are gone!

On this small example it may seem not much, but if the three effects all rely on the three components then it is way more relevant.

I agree the current explanations in the docs might be improved ;D

[spjuhel]

@ValentinGebhart : I think I addressed all remaining comments, and I've added a few more advanced examples to the guide. (Of course we can extend even more, but I think that's enough for now)

@chahank, @emanuel-schmid @peanutfun Can you have a quick code-owner look?