Skip to content

Commit f378a09

Browse files
ValentinGebhartValentinGebhart
committed
adapted docstrings
1 parent e5da2c0 commit f378a09

File tree

3 files changed

+71
-75
lines changed

3 files changed

+71
-75
lines changed

‎climada/engine/impact.py‎

Lines changed: 26 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -502,8 +502,7 @@ def local_exceedance_impact(
502502
):
503503
"""Compute local exceedance impact for given return periods. The default method
504504
is fitting the ordered impacts per centroid to the corresponding cummulated
505-
frequency with linear interpolation on log-log scale. Impacts are binned according
506-
to their n_sig_dig significant digits, see Notes.
505+
frequency with linear interpolation on log-log scale.
507506
508507
Parameters
509508
----------
@@ -525,16 +524,15 @@ def local_exceedance_impact(
525524
min_impact : float, optional
526525
Minimum threshold to filter the impact. Defaults to 0.
527526
log_frequency : bool, optional
528-
This parameter is only used if method is set to "extrapolate" or "interpolate". If set
529-
to True, (cummulative) frequency values are converted to log scale before inter- and
530-
extrapolation. Defaults to True.
527+
If set to True, (cummulative) frequency values are converted to log scale before
528+
inter- and extrapolation. Defaults to True.
531529
log_impact : bool, optional
532-
This parameter is only used if method is set to "extrapolate" or "interpolate". If set
533-
to True, impact values are converted to log scale before inter- and extrapolation.
534-
Defaults to True.
535-
n_sig_dig : int, optional
536-
Number of significant digits for the binning of the impact values, see Notes.
537-
Defaults to 3.
530+
If set to True, impact values are converted to log scale before
531+
inter- and extrapolation. Defaults to True.
532+
bin_decimals : int, optional
533+
This parameter is only used if method is set to "extrapolate". Number of decimals
534+
for the binning of the impact values, see Notes. If None,
535+
impact values are not binned. Defaults to None.
538536
539537
Returns
540538
-------
@@ -555,10 +553,10 @@ def local_exceedance_impact(
555553
556554
Notes
557555
-------
558-
Contrary to Impact.calc_freq_curve(), impacts are binned according to their n_sig_dig
559-
significant digits. This results in a smoother (and coarser) interpolation, and a
560-
more stable extrapolation. To not bin the values, please use a large value for n_sig_dig,
561-
e.g., n_sig_dig=7. For more information about the binning, see
556+
If method = "extrapolate" and an integer bin_decimals is provided, impacts are binned
557+
according to their bin_decimals decimal places. This results in a smoother (and coarser)
558+
interpolation, and a more stable extrapolation. The default bin_decimals=None results in
559+
not binning the values. For more information about the binning, see
562560
climada.util.interpolation.preprocess_and_interpolate_ev().
563561
"""
564562
LOGGER.info(
@@ -656,8 +654,7 @@ def local_return_period(
656654
):
657655
"""Compute local return periods for given threshold impacts. The default method
658656
is fitting the ordered impacts per centroid to the corresponding cummulated
659-
frequency with linear interpolation on log-log scale. Impacts are binned according
660-
to their n_sig_dig significant digits, see Notes.
657+
frequency with linear interpolation on log-log scale.
661658
662659
Parameters
663660
----------
@@ -680,16 +677,15 @@ def local_return_period(
680677
min_impacts : float, optional
681678
Minimum threshold to filter the impact. Defaults to 0.
682679
log_frequency : bool, optional
683-
This parameter is only used if method is set to "interpolate". If set to True,
684-
(cummulative) frequency values are converted to log scale before inter- and
685-
extrapolation. Defaults to True.
680+
If set to True, (cummulative) frequency values are converted to log scale before
681+
inter- and extrapolation. Defaults to True.
686682
log_impact : bool, optional
687-
This parameter is only used if method is set to "interpolate". If set to True,
688-
impact values are converted to log scale before inter- and extrapolation.
689-
Defaults to True.
690-
n_sig_dig : int, optional
691-
Number of significant digits for the binning of the impact values, see Notes.
692-
Defaults to 3.
683+
If set to True, impact values are converted to log scale before
684+
inter- and extrapolation. Defaults to True.
685+
bin_decimals : int, optional
686+
This parameter is only used if method is set to "extrapolate". Number of decimals
687+
for the binning of the impact values, see Notes. If None,
688+
impact values are not binned. Defaults to None.
693689
694690
Returns
695691
-------
@@ -710,10 +706,10 @@ def local_return_period(
710706
711707
Notes
712708
-------
713-
Contrary to Impact.calc_freq_curve(), impacts are binned according to their n_sig_dig
714-
significant digits. This results in a smoother (and coarser) interpolation, and a
715-
more stable extrapolation. To not bin the values, please use a large value for n_sig_dig,
716-
e.g., n_sig_dig=7. For more information about the binning, see
709+
If method = "extrapolate" and an integer bin_decimals is provided, impacts are binned
710+
according to their bin_decimals decimal places. This results in a smoother (and coarser)
711+
interpolation, and a more stable extrapolation. The default bin_decimals=None results in
712+
not binning the values. For more information about the binning, see
717713
climada.util.interpolation.preprocess_and_interpolate_ev().
718714
"""
719715

‎climada/hazard/base.py‎

Lines changed: 28 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -495,8 +495,7 @@ def local_exceedance_intensity(
495495
):
496496
"""Compute local exceedance intensity for given return periods. The default method
497497
is fitting the ordered intensitites per centroid to the corresponding cummulated
498-
frequency with linear interpolation on log-log scale. Intensities are binned according
499-
to their n_sig_dig significant digits, see Notes.
498+
frequency with linear interpolation on log-log scale.
500499
501500
Parameters
502501
----------
@@ -519,16 +518,15 @@ def local_exceedance_intensity(
519518
Minimum threshold to filter the hazard intensity. If set to None, self.intensity_thres
520519
will be used. Defaults to None.
521520
log_frequency : bool, optional
522-
This parameter is only used if method is set to "interpolate". If set to True,
523-
(cummulative) frequency values are converted to log scale before inter- and
524-
extrapolation. Defaults to True.
521+
If set to True, (cummulative) frequency values are converted to log scale before
522+
inter- and extrapolation. Defaults to True.
525523
log_intensity : bool, optional
526-
This parameter is only used if method is set to "interpolate". If set to True,
527-
intensity values are converted to log scale before inter- and extrapolation.
528-
Defaults to True.
529-
n_sig_dig : int, optional
530-
Number of significant digits for the binning of the intensity values, see Notes.
531-
Defaults to 3.
524+
If set to True, intensity values are converted to log scale before
525+
inter- and extrapolation. Defaults to True.
526+
bin_decimals : int, optional
527+
This parameter is only used if method is set to "extrapolate". Number of decimals
528+
for the binning of the intensity values, see Notes. If None,
529+
intensity values are not binned. Defaults to None.
532530
533531
Returns
534532
-------
@@ -549,12 +547,11 @@ def local_exceedance_intensity(
549547
550548
Notes
551549
-------
552-
Contrary to Impact.calc_freq_curve(), intensities are binned according to their n_sig_dig
553-
significant digits. This results in a smoother (and coarser) interpolation, and a
554-
more stable extrapolation. To not bin the values, please use a large value for n_sig_dig,
555-
e.g., n_sig_dig=7. For more information about the binning, see
556-
util.interpolation.preprocess_and_interpolate_ev().
557-
550+
If method = "extrapolate" and an integer bin_decimals is provided, intensites are binned
551+
according to their bin_decimals decimal places. This results in a smoother (and coarser)
552+
interpolation, and a more stable extrapolation. The default bin_decimals=None results in
553+
not binning the values. For more information about the binning, see
554+
climada.util.interpolation.preprocess_and_interpolate_ev().
558555
"""
559556
if not min_intensity and min_intensity != 0:
560557
min_intensity = self.intensity_thres
@@ -648,8 +645,7 @@ def local_return_period(
648645
):
649646
"""Compute local return periods for given hazard intensities. The default method
650647
is fitting the ordered intensitites per centroid to the corresponding cummulated
651-
frequency with linear interpolation on log-log scale. Intensities are binned according
652-
to their n_sig_dig significant digits, see Notes.
648+
frequency with linear interpolation on log-log scale.
653649
654650
Parameters
655651
----------
@@ -673,16 +669,16 @@ def local_return_period(
673669
Minimum threshold to filter the hazard intensity. If set to None, self.intensity_thres
674670
will be used. Defaults to None.
675671
log_frequency : bool, optional
676-
This parameter is only used if method is set to "interpolate". If set to True,
677-
(cummulative) frequency values are converted to log scale before inter- and
678-
extrapolation. Defaults to True.
672+
If set to True, (cummulative) frequency values are converted to log scale before
673+
inter- and extrapolation. Defaults to True.
679674
log_intensity : bool, optional
680-
This parameter is only used if method is set to "interpolate". If set to True,
681-
intensity values are converted to log scale before inter- and extrapolation.
682-
Defaults to True.
683-
n_sig_dig : int, optional
684-
Number of significant digits for the binning of the intensity values, see Notes.
685-
Defaults to 3.
675+
If set to True, intensity values are converted to log scale before
676+
inter- and extrapolation. Defaults to True.
677+
bin_decimals : int, optional
678+
This parameter is only used if method is set to "extrapolate". Number of decimals
679+
for the binning of the intensity values, see Notes. If None,
680+
intensity values are not binned. Defaults to None.
681+
686682
687683
Returns
688684
-------
@@ -703,10 +699,10 @@ def local_return_period(
703699
704700
Notes
705701
-------
706-
Contrary to Impact.calc_freq_curve(), intensities are binned according to their n_sig_dig
707-
significant digits. This results in a smoother (and coarser) interpolation, and a
708-
more stable extrapolation. To not bin the values, please use a large value for n_sig_dig,
709-
e.g., n_sig_dig=7. For more information about the binning, see
702+
If method = "extrapolate" and an integer bin_decimals is provided, intensites are binned
703+
according to their bin_decimals decimal places. This results in a smoother (and coarser)
704+
interpolation, and a more stable extrapolation. The default bin_decimals=None results in
705+
not binning the values. For more information about the binning, see
710706
climada.util.interpolation.preprocess_and_interpolate_ev().
711707
"""
712708
if not min_intensity and min_intensity != 0:

‎climada/util/interpolation.py‎

Lines changed: 17 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -40,9 +40,9 @@ def preprocess_and_interpolate_ev(
4040
y_asymptotic=np.nan,
4141
bin_decimals=None,
4242
):
43-
"""Function to first preprocess (frequency, values) data by binning the data according to
44-
their value with the given number of significant digits (see Notes), compute the cumulative
45-
frequencies, and then inter- and extrapolate either to test frequencies or to test values.
43+
"""Function to first preprocess (frequency, values) data (if extrapolating, one can bin the
44+
data according to their value, see Notes), compute the cumulative frequencies, and then
45+
inter- and extrapolate either to test frequencies or to test values.
4646
4747
Parameters
4848
----------
@@ -70,13 +70,16 @@ def preprocess_and_interpolate_ev(
7070
If set to "extrapolate_constant" or "stepfunction", test x values larger than given
7171
x values will be assigned largest given y value, and test x values smaller than the given
7272
x values will be assigned y_asymtotic. If set to "extrapolate", values will be extrapolated
73-
(and interpolated). Defaults to "interpolate".
73+
(and interpolated). The extrapolation to test frequencies or test values outside of the
74+
data range extends the two interpolations at the edges of the data to outside of
75+
the data. Defaults to "interpolate".
7476
y_asymptotic : float, optional
7577
Has no effect if method is "interpolate". Else, provides return value and if
7678
for test x values larger than given x values, if size < 2 or if method is set
7779
to "extrapolate_constant" or "stepfunction". Defaults to np.nan.
78-
n_sig_dig : int, optional
79-
Number of significant digits to group and bin the values, see Notes. Defaults to 3.
80+
bin_decimals : int or None, optional
81+
Number of decimals to group and bin the values, see Notes. If None, values are not binned.
82+
Defaults to None.
8083
8184
Returns
8285
-------
@@ -91,12 +94,12 @@ def preprocess_and_interpolate_ev(
9194
9295
Notes
9396
-----
94-
Before inter- and extrapolation, the values are binned according to their n_sig_dig
95-
significant digits, and their corresponding frequencies are summed. For instance, if
96-
n_sig_dig=3, the two values 12.01 and 11.97 with corresponding frequencies 0.1 and 0.2 are
97+
Before extrapolation, if an integer bin_decimals is given, the values are binned according to
98+
their bin_decimals decimals, and their corresponding frequencies are summed. For instance, if
99+
bin_decimals=1, the two values 12.01 and 11.97 with corresponding frequencies 0.1 and 0.2 are
97100
combined to a value 12.0 with frequency 0.3. This binning leads to a smoother (and coarser)
98-
interpolation, and a more stable extrapolation. To not bin the values, you can use a large
99-
n_sig_dig, e.g., n_sig_dig=7.
101+
interpolation, and a more stable extrapolation. The default bin_decimals=None results in not
102+
binning the values.
100103
"""
101104

102105
# check that only test frequencies or only test values are given
@@ -356,8 +359,9 @@ def _group_frequency(frequency, value, bin_decimals):
356359
Frequency array
357360
value : array_like
358361
Value array in ascending order
359-
n_sig_dig : int
360-
number of significant digits for value when grouping frequency.
362+
bin_decimals : int
363+
decimals according to which values are binned and their corresponding frequency are
364+
grouped.
361365
362366
Returns:
363367
------

0 commit comments

Comments
 (0)