From 99778673aca0e50d1015fbd2aed672b13ec68683 Mon Sep 17 00:00:00 2001 From: jorenham Date: Sat, 24 Aug 2024 04:31:00 +0200 Subject: [PATCH 1/8] improved `lmo.inference.fit` docs --- lmo/inference/_l_gmm.py | 33 ++++++++++++++++++++------------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/lmo/inference/_l_gmm.py b/lmo/inference/_l_gmm.py index 84260048..f08408fe 100644 --- a/lmo/inference/_l_gmm.py +++ b/lmo/inference/_l_gmm.py @@ -226,12 +226,14 @@ def fit( # noqa: C901 Fit the distribution parameters using the (Generalized) Method of L-Moments (L-(G)MM). - The goal is to find the "true" parameters $\theta_0$ of the distribution. - In practise, this is done using a reasonably close estimate, $\theta$. + The goal is to find the "true" parameters $\bm{\theta^*}$ of the + distribution. + In practise, this is done using a reasonably close estimate, + $\bm{\hat\theta}$. In the (non-Generalized) Method of L-moments (L-MM), this is done by - solving the system of equations $l^{(s, t)}_r = \lambda^{(s, t)}_r$, - for $r = 1, \dots, k$, with $n = |\theta|$ the number of parameters. + solving the system of equations $\ell^{(s, t)}_r = \lambda^{(s, t)}_r$, + for $r = 1, \dots, n$, with $n$ the number of free parameters. Because the amount of parameters matches the amount of *L-moment conditions*, the solution is *point-defined*, and can be found using simple least squares. @@ -241,11 +243,16 @@ def fit( # noqa: C901 system of $m$ equations: $$ - \hat{\theta} = - \mathop{\arg \min} \limits_{\theta \in \Theta} - (\vec{\lambda}^{(s, t)}_r - \vec{l}^{(s, t)})^T - W_m - (\vec{\lambda}^{(s, t)}_r - \vec{l}^{(s, t)}) + \bm{\hat\theta} = + \mathop{\arg \min} \limits_{\theta \in \Theta} \Bigl\{ + \left[ + \bm{\lambda}^{(s, t)}(X_\theta) - \bm{\ell}^{(s, t)} + \right]^T + W_m + \left[ + \bm{\lambda}^{(s, t)}(X_\theta) - \bm{\ell}^{(s, t)} + \right] + \Bigr\} \, , $$ @@ -267,13 +274,13 @@ def fit( # noqa: C901 - Raise on minimization error, warn on failed k-step convergence - Optional `integrality` kwarg with boolean mask for integral params. - Implement CUE: Continuously Updating GMM (i.e. implement and - use `_loss_cue()`, then run with `k=1`). See - https://github.com/jorenham/Lmo/issues/299 + use `_loss_cue()`, then run with `k=1`), see + [#299](https://github.com/jorenham/Lmo/issues/299). Parameters: ppf: The (vectorized) quantile function of the probability distribution, - with signature `(q: T, *params: float) -> T`. + with signature `(q: T, *theta: float) -> T`. args0: Initial estimate of the distribution's parameter values. n_obs: @@ -299,7 +306,7 @@ def fit( # noqa: C901 Will be ignored if $k$ is specified or if `n_extra=0`. l_moment_fn: Function for parametric L-moment calculation, with signature: - `(r: intp[:], *args, trim: float[2] | int[2]) -> float64[:]`. + `(r: intp[:], *theta: float, trim: tuple[int, int]) -> float64[:]`. n_mc_samples: The number of Monte-Carlo (MC) samples drawn from the distribution to to form the weight matrix in step $k > 1$. From a1a7071be25ab38f5f03747792b58db06a2520e4 Mon Sep 17 00:00:00 2001 From: jorenham Date: Sat, 24 Aug 2024 06:34:15 +0200 Subject: [PATCH 2/8] fix gitignore --- .gitignore | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/.gitignore b/.gitignore index 3d6dd73c..d76f01e6 100644 --- a/.gitignore +++ b/.gitignore @@ -9,15 +9,15 @@ dist/ site/ # Cache -.cache/ -.hypothesis/ -.pytest_cache/ -.ruff_cache/ -.tox/ +.cache +.hypothesis +.pytest_cache +.ruff_cache +.tox # Environments .env -.venv/ +.venv venv/ # IntelliJ From 83e18027c074bf32a3851cd4561659ee5a5fe0bc Mon Sep 17 00:00:00 2001 From: jorenham Date: Sat, 24 Aug 2024 08:17:32 +0200 Subject: [PATCH 3/8] minor improvements for `lmo.l_moment_influence` --- lmo/_lm.py | 51 +++++++++++++++++++++++++++++++++++---------------- lmo/_utils.py | 25 ++++++++++++++++++++----- 2 files changed, 55 insertions(+), 21 deletions(-) diff --git a/lmo/_lm.py b/lmo/_lm.py index 0d93f42d..b41a5dc6 100644 --- a/lmo/_lm.py +++ b/lmo/_lm.py @@ -926,6 +926,7 @@ def l_kurtosis( l_kurt = l_kurtosis +"""Alias for [`lmo.l_kurtosis`][lmo.l_kurtosis].""" def l_moment_cov( @@ -1112,7 +1113,7 @@ def l_stats_se( return l_ratio_se(a, r, s, trim=trim, axis=axis, dtype=dtype, **kwds) -_T_x = TypeVar('_T_x', float, npt.NDArray[_Floating]) +_T_x = TypeVar('_T_x', bound=float | npt.NDArray[_Floating]) def l_moment_influence( @@ -1125,54 +1126,68 @@ def l_moment_influence( tol: float = 1e-8, ) -> Callable[[_T_x], _T_x]: r""" - Empirical Influence Function (EIF) of a sample L-moment. + Calculate the *Empirical Influence Function (EIF)* for a + [sample L-moment][lmo.l_moment] estimate. Notes: - This function is not vectorized. + This function is *not* vectorized, and can only be used for a single + L-moment order `r`. + However, the returned (empirical influence) function *is* vectorized. Args: a: 1-D array-like containing observed samples. r: L-moment order. Must be a non-negative integer. trim: Left- and right- trim. Can be scalar or 2-tuple of - non-negative int or float. + non-negative int (or float). Other parameters: - sort ('quicksort' | 'heapsort' | 'stable'): + sort (True | False | 'quicksort' | 'heapsort' | 'stable'): Sorting algorithm, see [`numpy.sort`][numpy.sort]. + Set to `False` if the array is already sorted. tol: Zero-roundoff absolute threshold. Returns: influence_function: The (vectorized) empirical influence function. + Raises: + ValueError: If `a` is not 1-D array-like. + TypeError: If `a` is not a floating-point type. + """ _r = clean_order(r) s, t = clean_trim(trim) - x_k = np.array(a, copy=bool(sort)) + x_k = np.array(a, copy=bool(sort), dtype=np.float64) + if x_k.ndim != 1: + msg = f"'a' must be 1-D array-like, got ndim={x_k.ndim}." + raise ValueError(msg) x_k = sort_maybe(x_k, sort=sort, inplace=True) n = len(x_k) - w_k = l_weights(_r, n, (s, t))[-1] - l_r = np.inner(w_k, x_k) + w_k: onpt.Array[tuple[int], np.float64] = l_weights(_r, n, (s, t))[-1] + l_r = cast(np.float64, w_k @ x_k) def influence_function(x: _T_x, /) -> _T_x: - _x = np.asarray(x) + _x = np.asanyarray(x) # ECDF # k = np.maximum(np.searchsorted(x_k, _x, side='right') - 1, 0) - w = cast(_T_x, np.interp( + w = np.interp( _x, x_k, w_k, left=0 if s else w_k[0], right=0 if t else w_k[-1], - )) - + ) alpha = n * w * np.where(w, _x, 0) - return cast(_T_x, round0(alpha - l_r, tol=tol)[()]) + out = round0(alpha - l_r, tol=tol) + + if _x.ndim == 0 and np.isscalar(x): + return out.item() + return cast(_T_x, out) influence_function.__doc__ = ( f'Empirical L-moment influence function for {r=}, {trim=}, and {n=}.' @@ -1193,10 +1208,13 @@ def l_ratio_influence( tol: float = 1e-8, ) -> Callable[[_T_x], _T_x]: r""" - Empirical Influence Function (EIF) of a sample L-moment ratio. + Calculate the *Empirical Influence Function (EIF)* for a + [sample L-moment ratio][lmo.l_ratio] estimate. Notes: - This function is not vectorized. + This function is *not* vectorized, and can only be used for a single + L-moment order `r`. + However, the returned (empirical influence) function *is* vectorized. Args: a: 1-D array-like containing observed samples. @@ -1207,8 +1225,9 @@ def l_ratio_influence( non-negative int or float. Other parameters: - sort ('quicksort' | 'heapsort' | 'stable'): + sort (True | False | 'quicksort' | 'heapsort' | 'stable'): Sorting algorithm, see [`numpy.sort`][numpy.sort]. + Set to `False` if the array is already sorted. tol: Zero-roundoff absolute threshold. Returns: diff --git a/lmo/_utils.py b/lmo/_utils.py index e28ae2d8..43879c3e 100644 --- a/lmo/_utils.py +++ b/lmo/_utils.py @@ -40,6 +40,7 @@ _SCT_f = TypeVar('_SCT_f', bound='lnpt.Float', default=np.float64) _DT_f = TypeVar('_DT_f', bound=np.dtype['lnpt.Float']) +_AT_f = TypeVar('_AT_f', bound='npt.NDArray[lnpt.Float] | lnpt.Float') _SizeT = TypeVar('_SizeT', bound=int) @@ -89,20 +90,31 @@ def plotting_positions( return np.linspace(x0 / xn, (x0 + n - 1) / xn, n, dtype=np.float64) +@overload +def round0(a: _AT_f, /, tol: float | None = ...) -> _AT_f: ... +@overload def round0( a: onpt.CanArray[_ShapeT, _DT_f], /, + tol: float | None = ..., +) -> np.ndarray[_ShapeT, _DT_f]: ... +@overload +def round0(a: float, /, tol: float | None = ...) -> np.float64: ... +def round0( + a: float | onpt.CanArray[_ShapeT, np.dtype[_SCT_f]], + /, tol: float | None = None, -) -> np.ndarray[_ShapeT, _DT_f]: +) -> onpt.Array[_ShapeT, _SCT_f] | _SCT_f: """ Replace all values `<= tol` with `0`. Todo: - Add an `inplace: bool = False` kwarg """ - _a = np.asarray(a) + _a = np.asanyarray(a) _tol = np.finfo(_a.dtype).resolution * 2 if tol is None else abs(tol) - return cast(np.ndarray[_ShapeT, _DT_f], np.where(np.abs(a) <= _tol, 0, a)) + out = np.where(np.abs(_a) <= _tol, 0, a) + return out[()] if np.isscalar(a) else out def _apply_aweights( @@ -337,7 +349,10 @@ def moments_to_ratio( the L-moment ratio's. """ assert len(rs) == 2 - assert rs.shape[:l_rs.ndim] == l_rs.shape[:rs.ndim], [rs.shape, l_rs.shape] + assert rs.shape[: l_rs.ndim] == l_rs.shape[: rs.ndim], [ + rs.shape, + l_rs.shape, + ] r_eq_s = rs[0] == rs[1] if r_eq_s.ndim < l_rs.ndim - 1: @@ -361,7 +376,7 @@ def moments_to_stats_cov( # t_0r[1] isn't used, and can be set to anything # ll_kr is the L-moment cov of size R**2 (orders start at 1 here) assert len(t_0r) > 0 - assert (len(t_0r) - 1)**2 == ll_kr.size + assert (len(t_0r) - 1) ** 2 == ll_kr.size t_0, t_r = t_0r[0], t_0r[1:] tt_kr = np.empty_like(ll_kr) From 6cc3fb2a52cc985b55693695fa9bbc06b404f083 Mon Sep 17 00:00:00 2001 From: jorenham Date: Sat, 24 Aug 2024 10:33:43 +0200 Subject: [PATCH 4/8] l-comoment docstring fixes --- lmo/_lm_co.py | 21 ++------------------- lmo/typing/np.py | 2 +- 2 files changed, 3 insertions(+), 20 deletions(-) diff --git a/lmo/_lm_co.py b/lmo/_lm_co.py index 5d4f6873..6d1ba6e3 100644 --- a/lmo/_lm_co.py +++ b/lmo/_lm_co.py @@ -94,24 +94,6 @@ def l_comoment( trim: Left- and right-trim orders $(s, t)$, non-negative ints or floats that are bound by $s + t < n - r$. - - Some special cases include: - - - $(0, 0)$: The original **L**-moment, introduced by Hosking - (1990). Useful for fitting the e.g. log-normal and generalized - extreme value (GEV) distributions. - - $(0, m)$: **LL**-moment (**L**inear combination of **L**owest - order statistics), introduced by Bayazit & Onoz (2002). - Assigns more weight to smaller observations. - - $(s, 0)$: **LH**-moment (**L**inear combination of **H**igher - order statistics), by Wang (1997). - Assigns more weight to larger observations. - - $(t, t)$: **TL**-moment (**T**rimmed L-moment) $\\lambda_r^t$, - with symmetric trimming. First introduced by - Elamir & Seheult (2003). - Generally more robust than L-moments. - Useful for fitting heavy-tailed distributions, such as the - Cauchy distribution. rowvar: If `True`, then each row (axis 0) represents a variable, with observations in the columns (axis 1). @@ -252,7 +234,7 @@ def l_costats( ) -> _Array3D[Literal[4], Any, Any, _T_float]: """ Calculates the L-*co*scale, L-corr(elation), L-*co*skew(ness) and - L-*co*kurtosis. + L-*co*kurt(osis). Equivalent to `lmo.l_coratio(a, [2, 2, 3, 4], [0, 2, 2, 2], *, **)`. @@ -436,3 +418,4 @@ def l_cokurtosis( l_cokurt = l_cokurtosis +"""Alias for [`lmo.l_cokurtosis`][lmo.l_cokurtosis].""" diff --git a/lmo/typing/np.py b/lmo/typing/np.py index e132f19a..b45dbeaf 100644 --- a/lmo/typing/np.py +++ b/lmo/typing/np.py @@ -114,7 +114,7 @@ OrderCopy: TypeAlias = Literal[OrderReshape, 'K'] """Type of the `order` parameter of e.g. [`np.array`][numpy.array].""" -SortKind: TypeAlias = Literal['quicksort', 'heapsort', 'stable'] +SortKind: TypeAlias = Literal['quicksort', 'heapsort', 'stablesort'] """ Type of the `kind` parameter of e.g. [`np.sort`][numpy.sort], as allowed by numpy's own stubs. From 6feac078ce36973feb940bc91ad0db9fc387f414 Mon Sep 17 00:00:00 2001 From: jorenham Date: Sat, 24 Aug 2024 10:36:14 +0200 Subject: [PATCH 5/8] significantly improved reference docs --- .markdownlint.yaml | 2 + docs/api.md | 104 ------------------------------- docs/api/L-comoments.md | 27 ++++++++ docs/api/L-moments.md | 128 ++++++++++++++++++++++++++++++++++++++ docs/api/diagnostic.md | 5 ++ docs/api/distributions.md | 20 ++++++ docs/api/low_level.md | 40 ++++++++++++ docs/api/pandas.md | 14 +++++ mkdocs.yml | 35 ++++++++--- 9 files changed, 264 insertions(+), 111 deletions(-) delete mode 100644 docs/api.md create mode 100644 docs/api/L-comoments.md create mode 100644 docs/api/L-moments.md create mode 100644 docs/api/diagnostic.md create mode 100644 docs/api/distributions.md create mode 100644 docs/api/low_level.md create mode 100644 docs/api/pandas.md diff --git a/.markdownlint.yaml b/.markdownlint.yaml index a186b89d..6934db58 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -10,4 +10,6 @@ MD033: - "th" - "td" - "img" + - "sup" + - "sub" MD041: false diff --git a/docs/api.md b/docs/api.md deleted file mode 100644 index ed466535..00000000 --- a/docs/api.md +++ /dev/null @@ -1,104 +0,0 @@ -# Lmo reference - -## High-level API - -### Sample L-moments - -::: lmo - options: - filters: - - "!l_weights" - - "!^l_co" - - "!^l_rv" - heading_level: 4 - -### Sample L-comoments - -::: lmo - options: - filters: ["^l_co"] - heading_level: 4 - -### Distributions - -::: lmo.distributions - options: - heading_level: 4 - -### Statistical test and tools - -::: lmo.diagnostic - options: - heading_level: 4 - -## Third party integration - -### `scipy.stats` - -::: lmo.contrib.scipy_stats - options: - show_bases: false - members: - - l_rv_generic - heading_level: 4 - -### `pandas` (optional) - -::: lmo.contrib.pandas - options: - show_bases: false - members: - - Series - - DataFrame - heading_level: 4 - -## Low-level API - -::: lmo - options: - members: - - l_weights - heading_level: 3 - -### `constants` - -::: lmo.constants - options: - heading_level: 4 - -### `inference` - -::: lmo.inference - options: - heading_level: 4 - -### `linalg` - -::: lmo.linalg - options: - heading_level: 4 - show_root_full_path: true - -### `ostats` - -::: lmo.ostats - options: - heading_level: 4 - -### `pwm_beta` - -::: lmo.pwm_beta - options: - heading_level: 4 - -### `special` - -::: lmo.special - options: - heading_level: 4 - -### `theoretical` - -::: lmo.theoretical - options: - heading_level: 4 diff --git a/docs/api/L-comoments.md b/docs/api/L-comoments.md new file mode 100644 index 00000000..30670f3c --- /dev/null +++ b/docs/api/L-comoments.md @@ -0,0 +1,27 @@ +# Sample L-comoments + +Unbiased sample estimators of *L-comoment matrices* [@serfling2007] and +*generalized trimmed L-comoment matrices* [unpublished work by +[@jorenham](https://github.com/jorenham)]. + +## L-comoment matrix estimators + + + + +::: lmo.l_comoment +::: lmo.l_coratio +::: lmo.l_costats + +## Shorthand aliases + +::: lmo.l_coloc +::: lmo.l_coscale +::: lmo.l_corr +::: lmo.l_coskew +::: lmo.l_cokurt +::: lmo.l_cokurtosis + +## References + +\bibliography diff --git a/docs/api/L-moments.md b/docs/api/L-moments.md new file mode 100644 index 00000000..a4d0e977 --- /dev/null +++ b/docs/api/L-moments.md @@ -0,0 +1,128 @@ +# Sample L-moments + +Estimation of (trimmed) L-moments from sample data. + + +## L-moment Estimators + +Unbiased sample estimators of the L-moments and the (generalized) trimmed +L-moments. + +::: lmo.l_moment +::: lmo.l_ratio +::: lmo.l_stats + +### Shorthand aliases + +Some of the commonly used L-moment and L-moment ratio's have specific names, +analogous to the named raw-, central-, and standard product-moments: + +| | | | +|---|---|---| +| $\lambda_r / \lambda_s$ | $s = 0$ | $r = 2$ | +| $r=1$ | $\lambda_1$ -- "L-loc[ation]" | $\tau$ -- "L-variation" or "L-CV" | +| $r=2$ | $\lambda_2$ -- "L-scale" | ~~$1$ -- "L-one" or "L-unit"~~ | +| $r=3$ | $\lambda_3$ | $\tau_3$ -- "L-skew[ness]" | +| $r=4$ | $\lambda_4$ | $\tau_4$ -- "L-kurt[osis]" | + +/// note +The "L-" prefix often refers to untrimmed L-moments, i.e. $(s, t) = (0, 0)$. + +For some of the trimmed L-moments trim-lengths, specific alternative prefixes +are used: + +| | | | +|---|---|---| +| $\lambda_r^{(s, t)}$ | $t = 0$ | $t = 1$ | +| $s = 0$ | L-moment | LL-moment | +| $s = 1$ | LH-moment | TL-moment | + +The "L-" prefix refers to "Linear", i.e. an L-moment is a +"Linear combination of order statistics" [@hosking1990]. +Usually "TL-moments" are used to describe symmetrically *T*rimmed L-moments, +in most cases those with a trim-length of 1 [@elamir2003, @hosking2007]. +Similarly, "LH-moments" describe "linear combinations of order of *higher*-order +statistics" [@wang1997], and "LL-moments" that of "... the lowest order +statistics" [@bayazit2002]. + +Lmo supports all possible trim-lengths. +Technically, these are the "generalized trimmed L-moments". +But for the sake of brevity Lmo abbreviates this "L-moments". +/// + +::: lmo.l_loc + options: + heading_level: 4 +::: lmo.l_scale + options: + heading_level: 4 +::: lmo.l_variation + options: + heading_level: 4 +::: lmo.l_skew + options: + heading_level: 4 +::: lmo.l_kurt + options: + heading_level: 4 +::: lmo.l_kurtosis + options: + heading_level: 4 + +## L-moment Accuracy + + + +::: lmo.l_moment_cov +::: lmo.l_ratio_se +::: lmo.l_stats_se + +## Sensitivity & Robustness + +[Wikipedia](https://w.wiki/Azf$#Empirical_influence_function) describes the +*empirical influence function (EIF)* as follows: + +> The empirical influence function is a measure of the dependence of the +> estimator on the value of any one of the points in the sample. +> It is a model-free measure in the sense that it simply relies on calculating +> the estimator again with a different sample. + + +/// tip +The EIF can be used to calculate some useful +[properties](https://w.wiki/Azf$#Desirable_properties) related to the +robustness of the estimate. + +- [`lmo.diagnostic.rejection_point`][lmo.diagnostic.rejection_point] +- [`lmo.diagnostic.error_sensitivity`][lmo.diagnostic.error_sensitivity] +- [`lmo.diagnostic.shift_sensitivity`][lmo.diagnostic.shift_sensitivity] + +/// + + + +::: lmo.l_moment_influence +::: lmo.l_ratio_influence + +## L-moment sample weights + + + +::: lmo.l_weights + +## References + +\bibliography diff --git a/docs/api/diagnostic.md b/docs/api/diagnostic.md new file mode 100644 index 00000000..5e86a59b --- /dev/null +++ b/docs/api/diagnostic.md @@ -0,0 +1,5 @@ +# Statistical test and tools + +::: lmo.diagnostic + options: + heading_level: 2 diff --git a/docs/api/distributions.md b/docs/api/distributions.md new file mode 100644 index 00000000..ed521a41 --- /dev/null +++ b/docs/api/distributions.md @@ -0,0 +1,20 @@ +# Probability Distributions + + + +::: lmo.distributions + options: + heading_level: 2 + +## `scipy.stats` integration + + + + +::: lmo.contrib.scipy_stats + options: + heading_level: 3 + show_root_heading: false + show_root_toc_entry: false + members: + - l_rv_generic diff --git a/docs/api/low_level.md b/docs/api/low_level.md new file mode 100644 index 00000000..768b44f1 --- /dev/null +++ b/docs/api/low_level.md @@ -0,0 +1,40 @@ +# Low-level API + +::: lmo.constants + options: + heading_level: 2 + show_symbol_type_toc: true + +::: lmo.linalg + options: + heading_level: 2 + show_symbol_type_toc: true + +::: lmo.special + options: + heading_level: 2 + show_symbol_type_toc: true + +::: lmo.theoretical + options: + heading_level: 2 + show_symbol_type_toc: true + +::: lmo.inference + options: + heading_level: 2 + group_by_category: false + show_symbol_type_toc: true + members: + - fit + - GMMResult + + diff --git a/docs/api/pandas.md b/docs/api/pandas.md new file mode 100644 index 00000000..d14c1fde --- /dev/null +++ b/docs/api/pandas.md @@ -0,0 +1,14 @@ +# Optional `pandas` integration + + + + +::: lmo.contrib.pandas + options: + heading_level: 4 + show_root_heading: false + show_root_toc_entry: false + show_bases: false + members: + - Series + - DataFrame --> diff --git a/mkdocs.yml b/mkdocs.yml index e870ea13..91ce9a19 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -12,8 +12,15 @@ nav: - Overview: index.md - "Examples": - Fitting the GEV: examples/lmm.ipynb - - Reference: api.md - - Distributions: distributions.md + - "Reference": + - api/L-moments.md + - api/L-comoments.md + - api/distributions.md + - api/diagnostic.md + - api/pandas.md + - api/low_level.md + - "Theory": + - Distributions: distributions.md - Contributing: contributing.md theme: @@ -24,12 +31,15 @@ theme: - content.tabs.link - content.tooltips - navigation.path + - navigation.indexes + - navigation.prune + - navigation.sections - navigation.tabs - navigation.tabs.sticky - navigation.top - navigation.tracking - toc.follow - - toc.integrate + # - toc.integrate font: text: Fira Sans code: Fira Mono @@ -60,6 +70,7 @@ plugins: - git-revision-date-localized: type: iso_date exclude: ["*.ipynb"] + strict: false # https://github.com/mondeja/mkdocs-include-markdown-plugin - include-markdown @@ -98,19 +109,28 @@ plugins: - url: https://docs.scipy.org/doc/scipy/objects.inv - url: https://pandas.pydata.org/docs/objects.inv options: - annotations_path: source - docstring_section_style: spacy + heading_level: 3 + annotations_path: brief + unwrap_annotated: true + docstring_section_style: table line_length: 79 load_external_modules: true members_order: source merge_init_into_class: true show_bases: true + show_root_heading: true show_root_full_path: true + show_root_toc_entry: true show_root_members_full_path: true - show_root_toc_entry: false + show_symbol_type_heading: true + show_symbol_type_toc: false show_source: false show_submodules: false - signature_crossrefs: true + show_docstring_attributes: false + signature_crossrefs: false + docstring_options: + ignore_init_summary: true + trim_doctest_flags: true # https://squidfunk.github.io/mkdocs-material/plugins/search/ - search @@ -152,6 +172,7 @@ markdown_extensions: case: lower - pymdownx.tasklist: custom_checkbox: true + - pymdownx.tilde extra_css: - https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css From 7f518585cd693eb15825a01bee80568493727547 Mon Sep 17 00:00:00 2001 From: jorenham Date: Sat, 24 Aug 2024 10:41:15 +0200 Subject: [PATCH 6/8] fix distribution crossrefs --- lmo/distributions/__init__.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/lmo/distributions/__init__.py b/lmo/distributions/__init__.py index 02377107..77e85506 100644 --- a/lmo/distributions/__init__.py +++ b/lmo/distributions/__init__.py @@ -28,7 +28,7 @@ [`wakeby`][wakeby] takes \( b \), \( d \) and \( f \) as shape parameters. For a detailed description of the Wakeby distribution, refer to -[Distributions - Wakeby](distributions.md#wakeby). +[Distributions - Wakeby](../distributions.md#wakeby). """ @@ -52,7 +52,7 @@ [`kumaraswamy`][kumaraswamy] takes \( a \) and \( b \) as shape parameters. See Also: - - [Theoretical L-moments - Kumaraswamy](distributions.md#kumaraswamy) + - [Theoretical L-moments - Kumaraswamy](../distributions.md#kumaraswamy) """ @@ -70,5 +70,5 @@ shape parameter. For a detailed description of the GLD, refer to -[Distributions - GLD](distributions.md#gld). +[Distributions - GLD](../distributions.md#gld). """ From 4fc6282d8b11deef568406da4a20a6fa2274cd68 Mon Sep 17 00:00:00 2001 From: jorenham Date: Sat, 24 Aug 2024 10:43:43 +0200 Subject: [PATCH 7/8] fix typing errors --- lmo/typing/np.py | 48 +++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 39 insertions(+), 9 deletions(-) diff --git a/lmo/typing/np.py b/lmo/typing/np.py index b45dbeaf..f4395ac0 100644 --- a/lmo/typing/np.py +++ b/lmo/typing/np.py @@ -10,14 +10,37 @@ __all__ = ( - 'Bool', 'Int', 'Float', 'Number', 'Natural', 'Integer', 'Real', - 'AnyScalar', 'AnyScalarBool', 'AnyScalarInt', 'AnyScalarFloat', - 'AnyVector', 'AnyVectorBool', 'AnyVectorFloat', 'AnyVectorFloat', - 'AnyMatrix', 'AnyMatrixBool', 'AnyMatrixInt', 'AnyMatrixFloat', - 'AnyTensor', 'AnyTensorBool', 'AnyTensorInt', 'AnyTensorFloat', - 'AnyArray', 'AnyArrayBool', 'AnyArrayInt', 'AnyArrayFloat', + 'Bool', + 'Int', + 'Float', + 'Number', + 'Natural', + 'Integer', + 'Real', + 'AnyScalar', + 'AnyScalarBool', + 'AnyScalarInt', + 'AnyScalarFloat', + 'AnyVector', + 'AnyVectorBool', + 'AnyVectorFloat', + 'AnyVectorFloat', + 'AnyMatrix', + 'AnyMatrixBool', + 'AnyMatrixInt', + 'AnyMatrixFloat', + 'AnyTensor', + 'AnyTensorBool', + 'AnyTensorInt', + 'AnyTensorFloat', + 'AnyArray', + 'AnyArrayBool', + 'AnyArrayInt', + 'AnyArrayFloat', 'SortKind', - 'Order', 'OrderReshape', 'OrderCopy', + 'Order', + 'OrderReshape', + 'OrderCopy', 'RandomState', 'Casting', ) @@ -114,7 +137,14 @@ OrderCopy: TypeAlias = Literal[OrderReshape, 'K'] """Type of the `order` parameter of e.g. [`np.array`][numpy.array].""" -SortKind: TypeAlias = Literal['quicksort', 'heapsort', 'stablesort'] +SortKind: TypeAlias = Literal[ + 'quick', + 'quicksort', + 'stable', + 'stablesort', + 'heap', + 'heapsort', +] """ Type of the `kind` parameter of e.g. [`np.sort`][numpy.sort], as allowed by numpy's own stubs. @@ -136,7 +166,7 @@ | np.random.SeedSequence | np.random.BitGenerator | np.random.Generator -) +) # fmt: skip """ Any acceptable "seed" type that can be passed to [`numpy.random.default_rng`][numpy.random.default_rng]. From 2c1f76857c70b5ab2a691d4eb3904c753ef27276 Mon Sep 17 00:00:00 2001 From: jorenham Date: Sat, 24 Aug 2024 10:44:46 +0200 Subject: [PATCH 8/8] `sort` parameter docstring simplificiations --- lmo/_lm.py | 6 +++--- lmo/_lm_co.py | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/lmo/_lm.py b/lmo/_lm.py index b41a5dc6..3b2c1a1e 100644 --- a/lmo/_lm.py +++ b/lmo/_lm.py @@ -360,7 +360,7 @@ def l_moment( All `aweights` must be `>=0`, and the sum must be nonzero. The algorithm is similar to that for weighted quantiles. - sort (True | False | 'quicksort' | 'heapsort' | 'stable'): + sort (True | False | 'quick' | 'heap' | 'stable'): Sorting algorithm, see [`numpy.sort`][numpy.sort]. Set to `False` if the array is already sorted. cache: @@ -1142,7 +1142,7 @@ def l_moment_influence( non-negative int (or float). Other parameters: - sort (True | False | 'quicksort' | 'heapsort' | 'stable'): + sort (True | False | 'quick' | 'heap' | 'stable'): Sorting algorithm, see [`numpy.sort`][numpy.sort]. Set to `False` if the array is already sorted. tol: Zero-roundoff absolute threshold. @@ -1225,7 +1225,7 @@ def l_ratio_influence( non-negative int or float. Other parameters: - sort (True | False | 'quicksort' | 'heapsort' | 'stable'): + sort (True | False | 'quick' | 'heap' | 'stable'): Sorting algorithm, see [`numpy.sort`][numpy.sort]. Set to `False` if the array is already sorted. tol: Zero-roundoff absolute threshold. diff --git a/lmo/_lm_co.py b/lmo/_lm_co.py index 6d1ba6e3..d3a7c821 100644 --- a/lmo/_lm_co.py +++ b/lmo/_lm_co.py @@ -104,7 +104,7 @@ def l_comoment( Floating type to use in computing the L-moments. Default is [`numpy.float64`][numpy.float64]. - sort ('quicksort' | 'heapsort' | 'stable'): + sort ('quick' | 'heap' | 'stable'): Sorting algorithm, see [`numpy.sort`][numpy.sort]. cache: Set to `True` to speed up future L-moment calculations that have