[DOC] MkDocs Math (#901)

* [INF] simplify a bit linting, use pre-commit as CI linting checker (#892)

* [INF] simplify a bit linting

There is two similar linting CIs (pre-commit and code-checks) but also have tiny differences.

We should use one of them as the standard, not both.

* Update CHANGELOG.md

* should be `--config` not `-c`

`-c` = `--code TEXT`, Format the code passed in as a string.

* remove nbstripout

keep the same with the old code-checks.yml

* lint via pre-commit

* Update CHANGELOG.md

Co-authored-by: Eric Ma <[email protected]>

* [DOC] mkdocs updates to log() in math

* [DOC] mkdocs updates to ecdf() in math

* [DOC] mkdocs updates to exp() in math

* [DOC] mkdocs updates to logit() in math

* [DOC] mkdocs updates to normal_cdf() in math

* [DOC] mkdocs updates to probit() in math

* [DOC] mkdocs updates to single line docstrings in math

* [DOC] mkdocs updates to z_score() in math

Co-authored-by: Zero <[email protected]>
Co-authored-by: Eric Ma <[email protected]>

Author: 3 people

janitor/math.py

@@ -14,18 +14,16 @@
 @pf.register_series_method
 def log(s: pd.Series, error: str = "warn") -> pd.Series:
     """
-    Take natural logarithm of the Series
+    Take natural logarithm of the Series.
 
-    :param s: Input Series
+    :param s: Input Series.
     :param error: Determines behavior when taking the log of nonpositive
-        entries. If "warn" then a RuntimeWarning is thrown. If "raise",
-        then a RuntimeError is thrown. Otherwise, nothing is thrown and
-        log of nonpositive values is np.nan; defaults to "warn"
+        entries. If `'warn'` then a `RuntimeWarning` is thrown. If `'raise'`,
+        then a `RuntimeError` is thrown. Otherwise, nothing is thrown and
+        log of nonpositive values is `np.nan`; defaults to `'warn'`.
     :raises RuntimeError: Raised when there are nonpositive values in the
-        Series and error="raise"
-    :return: Transformed Series
-
-    .. # noqa: DAR103 error
+        Series and `error='raise'`.
+    :return: Transformed Series.
     """
     s = s.copy()
     nonpositive = s <= 0
@@ -43,37 +41,46 @@ def log(s: pd.Series, error: str = "warn") -> pd.Series:
 
 @pf.register_series_method
 def exp(s: pd.Series) -> pd.Series:
-    """Take the exponential transform of the series"""
+    """
+    Take the exponential transform of the series.
+
+    :param s: Input Series.
+    :return: Transformed Series.
+    """
     return np.exp(s)
 
 
 @pf.register_series_method
 def sigmoid(s: pd.Series) -> pd.Series:
     """
-    Take the sigmoid transform of the series where
+    Take the sigmoid transform of the series where:
+
+    ```python
     sigmoid(x) = 1 / (1 + exp(-x))
+    ```
 
-    .. # noqa: DAR101
-    .. # noqa: DAR201
+    :param s: Input Series.
+    :return: Transformed Series.
     """
     return expit(s)
 
 
 @pf.register_series_method
 def logit(s: pd.Series, error: str = "warn") -> pd.Series:
     """
-    Take logit transform of the Series
-    where logit(p) = log(p/(1-p))
-
-    :param s: Input Series
-    :param error: Determines behavior when s / (1-s) is outside of (0, 1). If
-        "warn" then a RuntimeWarning is thrown. If "raise", then a RuntimeError
-        is thrown. Otherwise, nothing is thrown and np.nan is returned
-        for the problematic entries, defaults to "warn"
-    :return: Transformed Series
-    :raises RuntimeError: if `error` is set to `raise``.
-
-    .. # noqa: DAR103 error
+    Take logit transform of the Series where:
+
+    ```python
+    logit(p) = log(p/(1-p))
+    ```
+
+    :param s: Input Series.
+    :param error: Determines behavior when `s / (1-s)` is outside of `(0, 1)`.
+        If `'warn'` then a `RuntimeWarning` is thrown. If `'raise'`, then a
+        `RuntimeError` is thrown. Otherwise, nothing is thrown and `np.nan`
+        is returned for the problematic entries; defaults to `'warn'`.
+    :return: Transformed Series.
+    :raises RuntimeError: if `error` is set to `'raise'`.
     """
     s = s.copy()
     odds_ratio = s / (1 - s)
@@ -93,25 +100,28 @@ def logit(s: pd.Series, error: str = "warn") -> pd.Series:
 
 @pf.register_series_method
 def normal_cdf(s: pd.Series) -> pd.Series:
-    """Transforms the Series via the CDF of the Normal distribution"""
+    """
+    Transforms the Series via the CDF of the Normal distribution.
+
+    :param s: Input Series.
+    :return: Transformed Series.
+    """
     return pd.Series(norm.cdf(s), index=s.index)
 
 
 @pf.register_series_method
 def probit(s: pd.Series, error: str = "warn") -> pd.Series:
     """
-    Transforms the Series via the inverse CDF of the Normal distribution
+    Transforms the Series via the inverse CDF of the Normal distribution.
 
-    :param s: Input Series
-    :param error: Determines behavior when s is outside of (0, 1). If
-        "warn" then a RuntimeWarning is thrown. If "raise", then a RuntimeError
-        is thrown. Otherwise, nothing is thrown and np.nan is returned
-        for the problematic entries, defaults to "warn"
+    :param s: Input Series.
+    :param error: Determines behavior when `s` is outside of `(0, 1)`.
+        If `'warn'` then a `RuntimeWarning` is thrown. If `'raise'`, then
+        a `RuntimeError` is thrown. Otherwise, nothing is thrown and `np.nan`
+        is returned for the problematic entries; defaults to `'warn'`.
     :raises RuntimeError: Raised when there are problematic values
-        in the Series and error="raise"
+        in the Series and `error='raise'`.
     :return: Transformed Series
-
-    .. # noqa: DAR103 error
     """
     s = s.copy()
     outside_support = (s <= 0) | (s >= 1)
@@ -136,18 +146,20 @@ def z_score(
     keys: Tuple[str, str] = ("mean", "std"),
 ) -> pd.Series:
     """
-    Transforms the Series into z-scores
+    Transforms the Series into z-scores where:
 
-    :param s: Input Series
-    :param moments_dict: If not None, then the mean and standard
-        deviation used to compute the z-score transformation is
-        saved as entries in moments_dict with keys determined by
-        the keys argument, defaults to None
-    :param keys: Determines the keys saved in moments_dict
-        if moments are saved, defaults to ("mean", "std")
-    :return: Transformed Series
+    ```python
+    z = (s - s.mean()) / s.std()
+    ```
 
-    .. # noqa: DAR103 moments_dict
+    :param s: Input Series.
+    :param moments_dict: If not `None`, then the mean and standard
+        deviation used to compute the z-score transformation is
+        saved as entries in `moments_dict` with keys determined by
+        the `keys` argument; defaults to `None`.
+    :param keys: Determines the keys saved in `moments_dict`
+        if moments are saved; defaults to (`'mean'`, `'std'`).
+    :return: Transformed Series.
     """
     mean = s.mean()
     std = s.std()
@@ -166,26 +178,26 @@ def ecdf(s: pd.Series) -> Tuple[np.ndarray, np.ndarray]:
 
     Intended to be used with the following pattern:
 
-    .. code-block:: python
-
-        df = pd.DataFrame(...)
+    ```python
+    df = pd.DataFrame(...)
 
-        # Obtain ECDF values to be plotted
-        x, y = df["column_name"].ecdf()
+    # Obtain ECDF values to be plotted
+    x, y = df["column_name"].ecdf()
 
-        # Plot ECDF values
-        plt.scatter(x, y)
+    # Plot ECDF values
+    plt.scatter(x, y)
+    ```
 
     Null values must be dropped from the series,
     otherwise a `ValueError` is raised.
 
-    Also, if the dtype of the series is not numeric,
-    a TypeError is raised.
+    Also, if the `dtype` of the series is not numeric,
+    a `TypeError` is raised.
 
-    :param s: A pandas series. dtype should be numeric.
-    :returns: (x, y).
-        x: sorted array of values.
-        y: cumulative fraction of data points with value `x` or lower.
+    :param s: A pandas series. `dtype` should be numeric.
+    :returns: `(x, y)`.
+        `x`: sorted array of values.
+        `y`: cumulative fraction of data points with value `x` or lower.
     :raises TypeError: if series is not numeric.
     :raises ValueError: if series contains nulls.
     """