lessPython 0.1.0__py3-none-any.whl

lessPy/plt_time.py

@@ -0,0 +1,143 @@
+# plt_time.py — analog of plt.time.R
+#
+# ts_unit/ts_agg for XY(): aggregate a date-x time series to a
+# coarser time unit, sum or mean per period. Ports .plt.time():
+# infer the existing unit from the date spacing, refuse a
+# requested unit finer than the data, drop the trailing
+# incomplete period, aggregate per period — per by= level when
+# present — with the date placed at the period start for
+# months/quarters/years (weeks and days keep the last observed
+# date of the period, as xts::period.apply indexes), and note
+# gaps in the final series. pandas periods replace the xts/zoo
+# machinery; the unit inference is the median-gap rule (the
+# calendar-structure refinements of .plt.time() for series with
+# missing periods are not ported).
+
+import numpy as np
+import pandas as pd
+
+from .utils import category_order
+
+_UNIT_ORDER = ("days", "weeks", "months", "quarters", "years")
+_PERIOD_FREQ = {"weeks": "W-SUN", "months": "M",
+                "quarters": "Q", "years": "Y"}
+
+
+def _infer_unit(dates):
+    """Existing time unit from the median day gap, "unknown"
+    when irregular. R analog: the tu_exist logic of .plt.time()"""
+    d = np.sort(pd.unique(pd.Series(dates).dropna()))
+    if len(d) <= 1:
+        return "days"
+    gaps = np.diff(d).astype("timedelta64[D]").astype(int)
+    gaps = gaps[gaps > 0]
+    if len(gaps) == 0:
+        return "days"
+    med = float(np.median(gaps))
+    if med <= 1.5:
+        return "days"
+    if 6 <= med <= 8:                  # weekly, unless biweekly
+        return ("unknown" if (gaps == 14).mean() >= 0.40
+                else "weeks")
+    if 28 <= med <= 31:
+        return "months"
+    if 90 <= med <= 92:
+        return "quarters"
+    if 365 <= med <= 366:
+        return "years"
+    return "unknown"
+
+
+def _agg_one(dser, yser, ts_unit, aggfun):
+    """Aggregate one series: truncate the trailing incomplete
+    period, then one value per period. R analogs: ts_truncate()
+    and the xts::period.apply block of .plt.time()"""
+    if ts_unit == "days":              # collapse duplicate dates
+        per = dser
+    else:
+        per = dser.dt.to_period(_PERIOD_FREQ[ts_unit])
+        # trailing partial period: last date short of period end
+        last_per = per.iloc[int(np.argmax(dser.to_numpy()))]
+        if dser.max() < last_per.end_time.normalize():
+            keep = (per != last_per).to_numpy()
+            dser, yser, per = dser[keep], yser[keep], per[keep]
+    if len(dser) == 0:
+        return (np.array([], dtype="datetime64[ns]"),
+                np.array([]))
+    y_out = yser.groupby(per.to_numpy()).agg(
+        lambda s: aggfun(s.to_numpy()))  # NaN propagates, as R
+    if ts_unit in ("months", "quarters", "years"):
+        x_out = y_out.index.to_timestamp(how="start")
+    else:                              # last observed date
+        x_out = dser.groupby(per.to_numpy()).max().to_numpy()
+    return np.asarray(x_out), y_out.to_numpy()
+
+
+def plt_time(x_ser, y_ser, by_ser, ts_unit, ts_agg, quiet=True):
+    """Aggregate the time series to ts_unit by ts_agg. Returns
+    (x_ser, y_ser, by_ser, ts_unit). R analog: .plt.time()"""
+    hold7 = ts_unit == "days7"
+    if hold7:
+        ts_unit = "days"
+    if ts_unit not in _UNIT_ORDER:
+        raise ValueError(
+            "ts_unit must be one of days, days7, weeks, months, "
+            "quarters, years")
+
+    unit_exist = _infer_unit(
+        x_ser.to_numpy() if by_ser is None
+        else x_ser[by_ser == category_order(by_ser)[0]]
+        .to_numpy())
+    if (unit_exist != "unknown"
+            and _UNIT_ORDER.index(ts_unit)
+            < _UNIT_ORDER.index(unit_exist)):
+        raise ValueError(
+            f"Resolution of data is {unit_exist}; requested "
+            f"{ts_unit} data is not available")
+
+    aggfun = np.sum if ts_agg == "sum" else np.mean
+    if by_ser is None:
+        xo, yo = _agg_one(x_ser, y_ser, ts_unit, aggfun)
+        x_out = pd.Series(xo, name=x_ser.name)
+        y_out = pd.Series(yo, name=y_ser.name)
+        by_out = None
+    else:
+        levels = category_order(by_ser)
+        xs, ys, bs = [], [], []
+        for lvl in levels:
+            m = (by_ser == lvl).to_numpy()
+            xl, yl = _agg_one(x_ser[m], y_ser[m], ts_unit,
+                              aggfun)
+            xs.append(xl)
+            ys.append(yl)
+            bs.extend([lvl] * len(xl))
+        x_out = pd.Series(np.concatenate(xs), name=x_ser.name)
+        y_out = pd.Series(np.concatenate(ys), name=y_ser.name)
+        by_out = pd.Series(
+            pd.Categorical(bs, categories=levels),
+            name=by_ser.name)
+
+    # gaps in the aggregated series (first by level, as R)
+    d = np.sort(x_out[by_out == levels[0]].to_numpy()
+                if by_out is not None else x_out.to_numpy())
+    gaps = False
+    if len(d) > 1:
+        dd = pd.DatetimeIndex(d)
+        if ts_unit == "days":
+            gaps = (np.diff(d).astype("timedelta64[D]")
+                    .astype(int) > 1).any()
+        elif ts_unit == "weeks":
+            gaps = (np.diff(d).astype("timedelta64[D]")
+                    .astype(int) > 7).any()
+        elif ts_unit == "months":
+            gaps = (np.diff(dd.year * 12 + dd.month) > 1).any()
+        elif ts_unit == "quarters":
+            gaps = (np.diff(dd.year * 4 + dd.quarter) > 1).any()
+        elif ts_unit == "years":
+            gaps = (np.diff(dd.year) > 1).any()
+    if gaps and not quiet:
+        print("There are gaps in the dates, so that there are "
+              "not regular\nintervals between all the dates.")
+
+    return (x_out, y_out, by_out,
+            "days7" if hold7 else ts_unit)

lessPy/prob_norm.py

@@ -0,0 +1,111 @@
+# prob_norm.py — analog of prob_norm.R.
+#
+# prob_norm(): plot a normal density curve, shade the interval
+# from lo to hi, and return the probability P(lo < Y < hi). An
+# open bound (lo or hi = None) extends to the tail. Prints the
+# probability and returns a results object with the plotly figure
+# in .plots.
+
+import numpy as np
+
+from .utils import fmt
+
+_FILL_NRM = "#E8E8E8"      # grey91
+_FILL_INT = "#9FB6CD"      # slategray3
+
+
+class ProbNormResults:
+    """Numeric results of prob_norm(): the interval probability,
+    the bounds lo/hi, mu/sigma, and the plotly figure in .plots
+    ("norm")."""
+
+    def __init__(self, **kw):
+        self.__dict__.update(kw)
+
+    def __repr__(self):
+        return f"<lessPy prob_norm: P={self.prob:.4g}>"
+
+
+def prob_norm(lo=None, hi=None, mu=0, sigma=1, nrm_color="black",
+              fill_nrm=_FILL_NRM, fill_int=_FILL_INT, y_axis=False,
+              z=True):
+    """Probability of a normal interval: shade the area under the
+    N(mu, sigma) curve from lo to hi and return P(lo < Y < hi). A
+    None bound extends to the tail. z adds a second axis of z
+    scores (suppressed for the standard normal). Prints the
+    probability and returns a ProbNormResults with .plots.
+    R analog: prob_norm()"""
+    from scipy.stats import norm
+    if lo is not None and hi is not None and lo > hi:
+        raise ValueError(f"lo ({lo}) cannot be larger than hi "
+                         f"({hi})")
+    if sigma <= 0:
+        raise ValueError("sigma must be larger than zero")
+
+    if mu == 0 and sigma == 1:
+        z = False
+
+    lo_lbl = "..." if lo is None else str(lo)
+    hi_lbl = "..." if hi is None else str(hi)
+    lo_v = mu - sigma * 10 if lo is None else lo
+    hi_v = mu + sigma * 10 if hi is None else hi
+
+    prob = norm.cdf(hi_v, mu, sigma) - norm.cdf(lo_v, mu, sigma)
+
+    fig = _plot(lo_v, hi_v, lo_lbl, hi_lbl, mu, sigma, prob,
+                nrm_color, fill_nrm, fill_int, y_axis, z)
+
+    print(f"Probability:  {prob}")
+
+    return ProbNormResults(prob=prob, lo=lo_v, hi=hi_v, mu=mu,
+                           sigma=sigma, plots={"norm": fig})
+
+
+def _plot(lo, hi, lo_lbl, hi_lbl, mu, sigma, prob, nrm_color,
+          fill_nrm, fill_int, y_axis, z):
+    import plotly.graph_objects as go
+    from scipy.stats import norm
+    min_x, max_x = mu - 4 * sigma, mu + 4 * sigma
+    cuts = [mu + k * sigma for k in range(-4, 5)]
+    x = np.linspace(min_x, max_x, 200)
+    dnrm = norm.pdf(x, mu, sigma)
+
+    fig = go.Figure()
+    # full curve, filled
+    fig.add_trace(go.Scatter(
+        x=np.concatenate(([min_x], x, [max_x])),
+        y=np.concatenate(([0.0], dnrm, [0.0])),
+        mode="lines", fill="toself", fillcolor=fill_nrm,
+        line=dict(color=nrm_color), hoverinfo="skip",
+        showlegend=False))
+    # shaded interval
+    m = (x > lo) & (x < hi)
+    xs = np.concatenate(([lo], x[m], [hi]))
+    ys = np.concatenate(([0.0], dnrm[m],
+                         [0.0]))
+    fig.add_trace(go.Scatter(
+        x=xs, y=ys, mode="lines", fill="toself",
+        fillcolor=fill_int, line=dict(color=fill_int),
+        hoverinfo="skip", showlegend=False))
+
+    title = (f"Prob = {float(f'{prob:.4g}')} for Y from "
+             f"{lo_lbl} to {hi_lbl}<br>"
+             f"<sub>μ={mu}  σ={sigma}</sub>")
+    fig.update_layout(
+        plot_bgcolor="white", paper_bgcolor="white",
+        margin=dict(t=50, r=20, b=60 if z else 40, l=40),
+        title=dict(text=title, x=0.5, xanchor="center",
+                   font=dict(size=13)),
+        xaxis=dict(tickvals=cuts, showgrid=False,
+                   linecolor="black", ticks="outside"),
+        yaxis=dict(visible=y_axis, showgrid=False,
+                   title="Normal Density" if y_axis else None,
+                   rangemode="tozero"),
+        showlegend=False)
+    if z:                                  # second row: z scores
+        for k, cx in zip(range(-4, 5), cuts):
+            fig.add_annotation(x=cx, xref="x", y=-0.13,
+                               yref="paper", text=str(k),
+                               showarrow=False,
+                               font=dict(size=11))
+    return fig

lessPy/prob_tcut.py

@@ -0,0 +1,131 @@
+# prob_tcut.py — analog of prob_tcut.R.
+#
+# prob_tcut(): plot a t density (df degrees of freedom) with the
+# central 1-alpha region shaded and the two alpha/2 tails shaded,
+# overlaid with a standard normal for comparison. Both the t and
+# normal two-tailed critical cutoffs are drawn as vertical lines
+# and labeled. Prints and returns the upper t cutoff,
+# qt(1 - alpha/2, df) — the value R reports (labeled "Probability").
+
+import numpy as np
+
+from .utils import fmt
+
+_BG = "#F9F9FC"             # rgb(249,249,252)
+_TAIL = "#8B475D"           # palevioletred4
+_NRM = "#B3B3B3"            # gray(.7)
+_T = "#141414"              # gray(.08)
+
+
+class ProbTcutResults:
+    """Result of prob_tcut(): the upper t cutoff, df, alpha, and the
+    plotly figure in .plots ("tcut")."""
+
+    def __init__(self, **kw):
+        self.__dict__.update(kw)
+
+    def __repr__(self):
+        return f"<lessPy prob_tcut: df={self.df} cutoff={self.cutoff:.4g}>"
+
+
+def prob_tcut(df, alpha=0.05, digits_d=3, y_axis=False,
+              fill="aliceblue", color_tail=_TAIL, nrm_color=_NRM,
+              color_t=_T):
+    """Two-tailed t cutoffs at alpha: shade the central 1-alpha
+    region of the t(df) curve and its alpha/2 tails, overlay a
+    standard normal, and mark both sets of critical values. Returns
+    a ProbTcutResults whose cutoff is the upper t critical value
+    qt(1 - alpha/2, df). R analog: prob_tcut()"""
+    from scipy.stats import t as t_dist, norm
+    if df < 2:
+        raise ValueError("df must be 2 or larger")
+
+    tail = alpha / 2
+    t_lo = t_dist.ppf(tail, df)
+    t_hi = t_dist.ppf(1 - tail, df)
+    cutoff = t_hi                          # value R returns
+    n_lo = norm.ppf(tail)
+    n_hi = norm.ppf(1 - tail)
+
+    fig = _plot(df, alpha, t_lo, t_hi, n_lo, n_hi, digits_d, y_axis,
+                fill, color_tail, nrm_color, color_t)
+
+    print(f"Probability:  {cutoff}")
+    return ProbTcutResults(cutoff=cutoff, df=df, alpha=alpha,
+                           plots={"tcut": fig})
+
+
+def _cut_line(fig, x, top, color):
+    fig.add_shape(type="line", x0=x, x1=x, y0=0, y1=top,
+                  line=dict(color=color))
+
+
+def _cut_lbl(fig, x, y, value, digits_d, color):
+    fig.add_annotation(x=x, y=y, text=fmt(value, digits_d),
+                       showarrow=False, font=dict(size=12,
+                       color=color))
+
+
+def _plot(df, alpha, t_lo, t_hi, n_lo, n_hi, digits_d, y_axis,
+          fill, color_tail, nrm_color, color_t):
+    import plotly.graph_objects as go
+    from scipy.stats import t as t_dist, norm
+    xmin, xmax = -5.5, 5.5
+    x = np.linspace(xmin, xmax, 400)
+    yt = t_dist.pdf(x, df)
+
+    fig = go.Figure()
+    # central 1-alpha region of the t curve (aliceblue)
+    fig.add_trace(go.Scatter(
+        x=np.concatenate(([xmin], x, [xmax])),
+        y=np.concatenate(([0.0], yt, [0.0])),
+        mode="lines", fill="toself", fillcolor=fill,
+        line=dict(color="rgba(0,0,0,0)"), hoverinfo="skip",
+        showlegend=False))
+    # alpha/2 tails (palevioletred4)
+    for lo, hi in ((xmin, t_lo), (t_hi, xmax)):
+        xs = np.linspace(lo, hi, 100)
+        ys = t_dist.pdf(xs, df)
+        fig.add_trace(go.Scatter(
+            x=np.concatenate(([lo], xs, [hi])),
+            y=np.concatenate(([0.0], ys, [0.0])),
+            mode="lines", fill="toself", fillcolor=color_tail,
+            line=dict(color=nrm_color, width=1), hoverinfo="skip",
+            showlegend=False))
+    # t curve on top
+    fig.add_trace(go.Scatter(
+        x=x, y=yt, mode="lines", line=dict(color=color_t, width=3),
+        name=f"t, df={df}", hoverinfo="skip"))
+    # standard normal overlay
+    fig.add_trace(go.Scatter(
+        x=x, y=norm.pdf(x), mode="lines",
+        line=dict(color=nrm_color, width=2), name="Normal",
+        hoverinfo="skip"))
+
+    # t cutoffs: line to .19, label at .20
+    for c in (t_lo, t_hi):
+        _cut_line(fig, c, 0.19, color_tail)
+        _cut_lbl(fig, c, 0.205, c, digits_d, color_t)
+    # normal cutoffs: line to .25, label at .26
+    for c in (n_lo, n_hi):
+        _cut_line(fig, c, 0.25, nrm_color)
+        _cut_lbl(fig, c, 0.265, c, digits_d, nrm_color)
+    # central confidence label, e.g. "95%"
+    fig.add_annotation(x=0, y=0.175,
+                       text=f"{round(100 * (1 - alpha))}%",
+                       showarrow=False,
+                       font=dict(size=17, color=nrm_color))
+
+    fig.update_layout(
+        plot_bgcolor=_BG, paper_bgcolor="white",
+        margin=dict(t=20, r=20, b=50, l=40),
+        xaxis=dict(title="Standard Errors from Zero", range=[xmin,
+                   xmax], showgrid=False, zeroline=False,
+                   linecolor="black", ticks="outside"),
+        yaxis=dict(visible=y_axis, range=[0, 0.42], showgrid=False,
+                   zeroline=False,
+                   title="Density" if y_axis else None),
+        legend=dict(x=0.99, y=0.99, xanchor="right", yanchor="top",
+                    bordercolor="black", borderwidth=0.5,
+                    font=dict(size=10)))
+    return fig

lessPy/prob_znorm.py

@@ -0,0 +1,110 @@
+# prob_znorm.py — analog of prob_znorm.R.
+#
+# prob_znorm(): plot a normal density curve marked at each integer
+# standard deviation, with the central +/-1, +/-2, and +/-3 sigma
+# regions shaded by three nested translucent bands. Because the
+# bands are translucent and stacked, the center (covered by all
+# three) is darkest, then two layers, then one — the empirical-rule
+# graphic. Unlike prob_norm() this returns no probability; it is a
+# display, so the results object holds only the plotly figure in
+# .plots ("znorm").
+
+import numpy as np
+
+
+class ProbZnormResults:
+    """Result of prob_znorm(): mu/sigma and the plotly figure in
+    .plots ("znorm"). No probability is computed."""
+
+    def __init__(self, **kw):
+        self.__dict__.update(kw)
+
+    def __repr__(self):
+        return f"<lessPy prob_znorm: mu={self.mu} sigma={self.sigma}>"
+
+
+def prob_znorm(mu=0, sigma=1, color_border="gray10", r=0.10,
+               g=0.34, b=0.94, a=0.20, main="", y_axis=False,
+               z=True):
+    """Normal curve with the central 1/2/3-sigma regions shown as
+    three nested translucent bands (the empirical-rule graphic).
+    color_border is the curve/outline color; r/g/b/a (each in
+    [0, 1]) set the translucent fill. z adds a second axis of z
+    scores (suppressed for the standard normal). Returns a
+    ProbZnormResults with .plots. R analog: prob_znorm()"""
+    if not all(0 <= v <= 1 for v in (r, g, b, a)):
+        raise ValueError("r, g, b and a must each be between 0 and "
+                         "1, inclusive")
+    if sigma <= 0:
+        raise ValueError("sigma must be larger than zero")
+
+    if mu == 0 and sigma == 1:
+        z = False
+
+    border = _gray_to_hex(color_border)
+    fill = f"rgba({round(r * 255)},{round(g * 255)}," \
+           f"{round(b * 255)},{a})"
+
+    fig = _plot(mu, sigma, border, fill, main, y_axis, z)
+    return ProbZnormResults(mu=mu, sigma=sigma, plots={"znorm": fig})
+
+
+def _gray_to_hex(color):
+    """plotly rejects R's grayNN/greyNN names; convert those to hex,
+    pass any other color string through unchanged."""
+    lc = color.lower()
+    for pre in ("gray", "grey"):
+        if lc.startswith(pre) and lc[len(pre):].isdigit():
+            v = round(int(lc[len(pre):]) / 100 * 255)
+            return f"#{v:02X}{v:02X}{v:02X}"
+    return color
+
+
+def _plot(mu, sigma, border, fill, main, y_axis, z):
+    import plotly.graph_objects as go
+    from scipy.stats import norm
+    xmin, xmax = mu - 4 * sigma, mu + 4 * sigma
+    cuts = [mu + k * sigma for k in range(-4, 5)]
+    x = np.linspace(xmin, xmax, 200)
+    y = norm.pdf(x, mu, sigma)
+
+    fig = go.Figure()
+    # normal curve
+    fig.add_trace(go.Scatter(
+        x=x, y=y, mode="lines", line=dict(color=border, width=2),
+        hoverinfo="skip", showlegend=False))
+    # dotted vertical segment at the mean, up to the peak
+    fig.add_shape(type="line", x0=mu, x1=mu, y0=0,
+                  y1=norm.pdf(mu, mu, sigma),
+                  line=dict(color=border, dash="dot"))
+    # nested translucent bands: +/-3, +/-2, +/-1 sigma. Drawn in
+    # this order so the overlaps stack — the center is darkest.
+    for k in (3, 2, 1):
+        lo, hi = mu - k * sigma, mu + k * sigma
+        m = (x > lo) & (x < hi)
+        fig.add_trace(go.Scatter(
+            x=np.concatenate(([lo], x[m], [hi])),
+            y=np.concatenate(([0.0], y[m], [0.0])),
+            mode="lines", fill="toself", fillcolor=fill,
+            line=dict(color=border, dash="dot", width=1),
+            hoverinfo="skip", showlegend=False))
+
+    fig.update_layout(
+        plot_bgcolor="white", paper_bgcolor="white",
+        margin=dict(t=50 if main else 30, r=20,
+                    b=60 if z else 40, l=40),
+        title=dict(text=main, x=0.5, xanchor="center",
+                   font=dict(size=13)),
+        xaxis=dict(tickvals=cuts, showgrid=False,
+                   linecolor="black", ticks="outside"),
+        yaxis=dict(visible=y_axis, showgrid=False,
+                   title="Normal Density" if y_axis else None,
+                   rangemode="tozero"),
+        showlegend=False)
+    if z:                                  # second row: z scores
+        for k, cx in zip(range(-4, 5), cuts):
+            fig.add_annotation(x=cx, xref="x", y=-0.13,
+                               yref="paper", text=str(k),
+                               showarrow=False,
+                               font=dict(size=11))
+    return fig