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

lessPy/XY.py

@@ -73,7 +73,7 @@ from .plotly_utils import (
     BASE_COLORS, as_plotly_color, axis_format, axis_num,
     facet_fig, facet_panels, finish_facet,
     get_tick_fmt, legend_style, make_trans, plot_border,
-    plotly_style, square_layout, sym_at, to_hex, x_grid,
+    plotly_style, square_layout, marks, to_hex, x_grid,
     font_scaled, by_colors)
 from .utils import (
     STAT_FUN, STAT_LBL, category_order, get_column, get_option,
@@ -213,14 +213,18 @@ def _loess_rows(xs, q_pt, span, degree, rw):
         w = (d == 0).astype(float)
     w = w * rw
     nz = np.flatnonzero(w)
-    xc = xs[nz] - q_pt
+    # x in units of the window, so the powers of a large-valued x,
+    #   such as dates as days, keep pinv well conditioned; the slope
+    #   back in units of x
+    sc = h if h > 0 else 1.0
+    xc = (xs[nz] - q_pt) / sc
     X = np.column_stack([xc ** k for k in range(degree + 1)])
     XtW = X.T * w[nz]
     B = np.linalg.pinv(XtW @ X) @ XtW
     val = np.zeros(n)
     slope = np.zeros(n)
     val[nz] = B[0]
-    slope[nz] = B[1]
+    slope[nz] = B[1] / sc
     return val, slope
 
 
@@ -306,6 +310,11 @@ def _loess(xv, yv, span, degree=2, family="gaussian"):
                                        (1 - (r / cmad) ** 2) ** 2, 1.0))
     l2 = (L ** 2).sum(axis=1)
     dof = n - 2 * np.trace(L) + l2.sum()   # tr[(I-L)'(I-L)]
+    # the t quantile of the band takes the fit's lookup degrees of
+    #   freedom, delta1^2 / delta2. R analog: predict.loess()$df
+    IL = np.eye(n) - L
+    M = IL.T @ IL
+    _loess.df = dof ** 2 / (M * M.T).sum()  # tr(M^2)
     return xs, ys, f, np.sqrt(res @ res / dof * l2)
 
 
@@ -378,7 +387,7 @@ def _qq_reference(fig, fit_color, fit_lwd):
             panels[key] = (min(lo, v.min()), max(hi, v.max()))
     refs = [go.Scatter(x=[lo, hi], y=[lo, hi], mode="lines",
                        xaxis=xa, yaxis=ya,
-                       line=dict(color=to_hex(get_option(
+                       line=dict(color=as_plotly_color(get_option(
                            "fit_color", "#5C4032")
                            if fit_color is None else fit_color),
                            width=1.5 if fit_lwd is None else fit_lwd),
@@ -411,17 +420,137 @@ def _ts_ylab(y_name, unit, aggregated, ts_agg):
 def _se_band(xs, ys, f, level):
     """SE band polygon about a least-squares line: fit +/- t * SE
     of the conditional mean. R analog: plt.main.R se bands, from
-    predict(se=TRUE) and qt(prb, n-1)."""
+    predict(se=TRUE) and qt(prb, df), df the residual df. None
+    when the band is undefined, fewer than 3 points or a single x
+    value, where R's se is NaN and no band is drawn."""
     n = len(xs)
+    if n < 3 or np.ptp(xs) == 0:
+        return None
     mse = ((ys - f) ** 2).sum() / (n - 2)
     xbar = xs.mean()
     sxx = ((xs - xbar) ** 2).sum()
     se = np.sqrt(mse * (1 / n + (xs - xbar) ** 2 / sxx))
-    tq = sps.t.ppf((1 + level) / 2, n - 1)
+    tq = sps.t.ppf((1 + level) / 2, n - 2)   # the residual df
     return (np.concatenate([xs, xs[::-1]]),
             np.concatenate([f + tq * se, (f - tq * se)[::-1]]))
 
 
+def _plt_bins(x_ser, y_ser, x, y, n_bins, stat, by, facet, pt_size,
+              ylab, digits_d, show):
+    """Bin x into n_bins equal intervals, R's cut() with the range
+    extended by 1/1000, and take the mean or median of y in each.
+    Returns the midpoints and statistics of the nonempty bins as the
+    new x and y, the y label, each point's pixel diameter, and the
+    bin counts, and prints R's two tables. R analog: .plt.bins()"""
+    st = "mean" if stat is None else stat
+    if st not in ("mean", "median"):
+        raise ValueError(
+            "stat can only take two values for binning: mean and "
+            "median")
+    if by is not None or facet is not None:
+        raise ValueError("n_bins bins one x variable: no by or facet")
+    if (not pd.api.types.is_numeric_dtype(x_ser)
+            or not pd.api.types.is_numeric_dtype(y_ser)):
+        raise ValueError("n_bins: both variables must be numeric")
+    n_bins = int(n_bins)
+    if n_bins < 2:
+        raise ValueError("Need at least two bins set by n_bins")
+    xv = x_ser.to_numpy(dtype=float)
+    yv = y_ser.to_numpy(dtype=float)
+    ok_x = np.isfinite(xv)
+    if len(np.unique(xv[ok_x])) < n_bins and show:
+        print(f"You specified {n_bins} bins, but only "
+              f"{len(np.unique(xv[ok_x]))} values of {x}\n"
+              "Empty bins will appear in the solution\n")
+    lo, hi = float(np.nanmin(xv)), float(np.nanmax(xv))
+    dx = hi - lo
+    bns = np.linspace(lo, hi, n_bins + 1)
+    bns[0], bns[-1] = lo - dx / 1000, hi + dx / 1000
+    mid = bns[:-1] + (bns[1:] - bns[:-1]) / 2
+    n = np.zeros(n_bins, dtype=int)
+    m = np.full(n_bins, np.nan)
+    for i in range(n_bins):
+        ys = yv[(xv > bns[i]) & (xv <= bns[i + 1])]
+        ys = ys[np.isfinite(ys)]
+        n[i] = len(ys)
+        if len(ys):
+            m[i] = ys.mean() if st == "mean" else np.median(ys)
+
+    if show:
+        def f_(v, d):
+            return f"{v:.{d}f}"
+        dx_ = 0 if np.all(xv[ok_x] == np.round(xv[ok_x])) else digits_d
+        ok_y = np.isfinite(yv)
+        dy_ = 0 if np.all(yv[ok_y] == np.round(yv[ok_y])) else digits_d
+        rows = [("n", str(ok_x.sum()), str(ok_y.sum())),
+                ("n.miss", str((~ok_x).sum()), str((~ok_y).sum())),
+                ("min", f_(np.nanmin(xv), dx_), f_(np.nanmin(yv), dy_)),
+                ("max", f_(np.nanmax(xv), dx_), f_(np.nanmax(yv), dy_)),
+                ("mean", f_(np.nanmean(xv), digits_d),
+                 f_(np.nanmean(yv), digits_d))]
+        w1 = max(len(x), max(len(r[1]) for r in rows))
+        w2 = max(len(y), max(len(r[2]) for r in rows))
+        print("\nSummary Stats\n")
+        print(f"{'':7}  {x:>{w1}}  {y:>{w2}}")
+        for r in rows:
+            print(f"{r[0]:7}  {r[1]:>{w1}}  {r[2]:>{w2}}")
+        brk = [f"{b:.{digits_d}f}" for b in bns]
+        labs = [f"({brk[i]},{brk[i + 1]}]" for i in range(n_bins)]
+        labs[0] = "[" + labs[0][1:]
+        tbl = pd.DataFrame({
+            "bin": labs, "n": n,
+            "midpt": [f"{v:.{digits_d}f}" for v in mid],
+            st: ["NaN" if not np.isfinite(v) else f"{v:.{digits_d}f}"
+                 for v in m]}, index=range(1, n_bins + 1))
+        print(f"\n{st} of {y} for levels of {x}\n")
+        print(tbl.to_string())
+
+    keep = n > 0
+    if isinstance(pt_size, (int, float)) and pt_size != 1:
+        cex = np.full(keep.sum(), float(pt_size))
+    else:                              # R: max size about 10
+        cex = (n[keep] / (n.max() / 10)) ** 0.6
+    x_new = pd.Series(mid[keep], name=x_ser.name)
+    y_new = pd.Series(m[keep], name=y_ser.name)
+    ylab = f"{st} of {y}" if ylab is None else ylab
+    return x_new, y_new, ylab, cex * 7.25, n[keep]
+
+
+def _as_years(s):
+    """A run of consecutive integers from 10 to 9999 as the dates of
+    Jan 1 of those years, else None. R analog: XY.R ~733"""
+    if (not pd.api.types.is_numeric_dtype(s)
+            or pd.api.types.is_bool_dtype(s) or len(s) < 2):
+        return None
+    v = s.to_numpy(dtype=float)
+    if (np.isnan(v).any() or (v != np.round(v)).any()
+            or not (np.diff(v) == 1).all()
+            or v.min() < 10 or v.max() > 9999):
+        return None
+    out = pd.Series(pd.to_datetime([f"{int(t):04d}-01-01" for t in v]),
+                    index=s.index, name=s.name)
+    return out
+
+
+def _ellipse_levels(ellipse):
+    """The confidence levels of the data ellipses: True is 0.95, a
+    number one level, a list several, as R's ellipse=c(.3,.5,.9).
+    False, None, or 0 is none."""
+    if ellipse is True:
+        return [0.95]
+    if ellipse is None or ellipse is False:
+        return []
+    lvls = (list(ellipse) if isinstance(ellipse, (list, tuple,
+                                                  np.ndarray))
+            else [ellipse])
+    lvls = [float(lv) for lv in lvls if lv]
+    for lv in lvls:
+        if not 0 < lv < 1:
+            raise ValueError("ellipse is the confidence level of "
+                             "a data ellipse, between 0 and 1")
+    return lvls
+
+
 def _ellipse_region(xv, yv, level, npoints=100):
     """Bivariate-normal data ellipse, the Murdoch and Chow
     construction of the ellipse package that XY() cites.
@@ -442,7 +571,7 @@ def _xy_facet(xv, yv, by_arr, by_order, facet_arr, facet_order,
               ellipse, ellipse_fill, ellipse_color, ellipse_lwd,
               x_lab, y_lab, main, digits_d,
               facet2_arr=None, facet2_order=None,
-              facet2_name=None, n_col=1):
+              facet2_name=None, n_col=1, fit_errors=False):
     """One scatter panel per facet level on shared axes,
     following the faceted-histogram conventions (_hs_facet):
     first level on the top panel, strip labels, legend
@@ -473,9 +602,10 @@ def _xy_facet(xv, yv, by_arr, by_order, facet_arr, facet_order,
                 if fit == "loess":
                     xs, ys_s, f, se_f = _loess(xg, yg, span)
                     fit_lines.append({"name": gname, "x": xs,
-                                      "y": f, "g": g})
+                                      "y": f, "g": g,
+                                      "err": (xs, ys_s, f)})
                     for lv in se_levels:
-                        tq = sps.t.ppf((1 + lv) / 2, len(xs) - 1)
+                        tq = sps.t.ppf((1 + lv) / 2, _loess.df)
                         se_polys.append((
                             np.concatenate([xs, xs[::-1]]),
                             np.concatenate(
@@ -485,14 +615,17 @@ def _xy_facet(xv, yv, by_arr, by_order, facet_arr, facet_order,
                     xs, ys_s, f = _plt_fit(xg, yg, fit, fit_power)
                     okf = np.isfinite(f)
                     fit_lines.append({"name": gname, "x": xs[okf],
-                                      "y": f[okf], "g": g})
+                                      "y": f[okf], "g": g,
+                                      "err": (xs[okf], ys_s[okf],
+                                              f[okf])})
                     if fit == "lm":
                         for lv in se_levels:
-                            se_polys.append(
-                                _se_band(xs, ys_s, f, lv))
-            if ellipse and len(xg) >= 3:
-                ellipses.append((g, *_ellipse_region(xg, yg,
-                                                     ellipse)))
+                            band = _se_band(xs, ys_s, f, lv)
+                            if band is not None:
+                                se_polys.append(band)
+            if len(xg) >= 3:
+                for lv in _ellipse_levels(ellipse):
+                    ellipses.append((g, *_ellipse_region(xg, yg, lv)))
         panels.append((pts, fit_lines, se_polys, ellipses))
         for fl in fit_lines:
             xs_all.append(fl["x"]); ys_all.append(fl["y"])
@@ -517,22 +650,22 @@ def _xy_facet(xv, yv, by_arr, by_order, facet_arr, facet_order,
         row, col = pos[i]
         for g, (gname, xg, yg) in enumerate(pts):
             fig.add_trace(go.Scatter(
-                x=xg, y=yg, mode="markers",
+                x=xg, y=yg,
                 name=None if gname is None else str(gname),
                 legendgroup=(None if gname is None
                              else str(gname)),
-                marker=dict(
-                    symbol=sym_at(shape, g), size=px,
-                    sizemode="diameter",
+                **marks(shape, g, "markers", dict(
+                    size=px, sizemode="diameter",
                     color=make_trans(fills[g], pt_opacity),
                     opacity=1,
-                    line=dict(color=to_hex(fills[g]), width=1)),
+                    line=dict(color=as_plotly_color(fills[g]),
+                              width=1))),
                 hoverinfo="x+y" + ("+name" if has_groups else ""),
                 showlegend=has_groups and i == 0,
             ), row=row, col=col)
         for g, ex, ey in ellipses:
-            edge = (to_hex(fills[g]) if has_groups
-                    else to_hex(ellipse_color))
+            edge = (as_plotly_color(fills[g]) if has_groups
+                    else as_plotly_color(ellipse_color))
             fig.add_trace(go.Scatter(
                 x=ex, y=ey, mode="lines",
                 line=dict(color=edge, width=ellipse_lwd),
@@ -546,6 +679,18 @@ def _xy_facet(xv, yv, by_arr, by_order, facet_arr, facet_order,
                 fillcolor=as_plotly_color(se_fill),
                 hoverinfo="skip", showlegend=False,
             ), row=row, col=col)
+        # fit_errors: each point's residual segment to its fitted
+        #   value, as on the single panel (R plt.main.R ~1403)
+        for fl in (fit_lines if fit_errors else []):
+            ex, ey = [], []
+            for xe, ye, fe in zip(*fl["err"]):
+                ex += [xe, xe, None]
+                ey += [ye, fe, None]
+            fig.add_trace(go.Scatter(
+                x=ex, y=ey, mode="lines",
+                line=dict(color="#822823", width=1),
+                hoverinfo="skip", showlegend=False,
+            ), row=row, col=col)
         for fl in fit_lines:
             if len(fl["x"]) < 2:
                 continue
@@ -555,8 +700,8 @@ def _xy_facet(xv, yv, by_arr, by_order, facet_arr, facet_order,
                 name="Fit" if single else f"Fit: {fl['name']}",
                 legendgroup=("fit" if single
                              else str(fl["name"])),
-                line=dict(color=(to_hex(fit_color) if single
-                                 else to_hex(fills[fl["g"]])),
+                line=dict(color=(as_plotly_color(fit_color) if single
+                                 else as_plotly_color(fills[fl["g"]])),
                           width=fit_lwd),
                 hoverinfo="skip",
                 showlegend=i == 0,
@@ -614,7 +759,7 @@ def _series_overlay(V, names, shared, on, fills, shape, pt_size,
                 xs, ys_s, f, se_f = _loess(xg, yg, span)
                 fit_lines.append((xs, f))
                 for lv in se_levels:
-                    tq = sps.t.ppf((1 + lv) / 2, len(xs) - 1)
+                    tq = sps.t.ppf((1 + lv) / 2, _loess.df)
                     se_polys.append((
                         np.concatenate([xs, xs[::-1]]),
                         np.concatenate([f + tq * se_f,
@@ -625,9 +770,12 @@ def _series_overlay(V, names, shared, on, fills, shape, pt_size,
                 fit_lines.append((xs[okf], f[okf]))
                 if fit == "lm":
                     for lv in se_levels:
-                        se_polys.append(_se_band(xs, ys_s, f, lv))
-        if ellipse and len(xg) >= 3:
-            ellipses.append(_ellipse_region(xg, yg, ellipse))
+                        band = _se_band(xs, ys_s, f, lv)
+                        if band is not None:
+                            se_polys.append(band)
+        if len(xg) >= 3:
+            for lv in _ellipse_levels(ellipse):
+                ellipses.append(_ellipse_region(xg, yg, lv))
         art.append((xg, yg, fit_lines, se_polys, ellipses))
         xs_all += [xg] + [fl[0] for fl in fit_lines] \
             + [ex for ex, _ in ellipses]
@@ -649,7 +797,7 @@ def _series_overlay(V, names, shared, on, fills, shape, pt_size,
         for ex, ey in ellipses:
             fig.add_trace(go.Scatter(
                 x=ex, y=ey, mode="lines",
-                line=dict(color=to_hex(fills[g]),
+                line=dict(color=as_plotly_color(fills[g]),
                           width=ellipse_lwd),
                 fill="toself",
                 fillcolor=as_plotly_color(ellipse_fill),
@@ -660,14 +808,14 @@ def _series_overlay(V, names, shared, on, fills, shape, pt_size,
                 fillcolor=as_plotly_color(se_fill),
                 hoverinfo="skip", showlegend=False))
         fig.add_trace(go.Scatter(
-            x=xg, y=yg, mode="markers", name=str(nm),
+            x=xg, y=yg, name=str(nm),
             legendgroup=str(nm),
-            marker=dict(symbol=sym_at(shape, g), size=px,
-                        sizemode="diameter",
-                        color=make_trans(fills[g], pt_opacity),
-                        opacity=1,
-                        line=dict(color=to_hex(fills[g]),
-                                  width=1)),
+            **marks(shape, g, "markers", dict(
+                size=px, sizemode="diameter",
+                color=make_trans(fills[g], pt_opacity),
+                opacity=1,
+                line=dict(color=as_plotly_color(fills[g]),
+                          width=1))),
             hoverinfo="x+y+name", showlegend=True))
         for fx_l, fy_l in fit_lines:
             if len(fx_l) < 2:
@@ -675,7 +823,7 @@ def _series_overlay(V, names, shared, on, fills, shape, pt_size,
             fig.add_trace(go.Scatter(
                 x=fx_l, y=fy_l, mode="lines",
                 legendgroup=str(nm),
-                line=dict(color=to_hex(fills[g]),
+                line=dict(color=as_plotly_color(fills[g]),
                           width=fit_lwd),
                 hoverinfo="skip", showlegend=False))
 
@@ -684,14 +832,14 @@ def _series_overlay(V, names, shared, on, fills, shape, pt_size,
     pad = 0.04 * (axT2[-1] - axT2[0])
     ax_y["range"] = [axT2[0] - pad, axT2[-1] + pad]
     ax_y.update(showgrid=True,
-                gridcolor=to_hex(style_opts["grid_col"]),
+                gridcolor=as_plotly_color(style_opts["grid_col"]),
                 gridwidth=1, griddash="dot")
     fig.update_layout(
         xaxis=ax_x, yaxis=ax_y,
         shapes=x_grid(axT1) + plot_border(),
         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"]),
         legend=legend_style("", style_opts),
         **square_layout(main=bool(main)))
     if main:
@@ -770,7 +918,7 @@ def _facet_series(V, names, shared, on, facet_arr, facet_order,
                             color=make_trans(fills[g],
                                              pt_opacity),
                             opacity=1,
-                            line=dict(color=to_hex(fills[g]),
+                            line=dict(color=as_plotly_color(fills[g]),
                                       width=1)),
                 hoverinfo="x+y+name",
                 showlegend=i == 0,
@@ -781,7 +929,7 @@ def _facet_series(V, names, shared, on, facet_arr, facet_order,
             fig.add_trace(go.Scatter(
                 x=fx_l, y=fy_l, mode="lines",
                 legendgroup=str(names[g]),
-                line=dict(color=to_hex(fills[g]),
+                line=dict(color=as_plotly_color(fills[g]),
                           width=fit_lwd),
                 hoverinfo="skip", showlegend=False,
             ), row=row, col=col)
@@ -860,6 +1008,7 @@ def _xy_series(x, y, data, x_multi, by, facet, form, n_row,
              if ylab is None else ylab)
 
     k = len(names)
+    fill = _expand_palette(fill, k)
     if isinstance(fill, (list, tuple)):
         fills = [fill[i % len(fill)] for i in range(k)]
     elif fill is not None:
@@ -951,8 +1100,10 @@ def _ts_facet(xv, yv, facet_arr, facet_order, fill0, border0,
           "axL2": axis_format(axT2, digits_d)}
 
     ypart = f"%{{y:{fmt2}}}" if fmt2 else "%{y}"
-    hover = (f"Date: %{{x|%Y-%m-%d}}<br>{y_lab.strip()}: "
-             f"{ypart}<extra></extra>")
+    xpart = ("Date: %{x|%Y-%m-%d}"
+             if np.issubdtype(np.asarray(xv).dtype, np.datetime64)
+             else f"{x_lab}: %{{x}}")
+    hover = f"{xpart}<br>{y_lab.strip()}: {ypart}<extra></extra>"
 
     style_opts = plotly_style()
     fig = facet_fig(n_row_g, n_col)
@@ -993,10 +1144,13 @@ def _ts_facet(xv, yv, facet_arr, facet_order, fill0, border0,
                              sizemode="diameter",
                              color=make_trans(f_c, pt_opacity),
                              opacity=1,
-                             line=dict(color=to_hex(b_c), width=1))
+                             line=dict(color=as_plotly_color(b_c), width=1))
                         if "markers" in mode_pts or line_width <= 0
                         else None),
-                line=dict(color=to_hex(b_c), width=line_width),
+                line=dict(color=as_plotly_color(
+                    style_opts["segment_color"]
+                    if nm is None and get_option("segment_color_set")
+                    else b_c), width=line_width),
                 name=nm, legendgroup=nm,
                 hovertemplate=hv,
                 showlegend=nm is not None and i == 0,
@@ -1016,7 +1170,7 @@ def _ts_facet(xv, yv, facet_arr, facet_order, fill0, border0,
     pad = 0.04 * (axT2[-1] - axT2[0])
     fig.update_yaxes(range=[axT2[0] - pad, axT2[-1] + pad])
     fig.update_xaxes(showgrid=True,
-                     gridcolor=to_hex(style_opts["grid_col"]),
+                     gridcolor=as_plotly_color(style_opts["grid_col"]),
                      gridwidth=1)
     if main:
         title_size = round(16 * get_option("main_size", 1))
@@ -1026,6 +1180,16 @@ def _ts_facet(xv, yv, facet_arr, facet_order, fill0, border0,
     return fig
 
 
+def _expand_palette(col, n):
+    """A palette name, such as fill="blues", as n of its colors,
+    one per series or by group, as R's fill="blues". Any other
+    value is returned unchanged."""
+    from .Chart import _color_range, _palette_names
+    if isinstance(col, str) and col in _palette_names():
+        return _color_range(col, n)
+    return col
+
+
 def _area_color(col, opacity):
     """Area fill color: "on" is the violin_fill option; an
     explicit #RRGGBBAA keeps its own alpha; otherwise the point
@@ -1122,14 +1286,14 @@ def _outlier_traces(fig, xv, yv, out_idx, labels, fill0,
                     sizemode="diameter",
                     color=make_trans(fill0, pt_opacity),
                     opacity=1,
-                    line=dict(color=to_hex(fill0), width=1.5)),
+                    line=dict(color=as_plotly_color(fill0), width=1.5)),
         hoverinfo="x+y", showlegend=False))
     font_sz = max(9, round(float(ID_size) * 14))
     for i in out_idx:
         fig.add_annotation(
             x=xv[i], y=yv[i], text=str(labels[i]),
             showarrow=False, yshift=-12,
-            font=dict(color=to_hex(ID_color), size=font_sz,
+            font=dict(color=as_plotly_color(ID_color), size=font_sz,
                       family="Arial"))
 
 
@@ -1216,16 +1380,17 @@ def _ts_fitted_lines(frcst, yv, x_name, y_name, ts_unit, digits_d):
 def XY(x, y=None, data=None, filter=None, by=None, facet=None,
        n_row=None, n_col=None,
        form="scatter", stat=None, sort="0", show_runs=False,
-       center_line="off",
+       center_line=None,
        contour_n=None, contour_nbins=None, contour_points=None,
        contour_legend=None,
        smooth_points=100, smooth_size=1, smooth_power=0.25,
-       smooth_bins=128,
+       smooth_bins=128, n_bins=None,
        enhance=False,
        segments_x=None, segments_y=None,
        add=None, x1=None, y1=None, x2=None, y2=None,
        fill=None, color=None, transparency=None,
        pt_size=1, pt_shape="circle", line_width=1.5,
+       radius=None, power=None,
        jitter_x=None, jitter_y=None,
        MD_cut=0, out_cut=0, out_shape="circle-open", out_size=1,
        ID=None, ID_color="gray50", ID_size=0.6,
@@ -1276,6 +1441,10 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
     contour_nbins = 50 if contour_nbins is None else contour_nbins
     contour_points = bool(contour_points)
     contour_legend = bool(contour_legend)
+    # fill="on" is the violin_fill color, as R (XY.R ~332)
+    if isinstance(fill, str) and fill == "on" or (
+            isinstance(fill, (list, tuple)) and "on" in fill):
+        fill = get_option("violin_fill", "#7485975A")
     if pt_shape == "sunflower":        # its earlier route, kept
         form, pt_shape = "sunflower", "circle"
     # the form is consulted before by is resolved, so a vector of by
@@ -1324,7 +1493,7 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
             "no facet=")
     if axis_fmt not in ("K", ",", ".", ""):
         raise ValueError('axis_fmt: "K", ",", ".", or ""')
-    if center_line not in ("off", "mean", "median", "zero"):
+    if center_line not in (None, "off", "mean", "median", "zero"):
         raise ValueError(
             'center_line: "off", "mean", "median", or "zero"')
     if span is not None:
@@ -1347,7 +1516,7 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
             "The segments it draws join each point to the fitted line, "
             "so they are the errors of the fit, and the name now says "
             "which fit they belong to, as fit, fit_color, and fit_se do.")
-    if center_line != "off" and facet is not None:
+    if center_line not in (None, "off") and facet is not None:
         raise ValueError(
             "center_line draws on a single panel: no facet=")
     if fit_errors:
@@ -1357,9 +1526,6 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
                 "line: specify fit=")
         if form != "scatter":
             raise ValueError('fit_errors applies to form="scatter"')
-        if facet is not None:
-            raise ValueError(
-                "fit_errors draws on a single panel: no facet=")
     if (scale_x is not None or scale_y is not None) \
             and facet is not None:
         raise ValueError(
@@ -1384,7 +1550,7 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
                          "specify facet=")
     if ts_agg not in ("sum", "mean"):
         raise ValueError('ts_agg: "sum" or "mean"')
-    if ts_stack and by is None:
+    if ts_stack and by is None and not isinstance(y, (list, tuple)):
         raise ValueError(
             "ts_stack stacks multiple time series: specify by=")
     if (by is not None and ts_area_fill is not None
@@ -1464,6 +1630,31 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
     # and keyed by name in the legend, drawn as a by= series would
     # be; the value axis reports only the aggregation and time unit
     # (XY.R, Aug 2026)
+    # a vector of y over .Index: one run chart per variable, overlaid,
+    # each numbered by row, as the date x above (XY.R run, n.ycol > 1)
+    if (y_multi and not x_multi and isinstance(x, str)
+            and x.lower() == ".index" and x not in data.columns):
+        if by is not None or facet is not None:
+            raise ValueError(
+                "A vector of y variables over .Index overlays its "
+                "variables as the\nseries of the run chart, so by and "
+                "facet do not apply.")
+        long = data[list(y)].copy()
+        long[".Index"] = np.arange(1, len(data) + 1)
+        long = long.melt(id_vars=[".Index"], value_vars=list(y),
+                         var_name="Series", value_name="Value")
+        long["Series"] = pd.Categorical(long["Series"],
+                                        categories=list(y))
+        fig_l = XY(".Index", "Value", data=long, by="Series",
+                   center_line=("off" if center_line is None
+                                else center_line),
+                   pt_size=pt_size, line_width=line_width, fill=fill,
+                   xlab=xlab, ylab=("" if ylab is None else ylab),
+                   main=main, digits_d=digits_d, quiet=True,
+                   rotate_x=rotate_x, rotate_y=rotate_y)
+        fig_l.update_layout(legend_title_text="")
+        return fig_l
+
     if y_multi and not x_multi and isinstance(x, str) \
             and x in data.columns:
         xd = data[x]
@@ -1596,6 +1787,8 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
     # chart: synthesize it rather than looking up a column
     def _resolve(name, arg):
         if isinstance(name, str) and name == ".Index":
+            if ".Index" in data.columns:   # numbered within series
+                return data[".Index"].rename("Index")
             return pd.Series(range(1, len(data) + 1),
                              index=data.index, name="Index")
         return get_column(data, name, arg)
@@ -1640,6 +1833,30 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
         y = "Index"
 
     by_ser = get_column(data, by, "by") if by is not None else None
+
+    # ----- bubbles: pt_size names a variable that sizes each point,
+    # its area by size^power, the largest radius inches across, as
+    # R's bubble plot (XY.R ~489, plt.plotly bubbles)
+    size_ser = size_name = None
+    if isinstance(pt_size, str):
+        if (facet is not None or form != "scatter"
+                or index_x or qq_key is not None):
+            raise ValueError(
+                f"pt_size='{pt_size}' sizes the points of a "
+                "scatterplot by a variable, a bubble plot,\nwhich "
+                "draws on one panel: no facet, form, run chart, or "
+                "q-q chart")
+        size_ser = get_column(data, pt_size, "pt_size")
+        if not pd.api.types.is_numeric_dtype(size_ser):
+            raise TypeError(
+                f"pt_size='{pt_size}' sizes the bubbles by the values "
+                "of a numeric variable")
+        size_name, pt_size = pt_size, 1
+    elif radius is not None or power is not None:
+        raise ValueError(
+            "radius and power size the bubbles of a bubble plot, "
+            "where pt_size names a\nnumeric variable, such as "
+            "pt_size='Pre'")
     (facet_ser, facet_name,
      facet2_ser, facet2_name) = resolve_facet(data, facet, "XY")
 
@@ -1716,6 +1933,17 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
 
     # stat: the statistic of y at each value of a continuous x, the
     # values first reported by level of x (XY.R, .ss.numeric(y, by=x))
+    # n_bins: the mean (or median) of y within each of n_bins equal
+    # bins of x, at the bin midpoints, the point sized by the count
+    # and the points joined (R .plt.bins)
+    bin_diam = bin_n = None
+    if n_bins is not None:
+        x_ser, y_ser, ylab, bin_diam, bin_n = _plt_bins(
+            x_ser, y_ser, x, y, n_bins, stat, by, facet, pt_size,
+            ylab, 3 if digits_d is None else digits_d, show)
+        data = pd.DataFrame({x: x_ser, y: y_ser})
+        stat = None
+
     stat_lines = None
     if stat is not None:
         for a_, b_ in ((x, y), (y, x)):
@@ -1776,6 +2004,16 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
         except (ValueError, TypeError):    # not a date column
             pass
 
+    # consecutive integer years become dates, Jan 1 of each, as XY.R
+    #   ~733, so they drive the time-series display and a forecast
+    yrs = None if index_x else _as_years(x_ser)
+    if yrs is not None:
+        x_ser = yrs
+        if show:
+            print(f"\n>>> Note: Variable {x} assumed to be annual years\n"
+                  "Converted to a type Date variable\n"
+                  "If forecasting, there will be no seasonality.\n")
+
     is_date = pd.api.types.is_datetime64_any_dtype(x_ser)
     # XY() displays the relationship of two continuous variables; a
     # categorical x or y belongs to another view, so name its call
@@ -1819,10 +2057,12 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
         y_ser = y_ser.fillna(ts_NA)
 
     used = [s for s in (x_ser, y_ser, by_ser, facet_ser,
-                        facet2_ser)
+                        facet2_ser, size_ser)
             if s is not None]
     keep = ~pd.concat(used, axis=1).isna().any(axis=1)
     x_ser, y_ser = x_ser[keep], y_ser[keep]
+    if size_ser is not None:
+        size_ser = size_ser[keep]
     if by_ser is not None:
         by_ser = by_ser[keep]
     if facet_ser is not None:
@@ -1830,11 +2070,50 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
     if facet2_ser is not None:
         facet2_ser = facet2_ser[keep]
 
+    if is_date and size_ser is not None:
+        raise ValueError(
+            f"pt_size='{size_name}' sizes the points of a scatterplot, "
+            "not of a time series")
     if is_date and form != "scatter":
         raise ValueError(
             f'form="{form}" describes the joint density of two '
             "numerical variables, not a time series")
 
+    if is_date and show:
+        # the line connects the points in date order within each
+        #   series. A date repeated within a series, unless ts_unit
+        #   aggregates it, means more than one series is present;
+        #   otherwise rows out of order are reordered for the plot
+        #   below, the data unchanged. R analog: XY.R date.var check
+        g_nm = [nm for nm, sr in ((by, by_ser), (facet_name, facet_ser),
+                                  (facet2_name, facet2_ser))
+                if sr is not None]
+        g_ser = [sr.astype(str) for sr in (by_ser, facet_ser, facet2_ser)
+                 if sr is not None]
+        key = (pd.concat(g_ser, axis=1).agg("\x1f".join, axis=1)
+               if g_ser else pd.Series("", index=x_ser.index))
+        in_grp = (f"  within each level of  {', '.join(g_nm)}"
+                  if g_nm else "")
+        rep = pd.DataFrame({"k": key, "x": x_ser}).groupby(
+            ["k", "x"]).size()
+        if ts_unit is not None:
+            pass                      # aggregated by period: any order
+        elif (rep > 1).any():
+            print(f"\n>>> Note\nThe dates of  {x}  repeat{in_grp}, up "
+                  f"to {int(rep.max())} times, so\n  the data hold more "
+                  "than one series, and the line connects\n  points "
+                  "from different series. Separate the series with  by  "
+                  "or  facet,\n  or select one with  filter.\n")
+        elif not all(grp.is_monotonic_increasing for _, grp in
+                     x_ser.groupby(key, sort=False)):
+            ob = g_nm + [x]
+            ob = (f"'{x}'" if len(ob) == 1
+                  else "[" + ", ".join(f"'{v}'" for v in ob) + "]")
+            print(f"\n>>> Note\nThe rows are not in order of  {x}{in_grp},"
+                  f"\n  so they are sorted by  {x}  for this plot.  The "
+                  "data frame is unchanged.\n  To sort it, enter:\n"
+                  f"    d = lp.order_by(d, by={ob})\n")
+
     if is_date:                        # time series: date order
         od = x_ser.sort_values(kind="stable").index
         x_ser, y_ser = x_ser.loc[od], y_ser.loc[od]
@@ -1844,10 +2123,15 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
             facet_ser = facet_ser.loc[od]
         if facet2_ser is not None:
             facet2_ser = facet2_ser.loc[od]
-        if fit != "off" or (ellipse is not False and ellipse):
-            raise NotImplementedError(
-                "fit and ellipse for a time series (date x) are "
-                "not yet ported")
+        if ellipse is not False and ellipse:
+            raise ValueError(
+                "An ellipse describes the joint distribution of two "
+                "continuous variables,\nnot a time series: no ellipse "
+                "with a date x")
+        if fit != "off" and facet_ser is not None:
+            raise ValueError(
+                "fit on a time series draws on a single panel: no "
+                "facet=")
         if MD_cut > 0 or out_cut > 0:
             raise ValueError(
                 "outlier flagging (MD_cut/out_cut) applies to a "
@@ -1857,10 +2141,14 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
             "forecasting (ts_ahead) requires a date variable "
             "for x")
 
-    if not is_date and (ts_stack or ts_area_fill is not None):
+    if not is_date and not index_x and (
+            ts_stack or ts_area_fill is not None):
         raise ValueError(
             "ts_stack and ts_area_fill apply to a time series "
-            "(date x)")
+            "(date x) or a run chart (x='.Index')")
+    if index_x and ts_stack:
+        raise ValueError(
+            "ts_stack stacks several time series over a date x")
 
     # ----- ts aggregation (ts_unit/ts_agg) --------------------------
     # facets aggregate within each panel, below
@@ -1875,7 +2163,7 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
         ylab = _ts_ylab(
             y, ts_unit if ts_unit is not None
             else _infer_unit(x_ser.to_numpy()), ts_agg_done, ts_agg)
-    if is_date and (ts_stack or ts_area_fill is not None) \
+    if (is_date or index_x) and (ts_stack or ts_area_fill is not None) \
             and pt_size == 1:
         pt_size = 0                    # R: no points with areas
 
@@ -1910,8 +2198,8 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
                 "not a time series")
         if ellipse is True:
             ellipse = 0.95
-        f_col = to_hex(get_option("fit_color", "#5C4032")
-                       if fit_color is None else fit_color)
+        f_col = as_plotly_color(get_option("fit_color", "#5C4032")
+                                if fit_color is None else fit_color)
         f_lwd = get_option("fit_lwd", 2) if fit_lwd is None else fit_lwd
         e_lvls = ([] if not ellipse else
                   list(ellipse) if isinstance(ellipse, (list, tuple))
@@ -1923,7 +2211,7 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
                 ex, ey = _ellipse_region(xv_, yv_, float(lv))
                 fig_.add_trace(go.Scatter(
                     x=ex, y=ey, mode="lines",
-                    line=dict(color=to_hex(
+                    line=dict(color=as_plotly_color(
                         get_option("ellipse_color", "gray20")
                         if ellipse_color is None else ellipse_color),
                         width=get_option("ellipse_lwd", 1)
@@ -2037,7 +2325,9 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
                 n_col=n_col_use, axis_fmt=axis_fmt,
                 axis_x_pre=axis_x_pre, axis_y_pre=axis_y_pre),
                 rotate_x, rotate_y)
-        if is_date:                    # time-series panels
+        # time-series panels; a filled run chart draws its panels
+        #   the same way, on the row index (XY.R lattice area)
+        if is_date or (index_x and ts_area_fill is not None):
             # ts_unit aggregates within each panel and group; the
             # forecast is of each panel's series (XY.R, Aug 2026)
             f_arr = facet_ser.to_numpy()
@@ -2064,7 +2354,7 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
                     ts_by = np.asarray(cols[ci], dtype=object)
             f_order = [str(v) for v in category_order(facet_ser)]
             f_arr = np.asarray(f_arr).astype(str)
-            if ylab is None:
+            if ylab is None and is_date:
                 from .plt_time import _infer_unit
                 ylab = _ts_ylab(y, ts_unit if ts_unit is not None
                                 else _infer_unit(x_ser.to_numpy()),
@@ -2142,8 +2432,8 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
                    for i in range(n_grp)]
         if transparency is None:
             transparency = get_option("trans_pt_fill", 0.10)
-        if fit_se is None:
-            fit_se = 0.95 if by is None else 0
+        if fit_se is None:             # residuals, not a band
+            fit_se = 0 if fit_errors else (0.95 if by is None else 0)
         se_lv = [lv for lv in (
             fit_se if isinstance(fit_se, (list, tuple))
             else [fit_se]) if lv]
@@ -2176,7 +2466,8 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
             y if ylab is None else ylab,
             main, 2 if digits_d is None else digits_d,
             facet2_arr=facet2_arr, facet2_order=f2_order,
-            facet2_name=facet2_name, n_col=n_col_use),
+            facet2_name=facet2_name, n_col=n_col_use,
+            fit_errors=fit_errors),
             rotate_x, rotate_y)
         if qq_key is not None:
             _qq_reference(fig_f, fit_color, fit_lwd)
@@ -2194,6 +2485,27 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
         groups = [(nm, xv[bv == nm], yv[bv == nm])
                   for nm in by_order]
 
+    # bubble diameters in pixels: 2 * (v / max)^power * radius at
+    #   96 dpi, radius .12 inches by default (R plt.plotly bubbles)
+    sizes = None
+    if bin_diam is not None:           # bins sized by their counts
+        sizes, size_name = [(bin_diam, bin_n)], "n"
+    if size_ser is not None:
+        sv = size_ser.to_numpy(dtype=float)
+        rad = 0.12 if radius is None else float(radius)
+        pw = 0.5 if power is None else float(power)
+        sz = np.clip(sv, 0, None) ** pw
+        mx = float(sz.max()) if len(sz) else 0.0
+        diam = (2 * (sz / mx) * rad * 96 if mx > 0
+                else np.zeros_like(sz))
+        sizes = ([(diam, sv)] if by_ser is None else
+                 [(diam[bv == nm], sv[bv == nm]) for nm in by_order])
+        if show:
+            print("\nSome Parameter values (can be manually set)")
+            print("-" * 55)
+            print(f"radius: {rad:.2f}    size of largest bubble")
+            print(f"power: {pw:.2f}     relative bubble sizes")
+
     # ----- jitter: the display coordinates only --------------------
     # auto-jitter an axis with few discrete values (R plt.main.R
     # ~634-659); the fit, ellipse, and statistics use the
@@ -2240,6 +2552,7 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
         fills = ([get_option("pt_color", "#324E5C")] if n_grp == 1
                  else by_colors(n_grp))
     else:
+        fill = _expand_palette(fill, n_grp)
         fills = list(fill) if isinstance(fill, (list, tuple)) \
             else [fill]
     borders = None if color is None else color
@@ -2261,6 +2574,7 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
                     "ts_stack requires the same dates at every "
                     "level of by=")
         if ts_area_fill is not None:
+            ts_area_fill = _expand_palette(ts_area_fill, n_grp)
             a_base = (list(ts_area_fill)
                       if isinstance(ts_area_fill, (list, tuple))
                       else [ts_area_fill])
@@ -2287,7 +2601,7 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
             cum = yc
         groups = stacked
         disp_groups = stacked
-    elif is_date and ts_area_fill is not None:
+    elif (is_date or index_x) and ts_area_fill is not None:
         nm0, xg, yg = groups[0]
         lo, hi = float(yg.min()), float(yg.max())
         pad_a = 0.04 * (hi - lo) if hi > lo else 1.0
@@ -2315,7 +2629,12 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
     fit_lines, se_polys, fit_stats = [], [], []
     err_lines = []                     # fit_errors residual segments
     if fit != "off":
-        for nm, xg, yg in groups:
+        # a date x is fit as days, the fit drawn back on the dates
+        day = 86400e9                  # nanoseconds
+        for nm, xg, yg in (
+                [(n_, xg_.astype("datetime64[ns]").astype("int64") / day,
+                  yg_) for n_, xg_, yg_ in groups]
+                if is_date else groups):
             if len(xg) < 2:
                 continue
             if fit == "loess":         # R: bands for lm and loess
@@ -2325,7 +2644,7 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
                 if fit_errors:
                     err_lines.append((xs, ys_s, f))
                 for lv in se_levels:
-                    tq = sps.t.ppf((1 + lv) / 2, len(xs) - 1)
+                    tq = sps.t.ppf((1 + lv) / 2, _loess.df)
                     se_polys.append((
                         np.concatenate([xs, xs[::-1]]),
                         np.concatenate([f + tq * se_f,
@@ -2340,23 +2659,36 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
                 err_lines.append((xs[okf], ys_s[okf], f[okf]))
             if fit == "lm":
                 for lv in se_levels:
-                    se_polys.append(_se_band(xs, ys_s, f, lv))
+                    band = _se_band(xs, ys_s, f, lv)
+                    if band is not None:
+                        se_polys.append(band)
+
+    if is_date and fit != "off":       # days back to dates
+        def _dates(v):
+            v = np.asarray(v, dtype=float)
+            return (v * day).round().astype("int64").astype(
+                "datetime64[ns]")
+        for fl in fit_lines:
+            fl["x"] = _dates(fl["x"])
+        se_polys = [(_dates(bx), by_) for bx, by_ in se_polys]
+        err_lines = [(_dates(xe), ye, fe) for xe, ye, fe in err_lines]
 
     # ----- ellipses ------------------------------------------------
     if ellipse is True:
         ellipse = 0.95
     ellipses = []
-    if ellipse:
-        if not 0 < ellipse < 1:
-            raise ValueError("ellipse is the confidence level of "
-                             "a data ellipse, between 0 and 1")
+    e_levels = _ellipse_levels(ellipse)
+    for nm, xg, yg in (groups if e_levels else []):
+        if len(xg) < 3:
+            who = "" if nm is None else f" for group '{nm}'"
+            raise ValueError(
+                f"ellipse: need at least 3 points{who}, "
+                f"found {len(xg)}")
+    # level by level, each over the groups, so ellipse k belongs to
+    # group k % n_grp
+    for lv in e_levels:
         for nm, xg, yg in groups:
-            if len(xg) < 3:
-                who = "" if nm is None else f" for group '{nm}'"
-                raise ValueError(
-                    f"ellipse: need at least 3 points{who}, "
-                    f"found {len(xg)}")
-            ellipses.append(_ellipse_region(xg, yg, ellipse))
+            ellipses.append(_ellipse_region(xg, yg, lv))
 
     if digits_d is None:
         digits_d = 2
@@ -2479,11 +2811,13 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
     fig = plt_plotly(
         disp_groups, by_name=by,
         fill=fills, border=borders, shape=pt_shape, pt_size=pt_size,
+        sizes=sizes, size_name=size_name,
         x_lab=x if xlab is None else xlab,
         y_lab=y if ylab is None else ylab,
         ax=ax, gridT1=gridT1, gridT2=ax["axT2"],
         main=main, digits_d=digits_d,
-        connect=is_date or show_runs or index_x, ln_width=line_width,
+        connect=(is_date or show_runs or index_x
+                 or bin_diam is not None), ln_width=line_width,
         is_date=is_date,
         pt_opacity=1 - transparency,
         area_polys=area_polys,
@@ -2521,6 +2855,17 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
     # runs test: connect the points and report the run analysis
     # below; the run chart's center line is the median, so a run
     # defaults center_line to "median" (XY.R ~809)
+    # unspecified, a run chart shows its median unless the values
+    #   seldom cross their mean, fewer than 15% of the steps (XY.R ~2382)
+    if center_line is None:
+        center_line = "off"
+        yc = np.asarray(yv, dtype=float)
+        yc = yc[np.isfinite(yc)]
+        if index_x and len(yc) > 1:
+            m_c = yc.mean()
+            n_change = int(np.sum((yc[1:] > m_c) != (yc[:-1] > m_c)))
+            if n_change / (len(yc) - 1) >= 0.15:
+                center_line = "median"
     run_lines = None
     if show_runs:
         m_run, run_lines = _run_analysis(yv, digits_d, True)
@@ -2536,7 +2881,7 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
             m_cl, lbl = float(np.median(yv)), " median"
         else:                          # "zero": line but no label
             m_cl, lbl = 0.0, ""
-        gray = to_hex("gray50")
+        gray = as_plotly_color("gray50")
         fig.add_hline(y=m_cl, line=dict(color=gray, dash="dash",
                                         width=1))
         if lbl:
@@ -2601,7 +2946,7 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
             fig.add_trace(go.Scatter(
                 x=xs2, y=f2, mode="lines",
                 name="Fit (no outliers)",
-                line=dict(color=to_hex(
+                line=dict(color=as_plotly_color(
                     get_option("fit_color", "#5C4032")
                     if fit_color is None else fit_color),
                     width=get_option("fit_lwd", 2)
@@ -2638,6 +2983,8 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
         say(xc.suggest_series(pre, ".Index", y, dname, given,
                               ser_extra, run=True, pt_size=pt_size),
             xc.run_summary(yv, dd_r), run_lines[1:])
+    elif bin_diam is not None:         # the bin tables are the report
+        pass
     else:
         say(*scatter_report(groups, fit_stats, md_lines))
         if fit_new is not None and fit in _FIT_NEW_OK and show:
@@ -2660,4 +3007,94 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
 # font_size= scales all text of the returned figure
 from .stats_out import attach_stats as _attach_stats  # noqa: E402
 from .style import with_theme as _with_theme  # noqa: E402
-XY = font_scaled(_attach_stats(_with_theme(XY), capture=True))
+from .utils import file_output  # noqa: E402
+def _banking(x, y, data, filter, facet):
+    """lattice's aspect="xy": banking to 45 degrees, the median of
+    |dx/dy| between x-adjacent points, each difference scaled by the
+    range of its variable, the median over the facet panels.
+    R analog: lattice::banking() of prepanel.default.xyplot"""
+    d = data.query(filter) if filter is not None else data
+    fcols = ([] if facet is None else
+             [facet] if isinstance(facet, str) else list(facet))
+    d = d[[x, y] + fcols].dropna()
+    xn = d[x]
+    if pd.api.types.is_datetime64_any_dtype(xn):
+        xn = xn.astype("datetime64[ns]").astype("int64")
+    xn = xn.to_numpy(dtype=float)
+    yn = d[y].to_numpy(dtype=float)
+    rx, ry = np.ptp(xn), np.ptp(yn)
+    if rx == 0 or ry == 0:
+        return 1.0
+    keys = ([np.zeros(len(d), int)] if not fcols else
+            [d[c].astype(str).to_numpy() for c in fcols])
+    key = pd.Series(list(zip(*keys)))
+    banks = []
+    for k in key.unique():
+        m = (key == k).to_numpy()
+        od = np.argsort(xn[m], kind="stable")
+        dx = np.diff(xn[m][od]) / rx
+        dy = np.diff(yn[m][od]) / ry
+        ok = (dx != 0) & (dy != 0)
+        if ok.any():
+            banks.append(float(np.median(np.abs(dx[ok] / dy[ok]))))
+    return float(np.median(banks)) if banks else 1.0
+
+
+def _set_aspect(fig, ratio, width=700):
+    """Size the figure so each panel's height is ratio times its
+    width, from the panel's share of the plotting area and the
+    margins, at width pixels unless the figure sets its own."""
+    lay = fig.layout
+    W = lay.width or width
+    m = lay.margin
+    ml = 80 if m.l is None else m.l
+    mr = 80 if m.r is None else m.r
+    mt = 100 if m.t is None else m.t
+    mb = 80 if m.b is None else m.b
+    xd = lay.xaxis.domain or (0, 1)
+    yd = lay.yaxis.domain or (0, 1)
+    panel_w = (xd[1] - xd[0]) * (W - ml - mr)
+    H = ratio * panel_w / (yd[1] - yd[0]) + mt + mb
+    fig.update_layout(width=W, height=round(H))
+
+
+def _with_aspect(func):
+    """aspect= the shape of the panels as their height over width,
+    lattice's aspect: a number, "xy" to bank the median slope to 45
+    degrees, or "fill", the default, the panels filling the figure."""
+    import functools
+    import inspect
+    sig = inspect.signature(func)
+
+    @functools.wraps(func)
+    def wrapper(*args, aspect="fill", **kwargs):
+        if not (aspect in ("fill", "xy") or (
+                isinstance(aspect, (int, float))
+                and not isinstance(aspect, bool) and aspect > 0)):
+            raise ValueError(
+                'aspect is the panel height over its width: a positive '
+                'number, "xy" to bank\nto 45 degrees, or "fill"')
+        fig = func(*args, **kwargs)
+        if aspect == "fill" or not hasattr(fig, "layout"):
+            return fig
+        if aspect == "xy":
+            b = sig.bind_partial(*args, **kwargs).arguments
+            x, y = b.get("x"), b.get("y")
+            if not (isinstance(x, str) and isinstance(y, str)
+                    and b.get("data") is not None
+                    and x in b["data"] and y in b["data"]):
+                raise ValueError(
+                    'aspect="xy" banks the slopes of one x variable '
+                    "and one y variable of the data")
+            ratio = _banking(x, y, b["data"], b.get("filter"),
+                             b.get("facet"))
+        else:
+            ratio = float(aspect)
+        _set_aspect(fig, ratio)
+        return fig
+
+    return wrapper
+
+
+XY = file_output(font_scaled(_attach_stats(_with_theme(_with_aspect(XY)),
+                                            capture=True)))