onekit 3.0.0__tar.gz → 3.1.0__tar.gz

{onekit-3.0.0 → onekit-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: onekit
-Version: 3.0.0
+Version: 3.1.0
 Summary: All-in-One Python Kit.
 License: BSD 3-Clause
 Keywords: onekit

{onekit-3.0.0 → onekit-3.1.0}/pyproject.toml

@@ -22,7 +22,7 @@ requires-python = ">=3.11"
 dependencies = []
 
 [tool.poetry]
-version = "3.0.0"
+version = "3.1.0"
 
 [project.optional-dependencies]
 base = [
@@ -58,7 +58,7 @@ sphinx-copybutton = "^0.5.2"
 time-machine = "^2.16.0"
 
 [tool.poetry.group.packaging.dependencies]
-python-semantic-release = "^8.3.0"
+python-semantic-release = "8.3.0"
 
 [tool.black]
 line-length = 88

{onekit-3.0.0 → onekit-3.1.0}/src/onekit/numpykit.py

@@ -8,6 +8,7 @@ from onekit import mathkit as mk
 __all__ = (
     "check_random_state",
     "check_vector",
+    "create_boolean_array",
     "digitscale",
     "stderr",
 )
@@ -91,6 +92,25 @@ def check_vector(x: ArrayLike, /, *, n_min: int = 1, n_max: int = np.inf) -> Vec
     return x
 
 
+# noinspection PyTypeChecker
+def create_boolean_array(data: ArrayLike, pos_label: int | str) -> np.ndarray:
+    """Returns a boolean array indicating positions of pos_label in input data.
+
+    Examples
+    --------
+    >>> from onekit import numpykit as npk
+    >>> data = [0, 1, 2, 1, 0, 1]
+    >>> npk.create_boolean_array(data, pos_label=1)
+    array([False,  True, False,  True, False,  True])
+
+    >>> data = ["cat", "dog", "cat", "bird", "cat", "dog"]
+    >>> npk.create_boolean_array(data, pos_label="dog")
+    array([False,  True, False, False, False,  True])
+    """
+    data_array = np.asarray(data)
+    return data_array == pos_label
+
+
 def digitscale(x: ArrayLike, /, *, kind: str = "log") -> np.ndarray:
     """NumPy version of digitscale.
 

{onekit-3.0.0 → onekit-3.1.0}/src/onekit/pythonkit.py

@@ -273,8 +273,8 @@ def coinflip(bias: float, /, *, seed: Seed = None) -> bool:
     return rng.random() < bias
 
 
-def concat_strings(sep: str, /, *strings: str | Iterable[str]) -> str:
-    """Concatenate strings.
+def concat_strings(sep: str, /, *strings: str | None | Iterable[str | None]) -> str:
+    """Concatenate strings, excluding None values.
 
     Examples
     --------
@@ -296,7 +296,14 @@ def concat_strings(sep: str, /, *strings: str | Iterable[str]) -> str:
     >>> list(map(ws_concat, [["Hello", "World"], ["Hi", "there"]]))
     ['Hello World', 'Hi there']
     """
-    return sep.join(toolz.pipe(strings, flatten, curried.map(str)))
+    return sep.join(
+        toolz.pipe(
+            strings,
+            flatten,
+            curried.filter(lambda x: x is not None),
+            curried.map(str),
+        )
+    )
 
 
 def contrast_sets(x: set, y: set, /, *, n: int = 3) -> dict:

onekit-3.1.0/src/onekit/scipykit.py

@@ -0,0 +1,126 @@
+import operator
+from typing import (
+    Iterable,
+    NamedTuple,
+)
+
+from scipy import (
+    optimize,
+    stats,
+)
+
+from onekit import numpykit as npk
+from onekit import pythonkit as pk
+
+__all__ = (
+    "BetaParams",
+    "compute_beta_posterior",
+)
+
+
+class BetaParams(NamedTuple):
+    """Represents the parameters of a Beta distribution."""
+
+    alpha: int | float = 1
+    beta: int | float = 1
+
+    @property
+    def mean(self) -> float:
+        """Compute the mean of the Beta distribution."""
+        return self.alpha / (self.alpha + self.beta)
+
+    @property
+    def mode(self) -> float | None:
+        """Compute the mode of the Beta distribution.
+
+        Note that the mode is undefined for alpha <= 1 or beta <= 1.
+        """
+        if self.alpha > 1 and self.beta > 1:
+            return (self.alpha - 1) / (self.alpha + self.beta - 2)
+
+    def hdi(self, hdi_prob: float = 0.95) -> tuple[float, float] | None:
+        """Compute the highest density interval (HDI) of the Beta distribution.
+
+        Note that the HDI is not computed for alpha <= 1 or beta <= 1.
+        """
+        if self.alpha > 1 and self.beta > 1:
+            beta_dist = stats.beta(self.alpha, self.beta)
+            tail_prob = 1 - hdi_prob
+
+            def interval_width(x: float) -> float:
+                return beta_dist.ppf(hdi_prob + x) - beta_dist.ppf(x)
+
+            hdi_tail_prob = operator.getitem(
+                optimize.fmin(interval_width, tail_prob, ftol=1e-12, disp=False),
+                0,
+            )
+            hdi_endpoints = beta_dist.ppf([hdi_tail_prob, hdi_prob + hdi_tail_prob])
+            return hdi_endpoints[0], hdi_endpoints[1]
+
+    def get_summary(self, hdi_prob: float = 0.95) -> str:
+        """Compute summary statistics of the Beta distribution."""
+        mode = self.mode
+        mode_info = f"mode={pk.num_to_str(mode)}" if mode is not None else None
+
+        hdi_info = None
+        hdi_endpoints = self.hdi(hdi_prob)
+        if hdi_endpoints is not None:
+            hdi_pct = pk.num_to_str(100 * hdi_prob)
+            hdi_lower_endpoint, hdi_upper_endpoint = map(pk.num_to_str, hdi_endpoints)
+            hdi_info = f"{hdi_pct}%-HDI=[{hdi_lower_endpoint}, {hdi_upper_endpoint}]"
+
+        return pk.concat_strings(
+            " ",
+            f"{self} ->",
+            f"mean={pk.num_to_str(self.mean)}",
+            mode_info,
+            hdi_info,
+        )
+
+
+def compute_beta_posterior(
+    data: Iterable[int | str],
+    prior: BetaParams | None = None,
+    pos_label: int | str = 1,
+) -> BetaParams:
+    """Update Beta prior with observed binomial data to compute posterior.
+
+    This function applies Bayesian inference to update the parameters of a Beta
+    distribution, given observed binomial data. The Beta distribution is commonly used
+    as a prior in binomial proportion estimation due to its conjugacy, simplifying the
+    calculation of the posterior.
+
+    Examples
+    --------
+    >>> from onekit import scipykit as sck
+    >>> from onekit.scipykit import BetaParams
+    >>> data = [1, 0, 1, 1, 0]
+    >>> posterior = sck.compute_beta_posterior(data)
+    >>> posterior.get_summary()
+    'BetaParams(alpha=4, beta=3) -> mean=0.571429 mode=0.6 95%-HDI=[0.238706, 0.895169]'
+
+    >>> data = ["head", "tail", "head", "head", "tail", "head", "head", "tail"]
+    >>> prior = BetaParams(alpha=2, beta=2)
+    >>> posterior = sck.compute_beta_posterior(data, prior, pos_label="head")
+    >>> posterior.get_summary()
+    'BetaParams(alpha=7, beta=5) -> mean=0.583333 mode=0.6 95%-HDI=[0.318232, 0.841428]'
+
+    >>> data = [1, 0, 1, 1, 0]
+    >>> prior = BetaParams(alpha=1, beta=1)
+    >>> posterior1 = sck.compute_beta_posterior(data, prior)
+    >>> posterior1.get_summary()
+    'BetaParams(alpha=4, beta=3) -> mean=0.571429 mode=0.6 95%-HDI=[0.238706, 0.895169]'
+    >>> more_data = [1, 0, 1, 0, 1]
+    >>> posterior2 = sck.compute_beta_posterior(more_data, prior=posterior1)
+    >>> posterior2.get_summary()
+    'BetaParams(alpha=7, beta=5) -> mean=0.583333 mode=0.6 95%-HDI=[0.318232, 0.841428]'
+    """
+    prior = prior or BetaParams()
+    y = npk.create_boolean_array(data, pos_label)
+    num_successes = y.sum()
+    num_trials = len(y)
+    posterior = BetaParams(
+        alpha=prior.alpha + num_successes,
+        beta=prior.beta + num_trials - num_successes,
+    )
+    return posterior

{onekit-3.0.0 → onekit-3.1.0}/src/onekit/vizkit.py

@@ -11,9 +11,13 @@ from matplotlib.axes import Axes
 from matplotlib.figure import Figure
 from mpl_toolkits.axes_grid1 import make_axes_locatable
 from mpl_toolkits.mplot3d.axes3d import Axes3D
+from scipy import (
+    stats,
+)
 
 from onekit import numpykit as npk
 from onekit import pythonkit as pk
+from onekit.scipykit import BetaParams
 
 ArrayLike = npt.ArrayLike
 
@@ -23,6 +27,7 @@ __all__ = (
     "create_xy_points",
     "create_xyz_points",
     "discrete_cmap",
+    "plot_beta_distribution",
     "plot_contour",
     "plot_digitscale",
     "plot_line",
@@ -432,6 +437,128 @@ def discrete_cmap(
     return [cmap(i) for i in np.linspace(lower_bound, upper_bound, num=n)]
 
 
+def plot_beta_distribution(
+    alpha: int | float,
+    beta: int | float,
+    hdi_prob: float = 0.95,
+    n_xvalues: int = 1001,
+    ax=None,
+) -> Axes:
+    """Plot Beta distribution with HDI.
+
+    See Also
+    --------
+    onekit.scipykit.BetaParams : Beta parameters
+
+    Examples
+    --------
+    >>> from onekit import vizkit as vk
+    >>> vk.plot_beta_distribution(alpha=2, beta=2)  # doctest: +SKIP
+    """
+    ax = ax or plt.gca()
+    beta_params = BetaParams(alpha, beta)
+
+    def beta_density(x: float) -> float:
+        return stats.beta.pdf(x, beta_params.alpha, beta_params.beta)
+
+    plotter = FunctionPlotter(
+        beta_density,
+        [(0, 1)],
+        n_xvalues=n_xvalues,
+        kws_plot=dict(zorder=1, alpha=0.7),
+    )
+
+    _, ax, _ = plotter.plot(ax=ax)
+    xy_points = getattr(plotter, "_xyz_pts")
+    x = xy_points.x
+    y = xy_points.y.ravel()
+
+    hdi_endpoints = beta_params.hdi(hdi_prob)
+    if hdi_endpoints is not None:
+        hdi_lower_endpoint, hdi_upper_endpoint = hdi_endpoints
+        ax.fill_between(
+            x,
+            y,
+            where=np.logical_and(x >= hdi_lower_endpoint, x <= hdi_upper_endpoint),
+            color="skyblue",
+            alpha=0.5,
+            zorder=0,
+        )
+
+        # add HDI endpoint labels
+        pad = 1.2
+        for endpoint in [hdi_lower_endpoint, hdi_upper_endpoint]:
+            density_of_endpoint = beta_density(endpoint)
+            ax.text(endpoint, pad * density_of_endpoint, f"{endpoint:.3f}", ha="center")
+            ax.plot(
+                [endpoint, endpoint],
+                [0, density_of_endpoint],
+                color="black",
+                linestyle="--",
+            )
+
+        # draw line segments
+        ax.plot(
+            [hdi_lower_endpoint, hdi_upper_endpoint],
+            [beta_density(hdi_lower_endpoint), beta_density(hdi_upper_endpoint)],
+            color="black",
+            linewidth=2,
+        )
+
+        # add HDI info
+        hdi_info = f"{pk.num_to_str(100 * hdi_prob)}% HDI"
+        hdi_mid_point = float(np.mean([hdi_lower_endpoint, hdi_upper_endpoint]))
+        ax.text(
+            hdi_mid_point,
+            1.25 * pad * beta_density(hdi_lower_endpoint),
+            hdi_info,
+            ha="center",
+            fontsize=12,
+        )
+
+        # Add mode to the legend
+        ax.scatter(
+            beta_params.mode,
+            0,
+            marker="v",
+            color="darkorange",
+            label=f"mode={pk.num_to_str(beta_params.mode)}",
+            alpha=0.6,
+        )
+    else:
+        ax.fill_between(
+            x,
+            y,
+            color="skyblue",
+            alpha=0.5,
+            zorder=0,
+        )
+
+    # Add mean to the legend
+    ax.scatter(
+        beta_params.mean,
+        0,
+        marker="v",
+        color="black",
+        label=f"mean={pk.num_to_str(beta_params.mean)}",
+        alpha=0.6,
+    )
+
+    ax.legend(
+        loc="best",
+        title=f"Beta(alpha={beta_params.alpha}, beta={beta_params.beta})",
+    )
+
+    ax.set_xlabel(r"$\theta$")
+    ax.set_ylabel(
+        r"$p(\theta \mid {}, {})$".format(beta_params.alpha, beta_params.beta)
+    )
+
+    ax.set_xticks(np.arange(0, 1.1, 0.1))
+
+    return ax
+
+
 def plot_contour(
     xyz_pts: XyzPoints,
     /,