lessPython 0.1.0__py3-none-any.whl

lessPy/plt_add.py

@@ -0,0 +1,129 @@
+# plt_add.py — analog of plt.add.R
+#
+# The add= annotation vocabulary shared by Chart(), X(), and
+# XY(): "v_line", "h_line", "line", "rect", "arrow", "point",
+# and any other string draws as text at (x1, y1). Style comes
+# from the add_ options (set_option): add_color (gray10),
+# add_fill (#D9D9D920), add_lwd (0.5), add_lty (solid),
+# add_size (1), add_trans (0) — each may be a list, recycled
+# per object as in R. One object with vector coordinates
+# repeats at every location; several objects consume one
+# coordinate per object, in order.
+
+import numpy as np
+import plotly.graph_objects as go
+
+from .plotly_utils import as_plotly_color, make_trans, to_hex
+from .utils import get_option
+
+_DASH = {"dashed": "dash", "dotted": "dot",
+         "dotdash": "dashdot", "longdash": "longdash",
+         "twodash": "longdashdot"}
+
+
+def _as_list(v):
+    if v is None:
+        return []
+    if isinstance(v, (list, tuple, np.ndarray)):
+        return list(v)
+    return [v]
+
+
+def plt_add(fig, add, x1=None, x2=None, y1=None, y2=None):
+    """Draw the add= annotation objects onto a built figure.
+    R analog: .plt.add()"""
+    add = _as_list(add)
+    x1v, x2v = _as_list(x1), _as_list(x2)
+    y1v, y2v = _as_list(y1), _as_list(y2)
+    n_obj = len(add)
+
+    colors = _as_list(get_option("add_color", "gray10"))
+    fills = _as_list(get_option("add_fill", "#D9D9D920"))
+    lwds = _as_list(get_option("add_lwd", 0.5))
+    ltys = _as_list(get_option("add_lty", "solid"))
+    sizes = _as_list(get_option("add_size", 1.0))
+    transs = _as_list(get_option("add_trans", 0.0))
+
+    idx = {"x1": 0, "x2": 0, "y1": 0, "y2": 0}
+
+    def locs(obj):
+        """Coordinate tuples for one object: all locations when
+        there is a single object, else the next one per vector."""
+        need_x = obj != "h_line"
+        need_y = obj != "v_line"
+        two = obj in ("line", "rect", "arrow")
+        if n_obj == 1:
+            n_loc = max(len(x1v) if need_x else 0,
+                        len(y1v) if need_y else 0, 1)
+            out = []
+            for k in range(n_loc):
+                out.append((
+                    x1v[k % len(x1v)] if need_x and x1v else None,
+                    y1v[k % len(y1v)] if need_y and y1v else None,
+                    x2v[k % len(x2v)] if two and x2v else None,
+                    y2v[k % len(y2v)] if two and y2v else None))
+            return out
+        vals = []
+        for name, vec, need in (("x1", x1v, need_x),
+                                ("y1", y1v, need_y),
+                                ("x2", x2v, two),
+                                ("y2", y2v, two)):
+            if need and vec:
+                vals.append(vec[idx[name] % len(vec)])
+                idx[name] += 1
+            else:
+                vals.append(None)
+        return [tuple(vals)]
+
+    for i, obj in enumerate(add):
+        col = to_hex(colors[i % len(colors)])
+        lwd = float(lwds[i % len(lwds)])
+        lty = str(ltys[i % len(ltys)])
+        cex = float(sizes[i % len(sizes)])
+        trn = float(transs[i % len(transs)])
+        fll = fills[i % len(fills)]
+        fill_c = (make_trans(fll, 1 - trn) if trn > 0
+                  else as_plotly_color(fll))
+        line = dict(color=col, width=max(0.5, lwd * 2))
+        if lty != "solid":
+            line["dash"] = _DASH.get(lty, lty)
+
+        for xx1, yy1, xx2, yy2 in locs(obj):
+            if obj == "v_line":
+                fig.add_shape(type="line", xref="x",
+                              yref="paper", x0=xx1, x1=xx1,
+                              y0=0, y1=1, line=line)
+            elif obj == "h_line":
+                fig.add_shape(type="line", xref="paper",
+                              yref="y", x0=0, x1=1,
+                              y0=yy1, y1=yy1, line=line)
+            elif obj == "line":
+                fig.add_shape(type="line", xref="x", yref="y",
+                              x0=xx1, y0=yy1, x1=xx2, y1=yy2,
+                              line=line)
+            elif obj == "rect":
+                fig.add_shape(type="rect", xref="x", yref="y",
+                              x0=xx1, y0=yy1, x1=xx2, y1=yy2,
+                              line=line, fillcolor=fill_c)
+            elif obj == "arrow":
+                fig.add_annotation(
+                    x=xx2, y=yy2, ax=xx1, ay=yy1,
+                    xref="x", yref="y", axref="x", ayref="y",
+                    showarrow=True, arrowhead=2,
+                    arrowcolor=col,
+                    arrowwidth=max(0.5, lwd * 2), text="")
+            elif obj == "point":
+                fig.add_trace(go.Scatter(
+                    x=[xx1], y=[yy1], mode="markers",
+                    marker=dict(symbol="circle",
+                                size=max(3, cex * 8),
+                                color=fill_c,
+                                line=dict(color=col, width=1)),
+                    hoverinfo="skip", showlegend=False))
+            else:                      # any other string: text
+                fig.add_annotation(
+                    x=xx1, y=yy1, text=str(obj),
+                    xref="x", yref="y", showarrow=False,
+                    font=dict(color=col,
+                              size=max(6, round(13 * cex))))
+    return fig

lessPy/plt_contour.py

@@ -0,0 +1,192 @@
+# plt_contour.py — analog of plt.contour.R
+#
+# form="contour" for XY(): filled contours of the 2-D kernel
+# density of <x, y>. The density grid ports MASS::kde2d() directly
+# (product normal kernel, bandwidth.nrd) so the contours match R.
+# Renderer conventions follow plt_plotly.py: the fit line and the
+# data ellipses arrive as prepared coordinates computed by XY().
+# Deviation: the fill ramp is fixed at the default-theme blues,
+# colorRampPalette(c("white", getColors("blues"))) — lessPy does
+# not port themes.
+
+import numpy as np
+import plotly.graph_objects as go
+from scipy import stats as sps
+
+from .plotly_utils import (
+    axis_format, axis_num, get_tick_fmt, plot_border,
+    plotly_style, to_hex)
+from .utils import get_option, pretty
+
+# getColors("blues") preceded by white: the filled-contour ramp
+# of the default lessR theme
+_RAMP = [
+    "#FFFFFF", "#CCECFF", "#B4D8FC", "#9DC5EB", "#84B2DB",
+    "#6B9FCC", "#4F8DBC", "#2D7CAE", "#006BA0", "#005B93",
+    "#004C8A", "#004087", "#0040A9",
+]
+_COLORSCALE = [[i / (len(_RAMP) - 1), c]
+               for i, c in enumerate(_RAMP)]
+
+
+def _bw_nrd(v):
+    """Normal reference bandwidth.
+    R analog: MASS::bandwidth.nrd()"""
+    q1, q3 = np.percentile(v, [25, 75])
+    return (4 * 1.06 * min(v.std(ddof=1), (q3 - q1) / 1.34)
+            * len(v) ** (-0.2))
+
+
+def _kde2d(x, y, n, lims, h=None):
+    """2-D product-normal kernel density on an n x n grid over
+    lims=(x_lo, x_hi, y_lo, y_hi). h: bandwidth pair on the
+    kde2d scale (kernel sd is h/4), default bandwidth.nrd per
+    axis. R analog: MASS::kde2d()"""
+    if h is None:
+        hx, hy = _bw_nrd(x) / 4, _bw_nrd(y) / 4
+    else:
+        hx, hy = h[0] / 4, h[1] / 4
+    if hx <= 0 or hy <= 0:
+        raise ValueError(
+            "cannot estimate the density: x or y has no spread")
+    gx = np.linspace(lims[0], lims[1], n)
+    gy = np.linspace(lims[2], lims[3], n)
+    ax = sps.norm.pdf((gx[:, None] - x[None, :]) / hx)
+    ay = sps.norm.pdf((gy[:, None] - y[None, :]) / hy)
+    z = ax @ ay.T / (len(x) * hx * hy)
+    return gx, gy, z                   # z[i, j] at (gx[i], gy[j])
+
+
+def plt_contour(xv, yv, contour_n, contour_nbins, contour_points,
+                pt_size, x_lab, y_lab, main, digits_d, ell95,
+                ellipses, ellipse_color, ellipse_lwd,
+                fit_lines, fit_color, fit_lwd, legend=False,
+                axis_fmt="K", axis_x_pre="", axis_y_pre=""):
+    """Filled-contour display of the joint density of x and y,
+    with optional data point, ellipse, and fit line overlays.
+    R analog: .plt.contour()"""
+
+    # KDE — extend grid beyond data so contours are not clipped
+    # at the data edges
+    x_ext = np.ptp(xv) * 0.12
+    y_ext = np.ptp(yv) * 0.12
+    gx, gy, z = _kde2d(xv, yv, contour_nbins,
+                       (xv.min() - x_ext, xv.max() + x_ext,
+                        yv.min() - y_ext, yv.max() + y_ext))
+
+    # 95% mass threshold, then contour-derived ranges
+    dz = z / z.sum()
+    zs = np.sort(dz.ravel())[::-1]
+    thr = zs[np.searchsorted(np.cumsum(zs), 0.95)]
+    mask = dz >= thr
+    x_in = gx[mask.any(axis=1)]
+    y_in = gy[mask.any(axis=0)]
+
+    # ellipse-derived ranges: the 95% data ellipse truncated to
+    # the data range
+    e_x, e_y = ell95
+    keep = ((e_x >= xv.min()) & (e_x <= xv.max())
+            & (e_y >= yv.min()) & (e_y <= yv.max()))
+    e_x, e_y = e_x[keep], e_y[keep]
+
+    # plot limits: when the kde grid covers the full data range,
+    # use the grid extent so contours are not clipped; otherwise
+    # the union of the data and truncated-ellipse ranges
+    def _lim(cont, data, ell, grid):
+        if cont[0] > data[0] or cont[1] < data[1]:
+            if len(ell) > 0:
+                return [min(data[0], ell.min()),
+                        max(data[1], ell.max())]
+            return list(data)
+        return list(grid)
+    x_lim = _lim((x_in.min(), x_in.max()), (xv.min(), xv.max()),
+                 e_x, (gx[0], gx[-1]))
+    y_lim = _lim((y_in.min(), y_in.max()), (yv.min(), yv.max()),
+                 e_y, (gy[0], gy[-1]))
+
+    if contour_points:                 # room for edge points
+        x_lim[1] += 0.015 * (x_lim[1] - x_lim[0])
+        y_lim[1] += 0.015 * (y_lim[1] - y_lim[0])
+
+    # ticks within the limits
+    axT1 = pretty(x_lim[0], x_lim[1])
+    axT2 = pretty(y_lim[0], y_lim[1])
+    fmt1 = get_tick_fmt(axT1, digits_d)
+    fmt2 = get_tick_fmt(axT2, digits_d)
+    axL1 = axis_format(axT1, digits_d, axis_fmt, axis_x_pre)
+    axL2 = axis_format(axT2, digits_d, axis_fmt, axis_y_pre)
+
+    style_opts = plotly_style()
+    fig = go.Figure()
+
+    # the filled contours: contour_n bands from min to max
+    # density; start at the first interior level so the region
+    # below it fills white, as in filled.contour()
+    lv0, lv1 = float(z.min()), float(z.max())
+    step = (lv1 - lv0) / contour_n
+    xpart = f"%{{x:{fmt1}}}" if fmt1 else "%{x}"
+    ypart = f"%{{y:{fmt2}}}" if fmt2 else "%{y}"
+    fig.add_trace(go.Contour(
+        x=gx, y=gy, z=z.T,
+        colorscale=_COLORSCALE,
+        contours=dict(start=lv0 + step, end=lv1, size=step),
+        line=dict(width=0),
+        showscale=bool(legend),
+        colorbar=dict(
+            tickfont=dict(
+                color=to_hex(get_option("axis_color", "black")),
+                size=16 * get_option("axis_size", 0.9)),
+            outlinewidth=0),
+        hovertemplate=(f"{x_lab}: {xpart}<br>{y_lab}: {ypart}"
+                       "<extra></extra>"),
+    ))
+
+    # R overlay style: translucent black fill, thin white border
+    if contour_points:
+        px = float(pt_size) * 7.25
+        if not np.isfinite(px) or px <= 0:
+            px = 5
+        fig.add_trace(go.Scatter(
+            x=xv, y=yv, mode="markers",
+            marker=dict(symbol="circle", size=px,
+                        sizemode="diameter",
+                        color="rgba(0,0,0,0.27)",
+                        line=dict(color="#FFFFFF", width=0.2)),
+            hoverinfo="skip", showlegend=False))
+
+    # data ellipses: line only on a contour (no fill, as in R)
+    for ex_l, ey_l in ellipses or []:
+        fig.add_trace(go.Scatter(
+            x=ex_l, y=ey_l, mode="lines",
+            line=dict(color=to_hex(ellipse_color),
+                      width=ellipse_lwd),
+            hoverinfo="skip", showlegend=False))
+
+    for fl in fit_lines or []:
+        if len(fl["x"]) < 2:
+            continue
+        fig.add_trace(go.Scatter(
+            x=fl["x"], y=fl["y"], mode="lines",
+            line=dict(color=to_hex(fit_color), width=fit_lwd),
+            hoverinfo="skip", showlegend=False))
+
+    ax_x = axis_num(x_lab, axT1, axL1)
+    ax_y = axis_num(y_lab, axT2, axL2)
+    ax_x["range"] = x_lim
+    ax_y["range"] = y_lim
+    fig.update_layout(
+        xaxis=ax_x, yaxis=ax_y,
+        shapes=plot_border(),
+        template=None,
+        plot_bgcolor=to_hex(style_opts["panel_fill"]),
+        paper_bgcolor=to_hex(style_opts["window_fill"]),
+    )
+
+    if main:
+        title_size = round(16 * get_option("main_size", 1))
+        fig.update_layout(
+            title=dict(text=main, x=0.5, xanchor="center",
+                       y=0.99, yanchor="top",
+                       font=dict(size=title_size)),
+            margin=dict(t=round(title_size * 2.2)))
+    return fig

lessPy/plt_contour_facet.py

@@ -0,0 +1,194 @@
+# plt_contour_facet.py — analog of plt.contourFacet.R
+#
+# Faceted form="contour" / form="smooth" for XY(): one density
+# panel per facet cell, computed on a common KDE grid and
+# bandwidth so density is comparable panel-to-panel — shared
+# contour levels (contour) or a shared color range on the
+# smooth_power-transformed density (smooth). As in R, the smooth
+# panels use kde2d with smoothScatter's bandwidth ((q95-q05)/25
+# per axis, h = 4x the kernel sd) so faceted and single-panel
+# smooths are consistent; contour keeps the normal-reference
+# bandwidth. A cell with < 3 points draws an empty panel; only
+# if no cell can estimate does the call stop. Layout follows R:
+# near-square single-facet grid (n_col computed by the caller),
+# rows = facet2 levels for two facets.
+
+import numpy as np
+import plotly.graph_objects as go
+
+from .plotly_utils import (
+    axis_format, facet_fig, facet_panels, finish_facet,
+    plotly_style, to_hex)
+from .plt_contour import _COLORSCALE, _bw_nrd, _kde2d
+from .plt_smooth import _RAMP as _SMOOTH_RAMP
+from .utils import get_option, pretty
+
+
+def _ss_bw(v):
+    """smoothScatter's kernel sd: the 5-95% quantile spread / 25.
+    R analog: the ss.bw() local of .plt.contour.facet"""
+    q05, q95 = np.percentile(v, [5, 95])
+    return (q95 - q05) / 25
+
+
+def plt_contour_facet(xv, yv, facet_arr, facet_order, facet_name,
+                      facet2_arr, facet2_order, facet2_name,
+                      contour_n, contour_nbins, contour_points,
+                      pt_size, x_lab, y_lab, main, digits_d,
+                      ellipse, ellipse_color, ellipse_lwd,
+                      fit, fit_power, fit_color, fit_lwd,
+                      fit_fn, ellipse_fn,
+                      render="contour", smooth_power=0.25,
+                      smooth_points=100, smooth_bins=128,
+                      n_col=1, axis_fmt="K", axis_x_pre="",
+                      axis_y_pre=""):
+    """Faceted joint-density display. fit_fn/ellipse_fn: the
+    caller's per-panel fit and ellipse constructors (XY._plt_fit,
+    XY._ellipse_region). R analog: .plt.contour.facet()"""
+    smooth = render == "smooth"
+    n_grid = smooth_bins if smooth else contour_nbins
+
+    labels, pos, sel, n_row_g, n_col = facet_panels(
+        facet_arr, facet_order, facet2_arr, facet2_order,
+        facet_name, facet2_name, n_col)
+    n_f = len(labels)
+
+    # common KDE grid + bandwidth: densities comparable across
+    # panels
+    x_ext = np.ptp(xv) * 0.12
+    y_ext = np.ptp(yv) * 0.12
+    lims = (xv.min() - x_ext, xv.max() + x_ext,
+            yv.min() - y_ext, yv.max() + y_ext)
+    if smooth:
+        h_common = [4 * _ss_bw(xv), 4 * _ss_bw(yv)]
+    else:
+        h_common = [_bw_nrd(xv), _bw_nrd(yv)]
+
+    dens = [None] * n_f
+    z_lo = z_hi = None
+    for i in range(n_f):
+        xi, yi = xv[sel[i]], yv[sel[i]]
+        if len(xi) < 3:
+            continue
+        h_i = [h if h > 0 else fb for h, fb in
+               zip(h_common, (_bw_nrd(xi), _bw_nrd(yi)))]
+        if min(h_i) <= 0:   # still degenerate (e.g., collinear)
+            continue
+        gx, gy, z = _kde2d(xi, yi, n_grid, lims, h=h_i)
+        dens[i] = (gx, gy, z)
+        z_lo = float(z.min()) if z_lo is None \
+            else min(z_lo, float(z.min()))
+        z_hi = float(z.max()) if z_hi is None \
+            else max(z_hi, float(z.max()))
+    if z_hi is None:
+        raise ValueError(
+            "No facet cell has enough data (>= 3 points) for a "
+            + ("smooth density." if smooth else "contour."))
+    step = (z_hi - z_lo) / contour_n
+    zlim_s = (max(z_lo, 0) ** smooth_power,
+              max(z_hi, 0) ** smooth_power)
+
+    # shared plot limits and ticks across panels
+    axT1 = pretty(float(xv.min()), float(xv.max()))
+    axT2 = pretty(float(yv.min()), float(yv.max()))
+    ax = {"axT1": axT1,
+          "axL1": axis_format(axT1, digits_d, axis_fmt,
+                              axis_x_pre),
+          "axT2": axT2,
+          "axL2": axis_format(axT2, digits_d, axis_fmt,
+                              axis_y_pre)}
+
+    ell_levels = [lv for lv in np.atleast_1d(ellipse) if lv]
+    px = float(pt_size) * 7.25
+    if not np.isfinite(px) or px <= 0:
+        px = 5
+
+    style_opts = plotly_style()
+    fig = facet_fig(n_row_g, n_col)
+    for i in range(n_f):
+        row, col = pos[i]
+        if dens[i] is None:
+            continue
+        gx, gy, z = dens[i]
+        xi, yi = xv[sel[i]], yv[sel[i]]
+        if smooth:
+            fig.add_trace(go.Heatmap(
+                x=gx, y=gy, z=(z ** smooth_power).T,
+                colorscale=_SMOOTH_RAMP, zsmooth="best",
+                zmin=zlim_s[0], zmax=zlim_s[1],
+                showscale=False, hoverinfo="skip",
+            ), row=row, col=col)
+            if smooth_points > 0:       # least-dense points
+                ix = np.clip(np.searchsorted(gx, xi), 0,
+                             len(gx) - 1)
+                iy = np.clip(np.searchsorted(gy, yi), 0,
+                             len(gy) - 1)
+                take = np.argsort(z[ix, iy],
+                                  kind="stable")[:smooth_points]
+                fig.add_trace(go.Scatter(
+                    x=xi[take], y=yi[take], mode="markers",
+                    marker=dict(symbol="circle", size=px,
+                                sizemode="diameter",
+                                color="rgba(0,0,0,0.33)",
+                                line=dict(color="#FFFFFF",
+                                          width=0.2)),
+                    hoverinfo="skip", showlegend=False,
+                ), row=row, col=col)
+        else:
+            fig.add_trace(go.Contour(
+                x=gx, y=gy, z=z.T,
+                colorscale=_COLORSCALE,
+                contours=dict(start=z_lo + step, end=z_hi,
+                              size=step),
+                line=dict(width=0), showscale=False,
+                hoverinfo="skip",
+            ), row=row, col=col)
+            if contour_points:
+                fig.add_trace(go.Scatter(
+                    x=xi, y=yi, mode="markers",
+                    marker=dict(symbol="circle", size=px,
+                                sizemode="diameter",
+                                color="rgba(0,0,0,0.27)",
+                                line=dict(color="#FFFFFF",
+                                          width=0.2)),
+                    hoverinfo="skip", showlegend=False,
+                ), row=row, col=col)
+        for lv in ell_levels:           # data ellipse(s)
+            if len(xi) < 3:
+                break
+            ex, ey = ellipse_fn(xi, yi, float(lv))
+            fig.add_trace(go.Scatter(
+                x=ex, y=ey, mode="lines",
+                line=dict(color=to_hex(ellipse_color),
+                          width=ellipse_lwd),
+                hoverinfo="skip", showlegend=False,
+            ), row=row, col=col)
+        if fit != "off" and len(xi) >= 3:
+            xs, _, f = fit_fn(xi, yi, fit, fit_power)
+            okf = np.isfinite(f)
+            if okf.sum() >= 2:
+                fig.add_trace(go.Scatter(
+                    x=xs[okf], y=f[okf], mode="lines",
+                    line=dict(color=to_hex(fit_color),
+                              width=fit_lwd),
+                    hoverinfo="skip", showlegend=False,
+                ), row=row, col=col)
+
+    # size the figure so each contour panel is roughly square
+    # (they read as scatter panels, not wide distribution strips)
+    panel = 300
+    finish_facet(fig, labels, ax, x_lab, y_lab, gridT1=None,
+                 style_opts=style_opts, n_col=n_col, pos=pos,
+                 height=150 + panel * n_row_g,
+                 width=130 + panel * n_col)
+    # density panels span the data, clipped to the shared limits
+    pad_x = 0.04 * (axT1[-1] - axT1[0])
+    pad_y = 0.04 * (axT2[-1] - axT2[0])
+    fig.update_xaxes(range=[axT1[0] - pad_x, axT1[-1] + pad_x])
+    fig.update_yaxes(range=[axT2[0] - pad_y, axT2[-1] + pad_y])
+    if main:
+        title_size = round(16 * get_option("main_size", 1))
+        fig.update_layout(
+            title=dict(text=main, x=0.5, xanchor="center",
+                       font=dict(size=title_size)))
+    return fig