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

lessPy/XY.py

@@ -63,20 +63,24 @@ from .plt_forecast import plt_forecast
 from .plt_plotly import plt_plotly
 from .plt_smooth import plt_smooth
 from .plt_time import plt_time
+from .sunflower_plotly import sunflower_plotly
 from .plt_mat_plotly import scatter_matrix
+from . import x_console as xc
+from .stats_out import _stat_by_levels
 from .stats_out import (
     facet_summary, md_outliers, resolve_quiet, xy_stats)
 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,
-    font_scaled)
+    plotly_style, square_layout, marks, to_hex, x_grid,
+    font_scaled, by_colors)
 from .utils import (
-    category_order, get_column, get_option, pretty, resolve_facet,
+    STAT_FUN, STAT_LBL, category_order, get_column, get_option,
+    pretty, resolve_facet,
 )
 
-_FORMS = ("scatter", "smooth", "contour")
+_FORMS = ("scatter", "smooth", "contour", "sunflower")
 _FITS = ("off", "loess", "lm", "ls", "null", "exp", "quad",
          "power", "log")
 
@@ -191,55 +195,362 @@ def _fit_new_table(groups, fit, fit_power, x_new, x_name, y_name,
     return lines
 
 
-def _loess(xv, yv, span):
-    """R-style loess at the sorted x values: local quadratic
-    regression with tri-cube weights, gaussian family, computed
-    exactly at each x (R surface="direct"). Also the SE of fit
-    from the equivalent-kernel rows, as predict(l.ln, se=TRUE).
-    R analog: .plt.fit() loess(y.lv ~ x.lv, span=span)"""
+def _loess_rows(xs, q_pt, span, degree, rw):
+    """The local fit at q_pt as linear operators on y: rows giving
+    the fitted value and the slope there. Tri-cube weights on the
+    floor(n*span) nearest points (times the robustness weights),
+    polynomial of the given degree centered at q_pt.
+    R analog: ehg127() of the loess Fortran"""
+    n = len(xs)
+    q = min(n, max(int(span * n + 1e-5), degree + 1))
+    d = np.abs(xs - q_pt)
+    h = np.partition(d, q - 1)[q - 1]
+    if span > 1:                       # window widens past data,
+        h *= span ** 0.5               # verified against R loess
+    if h > 0:
+        w = np.clip(1 - (d / h) ** 3, 0, 1) ** 3
+    else:                              # window is exact x ties
+        w = (d == 0).astype(float)
+    w = w * rw
+    nz = np.flatnonzero(w)
+    # 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] / sc
+    return val, slope
+
+
+def _loess_kd(xs, span, cell=0.2):
+    """Leaf cells of R's kd tree on one sorted x: the bounding box
+    widened by 0.5% each side, a cell split at its median x (moved
+    off ties) while it holds more than floor(n*span*cell) points.
+    Returns (lower, upper, split) per leaf, the split for the walk
+    down the tree. R analog: ehg126(), ehg124()"""
+    n = len(xs)
+    lo, hi = float(xs[0]), float(xs[-1])
+    mu = 0.005 * max(hi - lo, 1e-10 * max(abs(lo), abs(hi)) + 1e-30)
+    fc = int(np.floor(n * span * cell))
+    nodes = []                         # (l, u, vlo, vhi), 1-based
+
+    def build(l, u, vlo, vhi):
+        leaf = (u - l) + 1 <= fc
+        if not leaf:
+            m = (l + u) // 2
+            off = 0
+            while l <= m + off < u:
+                if xs[m + off - 1] == xs[m + off]:
+                    off = -off
+                    if off >= 0:
+                        off += 1
+                else:
+                    m += off
+                    break
+            v = float(xs[m - 1])
+            leaf = v == vlo or v == vhi
+        if leaf:
+            nodes.append((vlo, vhi))
+            return
+        build(l, m, vlo, v)
+        build(m + 1, u, v, vhi)
+
+    build(1, n, lo - mu, hi + mu)
+    return nodes
+
+
+def _loess(xv, yv, span, degree=2, family="gaussian"):
+    """R's default loess at the sorted x values: local fits of the
+    given degree at the vertices of a kd tree, each giving a value
+    and a slope, joined by cubic Hermite interpolation within each
+    cell (surface="interpolate"). family="symmetric" reweights by
+    the bisquare of the residuals over 4 iterations. Also the SE of
+    fit from the rows of the resulting smoother, as predict(l.ln,
+    se=TRUE). span may be given as (span, degree, family).
+    R analog: .plt.fit() loess(y.lv ~ x.lv, span, degree, family)"""
+    if isinstance(span, tuple):
+        span, degree, family = span
     od = np.argsort(xv, kind="stable")
-    xs, ys = xv[od], yv[od]
+    xs, ys = np.asarray(xv, float)[od], np.asarray(yv, float)[od]
     n = len(xs)
-    q = min(n, max(int(span * n), 3))  # points in the window
-    f = np.empty(n)
-    l2 = np.empty(n)                   # ||l_i||^2, for se.fit
-    trL = 0.0                          # trace of the smoother L
-    for i in range(n):
-        d = np.abs(xs - xs[i])
-        h = np.partition(d, q - 1)[q - 1]
-        if span > 1:                   # window widens past data,
-            h *= span ** 0.5           # verified against R loess
-        if h > 0:
-            w = np.clip(1 - (d / h) ** 3, 0, 1) ** 3
-        else:                          # window is exact x ties
-            w = (d == 0).astype(float)
-        nz = np.flatnonzero(w)
-        xc = xs[nz] - xs[i]
-        X = np.column_stack((np.ones(len(nz)), xc, xc * xc))
-        XtW = X.T * w[nz]
-        li = (np.linalg.pinv(XtW @ X) @ XtW)[0]  # equiv. kernel
-        f[i] = li @ ys[nz]
-        l2[i] = li @ li
-        trL += li[np.searchsorted(nz, i)]
-    res = ys - f
-    dof = n - 2 * trL + l2.sum()       # tr[(I-L)'(I-L)]
+    cells = _loess_kd(xs, span)
+    verts = sorted({v for c in cells for v in c})
+    rw = np.ones(n)
+    n_iter = 4 if family == "symmetric" else 1
+    for it in range(n_iter):
+        rows = {v: _loess_rows(xs, v, span, degree, rw) for v in verts}
+        L = np.empty((n, n))
+        for i, z in enumerate(xs):
+            for v0, v1 in cells:       # x on a split goes left
+                if z <= v1:
+                    break
+            hh = v1 - v0
+            u = (z - v0) / hh
+            g0, s0 = rows[v0]
+            g1, s1 = rows[v1]
+            L[i] = ((1 - u) ** 2 * (1 + 2 * u) * g0
+                    + u * u * (3 - 2 * u) * g1
+                    + (u * (1 - u) ** 2 * s0 - u * u * (1 - u) * s1) * hh)
+        f = L @ ys
+        res = ys - f
+        if it < n_iter - 1:            # R lowesw(): bisquare weights
+            cmad = 6 * np.median(np.abs(res))
+            if cmad < np.finfo(float).tiny:
+                rw = np.ones(n)
+            else:
+                r = np.abs(res)
+                rw = np.where(r > 0.999 * cmad, 0.0,
+                              np.where(r > 0.001 * cmad,
+                                       (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)
 
 
+_QQ_LAB = {".normal": "Normal Quantiles",
+           ".lognormal": "Lognormal Quantiles",
+           ".exponential": "Exponential Quantiles",
+           ".uniform": "Uniform Quantiles"}
+
+
+def _qq_quantiles(y, key):
+    """Theoretical quantiles, one per value of y in the row order of
+    y (NaN where y is missing): the i-th smallest y pairs with the
+    i-th smallest quantile of the distribution fit by y's moments.
+    R analog: .qq.quantiles() (qq.R)"""
+    y = np.asarray(y, dtype=float)
+    ok = ~np.isnan(y)
+    n = int(ok.sum())
+    if n < 3:
+        raise ValueError(
+            "A q-q chart requires at least 3 non-missing values of y, "
+            f"but only {n} found.")
+    yv = y[ok]
+    m, sd = yv.mean(), yv.std(ddof=1)
+    if sd == 0:
+        raise ValueError(
+            "All values of y are the same, so there is no "
+            "distribution\nto compare against a theoretical "
+            "distribution.")
+    if key == ".lognormal" and (yv <= 0).any():
+        raise ValueError(
+            "A lognormal distribution is defined only for positive "
+            f"values,\nbut y has {(yv <= 0).sum()} value(s) of zero or "
+            "less.\n\nFor data that include zero, consider .exponential")
+    if key == ".exponential" and (yv < 0).any():
+        raise ValueError(
+            "An exponential distribution is defined only for "
+            f"non-negative\nvalues, but y has {(yv < 0).sum()} "
+            "negative value(s).")
+    a = 3 / 8 if n <= 10 else 0.5      # R ppoints()
+    p = (np.arange(1, n + 1) - a) / (n + 1 - 2 * a)
+    if key == ".normal":
+        q = sps.norm.ppf(p, m, sd)
+    elif key == ".lognormal":
+        lg = np.log(yv)
+        q = np.exp(sps.norm.ppf(p, lg.mean(), lg.std(ddof=1)))
+    elif key == ".exponential":
+        q = -m * np.log1p(-p)
+    else:
+        q = m - np.sqrt(3) * sd + p * 2 * np.sqrt(3) * sd
+    out = np.full(len(y), np.nan)
+    rk = np.empty(n, dtype=int)        # rank, ties.method="first"
+    rk[np.argsort(yv, kind="stable")] = np.arange(n)
+    out[ok] = q[rk]
+    return out
+
+
+def _qq_reference(fig, fit_color, fit_lwd):
+    """The 45-degree reference of a q-q chart in every panel, from
+    the range of that panel's plotted values, drawn beneath the
+    points. R analog: plt.plotly.R qq reference"""
+    panels = {}
+    for tr in fig.data:
+        if tr.type != "scatter" or tr.x is None or tr.y is None:
+            continue
+        key = (tr.xaxis or "x", tr.yaxis or "y")
+        v = np.r_[np.asarray(tr.x, float), np.asarray(tr.y, float)]
+        v = v[np.isfinite(v)]
+        if len(v):
+            lo, hi = panels.get(key, (np.inf, -np.inf))
+            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=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),
+                       showlegend=False, hoverinfo="skip")
+            for (xa, ya), (lo, hi) in panels.items()]
+    k = len(refs)
+    fig.add_traces(refs)
+    fig.data = fig.data[-k:] + fig.data[:-k] if k else fig.data
+    return fig
+
+
+def _ts_ylab(y_name, unit, aggregated, ts_agg):
+    """Default value-axis label of a time series: the aggregation
+    and the time unit, as "Total Sales by Year"; a vector of y
+    (y_name None) is named by its legend, so "Total by Year", and
+    with no aggregation to report either, no label. R analog: the
+    y.lab of .plt.main() for a date x"""
+    if unit in (None, "unknown"):
+        return y_name or ""
+    tu = "days" if unit == "days7" else unit
+    tu = tu[:-1] if tu.endswith("s") else tu
+    agg = (("Total" if ts_agg == "sum" else "Mean")
+           if aggregated else "")
+    if y_name is None and not agg:
+        return ""
+    return " ".join(p for p in (agg, y_name, "by", tu.capitalize())
+                    if p)
+
+
 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.
@@ -260,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
@@ -291,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(
@@ -303,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"])
@@ -335,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),
@@ -364,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
@@ -373,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,
@@ -432,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,
@@ -443,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]
@@ -467,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),
@@ -478,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:
@@ -493,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))
 
@@ -502,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:
@@ -588,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,
@@ -599,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)
@@ -678,13 +1008,13 @@ 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:
         fills = [fill] * k
     else:
-        fills = [BASE_COLORS[i % len(BASE_COLORS)]
-                 for i in range(k)]
+        fills = by_colors(k)           # theme's palette, as R
     if transparency is None:
         transparency = get_option("trans_pt_fill", 0.10)
     if ellipse is True:
@@ -736,13 +1066,19 @@ def _ts_facet(xv, yv, facet_arr, facet_order, fill0, border0,
               pt_size, pt_opacity, x_lab, y_lab, main, digits_d,
               area_fill=None, area_split=0,
               facet_name=None, facet2_arr=None,
-              facet2_order=None, facet2_name=None, n_col=1):
+              facet2_order=None, facet2_name=None, n_col=1,
+              by_arr=None, by_order=None, by_name=None,
+              line_width=1.5, frcsts=None, ts_PI=0.95):
     """One time-series panel per facet level on shared axes,
     following the faceted-scatter conventions (_xy_facet):
     first level on the top panel, strip labels. The x axis
     uses plotly's native date ticks, as the single-panel time
     series does. R analog: the lattice cont_cont path for a
-    date x. facet2: the two-facet grid, rows = facet2 levels."""
+    date x. facet2: the two-facet grid, rows = facet2 levels.
+    by: several series per panel in the legend's colors, unfilled
+    unless area_fill is asked for. frcsts: a forecast per panel
+    (panel index -> plt_forecast result), every panel on one scale
+    that holds the prediction intervals."""
     labels, pos, sel, n_row_g, n_col = facet_panels(
         facet_arr, facet_order, facet2_arr, facet2_order,
         facet_name, facet2_name, n_col)
@@ -752,15 +1088,22 @@ def _ts_facet(xv, yv, facet_arr, facet_order, fill0, border0,
         px = 5
     mode_pts = "lines+markers" if px > 0 else "lines"
 
-    axT2 = pretty(float(np.nanmin(yv)), float(np.nanmax(yv)))
+    y_all = [np.asarray(yv, float)]
+    for fr in (frcsts or {}).values():
+        y_all += [np.asarray(fr["y_lwr"], float),
+                  np.asarray(fr["y_upr"], float)]
+    y_all = np.concatenate(y_all)
+    axT2 = pretty(float(np.nanmin(y_all)), float(np.nanmax(y_all)))
     fmt2 = get_tick_fmt(axT2, digits_d)
     ax = {"axT1": None, "axL1": None,
           "axT2": axT2,
           "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)
@@ -768,39 +1111,66 @@ def _ts_facet(xv, yv, facet_arr, facet_order, fill0, border0,
         rng_pad = 0.04 * (axT2[-1] - axT2[0])  # panel-clipped
         base = min(max(float(area_split), axT2[0] - rng_pad),
                    axT2[-1] + rng_pad)
+    if by_arr is None:
+        series = [(None, np.ones(len(xv), dtype=bool), fill0,
+                   border0)]
+    else:
+        by_s = np.asarray(by_arr).astype(str)
+        cols = by_colors(len(by_order))
+        series = [(str(lv), by_s == str(lv), cols[g], cols[g])
+                  for g, lv in enumerate(by_order)]
     for i in range(n_f):
-        m = sel[i]
         row, col = pos[i]
-        if area_fill is not None and m.any():
+        for nm, bm, f_c, b_c in series:
+            m = sel[i] & bm
+            if not m.any():
+                continue
+            od = np.argsort(xv[m], kind="stable")
+            xm, ym = xv[m][od], yv[m][od]
+            if area_fill is not None:
+                fig.add_trace(go.Scatter(
+                    x=np.concatenate([xm, xm[-1:], xm[:1]]),
+                    y=np.concatenate([ym, [base, base]]),
+                    mode="none", fill="toself",
+                    fillcolor=area_fill, hoverinfo="skip",
+                    showlegend=False,
+                ), row=row, col=col)
+            hv = hover if nm is None else (
+                f"{by_name}: {nm}<br>" + hover)
             fig.add_trace(go.Scatter(
-                x=np.concatenate([xv[m], xv[m][-1:],
-                                  xv[m][:1]]),
-                y=np.concatenate([yv[m], [base, base]]),
-                mode="none", fill="toself",
-                fillcolor=area_fill, hoverinfo="skip",
-                showlegend=False,
-            ), row=row, col=col)
-        fig.add_trace(go.Scatter(
-            x=xv[m], y=yv[m], mode=mode_pts,
-            marker=(dict(symbol="circle", size=px,
-                         sizemode="diameter",
-                         color=make_trans(fill0, pt_opacity),
-                         opacity=1,
-                         line=dict(color=to_hex(border0),
-                                   width=1))
-                    if "markers" in mode_pts else None),
-            line=dict(color=to_hex(border0), width=1.5),
-            hovertemplate=hover, showlegend=False,
-        ), row=row, col=col)           # first level top-left
+                x=xm, y=ym, mode=mode_pts if line_width > 0
+                else "markers",
+                marker=(dict(symbol="circle", size=px,
+                             sizemode="diameter",
+                             color=make_trans(f_c, pt_opacity),
+                             opacity=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=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,
+            ), row=row, col=col)       # first level top-left
+        if frcsts and i in frcsts:
+            _forecast_traces(fig, frcsts[i], ts_PI, row=row, col=col,
+                             legend=i == min(frcsts))
 
     finish_facet(fig, labels, ax, x_lab, y_lab,
                  gridT1=None, style_opts=style_opts,
                  n_col=n_col, pos=pos)
+    if by_arr is not None or frcsts:
+        fig.update_layout(showlegend=True,
+                          legend=legend_style(by_name, style_opts)
+                          if by_arr is not None else None)
     # ts panels: y spans the data; native date grid on x
     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))
@@ -810,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
@@ -880,11 +1260,14 @@ def _run_analysis(yv, digits_d, show_detail):
     lines.append(f"\nTotal number of runs: {n_runs}")
     lines.append("Total number of values that do not equal the "
                  f"median: {n - len(eq)}")
-    if eq:
+    if eq:                             # listed only with show_runs
         if show_detail:
             lines.append("\nValues ignored that equal the median")
             lines += [f"    #{j}  {y[j - 1]:.{dd}f}" for j in eq]
-        lines.append(f"Total number of values ignored: {len(eq)}")
+            lines.append(f"Total number of values ignored: {len(eq)}")
+    else:
+        lines.append("Total number of values ignored that equal the "
+                     "median: 0")
     return m, lines
 
 
@@ -903,18 +1286,19 @@ 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"))
 
 
-def _forecast_traces(fig, frcst, ts_PI):
+def _forecast_traces(fig, frcst, ts_PI, row=None, col=None,
+                     legend=True):
     """Overlay the forecast on the time series display: model-fit
     line, PI band with dotted boundaries, forecast line + points.
     R analog: plt.plotly.R forecast section (~lines 343-451),
@@ -925,6 +1309,16 @@ def _forecast_traces(fig, frcst, ts_PI):
     xf = np.asarray(frcst["x_fit"])    # numpy datetimes: plain
     xh = np.asarray(frcst["x_hat"])    # Timestamps break kaleido
     yf, yh = frcst["y_fit"], frcst["y_hat"]
+    at = {} if row is None else dict(row=row, col=col)
+    _add = fig.add_trace
+
+    def add(tr, **kw):                 # one legend entry per role
+        if not legend:
+            tr.showlegend = False
+        tr.legendgroup = tr.name
+        _add(tr, **at)
+
+    fig = _Adder(fig, add)
     fig.add_trace(go.Scatter(
         x=xf, y=yf, mode="lines",
         line={"color": fit_rgba, "width": 1.5},
@@ -953,6 +1347,12 @@ def _forecast_traces(fig, frcst, ts_PI):
         name="Forecast", showlegend=True))
 
 
+class _Adder:
+    """fig.add_trace routed through a placement function."""
+    def __init__(self, fig, add):
+        self._fig, self.add_trace = fig, add
+
+
 def _ts_fitted_lines(frcst, yv, x_name, y_name, ts_unit, digits_d):
     """Table of the observed y beside the model-fitted y over the
     historical dates, printed when ts_fitted=True. R analog: the
@@ -980,22 +1380,24 @@ 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,
        fit="off", fit_power=1, fit_se=None, fit_errors=False,
        fit_new=None,
-       fit_color=None, fit_lwd=None, span=0.75,
+       fit_color=None, fit_lwd=None, fit_span_loess=0.75,
+       fit_degree_loess=2, fit_family_loess="gaussian",
        ellipse=0, ellipse_fill=None, ellipse_color=None,
        ellipse_lwd=None,
        ts_unit=None, ts_agg="sum", ts_stack=False,
@@ -1010,7 +1412,7 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
        rotate_x=0, rotate_y=0, scale_x=None, scale_y=None,
        xlab=None, ylab=None, main=None, digits_d=None,
        quiet=None,
-       plot_errors=None):
+       plot_errors=None, span=None):
     """Analytic view of the relationship between two numerical
     variables, optionally grouped (by=). A date x displays as a
     time series. Variables are strings naming columns of the
@@ -1034,14 +1436,54 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
            (contour_n, contour_nbins, contour_points,
             contour_legend)):
         form = "contour"
+    contour_n_user = contour_n         # a matrix cell defaults to 8
     contour_n = 20 if contour_n is None else contour_n
     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
+    # gets the sunflower's own reason (XY.R)
+    if form == "sunflower" and by is not None:
+        raise ValueError(
+            'Parameter by is not available for form="sunflower".\n\n'
+            "A petal count is defined for one set of coordinates, not\n"
+            "separately within each group, so overlaid groups would\n"
+            "interleave their petals at a shared coordinate.\n"
+            "To stratify the same two variables, use facet, which "
+            "draws\neach group in its own panel with its own "
+            "coordinates.")
+    if form == "sunflower" and (isinstance(x, (list, tuple))
+                                or isinstance(y, (list, tuple))):
+        raise ValueError(
+            "The petal count is defined for one set of coordinates, "
+            "not\nseparately for each series, so a vector of x or y "
+            'variables\nis not available for form="sunflower". To '
+            'overlay the series,\nuse form="scatter".')
+    if isinstance(by, (list, tuple)):
+        raise ValueError(
+            "Only one by variable is permitted, but more than one "
+            f"specified:\n  by = {list(by)}\n\n"
+            "The groups of by are overlaid within the panel, "
+            "distinguished by\ncolor and optionally symbol. That one "
+            "channel is carried by the\nfirst variable, so a second "
+            "has no encoding left by which to\nseparate its levels.\n"
+            "To stratify by a second variable, use facet, which draws "
+            "each of\nits groups in a panel of its own.")
     if form != "scatter" and by is not None:
         raise ValueError(
-            'by= is active only for a scatter plot, '
-            'form="scatter"')
+            f'Parameter by is not available for form="{form}".\n\n'
+            f"A {form} plot summarizes the joint density over the "
+            "whole\nplotting region, so summaries superimposed on it "
+            "would obstruct\none another rather than remain "
+            "distinguishable.\nTo stratify the same two variables, "
+            "use facet, which draws\neach group in its own panel with "
+            "its own density.")
     if add is not None and form in ("contour", "smooth"):
         raise ValueError(
             'add is not active for "contour" or "smooth" plots')
@@ -1051,16 +1493,30 @@ 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:
+        raise ValueError(
+            "Parameter span has been renamed to fit_span_loess.\n\n"
+            "It sets the span of a loess fit, so the name now says "
+            "which\nfit it belongs to, alongside fit_degree_loess "
+            "and fit_family_loess.")
+    if fit_degree_loess not in (1, 2):
+        raise ValueError("fit_degree_loess: 1 or 2")
+    if fit_family_loess not in ("gaussian", "symmetric"):
+        raise ValueError('fit_family_loess: "gaussian" or "symmetric"')
+    # the loess settings travel together to every fit (R: loess(...,
+    # span, degree, family) in .plt.fit())
+    span = (float(fit_span_loess), int(fit_degree_loess),
+            fit_family_loess)
     if plot_errors is not None:
         raise ValueError(
             "Parameter plot_errors has been renamed to fit_errors. "
             "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:
@@ -1070,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(
@@ -1091,16 +1544,13 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
             raise ValueError(
                 "outlier flagging (MD_cut/out_cut) applies to "
                 'the scatter form, form="scatter"')
-    if ts_unit is not None and facet is not None:
-        raise ValueError(
-            "ts_unit does not yet apply to facet plots")
     if (n_row is not None or n_col is not None) \
             and facet is None:
         raise ValueError("n_row and n_col lay out facet panels: "
                          "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
@@ -1112,14 +1562,35 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
     if ts_ahead > 0:
         if ts_source not in ("fable", "classic"):
             raise ValueError('ts_source: "fable" or "classic"')
-        if by is not None:
-            raise ValueError(
-                "Can only forecast a single time series, "
-                "so no by=")
-        if facet is not None:
-            raise ValueError(
-                "Can only forecast a single time series, "
-                "so no facet=")
+        if by is not None:             # XY.R: the overlay channel
+            raise ValueError(            # is not available
+                "A forecast draws its fit, prediction interval, and "
+                "forecast\nin the series' own colors, so the overlay "
+                "of by= groups is not\navailable to it. To forecast "
+                "each group, use facet=, which\nforecasts each panel "
+                "on one scale.")
+
+    # for the report: the caller's own names, the parameters named in
+    # the call (which the suggestions skip), the digits as given
+    data_in = data
+    digits_user = digits_d
+    x_call = x                         # as written, keyword included
+    given = {nm for nm, v in (
+        ("enhance", enhance or None), ("fill", fill), ("color", color),
+        ("fit", None if fit == "off" else fit),
+        ("out_cut", out_cut or None), ("MD_cut", MD_cut or None),
+        ("pt_shape", None if pt_shape == "circle" else pt_shape),
+        ("pt_size", None if pt_size == 1 else pt_size),
+        ("line_width", None if line_width == 1.5 else line_width),
+        ("ts_ahead", ts_ahead or None), ("ts_unit", ts_unit),
+        ("ts_agg", None if ts_agg == "sum" else ts_agg),
+        ("ts_seasons", ts_seasons), ("ts_area_fill", ts_area_fill),
+        ("ts_stack", ts_stack or None)) if v is not None}
+    show = not resolve_quiet(quiet)
+
+    def say(*comps):
+        if show:
+            print(xc.report(*comps))
 
     if filter is not None:
         data = data.query(filter)
@@ -1150,16 +1621,131 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
         return scatter_matrix(
             mat_df, fit=("off" if fit in ("off", "null")
                          else fit),
-            digits_d=digits_d, main=main)
+            digits_d=digits_d, main=main, form=form,
+            contour_n=contour_n_user,
+            contour_nbins=contour_nbins,
+            contour_points=contour_points, smooth_bins=smooth_bins,
+            smooth_power=smooth_power)
+    # a vector of y on a date x: one series per variable, overlaid
+    # 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]
+        if not pd.api.types.is_datetime64_any_dtype(xd) \
+                and not pd.api.types.is_numeric_dtype(xd):
+            from .date_infer import date_infer as _infer_dates
+            try:
+                xd = _infer_dates(xd)
+            except Exception:
+                pass
+        if pd.api.types.is_datetime64_any_dtype(xd):
+            if by is not None:
+                raise ValueError(
+                    "A vector of y variables overlays its variables as "
+                    "the series of the\nplot, which spends the color "
+                    "dimension that by requires.\nTo display a "
+                    "grouping variable, use facet=, which panels the "
+                    "series.")
+            fcols = ([facet] if isinstance(facet, str) else
+                     list(facet) if isinstance(facet, (list, tuple))
+                     else [])
+            long = data[[x] + fcols + list(y)].copy()
+            long[x] = xd
+            long = long.melt(id_vars=[x] + fcols, value_vars=list(y),
+                             var_name="Series", value_name="Value")
+            long["Series"] = pd.Categorical(long["Series"],
+                                            categories=list(y))
+            if ylab is None:
+                from .plt_time import _infer_unit
+                ylab = _ts_ylab(None, ts_unit if ts_unit is not None
+                                else _infer_unit(long[x].to_numpy()),
+                                ts_unit is not None, ts_agg)
+            fig_l = XY(x, "Value", data=long, by="Series", facet=facet,
+                       ts_unit=ts_unit, ts_agg=ts_agg,
+                       ts_stack=ts_stack, ts_area_fill=ts_area_fill,
+                       ts_area_split=ts_area_split, pt_size=pt_size,
+                       line_width=line_width, n_row=n_row, n_col=n_col,
+                       fill=fill, xlab=xlab, ylab=ylab, main=main,
+                       digits_d=digits_d, quiet=True,
+                       rotate_x=rotate_x, rotate_y=rotate_y)
+            fig_l.update_layout(legend_title_text="")
+            pre_l, dn_l = xc.call_names(data_in)
+            say(xc.suggest_series(
+                pre_l, x, list(y), dn_l, given,
+                "".join(f', {k}="{v}"' if isinstance(v, str)
+                        else f", {k}={v}"
+                        for k, v in (("ts_unit", ts_unit),)
+                        if v is not None), pt_size=pt_size))
+            return fig_l
+
     if x_multi or y_multi:
-        return _apply_rotate(_xy_series(
+        # a vector against a categorical variable is Chart()'s dot
+        # chart, named rather than drawn (XY.R)
+        one = y if x_multi else x
+        if (isinstance(one, str) and one in data.columns
+                and not pd.api.types.is_numeric_dtype(data[one])
+                and not pd.api.types.is_datetime64_any_dtype(
+                    data[one])):
+            vec = x if x_multi else y
+            vec_s = "[" + ", ".join(f"'{v}'" for v in vec) + "]"
+            raise ValueError(
+                "XY() requires a continuous x and a continuous y.\n"
+                f"{one} is categorical.\n\nFor several values at each "
+                f"level of {one}, use Chart()\nwith a vector of y "
+                f"variables:\n  Chart('{one}', y={vec_s}, form='dot')")
+        fig_s = _apply_rotate(_xy_series(
             x, y, data, x_multi, by, facet, form, n_row, n_col,
             fill, transparency, pt_shape, pt_size,
             fit, fit_power, fit_se, fit_lwd, span,
             ellipse, ellipse_fill, ellipse_lwd,
             MD_cut, out_cut,
-            xlab, ylab, main, digits_d, quiet),
+            xlab, ylab, main, digits_d, True),
             rotate_x, rotate_y)
+        # the report: one correlation per plotted variable, each
+        # headed by its name (R overwrote all but the last)
+        pre, dname = xc.call_names(data_in)
+        names = list(x) if x_multi else list(y)
+        other = data[y if x_multi else x]
+        comps = [xc.suggest_scatter(pre, x, y, dname, given)]
+        if (fit in ("off", "lm")
+                and pd.api.types.is_numeric_dtype(other)):
+            for nm in names:
+                xv_ = pd.to_numeric(data[nm], errors="coerce")
+                pair = (xv_, other) if x_multi else (other, xv_)
+                head = (f"Variable: {nm} with {y}" if x_multi
+                        else f"Variable: {x} with {nm}")
+                comps.append(["", head] + xc.cor_block(
+                    pair[0].to_numpy(float), pair[1].to_numpy(float),
+                    nm if x_multi else x, y if x_multi else nm))
+        say(*comps)
+        return fig_s
 
     # ----- row_names: each row label identifies a single case, a
     # categorical axis that belongs to Chart(form="dot")
@@ -1176,21 +1762,18 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
             f"  display the values of {cont} directly with Chart():\n"
             f"  Chart('row_names', y='{cont}', form='dot')")
 
-    # stat, sort, and the segments_x/_y droplines served the dot
-    # plot XY() once drew of a categorical variable, now Chart()'s;
-    # R's stat aggregates y within bins of x (n_bins), not ported
+    # sort and the segments_x/_y droplines served the dot plot XY()
+    # once drew of a categorical variable, now Chart()'s
     if stat is not None:
-        cat_, cont = "x", "y"
-        for a, b in ((x, y), (y, x)):
-            if (isinstance(a, str) and isinstance(b, str)
-                    and a in data.columns and b in data.columns
-                    and not pd.api.types.is_numeric_dtype(data[a])):
-                cat_, cont = a, b
-        raise ValueError(
-            "stat in XY() aggregates y within bins of x (n_bins), "
-            "which is not yet ported. For a statistic of a numerical "
-            "variable across the levels of a categorical one, use "
-            f"Chart():\n  Chart('{cat_}', y='{cont}', stat='{stat}')")
+        if stat not in STAT_FUN:
+            raise ValueError("stat must be one of "
+                             + ", ".join(f'"{k}"' for k in STAT_FUN))
+        if (by is not None or facet is not None
+                or isinstance(x, (list, tuple))
+                or isinstance(y, (list, tuple))):
+            raise ValueError(
+                "stat plots one statistic of y at each value of x: "
+                "no by=, facet=, or vector of variables")
     for nm, v in (("sort", None if sort == "0" else sort),
                   ("segments_x", segments_x),
                   ("segments_y", segments_y)):
@@ -1204,23 +1787,185 @@ 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)
 
+    # a keyword in the x role names no variable, so it is matched
+    # without regard to case: .index for the run chart, .normal,
+    # .lognormal, .exponential, .uniform for a q-q chart (XY.R)
+    qq_key = None
+    if (isinstance(x, str) and x.startswith(".")
+            and x not in data.columns):
+        key = x.lower()
+        if key == ".index":
+            x = ".Index"
+        elif key in _QQ_LAB:
+            qq_key = key
+        else:
+            raise ValueError(
+                "A name in the x role that begins with a period is a "
+                f"keyword\nfor a generated variable, but {x} is not one "
+                "of\nthe keywords, and is not a variable in the data.\n\n"
+                "Available keywords, matched without regard to case:\n"
+                "  .index  generates the consecutive integers of a run "
+                "chart\n  " + ", ".join(_QQ_LAB) + "  each generates\n"
+                "    the theoretical quantiles of the corresponding "
+                "q-q chart")
+    if qq_key is not None and (isinstance(y, (list, tuple))
+                               or form != "scatter"):
+        raise ValueError(
+            "A q-q chart plots one y variable as a scatterplot "
+            'against its theoretical quantiles: one y, form="scatter"')
+
     index_x = isinstance(x, str) and x == ".Index"
     index_y = isinstance(y, str) and y == ".Index"
-    x_ser = _resolve(x, "x")
     y_ser = _resolve(y, "y")
+    x_ser = (pd.Series(np.nan, index=data.index, name=_QQ_LAB[qq_key])
+             if qq_key is not None else _resolve(x, "x"))
+    if qq_key is not None:
+        x = _QQ_LAB[qq_key]
     if index_x:                 # for axis labels below
         x = "Index"
     if index_y:
         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")
 
+    # q-q: the quantiles of y, regenerated within each group of by
+    # and each panel of facet, so every group reads against its own
+    # distribution; both axes then share one range (XY.R)
+    if qq_key is not None:
+        if not pd.api.types.is_numeric_dtype(y_ser):
+            raise ValueError(
+                "A q-q chart displays the distribution of a continuous "
+                "variable,\nbut the y variable is not numeric.")
+        grp = None
+        for g in (by_ser, facet_ser, facet2_ser):
+            if g is not None:
+                gs = g.astype(str).where(g.notna())
+                grp = gs if grp is None else grp + "\x1f" + gs
+        yv = y_ser.to_numpy(dtype=float)
+        if grp is None:
+            qv = _qq_quantiles(yv, qq_key)
+        else:
+            qv = np.full(len(yv), np.nan)
+            for lv in grp.dropna().unique():
+                i = (grp == lv).to_numpy()
+                if (~np.isnan(yv[i])).sum() >= 3:
+                    qv[i] = _qq_quantiles(yv[i], qq_key)
+        x_ser = pd.Series(qv, index=data.index, name=x)
+        if scale_x is None and scale_y is None:
+            pr = pretty(float(np.nanmin(np.r_[qv, yv])),
+                        float(np.nanmax(np.r_[qv, yv])))
+            scale_x = scale_y = (pr[0], pr[-1], len(pr) - 1)
+
+    # the report (x_console): ports of R's printers, built as the
+    # display is; xy_stats() records the numbers for fig.stats
+    pre, dname = xc.call_names(data_in)
+    _lbls = ((getattr(data_in, "attrs", {}) or {})
+             .get("variable_labels", {}) or {})
+    x_lbl, y_lbl = _lbls.get(x), _lbls.get(y)
+    dd_r = (xc.xy_digits(pd.to_numeric(y_ser, errors="coerce")
+                         .to_numpy(float), digits_user)
+            if not isinstance(y, (list, tuple)) else 3)
+
+    def scatter_report(groups_, fit_stats_, md_lines_):
+        xy_stats(groups_, x, y, fit_stats_, digits_d, by_name=by)
+        if stat_lines is not None:     # R reports the levels alone
+            return [stat_lines]
+        comps = [xc.suggest_scatter(pre, x_call, y, dname, given,
+                                    by=by)]
+        if md_lines_ is not None:
+            comps.append(md_lines_)
+        # correlation for no fit or a linear one, not with by, not
+        # for a q-q chart (.plt.txt)
+        if fit in ("off", "lm") and by is None and qq_key is None:
+            for _, xg, yg in groups_:
+                comps.append(xc.cor_block(xg, yg, x, y, x_lbl, y_lbl))
+        # the fit that enhance= supplies is drawn, not reported (R)
+        if (fit not in ("off", "null") and fit_stats_
+                and not (enhance and "fit" not in given)):
+            comps.append(xc.fit_text(fit_stats_, fit, fit_power, y,
+                                     dd_r, by_name=by))
+        return comps
+
+    def facet_report(xv_s):
+        """XY.R's summary of x per grouping variable; x's own
+        decimals, at least 2, as X() now gives them"""
+        sd = max(xc.max_dd(xv_s), 2)
+        summ = ["", f"---------- Summary Statistics for {x}"]
+        for g, nm in ((by_ser, by), (facet_ser, facet_name),
+                      (facet2_ser, facet2_name)):
+            if g is not None:
+                summ += [""] + xc.vbs_summary(
+                    xv_s, g.to_numpy(), nm, sd,
+                    order=category_order(g))
+        return summ
+
+    # 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)):
+            if not pd.api.types.is_numeric_dtype(data[a_]):
+                raise ValueError(
+                    "stat in XY() plots a statistic of y at each value "
+                    "of a continuous x. For a statistic of a numerical "
+                    "variable across the levels of a categorical one, "
+                    f"use Chart():\n  Chart('{a_}', y='{b_}', "
+                    f"stat='{stat}')")
+        okx = x_ser.notna()
+        stat_lines = _stat_by_levels(
+            pd.to_numeric(y_ser[okx]), x_ser[okx], y, x,
+            max(xc.max_dd(y_ser.to_numpy(float)) + 1, 2))
+        agg = (pd.to_numeric(y_ser[okx]).groupby(x_ser[okx])
+               .agg(STAT_FUN[stat]).dropna())
+        data = pd.DataFrame({x: agg.index.to_numpy(float),
+                             y: agg.to_numpy(float)})
+        x_ser, y_ser = data[x], data[y]
+        if ylab is None:
+            ylab = f"{STAT_LBL[stat]} of {y}"
+
     # facet needs a categorical variable; a numeric one with more
     # than 25 distinct values is almost surely continuous, so stop
     # and point to a category conversion (XY.R ~1168). A category
@@ -1259,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
@@ -1302,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:
@@ -1313,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]
@@ -1327,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 "
@@ -1340,17 +2141,29 @@ 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) --------------------------
-    if is_date and ts_unit is not None:
+    # facets aggregate within each panel, below
+    ts_agg_done = is_date and ts_unit is not None and facet_ser is None
+    if ts_agg_done:
         x_ser, y_ser, by_ser, ts_unit = plt_time(
             x_ser, y_ser, by_ser, ts_unit, ts_agg,
             quiet=resolve_quiet(quiet))
-    if is_date and (ts_stack or ts_area_fill is not None) \
+    if is_date and ylab is None and facet_ser is None:  # a given
+        # ylab names the axis
+        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()), ts_agg_done, ts_agg)
+    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
 
@@ -1377,6 +2190,87 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
         add_means = (form in ("scatter", "smooth")
                      and facet is None)
 
+    # ----- sunflower: petals where observations coincide ----------
+    if form == "sunflower":
+        if is_date:
+            raise ValueError(
+                'form="sunflower" plots two continuous variables, '
+                "not a time series")
+        if ellipse is True:
+            ellipse = 0.95
+        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))
+                  else [ellipse])
+
+        def overlay(fig_, xv_, yv_, row, col):
+            at = {} if row is None else dict(row=row, col=col)
+            for lv in e_lvls:
+                ex, ey = _ellipse_region(xv_, yv_, float(lv))
+                fig_.add_trace(go.Scatter(
+                    x=ex, y=ey, mode="lines",
+                    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)
+                        if ellipse_lwd is None else ellipse_lwd),
+                    hoverinfo="skip", showlegend=False), **at)
+            if fit not in ("off", "null"):
+                if fit == "loess":
+                    xs_, _, f_, _ = _loess(xv_, yv_, span)
+                else:
+                    xs_, _, f_ = _plt_fit(xv_, yv_, fit, fit_power)
+                fig_.add_trace(go.Scatter(
+                    x=xs_, y=f_, mode="lines",
+                    line=dict(color=f_col, width=f_lwd),
+                    hoverinfo="skip", showlegend=False), **at)
+
+        xv_f = x_ser.to_numpy(dtype=float)
+        yv_f = y_ser.to_numpy(dtype=float)
+        if facet is not None:
+            n_lvl = len(category_order(facet_ser))
+            n_col_sf = (int(n_col) if n_col is not None else
+                        math.ceil(n_lvl / int(n_row)) if n_row
+                        is not None else math.ceil(math.sqrt(n_lvl)))
+            fig = sunflower_plotly(
+                xv_f, yv_f, x if xlab is None else xlab,
+                y if ylab is None else ylab, main,
+                facet=facet_ser.to_numpy(),
+                facet_order=category_order(facet_ser),
+                facet_name=facet_name,
+                facet2=(None if facet2_ser is None
+                        else facet2_ser.to_numpy()),
+                facet2_order=(None if facet2_ser is None
+                              else category_order(facet2_ser)),
+                facet2_name=facet2_name, n_col=n_col_sf,
+                pt_size=pt_size, fill=fill, color=color,
+                overlay=overlay,
+                digits_d=2 if digits_d is None else digits_d,
+                axis_fmt=axis_fmt, axis_x_pre=axis_x_pre,
+                axis_y_pre=axis_y_pre)
+            xy_stats([(None, xv_f, yv_f)], x, y,
+                     digits_d=2 if digits_d is None else digits_d)
+            say(facet_report(xv_f))
+        else:
+            fig = sunflower_plotly(
+                xv_f, yv_f, x if xlab is None else xlab,
+                y if ylab is None else ylab, main, pt_size=pt_size,
+                fill=fill, color=color, overlay=overlay,
+                digits_d=2 if digits_d is None else digits_d,
+                axis_fmt=axis_fmt, axis_x_pre=axis_x_pre,
+                axis_y_pre=axis_y_pre)
+            fs = []
+            if fit not in ("off", "null"):
+                if fit == "loess":
+                    xs_, ys_, f_, _ = _loess(xv_f, yv_f, span)
+                else:
+                    xs_, ys_, f_ = _plt_fit(xv_f, yv_f, fit, fit_power)
+                fs = [(None, fit, ys_, f_, xs_)]
+            say(*scatter_report([(None, xv_f, yv_f)], fs, None))
+        return _apply_rotate(fig, rotate_x, rotate_y)
+
     # ----- facet: one panel per level -----------------------------
     if facet is not None:
         facet2_arr = f2_order = None
@@ -1399,12 +2293,10 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
         if form in ("contour", "smooth"):
             if ellipse is True:
                 ellipse = 0.95
-            if not resolve_quiet(quiet):
-                print("\n".join(xy_stats(
-                    [(None, x_ser.to_numpy(dtype=float),
-                      y_ser.to_numpy(dtype=float))], x, y,
-                    digits_d=2 if digits_d is None
-                    else digits_d)))
+            xy_stats([(None, x_ser.to_numpy(dtype=float),
+                       y_ser.to_numpy(dtype=float))], x, y,
+                     digits_d=2 if digits_d is None else digits_d)
+            say(facet_report(x_ser.to_numpy(dtype=float)))
             return _apply_rotate(plt_contour_facet(
                 x_ser.to_numpy(dtype=float),
                 y_ser.to_numpy(dtype=float),
@@ -1433,11 +2325,57 @@ 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
-            if by is not None:
-                raise NotImplementedError(
-                    "by= with facet= for a time series is not "
-                    "yet ported")
+        # 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()
+            ts_by = by_ser.to_numpy() if by_ser is not None else None
+            agg_done = ts_unit is not None
+            if agg_done:
+                parts = [s_.astype(str).to_numpy() for s_ in
+                         (facet_ser, facet2_ser, by_ser)
+                         if s_ is not None]
+                key = pd.Series(["\x1f".join(t) for t in zip(*parts)],
+                                index=x_ser.index)
+                xa, ya, ka, ts_unit = plt_time(
+                    x_ser, y_ser, key, ts_unit, ts_agg,
+                    quiet=resolve_quiet(quiet))
+                cols = list(zip(*[str(k).split("\x1f")
+                                  for k in ka.astype(str)]))
+                x_ser, y_ser = xa, ya
+                f_arr = np.asarray(cols[0], dtype=object)
+                ci = 1
+                if facet2_ser is not None:
+                    facet2_arr = np.asarray(cols[ci], dtype=object)
+                    ci += 1
+                if by_ser is not 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 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()),
+                                agg_done, ts_agg)
+            frcsts = {}
+            if ts_ahead > 0:
+                xs_all = x_ser.to_numpy()
+                ys_all = y_ser.to_numpy(dtype=float)
+                for i_f, lv in enumerate(f_order):
+                    mm = f_arr == lv
+                    if mm.sum() < 4:
+                        continue
+                    od = np.argsort(xs_all[mm], kind="stable")
+                    frcsts[i_f] = plt_forecast(
+                        xs_all[mm][od], ys_all[mm][od], x, y,
+                        ts_unit=ts_unit, ts_ahead=ts_ahead,
+                        ts_method=ts_method, ts_source=ts_source,
+                        ts_error=ts_error, ts_trend=ts_trend,
+                        ts_seasons=ts_seasons, ts_alpha=ts_alpha,
+                        ts_beta=ts_beta, ts_gamma=ts_gamma,
+                        ts_PI=ts_PI, digits_d=digits_d)
             if transparency is None:
                 transparency = get_option("trans_pt_fill", 0.10)
             fill0 = (get_option("pt_color", "#324E5C")
@@ -1451,7 +2389,7 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
             ts_fig = _ts_facet(
                 x_ser.to_numpy(),
                 y_ser.to_numpy(dtype=float),
-                facet_ser.to_numpy(), category_order(facet_ser),
+                f_arr, f_order,
                 fill0, border0, pt_size, 1 - transparency,
                 x if xlab is None else xlab,
                 y if ylab is None else ylab,
@@ -1460,9 +2398,22 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
                 area_split=float(ts_area_split),
                 facet_name=facet_name, 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,
+                by_arr=ts_by,
+                by_order=(None if by_ser is None else
+                          [str(v) for v in category_order(by_ser)]),
+                by_name=by, line_width=line_width,
+                frcsts=frcsts, ts_PI=ts_PI)
             if ts_n_x_tics is not None:     # date-axis tick count
                 ts_fig.update_xaxes(nticks=int(ts_n_x_tics))
+            if show:
+                for i_f, fr in frcsts.items():
+                    print(f"\n{facet_name}: {f_order[i_f]}")
+                    print("\n".join(fr["report"]))
+                    print("Forecast\n--------")
+                    print(fr["forecast"].to_string(
+                        float_format=lambda v:
+                        f"{v:.{(2 if digits_d is None else digits_d) + 2}f}"))
             return _apply_rotate(ts_fig, rotate_x, rotate_y)
         by_arr = by_order = None
         if by_ser is not None:
@@ -1472,8 +2423,7 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
         if fill is None:
             fills_f = ([get_option("pt_color", "#324E5C")]
                        if n_grp == 1
-                       else [BASE_COLORS[i % len(BASE_COLORS)]
-                             for i in range(n_grp)])
+                       else by_colors(n_grp))
         else:
             fills_f = (list(fill)
                        if isinstance(fill, (list, tuple))
@@ -1482,35 +2432,18 @@ 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]
         if ellipse is True:
             ellipse = 0.95
-        if not resolve_quiet(quiet):   # overall relationship
-            dd_s = 2 if digits_d is None else digits_d
-            xv_s = x_ser.to_numpy(dtype=float)
-            print("\n".join(xy_stats(
-                [(None, xv_s, y_ser.to_numpy(dtype=float))],
-                x, y, digits_d=dd_s)))
-            # summary table per grouping variable, ~ XY.R's
-            # .vbs_summary_table pivot block
-            print(f"\n---------- Summary Statistics for {x}")
-            if by_ser is not None:
-                print()
-                print(facet_summary(xv_s, by_ser.to_numpy(),
-                                    by, dd_s))
-            print()
-            print(facet_summary(xv_s, facet_ser.to_numpy(),
-                                facet_name, dd_s))
-            if facet2_ser is not None:
-                print()
-                print(facet_summary(xv_s,
-                                    facet2_ser.to_numpy(),
-                                    facet2_name, dd_s))
-        return _apply_rotate(_xy_facet(
+        xv_s = x_ser.to_numpy(dtype=float)
+        xy_stats([(None, xv_s, y_ser.to_numpy(dtype=float))],
+                 x, y, digits_d=2 if digits_d is None else digits_d)
+        say(facet_report(xv_s))
+        fig_f = _apply_rotate(_xy_facet(
             x_ser.to_numpy(dtype=float),
             y_ser.to_numpy(dtype=float),
             by_arr, by_order,
@@ -1533,8 +2466,12 @@ 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)
+        return fig_f
 
     # ----- groups and colors --------------------------------------
     xv = x_ser.to_numpy() if is_date \
@@ -1548,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
@@ -1592,9 +2550,9 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
     n_grp = len(groups)
     if fill is None:
         fills = ([get_option("pt_color", "#324E5C")] if n_grp == 1
-                 else [BASE_COLORS[i % len(BASE_COLORS)]
-                       for i in range(n_grp)])
+                 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
@@ -1616,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])
@@ -1642,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
@@ -1670,17 +2629,22 @@ 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
                 xs, ys_s, f, se_f = _loess(xg, yg, span)
                 fit_lines.append({"name": nm, "x": xs, "y": f})
-                fit_stats.append((nm, fit, ys_s, f))
+                fit_stats.append((nm, fit, ys_s, f, xs))
                 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,
@@ -1690,28 +2654,41 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
             okf = np.isfinite(f)       # exp/log back-transform NaN
             fit_lines.append({"name": nm, "x": xs[okf],
                               "y": f[okf]})
-            fit_stats.append((nm, fit, ys_s[okf], f[okf]))
+            fit_stats.append((nm, fit, ys_s[okf], f[okf], xs[okf]))
             if fit_errors:
                 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
@@ -1740,11 +2717,7 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
             axis_fmt=axis_fmt, axis_x_pre=axis_x_pre,
             axis_y_pre=axis_y_pre)
         _apply_rotate(fig, rotate_x, rotate_y)
-        if not resolve_quiet(quiet):
-            print("\n".join(xy_stats(groups, x, y, fit_stats,
-                                     digits_d)))
-            if md_lines is not None:
-                print("\n" + "\n".join(md_lines))
+        say(*scatter_report(groups, fit_stats, md_lines))
         return fig
 
     # ----- forecast (date x, ts_source="classic") -------------------
@@ -1767,7 +2740,7 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
             frcst["y_lwr"], frcst["y_upr"]] if frcst else []))
     if scale_y is not None:            # explicit y scale
         axT2 = np.linspace(float(scale_y[0]), float(scale_y[1]),
-                           int(scale_y[2]))
+                           int(scale_y[2]) + 1)  # n intervals
     else:
         axT2 = pretty(float(np.nanmin(ys_all)),
                       float(np.nanmax(ys_all)))
@@ -1783,7 +2756,7 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
         if scale_x is not None:        # explicit x scale
             axT1 = np.linspace(float(scale_x[0]),
                                float(scale_x[1]),
-                               int(scale_x[2]))
+                               int(scale_x[2]) + 1)  # n intervals
         else:
             axT1 = pretty(float(np.nanmin(xs_all)),
                           float(np.nanmax(xs_all)))
@@ -1832,19 +2805,19 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
         _apply_rotate(fig, rotate_x, rotate_y)
         if add_means:
             _add_means(fig, xv, yv)
-        if not resolve_quiet(quiet):
-            print("\n".join(xy_stats(groups, x, y, fit_stats,
-                                     digits_d)))
+        say(*scatter_report(groups, fit_stats, md_lines))
         return fig
 
     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,
@@ -1882,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)
@@ -1897,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:
@@ -1911,6 +2895,8 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
 
     if add_means:                      # enhance: mean crosshair
         _add_means(fig, xv, yv)
+    if qq_key is not None:
+        _qq_reference(fig, fit_color, fit_lwd)
 
     if scale_x is not None:            # explicit axis ranges
         fig.update_xaxes(range=[float(scale_x[0]),
@@ -1960,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)
@@ -1968,28 +2954,43 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
                     dash="dash"),
                 showlegend=True))
 
+    # the series displays: suggestions (with the forecast report
+    # and table when one is made), the run analysis of a run chart
+    ser_extra = "".join(
+        f", {k}={v!r}" if isinstance(v, str) else f", {k}={v}"
+        for k, v in (("by", by), ("ts_unit", ts_unit),
+                     ("ts_ahead", ts_ahead or None))
+        if v is not None).replace("'", '"')
     if frcst is not None:
         _forecast_traces(fig, frcst, ts_PI)
-        if not resolve_quiet(quiet):
+        if show:
             for ln in frcst["report"]:
                 print(ln)
             if ts_fitted:              # observed vs model-fit table
                 print("\n".join(_ts_fitted_lines(
                     frcst, yv, x, y, ts_unit, digits_d)))
-            print("\nForecast\n--------")
+            say(xc.suggest_series(pre, x, y, dname, given,
+                                  ser_extra, pt_size=pt_size))
+            print("Forecast\n--------")
             print(frcst["forecast"].to_string(
                 float_format=lambda v: f"{v:.{digits_d + 2}f}"))
-    elif not is_date and not resolve_quiet(quiet):
-        print("\n".join(xy_stats(groups, x, y, fit_stats,
-                                 digits_d)))
-        if fit_new is not None and fit in _FIT_NEW_OK:
+    elif is_date:
+        say(xc.suggest_series(pre, x, y, dname, given, ser_extra,
+                              pt_size=pt_size))
+    elif index_x:                      # run chart: R's run analysis
+        if run_lines is None:
+            _, run_lines = _run_analysis(yv, digits_d, False)
+        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:
             print("\n".join(_fit_new_table(
                 groups, fit, fit_power, fit_new, x, y, digits_d)))
-        if run_lines is not None:
-            print("\n".join(run_lines))
-        if md_lines is not None:
-            print("\n" + "\n".join(md_lines))
-        if jitter_x > 0 or jitter_y > 0:
+        if (jitter_x > 0 or jitter_y > 0) and show:
             print("\nSome Parameter values (can be manually set)")
             print("-" * 55)
             print(f"size: {float(pt_size):.2f} "
@@ -2004,4 +3005,96 @@ def XY(x, y=None, data=None, filter=None, by=None, facet=None,
 
 
 # font_size= scales all text of the returned figure
-XY = font_scaled(XY)
+from .stats_out import attach_stats as _attach_stats  # noqa: E402
+from .style import with_theme as _with_theme  # noqa: E402
+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)))