Skip to content

Commit 9e9fa4e

Browse files
timceratimcera
committed
docs: now both the CLI and API have docstrings
1 parent 5814f82 commit 9e9fa4e

9 files changed

Lines changed: 1590 additions & 1978 deletions

File tree

‎docs/command_line.rst‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,6 @@ Help::
77

88
mettoolbox --help
99

10-
about
11-
~~~~~
12-
.. program-output:: mettoolbox about --help
13-
:prompt:
14-
1510
disaggregate
1611
~~~~~~~~~~~~
1712
.. program-output:: mettoolbox disaggregate --help

‎docs/function_summary.rst‎

Lines changed: 18 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -6,22 +6,21 @@ Python API Function Summary
66
.. autosummary::
77
:toctree: _function_autosummary
88

9-
mettoolbox.mettoolbox.about
10-
mettoolbox.mettoolbox.disaggregate.dewpoint_temperature
11-
mettoolbox.mettoolbox.disaggregate.evaporation
12-
mettoolbox.mettoolbox.disaggregate.humidity
13-
mettoolbox.mettoolbox.disaggregate.precipitation
14-
mettoolbox.mettoolbox.disaggregate.radiation
15-
mettoolbox.mettoolbox.disaggregate.temperature
16-
mettoolbox.mettoolbox.disaggregate.wind_speed
17-
mettoolbox.mettoolbox.indices.pe
18-
mettoolbox.mettoolbox.indices.spei
19-
mettoolbox.mettoolbox.pet.allen
20-
mettoolbox.mettoolbox.pet.blaney_criddle
21-
mettoolbox.mettoolbox.pet.hamon
22-
mettoolbox.mettoolbox.pet.hargreaves
23-
mettoolbox.mettoolbox.pet.linacre
24-
mettoolbox.mettoolbox.pet.oudin_form
25-
mettoolbox.mettoolbox.pet.priestley_taylor
26-
mettoolbox.mettoolbox.pet.romanenko
27-
mettoolbox.mettoolbox.ret.penman_monteith
9+
mettoolbox.disaggregate.dewpoint_temperature
10+
mettoolbox.disaggregate.evaporation
11+
mettoolbox.disaggregate.humidity
12+
mettoolbox.disaggregate.precipitation
13+
mettoolbox.disaggregate.radiation
14+
mettoolbox.disaggregate.temperature
15+
mettoolbox.disaggregate.wind_speed
16+
mettoolbox.indices.pe
17+
mettoolbox.indices.spei
18+
mettoolbox.pet.allen
19+
mettoolbox.pet.blaney_criddle
20+
mettoolbox.pet.hamon
21+
mettoolbox.pet.hargreaves
22+
mettoolbox.pet.linacre
23+
mettoolbox.pet.oudin_form
24+
mettoolbox.pet.priestley_taylor
25+
mettoolbox.pet.romanenko
26+
mettoolbox.ret.penman_monteith

‎requirements.txt‎

Whitespace-only changes.

‎src/mettoolbox/disaggregate.py‎

Lines changed: 637 additions & 15 deletions
Large diffs are not rendered by default.

‎src/mettoolbox/indices.py‎

Lines changed: 168 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,9 @@
33
import pandas as pd
44
from pydantic import PositiveInt
55

6-
from .standard_precip.standard_precip.spi import SPI
7-
from .toolbox_utils.src.toolbox_utils import tsutils
6+
from mettoolbox.mettoolbox_utils import _LOCAL_DOCSTRINGS
7+
from mettoolbox.standard_precip.standard_precip.spi import SPI
8+
from mettoolbox.toolbox_utils.src.toolbox_utils import tsutils
89

910
try:
1011
from pydantic import validate_arguments as validate_call
@@ -52,6 +53,7 @@ def _nlarge_nsmall(
5253

5354
@tsutils.transform_args(source_units=tsutils.make_list)
5455
@validate_call(config={"arbitrary_types_allowed": True})
56+
@tsutils.doc(_LOCAL_DOCSTRINGS)
5557
def spei(
5658
rainfall: Union[PositiveInt, str, pd.DataFrame],
5759
pet: Union[PositiveInt, str, pd.DataFrame],
@@ -70,6 +72,98 @@ def spei(
7072
skiprows=None,
7173
index_type="datetime",
7274
):
75+
"""
76+
Standard Precipitation/Evaporation Index.
77+
78+
Calculates a windows cumulative sum of daily precipitation minus
79+
evaporation.
80+
81+
Parameters
82+
----------
83+
rainfall
84+
A csv, wdm, hdf5, xlsx file or a pandas DataFrame or Series or
85+
an integer column or string name of standard input.
86+
87+
Represents a daily time-series of precipitation in units specified in
88+
`source_units`.
89+
pet
90+
A csv, wdm, hdf5, xlsx file or a pandas DataFrame or Series or
91+
an integer column or string name of standard input.
92+
93+
Represents a daily time-series of evaporation in units specified in
94+
`source_units`.
95+
${source_units}
96+
nsmallest : int
97+
[optional, default is None]
98+
99+
Return the "n" days with the smallest precipitation minus evaporation
100+
index value within the `groupby` pandas offset period.
101+
102+
Cannot assign both `nsmallest` and `nlargest` keywords.
103+
nlargest : int
104+
[optional, default is None]
105+
106+
Return the "n" days with the largest precipitation minus evaporation
107+
index value within the `groupby` pandas offset period.
108+
109+
Cannot assign both `nsmallest` and `nlargest` keywords.
110+
groupby : str
111+
Pandas offset period string representing the time over which the
112+
`nsmallest` or `nlargest` values would be evaluated.
113+
fit_type : str ("lmom" or "mle")
114+
Specify the type of fit to use for fitting distribution to the
115+
precipitation data. Either L-moments (lmom) or Maximum Likelihood
116+
Estimation (mle). Note use L-moments when comparing to NCAR's NCL code
117+
and R's packages to calculate SPI and SPEI.
118+
dist_type : str
119+
The distribution type to fit using either L-moments (fit_type="lmom")
120+
or MLE (fit_type="mle").
121+
122+
+-----------+---------------------------+-----------+----------+
123+
| dist_type | Distribution | fit_type | fit_type |
124+
| | | lmom | mle |
125+
+===========+===========================+===========+==========+
126+
| gam | Gamma | X | X |
127+
+-----------+---------------------------+-----------+----------+
128+
| exp | Exponential | X | X |
129+
+-----------+---------------------------+-----------+----------+
130+
| gev | Generalized Extreme Value | X | X |
131+
+-----------+---------------------------+-----------+----------+
132+
| gpa | Generalized Pareto | X | X |
133+
+-----------+---------------------------+-----------+----------+
134+
| gum | Gumbel | X | X |
135+
+-----------+---------------------------+-----------+----------+
136+
| nor | Normal | X | X |
137+
+-----------+---------------------------+-----------+----------+
138+
| pe3 | Pearson III | X | X |
139+
+-----------+---------------------------+-----------+----------+
140+
| wei | Weibull | X | X |
141+
+-----------+---------------------------+-----------+----------+
142+
| glo | Generalized Logistic | | X |
143+
+-----------+---------------------------+-----------+----------+
144+
| gno | Generalized Normal | | X |
145+
+-----------+---------------------------+-----------+----------+
146+
| kap | Kappa | | X |
147+
+-----------+---------------------------+-----------+----------+
148+
| wak | Wakeby | X | |
149+
+-----------+---------------------------+-----------+----------+
150+
151+
scale : int (default=1)
152+
Integer to specify the number of time periods over which the
153+
standardized precipitation index is to be calculated. If freq="M" then
154+
this is the number of months.
155+
${input_ts}
156+
${start_date}
157+
${end_date}
158+
${dropna}
159+
${clean}
160+
${round_index}
161+
${skiprows}
162+
${index_type}
163+
${names}
164+
${print_input}
165+
${tablefmt}
166+
"""
73167
from tstoolbox.tstoolbox import read
74168

75169
tsd = read(
@@ -114,6 +208,7 @@ def spei(
114208

115209
@tsutils.transform_args(source_units=tsutils.make_list)
116210
@validate_call(config={"arbitrary_types_allowed": True})
211+
@tsutils.doc(_LOCAL_DOCSTRINGS)
117212
def pe(
118213
rainfall: Union[PositiveInt, str, pd.DataFrame],
119214
pet: Union[PositiveInt, str, pd.DataFrame],
@@ -128,6 +223,77 @@ def pe(
128223
closed=None,
129224
target_units="mm",
130225
):
226+
"""
227+
Precipitation minus evaporation index.
228+
229+
Calculates a windows cumulative sum of daily precipitation minus evaporation.
230+
231+
Parameters
232+
----------
233+
rainfall
234+
A csv, wdm, hdf5, xlsx file or a pandas DataFrame or Series or
235+
an integer column or string name of standard input.
236+
237+
Represents a daily time-series of precipitation in units specified in
238+
`source_units`.
239+
pet
240+
A csv, wdm, hdf5, xlsx file or a pandas DataFrame or Series or
241+
an integer column or string name of standard input.
242+
243+
Represents a daily time-series of evaporation in units specified in
244+
`source_units`.
245+
${source_units}
246+
nsmallest : int
247+
[optional, default is None]
248+
249+
Return the "n" days with the smallest precipitation minus evaporation
250+
index value within the `groupby` pandas offset period.
251+
252+
Cannot assign both `nsmallest` and `nlargest` keywords.
253+
nlargest : int
254+
[optional, default is None]
255+
256+
Return the "n" days with the largest precipitation minus evaporation
257+
index value within the `groupby` pandas offset period.
258+
259+
Cannot assign both `nsmallest` and `nlargest` keywords.
260+
groupby : str
261+
Pandas offset period string representing the time over which the
262+
`nsmallest` or `nlargest` values would be evaluated.
263+
window : int
264+
[optional, default is 30]
265+
266+
Size of the moving window. This is the number of observations used for
267+
calculating the statistic. Each window will be a fixed size.
268+
269+
If its an offset then this will be the time period of each window. Each
270+
window will be a variable sized based on the observations included in
271+
the time-period. This is only valid for datetimelike indexes.
272+
min_periods : int, default 170 days
273+
Minimum number of observations in window required to have a value
274+
(otherwise result is NA). For a window that is specified by an offset,
275+
min_periods will default to 1. Otherwise, min_periods will default to
276+
the size of the window.
277+
center : bool, default False
278+
Set the labels at the center of the window.
279+
win_type : str, default None
280+
Provide a window type. If None, all points are evenly weighted. See the
281+
notes below for further information.
282+
closed : str, default None
283+
Make the interval closed on the ‘right’, ‘left’, ‘both’ or ‘neither’
284+
endpoints. Defaults to ‘right’.
285+
${input_ts}
286+
${start_date}
287+
${end_date}
288+
${dropna}
289+
${clean}
290+
${round_index}
291+
${index_type}
292+
${names}
293+
${target_units}
294+
${print_input}
295+
${tablefmt}
296+
"""
131297
from tstoolbox.tstoolbox import read
132298

133299
tsd = read(

0 commit comments

Comments
 (0)