lessPython 0.2.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

lessPy/ttest.py

@@ -24,7 +24,7 @@ import numpy as np
 import pandas as pd
 
 from .Regression import _getdigits
-from .utils import fmt, get_column, get_option
+from .utils import fmt, get_column, get_option, file_output, show_plots
 
 
 class ttestResults:
@@ -309,14 +309,14 @@ def _two_group(n1, m1, s1, n2, m2, s2, Ynm, Xnm, X1nm, X2nm,
     if graph and from_data:
         plots["two_group"] = _two_group_plot(
             YA, YB, Ynm, X1nm, X2nm, m1, m2, d)
-    return ttestResults(
+    return show_plots(ttestResults(
         kind="two-group", n_total=n1 + n2, digits_d=d,
         group1={"name": X1nm, "n": n1, "mean": m1, "sd": s1},
         group2={"name": X2nm, "n": n2, "mean": m2, "sd": s2},
         mean_diff=m1 - m2, pooled_sd=sw, cohen_d=smd,
         equal_var={"t": tvalue, "df": df, "p_value": pvalue,
                    "se": sterr, "lb": lb, "ub": ub},
-        welch=welch, plots=plots)
+        welch=welch, plots=plots))
 
 
 def _assumptions(YA, YB, X1nm, X2nm, Ynm, n1, n2, v1, v2, df1,
@@ -529,12 +529,12 @@ def _one_group(Y, n, m, s, mu, Ynm, brief, conf_level,
     if graph and from_data:
         plots["one_group"] = _one_group_plot(
             Y, Ynm, m, lb, ub, d, paired)
-    return ttestResults(
+    return show_plots(ttestResults(
         kind="paired" if paired else "one-group", n_total=n,
         digits_d=d, n=n, mean=m, sd=s, mu=mu,
         infer={"t": tvalue, "df": df, "p_value": pvalue,
                "se": sterr, "lb": lb, "ub": ub},
-        cohen_d=cohen, plots=plots)
+        cohen_d=cohen, plots=plots))
 
 
 def _needed_1(Edesired, conf_level, s, E, n, d):
@@ -572,7 +572,7 @@ def _kde(v):
 def _two_group_plot(YA, YB, Ynm, X1nm, X2nm, m1, m2, d):
     import plotly.graph_objects as go
     from .plotly_utils import (
-        BASE_COLORS, axis_format, axis_num, make_trans,
+        as_plotly_color, BASE_COLORS, axis_format, axis_num, make_trans,
         plot_border, plotly_style, to_hex, x_grid)
     from .utils import pretty
     style = plotly_style()
@@ -595,8 +595,8 @@ def _two_group_plot(YA, YB, Ynm, X1nm, X2nm, m1, m2, d):
     fig.update_layout(
         xaxis=ax_x, yaxis=ax_y,
         shapes=x_grid(axT1) + plot_border(), template=None,
-        plot_bgcolor=to_hex(style["panel_fill"]),
-        paper_bgcolor=to_hex(style["window_fill"]),
+        plot_bgcolor=as_plotly_color(style["panel_fill"]),
+        paper_bgcolor=as_plotly_color(style["window_fill"]),
         legend=dict(title=dict(text=str(X1nm) + " / " + str(X2nm))),
         title=dict(text="Two-Group Density Plot", x=0.5,
                    xanchor="center",
@@ -608,7 +608,7 @@ def _two_group_plot(YA, YB, Ynm, X1nm, X2nm, m1, m2, d):
 def _one_group_plot(Y, Ynm, m, lb, ub, d, paired):
     import plotly.graph_objects as go
     from .plotly_utils import (
-        BASE_COLORS, axis_format, axis_num, make_trans,
+        as_plotly_color, BASE_COLORS, axis_format, axis_num, make_trans,
         plot_border, plotly_style, to_hex, x_grid)
     from .utils import pretty
     style = plotly_style()
@@ -616,13 +616,13 @@ def _one_group_plot(Y, Ynm, m, lb, ub, d, paired):
     c = BASE_COLORS[0]
     fig = go.Figure()
     fig.add_trace(go.Scatter(
-        x=xs, y=ys, mode="lines", line=dict(color=to_hex(c),
+        x=xs, y=ys, mode="lines", line=dict(color=as_plotly_color(c),
                                             width=2),
         fill="tozeroy", fillcolor=make_trans(c, 0.85),
         hoverinfo="x", showlegend=False))
     ym = float(np.interp(m, xs, ys))
     fig.add_shape(type="line", x0=m, x1=m, y0=0, y1=ym,
-                  line=dict(color=to_hex("gray50"), width=1))
+                  line=dict(color=as_plotly_color("gray50"), width=1))
     axT1 = pretty(float(xs.min()), float(xs.max()))
     xlab = ("Differences of Matched Pairs" if paired else Ynm)
     ax_x = axis_num(xlab, axT1, axis_format(axT1, d))
@@ -631,11 +631,15 @@ def _one_group_plot(Y, Ynm, m, lb, ub, d, paired):
     fig.update_layout(
         xaxis=ax_x, yaxis=ax_y,
         shapes=x_grid(axT1) + plot_border(), template=None,
-        plot_bgcolor=to_hex(style["panel_fill"]),
-        paper_bgcolor=to_hex(style["window_fill"]),
+        plot_bgcolor=as_plotly_color(style["panel_fill"]),
+        paper_bgcolor=as_plotly_color(style["window_fill"]),
         title=dict(
             text="One-Group Density Plot", x=0.5,
             xanchor="center",
             font=dict(size=round(16 * get_option("main_size",
                                                  1)))))
     return fig
+
+
+# pdf_file= and png_file= write the figures, as lessR's pdf_file=
+ttest = file_output(ttest)

lessPy/utils.py

@@ -8,9 +8,9 @@ import math
 
 # style settings; R analog: options() set by lessR style()
 _OPTIONS = {
-    "main_size":     1.0,
-    "lab_size":      1.0,
-    "axis_size":     0.9,
+    "main_size":     1.16,      # zzz_on.R
+    "lab_size":      1.05,      # zzz_on.R
+    "axis_size":     0.80,      # zzz_on.R
     "axis_color":    "black",
     "lab_color":     "black",
     "grid_color":    "gray90",
@@ -23,6 +23,7 @@ _OPTIONS = {
     "panel_fill":    "white",
     "window_fill":   "white",
     "digits_d":      2,
+    "suggest":       True,      # >>> Suggestions, as R
     "pt_color":      "#324E5C",   # rgb(50,78,92), zzz_on.R
     "trans_pt_fill": 0.10,
     "segment_color": "gray40",
@@ -159,9 +160,10 @@ def resolve_facet(data, facet, fun):
                 "facet names a categorical variable for its "
                 "panels")
         if len(facet) > 2:
-            print(f"facet has {len(facet)} variables. {fun}() "
-                  "uses the first two: "
-                  f"{facet[0]}, {facet[1]}.")
+            from .stats_out import advise
+            advise(f"facet has {len(facet)} variables. {fun}() "
+                   "uses the first two: "
+                   f"{facet[0]}, {facet[1]}.")
         f1 = get_column(data, facet[0], "facet")
         if len(facet) == 1:
             return f1, facet[0], None, None
@@ -273,3 +275,141 @@ def pretty(lo, hi, n=5):
     vals = [(ns + i) * unit for i in range(int(nu - ns) + 1)]
     # avoid -0.0 and float dust such as 0.30000000000000004
     return [round(v, 10) + 0.0 for v in vals]
+
+
+def _in_notebook():
+    """True in a notebook kernel (Jupyter, Colab, VS Code), False in
+    a script, the terminal, or the IPython console."""
+    try:
+        from IPython import get_ipython
+    except ImportError:
+        return False
+    ip = get_ipython()
+    return ip is not None and getattr(ip, "kernel", None) is not None
+
+
+def show_plots(result):
+    """Show the figures an analysis returns, as lessR draws its
+    graphics as it runs. Only in a notebook: elsewhere fig.show()
+    opens a browser tab per figure, so the figures stay in .plots
+    (or .attrs["plots"] for a returned DataFrame). Displayed as a
+    notebook displays a returned Chart() figure; a display failure
+    leaves the figures in .plots rather than lose the analysis.
+    Returns result."""
+    attrs = getattr(result, "attrs", None)
+    plots = (attrs.get("plots") if isinstance(attrs, dict)
+             else getattr(result, "plots", None))
+    if plots and _in_notebook():
+        from IPython.display import display
+        try:
+            for fig in plots.values():
+                if fig is not None:
+                    display(fig)
+        except Exception as e:
+            import warnings
+            warnings.warn(f"figures not displayed ({e}); they are "
+                          "in .plots, show one with .show()")
+    return result
+
+
+def _figures_of(out, names=None):
+    """The figures a function returned, keyed by the file-name
+    suffix: an analysis result's .plots (or .attrs["plots"]) by plot
+    name, a list of Figures by variable name (X() of a list), and a
+    single Figure by no suffix."""
+    if hasattr(out, "write_image"):
+        return {"": out}
+    if isinstance(out, (list, tuple)):
+        keys = ([str(v) for v in names] if names
+                and len(names) == len(out)
+                else [str(i + 1) for i in range(len(out))])
+        return {k: f for k, f in zip(keys, out)
+                if hasattr(f, "write_image")}
+    attrs = getattr(out, "attrs", None)
+    plots = (attrs.get("plots") if isinstance(attrs, dict)
+             else getattr(out, "plots", None))
+    return {k: f for k, f in (plots or {}).items() if f is not None}
+
+
+def write_figures(out, stem, ext, names=None):
+    """Write the returned figures to ext ("pdf", "png") files named
+    from stem, as lessR's pdf_file=: one figure is stem.ext, several
+    are stem_<name>.ext. Reports the files as lessR's .showfile();
+    on Colab also downloads them to the user's computer. A write
+    failure warns and leaves the analysis result intact."""
+    import os
+    import sys
+    import warnings
+    stem = str(stem)
+    if stem.lower().endswith("." + ext):
+        stem = stem[:-len(ext) - 1]
+    figs = _figures_of(out, names)
+    if not figs:
+        return
+    if len(figs) == 1:
+        figs = {"": next(iter(figs.values()))}
+    dir_nm = os.path.dirname(stem)
+    if dir_nm and not os.path.isdir(dir_nm):
+        warnings.warn(f"{ext} file not written: no folder {dir_nm}",
+                      stacklevel=3)
+        return
+    files = []
+    try:
+        for key, fig in figs.items():
+            fname = f"{stem}_{key}.{ext}" if key else f"{stem}.{ext}"
+            fig.write_image(fname, scale=2 if ext == "png" else 1)
+            files.append(fname)
+    except Exception as e:
+        warnings.warn(
+            f"{ext} file not written ({e})\nWriting {ext} files needs "
+            "the png extra: pip install \"lessPython[png]\", then "
+            "plotly_get_chrome -y once (on Colab: !plotly_get_chrome "
+            "-y).", stacklevel=3)
+    if not files:
+        return
+    where = ("written at the current working directory"
+             if not dir_nm else "written")
+    workdir = os.getcwd() if not dir_nm else dir_nm
+    word = "file" if len(files) == 1 else "files"
+    print(f"\nThe {ext} {word} {where}")
+    for f in files:
+        print(f"        {os.path.basename(f)}")
+    print(f"    in:  {workdir}\n")
+    if "google.colab" in sys.modules:
+        try:
+            from google.colab import files as _colab_files
+            for f in files:
+                _colab_files.download(f)
+        except Exception:
+            pass
+
+
+def file_output(func):
+    """Wrap a function that returns figures so pdf_file= and
+    png_file= write them to files, as lessR's pdf_file=: the file
+    name, or with several figures the stem of the names,
+    stem_<plot>.ext. For a list of x variables (X()), each file is
+    named by its variable. As in lessR, True is refused: the name
+    is always given, so a second analysis cannot overwrite the
+    files of the first under a fixed name."""
+    import functools
+
+    @functools.wraps(func)
+    def wrapper(*args, pdf_file=None, png_file=None, **kwargs):
+        for given, prm in ((pdf_file, "pdf_file"), (png_file, "png_file")):
+            if isinstance(given, bool) and given:
+                raise ValueError(
+                    f"{prm} takes the stem of the file names, such as "
+                    f"{prm}=\"myReg\", which for Regression() writes "
+                    "one file per chart, such as "
+                    "myReg_scatter_matrix." + prm[:3] + ".")
+        out = func(*args, **kwargs)
+        if pdf_file or png_file:
+            xs = kwargs.get("x", args[0] if args else None)
+            names = xs if isinstance(xs, (list, tuple)) else None
+            for given, ext in ((pdf_file, "pdf"), (png_file, "png")):
+                if given:
+                    write_figures(out, given, ext, names)
+        return out
+
+    return wrapper

lessPy/vbs_plotly.py

@@ -42,7 +42,7 @@ import plotly.graph_objects as go
 from .plotly_utils import (
     as_plotly_color, axis_format, axis_num, get_tick_fmt,
     make_trans,
-    plot_border, plotly_style, sym_at, to_hex, x_grid,
+    plot_border, plotly_style, marks, to_hex, x_grid,
 )
 from .utils import band_width, fmt, get_option, kde, pretty
 
@@ -200,9 +200,10 @@ def vbs_plotly(x, x_name=None, vbs_plot="vbs",
     strip = "s" in vbs_plot
 
     # grouped replication measures, .param.VBS() group branch;
-    # by and facet share the branch, as .param.VBS() does
-    grp = by if by is not None else facet
-    grp_ord = by_order if by is not None else facet_order
+    # by and facet share the branch, the facet levels when both are
+    # given (.param.VBS(): facet1 <- by0 only when facet1 is missing)
+    grp = facet if facet is not None else by
+    grp_ord = facet_order if facet is not None else by_order
     if grp is not None:
         mx_gc = max((grp == nm).sum() for nm in grp_ord)
         mc_w = max(int(np.unique(x[grp == nm],
@@ -210,7 +211,9 @@ def vbs_plotly(x, x_name=None, vbs_plot="vbs",
                    for nm in grp_ord if (grp == nm).any())
         reps = (n - n_ux) / n > 0.15 and mc_w > 0.05 * n
 
-    # jitter_x breaks ties in the data itself, as in X.R
+    # jitter_x breaks ties in the data itself, as in X.R; the violin
+    # bandwidth is read from the data as given, as .param.VBS() does
+    x_given = x.copy()
     if jitter_x is None:
         if grp is None:
             jitter_x = 1.1 * (1 - np.exp(-0.03 * mx_c))
@@ -256,13 +259,21 @@ def vbs_plotly(x, x_name=None, vbs_plot="vbs",
         box_fill = get_option("box_fill", "#419BD2")
     if box_color is None:
         box_color = get_option("box_color", "gray15")
-    box_color = to_hex(box_color)
+    box_color = as_plotly_color(box_color)
 
     fig = go.Figure()
     val_fmt = get_tick_fmt(x, digits_d)
     vpart = f"%{{x:{val_fmt}}}" if val_fmt else "%{x}"
     rng_ = np.random.default_rng(n)      # reproducible spread
     jy = 0.5 if jitter_y is None else float(jitter_y)
+    # the values plotted, for X()'s "Parameter values" report; one
+    # bandwidth only when one violin is drawn (facets take their own)
+    from .stats_out import record_stats
+    record_stats(pt_size=float(cex), out_size=float(out_cex),
+                 jitter_x=float(jitter_x), jitter_y=jy,
+                 bw=(float(bw) if bw is not None else
+                     float(band_width(x_given, bw_iter)) if facet is None
+                     else None))
 
     # facet units, first level in the TOP band (reading order, as
     # lessR as.table=TRUE); facet2 stacks one section of facet
@@ -326,7 +337,7 @@ def vbs_plotly(x, x_name=None, vbs_plot="vbs",
         # violin: mirrored KDE, max width = vbs_ratio
         if violin and len(xu) > 1:
             h = (bw if bw is not None
-                 else band_width(xu, bw_iter))
+                 else band_width(x_given[um], bw_iter))
             grid = np.linspace(xu.min() - 3 * h,
                                xu.max() + 3 * h, 512)
             dens = kde(xu, grid, h)
@@ -336,7 +347,7 @@ def vbs_plotly(x, x_name=None, vbs_plot="vbs",
                 y=np.concatenate([yc + half,
                                   yc - half[::-1]]),
                 mode="lines",
-                line=dict(color=to_hex(violin_color), width=1),
+                line=dict(color=as_plotly_color(violin_color), width=1),
                 fill="toself",
                 fillcolor=as_plotly_color(violin_fill),
                 hoverinfo="skip", showlegend=False,
@@ -397,21 +408,22 @@ def vbs_plotly(x, x_name=None, vbs_plot="vbs",
                                        len(pts))
                 # by groups differ by color only; shape= (scalar or
                 # per-group vector) overrides for every group
-                sym = "circle" if shape is None else sym_at(shape, i)
                 hover = f"{x_lab}: {vpart}"
                 if nm is not None:
                     hover += f"<br>{by_name}: {nm}"
                 hover += lvl_part
                 fig.add_trace(go.Scatter(
-                    x=pts, y=yj, mode="markers",
+                    x=pts, y=yj,
                     name=None if nm is None else str(nm),
-                    marker=dict(
-                        symbol=sym, size=px,
-                        color=make_trans(_col_for(pt_fill, i),
-                                         1 - pt_trans),
-                        line=dict(
-                            color=to_hex(_col_for(pt_color, i)),
-                            width=0.5)),
+                    **marks("circle" if shape is None else shape, i,
+                            "markers", dict(
+                                size=px,
+                                color=make_trans(_col_for(pt_fill, i),
+                                                 1 - pt_trans),
+                                line=dict(
+                                    color=as_plotly_color(
+                                        _col_for(pt_color, i)),
+                                    width=0.5))),
                     hovertemplate=hover + "<extra></extra>",
                     showlegend=nm is not None and ui == 0,
                 ))
@@ -444,8 +456,8 @@ def vbs_plotly(x, x_name=None, vbs_plot="vbs",
                         mode="markers",
                         marker=dict(
                             symbol=out_shape, size=px_out,
-                            color=to_hex(o_fill),
-                            line=dict(color=to_hex(o_color),
+                            color=as_plotly_color(o_fill),
+                            line=dict(color=as_plotly_color(o_color),
                                       width=1)),
                         hovertemplate=hover + "<extra></extra>",
                         showlegend=False,
@@ -465,7 +477,7 @@ def vbs_plotly(x, x_name=None, vbs_plot="vbs",
                 keep_i = cand[np.argsort(-np.abs(xu[cand]),
                                          kind="stable")][:out_cut]
                 id_font = dict(
-                    color=to_hex(get_option("ID_color",
+                    color=as_plotly_color(get_option("ID_color",
                                             "gray50")),
                     size=max(8, round(float(ID_size) * 14)))
                 for ii in keep_i:
@@ -486,8 +498,8 @@ def vbs_plotly(x, x_name=None, vbs_plot="vbs",
     annotations = []
     if n_fac > 1:               # shaded strip label per band
         s_fill = as_plotly_color(get_option("strip_fill"))
-        s_line = to_hex(get_option("strip_color"))
-        s_text = to_hex(get_option("strip_text_color"))
+        s_line = as_plotly_color(get_option("strip_color"))
+        s_text = as_plotly_color(get_option("strip_text_color"))
         s_font = round(14 * get_option("axis_size", 0.9))
         strip_items = [(u["yc"] + _STRIP[0],
                         u["yc"] + _STRIP[1], u["strip"])
@@ -519,22 +531,22 @@ def vbs_plotly(x, x_name=None, vbs_plot="vbs",
         shapes=shapes,
         annotations=annotations,
         template=None,
-        plot_bgcolor=to_hex(style_opts["panel_fill"]),
-        paper_bgcolor=to_hex(style_opts["window_fill"]),
+        plot_bgcolor=as_plotly_color(style_opts["panel_fill"]),
+        paper_bgcolor=as_plotly_color(style_opts["window_fill"]),
         height=(450 if n_fac == 1
                 else 120 + 190 * n_fac
                 + 40 * len(sec_strips)),
     )
     if n_grp > 1:               # lattice key: top, one row
-        leg_color = to_hex(style_opts["lab_color"])
+        leg_color = as_plotly_color(style_opts["lab_color"])
         fig.update_layout(legend=dict(
             orientation="h",
             x=0.5, xanchor="center", y=1.02, yanchor="bottom",
             font=dict(size=round(14 * get_option("axis_size",
                                                  0.9)),
                       family="Arial", color=leg_color),
-            bgcolor=to_hex(style_opts["window_fill"]),
-            bordercolor=to_hex("gray80"), borderwidth=1,
+            bgcolor=as_plotly_color(style_opts["window_fill"]),
+            bordercolor=as_plotly_color("gray80"), borderwidth=1,
             itemsizing="constant",
         ))
     if main: