Improve efficiency of local exceedance intensitry/impact and local return periods functions

[ValentinGebhart]

Changes proposed in this PR:
Changes address the methods Hazard.local_exceedance_intensity, Hazard.local_return_period, Impact.local_exceedance_impact, and Impact.local_return_period.

• In the computation, intensity/impact values are now only binned (and their frequency added in each bin) if bin_decimals is an integer (default: None). Then, the values are binned according to their bin_decimals decimal places. In all other cases, no binning occurs. In the notes, some possible values for bin_decimals are given.
• The interpolation util function is now only called for centroids with nonzero intensity/impact.
• docstring was extented to explain how data are extrapolated.
• The plotting functions Hazard.plot_rp_intensity and Impact.plot_rp_imp now directly call the corresponding functions above, and a warning is added about how to recover values that are computed with CLIMADA 5.0.0 or earlier.

Comments for future improvements:

• It would be nice to have a fit method, also for extrapolation.
• The impact method calc_freq_curve and the class ImpactFreqCurve could be adapted to also include the different methods of util.interpolation.

This PR fixes #1010 and #1015

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

[chahank]

Cool idea, I am not sure though that this should be an info logging. @emanuel-schmid : what would be the most elegant way to inform the users that something changed, without having logs all the time?

[chahank]

Could you make this calculous optional? Or what would be the way to refine the plot without having to recalculate these values (which can take quite long)? Is it using the util method instead?

[ValentinGebhart]

I think the best way is to do gdf, title, columns = hazard.local_exceedance_intensity() and u_plot.plot_from_gdf(gdf, title, columns). Then you can just change the plot options by repeating the second step, without recalculating the gdf. The plot_rp_intensity is just a wrapper around these two functions, which is why I asked if we want to keep it in the first place.

One way of not repeating the calculation here if one calls the function plot_rp_intensity twice would be to save the local exceedance gdf as an attribute of the Hazard object, but I don't think we want to do that?

[ValentinGebhart]

What about writing the info to better use the other two functions in the docstring, as you suggested in the issue? Is this enough?

[chahank]

Yeah, that would be a solution I think. For small hazards I guess the method is rather fast, and for lager ones there would the solution in the docstring.

[ValentinGebhart]

This PR is now ready for review. Note that I did not add a code example to any docstring as I think the only understandable place would be util.interpolation._group_frequency which is a private function that will not be seen by the user.

[ValentinGebhart]

just realized that the fix of the rounding method is much slower than the method before that had floating point problems. I will try to solve this, I'll say as soon as I'm ready

[ValentinGebhart]

Quick update:
I removed the method of rounding to significant digits. Now the default is to not bin any values. Binning can be activated for extrapolation: by method="extrapolate" (default "interpolate") and setting bin_decimals to an integer (default None). Then values are binned according to bin_decimals decimal places.

[chahank]

Does this mean that one cannot bin for the "interpolate" method? And does that mean that the user always has to come up with a number for the rounding?

[ValentinGebhart]

Yes, one cannot bin anymore in interpolation, as binning does have little effect here (it just "smoothens" the data).

In extrapolation, default is not binning, and the user has to provide the decimal places to bin if they want to bin. Binning in decimals and not n_sig_sigits because it is simpler.

In this way, binning has to be consciously chosen by the user, as it is also not clear what a good default value would be and if one would want to bin by default.

[ValentinGebhart]

Update:
Binning is now possible for all methods (default: no binning). Some example choices for bin_decimals (the decimals about how to bin) are added to the docstrings.

[chahank]

Awesome. I made some suggestions for passing the keyword arguments to the underlying method in the case of the plotting method. I hope these work as intended.

Nice work! The test coverage is a bit lower now, not sure why exactly. The pre-commit checks are failing, but I do not understand why exactly. Maybe retry it.

[ValentinGebhart]

Thanks for the review! I included the suggestions and checked that they work. Also, the tutorial now uses a hazard object with the correct frequencies, without redefining frequencies (Emanuel put it on the API). Let me know if we can merge :)

[chahank]

Really only a small detail, but it seems that the entire docstring is moved one space to the right.

[ValentinGebhart]

nice catch, how did you find that? :D it doesn't show in my pylint

[chahank]

Haha, it just showed weirdly on the screen in the github file-change view. Laser-eyes :D

[chahank]

Great, this makes the methods much clearer, faster and better tested! This is ready to merge. Before, please do not forget to update the changelog file!