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

lessPy/Chart.py

@@ -35,14 +35,18 @@ from .plt_add import plt_add
 from .bubble_plotly import bubble_plotly
 from .dot_plotly import dot_plotly
 from .hier_plotly import (
-    hier_aggregate, hier_color_resolve, hier_plotly,
+    hier_aggregate, hier_color_resolve, hier_color_resolve_byfac,
+    hier_plotly,
 )
 from .pie_plotly import pie_plotly
 from .plt_plotly import plt_plotly
 from .profile_plotly import profile_facet_plotly
 from .radar_plotly import radar_plotly
 from .plotly_utils import build_title, font_scaled
-from .stats_out import chart_stats, resolve_quiet
+from .stats_out import (
+    CALL_STATS, ChartStats, attach_stats, chart_stats,
+    chart_stats_data, resolve_quiet,
+)
 from .utils import (
     STAT_FUN, STAT_LBL, category_order as _category_order,
     facet_values, get_column as _get_column, get_option, pretty,
@@ -62,6 +66,36 @@ _THEME_PALETTE = {
 }
 
 
+# each theme's single bar color, a bar chart without by drawn in it
+#   (R: style(theme)$bar$bar_fill_discrete, alpha from trans_bar_fill)
+_THEME_BAR_FILL = {
+    "lightbronze": "#7B8C96", "dodgerblue": "#1874CDE6",
+    "darkred": "#8B0000E6", "gray": "#595959E6", "gold": "#CD9B1DE6",
+    "darkgreen": "#006400E6", "blue": "#4876FFE6", "red": "#CD2626E6",
+    "rose": "#CD9B9BE6", "green": "#006400E6", "purple": "#9B30FFE6",
+    "sienna": "#CD6839E6", "brown": "#8B6969E6", "orange": "#FFA500E6",
+    "white": "#FFFFFFE6", "slatered": "#A35763E6",
+}
+
+
+def _color_range(pal, n):
+    """n colors of a named palette, alpha dropped. Two grays are set
+    further apart than the palette spaces them, gray60 and gray30,
+    as in R. R analog: .color_range()"""
+    from .getColors import getColors
+    if pal == "grays" and n == 2:
+        return ["#999999", "#4D4D4D"]
+    cols = getColors(pal, n=max(1, n), quiet=True)
+    return [c[:7] if len(c) == 9 and c.endswith("FF") else c
+            for c in cols]
+
+
+def _palette_names():
+    from .getColors import _SEQ_NAMES, _SEQ_R, _VIRIDIS
+    return set(_SEQ_NAMES) | set(_SEQ_R) | set(_VIRIDIS) | {
+        "hues", "Okabe-Ito", "Tableau", "distinct"}
+
+
 def _theme_fill(theme, n):
     """A theme's fill: an n-color sequential palette in the theme's
     hue. R analog: the theme branch of the fill assignment."""
@@ -80,9 +114,10 @@ def _facet_table(x_s, y_s, by_s, stat, is_agg, x_order, by_order,
     """Frequency or stat table for one facet level, on the global
     category set(s) so panels stay aligned; absent cells fill 0,
     as in R's xtabs. Series without by, DataFrame (by x cats)
-    with. proportion normalizes the per-panel counts (no y, no by)
-    to sum to 1, the faceted stat_x="proportion". Used by the
-    faceted radar and bubble paths."""
+    with. proportion normalizes the per-panel counts to sum to 1,
+    the faceted stat_x="proportion": the whole panel without by,
+    each by row with it. Used by the faceted radar and bubble
+    paths."""
     if by_s is None:
         if y_s is None:
             t = x_s.groupby(x_s, observed=True).size() \
@@ -108,8 +143,12 @@ def _facet_table(x_s, y_s, by_s, stat, is_agg, x_order, by_order,
         t = STAT_FUN[stat](
             df.groupby(["by", "x"], observed=True)["y"]
         ).unstack("x")
-    return (t.reindex(index=by_order, columns=x_order)
-            .fillna(0))
+    t = t.reindex(index=by_order, columns=x_order).fillna(0)
+    if proportion and y_s is None:
+        # each group's distribution over x: every by row sums to 1
+        tot = t.sum(axis=1)
+        t = t.div(tot.where(tot != 0), axis=0).fillna(0)
+    return t
 
 _FORMS = ("bar", "radar", "bubble", "dot", "pie", "icicle", "treemap",
           "profile")
@@ -170,7 +209,7 @@ def _dot_origin_grid(vals, origin_in=None, is_counts=None):
 def _chart_items(data, items, y, by, facet, form, stat, sort,
                  sort_miss, stack100, horiz, fill, theme, labels,
                  labels_size, gap, labels_cut, xlab, ylab, main,
-                 legend_title,
+                 legend_title, power, radius, one_plot,
                  n_col, n_row, axis_fmt, axis_x_pre, rotate_x,
                  rotate_y, quiet):
     """The multi-item stacked chart and its faceted form. R analog:
@@ -185,22 +224,74 @@ def _chart_items(data, items, y, by, facet, form, stat, sort,
     if facet is not None and form != "bar":
         raise ValueError(
             'facet with multiple x variables requires form="bar"')
-    if form == "bubble":
-        raise NotImplementedError(
-            "the bubble plot frequency matrix of multiple x "
-            'variables is not yet ported; use form="bar"')
-    if form != "bar":
+    if form not in ("bar", "bubble"):
         raise ValueError(
             'Multiple x variables only available for form="bar"')
     if y is not None or stat is not None:
         raise ValueError(
             "A multi-item chart counts the responses to each item, "
             "so y and stat do not apply")
-    if not horiz:
-        raise NotImplementedError(
-            "the vertical multi-item chart is not yet ported")
     cols = [_get_column(data, it, "x") for it in items]
+
+    # one_plot: the items compose one chart when they share one set of
+    #   responses, decided from the data unless given; otherwise each
+    #   variable is its own bar chart. R analog: Chart.R one_plot test
+    sets = [set(c.dropna().unique()) for c in cols]
+    widest = max(sets, key=len)
+    shared = not any(st - widest for st in sets)
+    if one_plot is None:
+        one_plot = shared
+    if not one_plot:
+        if facet is not None:
+            raise ValueError(
+                "facet requires the multi-item stacked chart, which "
+                "needs the x variables to share the same response "
+                "categories: a separate chart per variable is not a "
+                "single composition, so there are no panels to "
+                "condition")
+        if form != "bar":
+            raise ValueError(
+                'A separate chart per variable is a bar chart, so it '
+                'needs form="bar"')
+        return _chart_per_variable(data, items, cols, fill, xlab,
+                                   main, quiet)
+
     frq, wm, numeric = items_table(cols, items)
+
+    if form == "bubble":
+        # the bubble plot frequency matrix: one row of bubbles per
+        #   item, one column per response, each bubble sized by its
+        #   count, the items in the order given from the bottom unless
+        #   sorted by their mean. R analog: .dpmat.main()
+        order = list(items)
+        if sort != "0":
+            order = list(wm.sort_values(ascending=(sort == "+"),
+                                        kind="stable").index)
+        _set_stats(ChartStats(n_dim=2, freq=frq[order].T,
+                              mean=wm[order]),
+                   items_stats_lines(
+                       frq[order], wm[order],
+                       "Frequencies of Responses by Variable", numeric,
+                       with_sum=True), quiet)
+        # the matrix lists its first row at the top, so reverse the
+        #   order to draw the first item at the bottom, as R does
+        mat = frq[order[::-1]].T.astype(float)
+        mat.index.name, mat.columns.name = "Item", "Response"
+        cut = power / 2.5 * float(np.nanmax(mat.to_numpy()))
+        if fill is None:
+            fill = get_option("bar_fill_cont", "#96AAC3")
+        return bubble_plotly(
+            mat, x_name="Response", y_name="Count", by_name="Item",
+            x_lab="" if xlab is None else xlab,
+            y_lab="" if ylab is None else ylab,
+            main=main or None,
+            fill=(list(fill)[::-1] if isinstance(fill, (list, tuple))
+                  else [fill] * len(order)),
+            border=get_option("pt_color", "#324E5C"),
+            opacity=0.6, power=power, radius=radius, digits_d=0,
+            labels="input" if labels is None else labels,
+            labels_color=get_option("bubble_text_color", "#F7F2E6"),
+            label_min_value=cut)
     fill_use = (fill if isinstance(fill, (list, tuple))
                 else [fill] * len(frq.index) if fill is not None
                 else items_fill(theme, len(frq.index)))
@@ -217,10 +308,11 @@ def _chart_items(data, items, y, by, facet, form, stat, sort,
         if sort != "0":
             order = list(wm.sort_values(ascending=(sort == "+"),
                                         kind="stable").index)
-        if show:
-            # the table lists the items top of the chart first
-            print("\n".join(_items_print(
-                frq[order[::-1]], wm[order[::-1]], numeric)))
+        # the table lists the items top of the chart first
+        _set_stats(ChartStats(n_dim=2, freq=frq[order[::-1]].T,
+                              mean=wm[order[::-1]]),
+                   _items_print(frq[order[::-1]], wm[order[::-1]],
+                                numeric), quiet)
         return bc_items_plotly(
             frq, order, fill_use,
             labels="%" if labels is None else labels,
@@ -230,7 +322,7 @@ def _chart_items(data, items, y, by, facet, form, stat, sort,
             y_lab="" if ylab is None else ylab,
             legend_title=leg, main=main or None,
             axis_fmt=axis_fmt, axis_x_pre=axis_x_pre,
-            rotate_x=rotate_x, rotate_y=rotate_y)
+            rotate_x=rotate_x, rotate_y=rotate_y, horiz=horiz)
 
     # faceted: a panel is a fraction of the width of the single
     #   chart, too narrow for segment labels, and the paneled chart
@@ -262,24 +354,27 @@ def _chart_items(data, items, y, by, facet, form, stat, sort,
     facet_order = _category_order(fac[keep])
     resp = list(frq.index)
     tbls = {}
+    rep_lines, panels = [], {}
     for lv in facet_order:
         m = keep & (fac == lv)
         f_lv, w_lv, _ = items_table([c[m] for c in cols], items) \
             if all(c[m].notna().any() for c in cols) else (
                 pd.DataFrame(0, index=resp, columns=items), None, None)
         f_lv = f_lv.reindex(index=resp, fill_value=0)
-        if show:
-            if w_lv is None:
-                w_lv = pd.Series(np.nan, index=items)
-            print("\n".join(_items_print(
-                f_lv, w_lv, numeric,
-                f"Frequencies of Responses by Variable, "
-                f"{facet_name}: {lv}")))
+        if w_lv is None:
+            w_lv = pd.Series(np.nan, index=items)
+        rep_lines += _items_print(
+            f_lv, w_lv, numeric,
+            f"Frequencies of Responses by Variable, "
+            f"{facet_name}: {lv}")
+        panels[lv] = ChartStats(freq=f_lv.T, mean=w_lv)
         t = f_lv.astype(float)
         if stack100:
             tot = t.sum(axis=0)
             t = t.div(tot.where(tot != 0), axis=1).fillna(0)
-        tbls[lv] = t[items[::-1]]       # first item at the top
+        # first item at the top, or at the left of a vertical chart
+        tbls[lv] = t[items[::-1]] if horiz else t[items]
+    _set_stats(ChartStats(n_dim=3, panels=panels), rep_lines, quiet)
     tbl = pd.DataFrame([tbls[lv].sum(axis=0) for lv in facet_order],
                        index=facet_order)
     tbl.index.name = facet_name
@@ -296,7 +391,86 @@ def _chart_items(data, items, y, by, facet, form, stat, sort,
         rotate_x=rotate_x, rotate_y=rotate_y, main=main,
         by_tbls=tbls, by_name=leg, beside=False,
         val_name=("Proportion" if stack100 else "Count"),
-        legend_title=leg)
+        legend_title=leg, horiz=horiz)
+
+
+def _chart_per_variable(data, items, cols, fill, xlab, main, quiet):
+    """One bar chart of counts per categorical variable, as panels of
+    one figure, each followed at the console by its frequencies and
+    chi-square test. Numeric variables are passed over, as are a
+    variable that identifies each case and one with a single value.
+    R analog: bc.data.frame()"""
+    from plotly.subplots import make_subplots
+    import plotly.graph_objects as go
+    from .plotly_utils import (
+                               as_plotly_color, BASE_COLORS, auto_text_color,
+                               axis_format, plotly_style, to_hex)
+    from .stats_out import _counts_1d
+    show = not resolve_quiet(quiet)
+    keep = []
+    for nm, c in zip(items, cols):
+        if is_numeric_dtype(c) and not isinstance(
+                c.dtype, pd.CategoricalDtype):
+            continue                     # R: .is.num.cat(x, 0) FALSE
+        v = c.dropna()
+        if v.nunique() >= len(v):        # identifies each case
+            continue
+        if v.nunique() == 1:
+            if show:
+                print(f"\nVariable {nm} has only one value.\n"
+                      " No bar chart produced.\n")
+            continue
+        keep.append((nm, c))
+    if not keep:
+        raise ValueError(
+            "No categorical variables, so no bar charts.\n\n"
+            "If you have integer variables that are categorical, "
+            "convert them to pandas Categorical, e.g.\n"
+            "  d['Plan'] = d['Plan'].astype('category')")
+
+    n = len(keep)
+    n_col = min(3, n)
+    n_row = math.ceil(n / n_col)
+    fig = make_subplots(rows=n_row, cols=n_col,
+                        subplot_titles=[nm for nm, _ in keep],
+                        horizontal_spacing=0.08,
+                        vertical_spacing=max(0.08, 0.3 / n_row))
+    st = plotly_style()
+    rep_lines, per_var = [], {}
+    for k, (nm, c) in enumerate(keep):
+        rep_lines += _counts_1d(c.dropna(), nm,
+                                int(c.isna().sum())) + [""]
+        per_var[nm] = chart_stats_data(c.dropna(), None, None, None,
+                                       n_miss=int(c.isna().sum()))
+        order = _category_order(c.dropna())
+        cnt = c.value_counts().reindex(order, fill_value=0)
+        f = (fill if isinstance(fill, (list, tuple))
+             else [fill] if fill is not None else BASE_COLORS)
+        cols_k = [to_hex(f[i % len(f)]) for i in range(len(cnt))]
+        r, cc = k // n_col + 1, k % n_col + 1
+        fig.add_trace(go.Bar(
+            x=[str(v) for v in cnt.index], y=cnt.to_numpy(),
+            marker=dict(color=cols_k), text=[str(v) for v in cnt],
+            textposition="inside", showlegend=False,
+            textfont=dict(color=auto_text_color(cols_k)),
+            hovertemplate=f"{nm}: %{{x}}<br>Count: %{{y}}"
+                          "<extra></extra>"), row=r, col=cc)
+        ticks = pretty(0.0, float(cnt.max()))
+        fig.update_yaxes(row=r, col=cc, tickvals=ticks,
+                         ticktext=axis_format(ticks, 0),
+                         range=[0, ticks[-1] * 1.04],
+                         gridcolor="#E5E5E5",
+                         title_text="Count" if cc == 1 else "")
+        fig.update_xaxes(row=r, col=cc, type="category",
+                         title_text=xlab or "")
+    _set_stats(ChartStats(n_dim=1, variables=per_var), rep_lines,
+               quiet)
+    fig.update_layout(
+        template=None, height=140 + 260 * n_row,
+        plot_bgcolor=as_plotly_color(st["panel_fill"]),
+        paper_bgcolor=as_plotly_color(st["window_fill"]),
+        title=(dict(text=main, x=0.5) if main else None))
+    return fig
 
 
 def _items_print(frq, wm, numeric, title=None):
@@ -305,6 +479,15 @@ def _items_print(frq, wm, numeric, title=None):
         numeric)
 
 
+def _set_stats(st, lines, quiet):
+    """Keep the statistics of this call, with the report as their
+    text, and display the report unless quiet."""
+    st["text"] = "\n".join(lines)
+    CALL_STATS.set(st)
+    if not resolve_quiet(quiet):
+        print(st["text"])
+
+
 def _profile_fill(theme):
     """One hue per series from the theme, as R's profile does:
     .color_range(.get_fill(theme), n), the qualitative hues for the
@@ -352,7 +535,7 @@ def _dot_diff_lines(cats, ydf, x_name):
 
 
 def _dot_paired(cats, ydf, sort, sort_miss, origin_x, show_diff,
-                x_name, **render):
+                x_name, quiet=None, **render):
     """Order a multi-series dot plot and draw it. Two series are a
     pair, read for the gap between them, so by default they are
     ordered by that difference, ascending so the largest positive
@@ -370,8 +553,23 @@ def _dot_paired(cats, ydf, sort, sort_miss, origin_x, show_diff,
                            kind="stable")
         cats = [cats[i] for i in order]
         ydf = ydf.iloc[order]
-    if dif_pair and show_diff:
-        print("\n".join(_dot_diff_lines(cats, ydf, x_name)))
+    if dif_pair:
+        # the difference the display presents, kept with the figure; it
+        #   is reported where R lists it (show_diff), unless quiet
+        dif = pd.Series(
+            (ydf.iloc[:, 1] - ydf.iloc[:, 0]).to_numpy(dtype=float),
+            index=cats, name=f"{ydf.columns[1]} - {ydf.columns[0]}")
+        st = CALL_STATS.get()
+        if st is None:
+            st = ChartStats(n_dim=2, values=ydf.set_axis(cats), text="")
+            CALL_STATS.set(st)
+        st["diff"] = dif
+        if show_diff:
+            lines = _dot_diff_lines(cats, ydf, x_name)
+            st["text"] = "\n".join(
+                [t for t in (st.get("text", ""), "\n".join(lines)) if t])
+            if not resolve_quiet(quiet):
+                print("\n".join(lines))
     origin, gridT = _dot_origin_grid(
         ydf.to_numpy(dtype=float).ravel(),
         origin_in=0 if (dif_pair and origin_x is None) else origin_x)
@@ -396,7 +594,7 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
           theme=None,
           labels=None, labels_position=None,
           labels_color=None, labels_size=None, labels_decimals=None,
-          labels_cut=None, segments=None,
+          labels_cut=None, segments=None, one_plot=None,
           legend_title=None, legend_position=None,
           legend_labels=None, legend_horiz=False,
           legend_size=None, legend_abbrev=None, legend_adjust=0,
@@ -453,6 +651,10 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
 
     Variables are strings naming columns of the DataFrame `data`.
     Returns a plotly Figure; call .show() to display from a script.
+    The statistics behind the chart come with it as fig.stats, read
+    as attributes or by name: fig.stats.freq, fig.stats.p_value,
+    fig.stats.text (the console report, kept when quiet=True), named
+    as R's Chart() names its returned list.
     """
 
     # ----- validate parameters ------------------------------------
@@ -566,6 +768,13 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
         raise ValueError('labels_position must be "in" or "out"')
     if axis_fmt not in ("K", ",", ".", ""):
         raise ValueError('axis_fmt must be "K", ",", "." or ""')
+    # proportions of a bar chart with by are taken within each bar,
+    #   the 100% stacked chart. R analog: .bc.main()
+    #   if (!is.null(by) && prop) stack100 <- TRUE
+    if (stat_x == "proportion" and by is not None and form == "bar"
+            and facet is None and y is None):
+        stack100 = True
+        stat_x = "count"
     if stack100:
         if form != "bar":
             raise ValueError('stack100 rescales the bars of a bar '
@@ -662,9 +871,6 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
             if sort != "0":
                 raise ValueError("Sort not applicable to Trellis "
                                  "(faceted bar) charts")
-            if stat_x == "proportion" and by is not None:
-                raise NotImplementedError(
-                    'stat_x="proportion" with by= is not yet ported')
 
     # ----- resolve variables and filter ---------------------------
     if filter is not None:
@@ -692,7 +898,8 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
             stat=stat, sort=sort, sort_miss=sort_miss,
             stack100=stack100, horiz=horiz, fill=fill, theme=theme,
             labels=labels, labels_size=labels_size, gap=gap,
-            labels_cut=labels_cut,
+            labels_cut=labels_cut, power=power, radius=radius,
+            one_plot=one_plot,
             xlab=xlab, ylab=ylab, main=main,
             legend_title=legend_title, n_col=n_col, n_row=n_row,
             axis_fmt=axis_fmt, axis_x_pre=axis_x_pre,
@@ -737,7 +944,7 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
         x_lab_dot = (xlab if xlab else ylab if ylab else val_lab)
         return _dot_paired(
             cats, ydf.reset_index(drop=True), sort, sort_miss,
-            origin_x, show_diff=not resolve_quiet(quiet), x_name=x,
+            origin_x, show_diff=True, quiet=quiet, x_name=x,
             fill=fill, border=color, pt_size=pt_size,
             x_lab=x_lab_dot, y_lab=x,
             digits_d=2 if digits_d is None else digits_d,
@@ -814,12 +1021,53 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
     facet_order = (_category_order(facet_ser)
                    if facet_ser is not None else None)
 
-    # theme=: a sequential palette in the theme's hue over the fill
-    # elements (the by groups if present, else the x categories)
-    if theme is not None and fill is None:
-        n_fill = len(by_order) if by_order is not None \
-            else len(x_order)
-        fill = _theme_fill(theme, n_fill)
+    # a theme set by style(), or by this call's theme=, which the
+    #   wrapper has applied for the call
+    if theme is None:
+        theme = get_option("theme")
+
+    # an ordered category is ordinal, so its default fill is the
+    #   theme's sequential palette, light to dark in the order of the
+    #   levels, not distinct hues. Fill encodes x without by and by
+    #   with it, so the ordering of that variable is the one that
+    #   applies. R analog: Chart.R is.ordered() fill
+    if (form == "bar" and fill is None and facet_ser is None
+            and fill_split is None and not fill_scaled):
+        enc = by_ser if by_ser is not None else x_ser
+        if (isinstance(enc.dtype, pd.CategoricalDtype)
+                and enc.cat.ordered):
+            fill = _color_range(
+                _THEME_PALETTE.get(theme, "blues"),
+                len(by_order) if by_order is not None
+                else len(x_order))
+
+    # theme=: a bar chart without by is drawn in the theme's single
+    #   bar color, which fill_scaled then varies in luminance; with
+    #   by, the levels span the theme's sequential palette, darkest
+    #   first. The default theme keeps the qualitative hues.
+    #   R analog: Chart.R fill block (theme.seq) and .bc.main()
+    if (theme is not None and fill is None
+            and theme not in ("colors", "hues")):
+        if theme not in _THEME_PALETTE:
+            raise ValueError(
+                f"unknown theme '{theme}'; one of: "
+                f"{', '.join(sorted(_THEME_PALETTE))}")
+        if by_order is not None:
+            fill = list(reversed(_color_range(_THEME_PALETTE[theme],
+                                              len(by_order))))
+        elif form == "bar":
+            fill = [_THEME_BAR_FILL.get(theme, "#595959E6")] \
+                * len(x_order)
+        else:
+            fill = _theme_fill(theme, len(x_order))
+
+    # a palette name in fill, such as "reds", names a range of colors,
+    #   one per bar, or per level of by. R analog: .bc.main()
+    #   .color_range(fill, n.levels)
+    if (form == "bar" and isinstance(fill, str) and not fill_scaled
+            and fill in _palette_names()):
+        fill = _color_range(fill, len(by_order) if by_order is not None
+                            else len(x_order))
 
     # explicit panel-grid layout: n_col wins, else derive from
     # n_row; None keeps each renderer's own default (single-column
@@ -915,35 +1163,50 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
                 f"have a numerical variable y='{y}', so specify "
                 'stat to define the aggregation, e.g., stat="mean"')
 
-    # accompanying statistics: frequencies, or the stat of y
-    if not resolve_quiet(quiet):
-        y_out = (y_ser if y_ser is not None
-                 and stat in STAT_FUN else None)
-        if by_more_sers and (y_ser is None or y_out is not None):
-            from .stats_out import nested_stats
-            print("\n".join(nested_stats(
-                [x_ser, by_ser] + by_more_sers, [x, by] + by_more,
-                y_out, stat, y,
-                2 if digits_d is None else digits_d)))
-        elif y_ser is None or y_out is not None:
-            var_lbl = data.attrs.get("variable_labels", {}) or {}
-            print("\n".join(chart_stats(
-                x_ser, by_ser, y_out, stat, x, by, y,
-                2 if digits_d is None else digits_d,
-                stack100=stack100, n_miss=n_miss_x,
-                x_lbl=var_lbl.get(x), y_lbl=var_lbl.get(y),
-                facet_ser=facet_ser, facet_name=facet_name,
-                form=form)))
-
-    # labels default for aggregated data; for counts leave labels
-    # None so bc_plotly shows the value with % lines in hover
-    # R analog: Chart.R line ~716
+    # accompanying statistics: frequencies, or the stat of y. They are
+    #   computed whether or not displayed, and returned with the figure
+    #   as fig.stats, as R's Chart() returns its list
+    y_out = (y_ser if y_ser is not None
+             and stat in STAT_FUN else None)
+    if by_more_sers and (y_ser is None or y_out is not None):
+        from .stats_out import nested_stats
+        lines = nested_stats(
+            [x_ser, by_ser] + by_more_sers, [x, by] + by_more,
+            y_out, stat, y, 2 if digits_d is None else digits_d)
+        cols_n = [x_ser, by_ser] + by_more_sers
+        df_n = pd.DataFrame({nm: c for nm, c in
+                             zip([x, by] + by_more, cols_n)})
+        _set_stats(ChartStats(
+            n_dim=len(cols_n),
+            freq=df_n.groupby([x, by] + by_more, observed=True).size()
+            if y_out is None else None),
+            lines, quiet)
+    elif y_ser is None or y_out is not None:
+        var_lbl = data.attrs.get("variable_labels", {}) or {}
+        lines = chart_stats(
+            x_ser, by_ser, y_out, stat, x, by, y,
+            2 if digits_d is None else digits_d,
+            stack100=stack100, n_miss=n_miss_x,
+            x_lbl=var_lbl.get(x), y_lbl=var_lbl.get(y),
+            facet_ser=facet_ser, facet_name=facet_name,
+            form=form)
+        _set_stats(chart_stats_data(x_ser, by_ser, y_out, stat,
+                                    facet_ser=facet_ser,
+                                    n_miss=n_miss_x),
+                   lines, quiet)
+
+    # labels default for aggregated data, the value of the statistic;
+    #   bars of counts are labeled with their percentages, as lessR's
+    #   do (getOption("values"), "%"): of the total, or of each bar for
+    #   the 100% stacked chart. R analog: Chart.R ~716, .bc.main()
     if labels is None and (stat is not None or
                            (is_agg and y_ser is not None)):
         # the bars carry a statistic, so the label is its value;
         #   beside only arranges the bars, and a percentage of a sum
         #   of means is not a quantity
         labels = "input"
+    elif labels is None and form == "bar" and y_ser is None:
+        labels = "%"
 
     # ----- hierarchical forms aggregate per nesting level ---------
     # from the raw columns, not from the flat table built below
@@ -962,6 +1225,10 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
                              facet_order=facet_order)
         fill_vec = hier_color_resolve(x_order, fill, x=x_ser,
                                       y=y_ser, stat=stat)
+        fill_vec_byfac = (None if facet_ser is None else
+                          hier_color_resolve_byfac(
+                              x_order, fill, x_ser, y_ser, stat,
+                              facet_ser, facet_order))
         if main is None:
             main = build_title(x, by_name=by_label, y_name=y,
                                stat=stat, facet_name=facet_name)
@@ -974,6 +1241,7 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
         # keep the inner rings meaningful.
         return hier_plotly(
             agg, fill_vec, type=hier_type,
+            fill_vec_byfac=fill_vec_byfac,
             x_name=x, by_name=by, facet_name=facet_name,
             main=main, border=color, digits_d=digits_d,
             labels="%" if labels is None else labels,
@@ -1021,6 +1289,11 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
                                        columns=x_order)
             if y_ser is None:
                 t = t.fillna(0)
+                if stat_x == "proportion" and not stack100:
+                    # every cell of the panel as a share of the panel,
+                    #   as lattice's prop.table(margin=panel)
+                    tot = t.to_numpy().sum()
+                    t = t / tot if tot > 0 else t
             if stack100:
                 # each bar scaled to its own total compares
                 #   composition rather than magnitude
@@ -1048,7 +1321,9 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
         elif y_ser is not None:
             val_name = y
         elif by_ser is not None:
-            val_name = "Count"
+            # named for x, as lattice's "Count of" / "Proportion of"
+            val_name = ("Proportion of " if stat_x == "proportion"
+                        else "Count of ") + x
         else:
             val_name = None             # Count/Proportion of x
         return bc_facet_plotly(
@@ -1070,9 +1345,6 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
         )
 
     if facet_ser is not None and form == "radar":
-        if stat_x == "proportion" and by_ser is not None:
-            raise NotImplementedError(
-                'stat_x="proportion" with by= is not yet ported')
         facets = {
             str(lv): _facet_table(
                 x_ser[facet_ser == lv],
@@ -1174,6 +1446,10 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
         g = df.groupby(["f", "g", "x"], observed=True)["y"]
         t = (g.sum() if y_ser is None
              else STAT_FUN[stat](g) if agg_y else g.mean())
+        if y_ser is None and stat_x == "proportion":
+            # each series is its group's distribution over x in that
+            #   panel; without by, the panel's own distribution
+            t = t / t.groupby(level=["f", "g"]).transform("sum")
         cells = {}
         for (f, gg, xx), v in t.items():
             nm = None if by_ser is None else gg
@@ -1194,8 +1470,12 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
             digits_d = 0 if y_ser is None else 2
         from .plotly_utils import axis_format
         y_lab = (ylab if ylab is not None
+                 else f"Proportion of {x}" if (y_ser is None
+                                               and stat_x == "proportion")
                  else "Count" if y_ser is None
                  else f"{STAT_LBL[stat]} of {y}" if agg_y else y)
+        if y_ser is None and stat_x == "proportion" and digits_d == 0:
+            digits_d = 2
         return profile_facet_plotly(
             cells, x_lv, series, y_tick,
             axis_format(y_tick, digits_d, axis_fmt, axis_y_pre),
@@ -1220,9 +1500,6 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
         agg_y = not is_agg and stat is not None
         cats_l, vals_l, fac_l = [], [], []
         if by_ser is not None:
-            if prop:
-                raise ValueError(
-                    'stat_x="proportion" with by= is not yet ported')
             rows = []
             for lv in facet_order:
                 m = facet_ser == lv
@@ -1236,6 +1513,10 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
                 wide = (t.unstack("by")
                         .reindex(index=[str(c) for c in x_order],
                                  columns=[str(b) for b in by_order]))
+                if prop and y_ser is None:
+                    # each group's distribution over x in this panel
+                    tot = wide.sum(axis=0)
+                    wide = wide.div(tot.where(tot != 0), axis=1)
                 rows.append(wide)
                 cats_l += list(wide.index)
                 fac_l += [str(lv)] * len(wide)
@@ -1266,8 +1547,8 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
         # an aggregated value is labeled by its statistic, as the
         #   unfaceted chart is: "Mean of Salary", not "Salary"
         if y_ser is None:
-            val_lab = ("Count" if by_ser is not None
-                       else f"Proportion of {x}" if prop
+            val_lab = (f"Proportion of {x}" if prop
+                       else "Count" if by_ser is not None
                        else f"Count of {x}")
         else:
             val_lab = f"{STAT_LBL[stat]} of {y}" if agg_y else y
@@ -1317,9 +1598,6 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
 
     # ----- build the table the renderer receives ------------------
     if y_ser is None:                        # counts of x
-        if stat_x == "proportion" and by_ser is not None:
-            raise NotImplementedError(
-                'stat_x="proportion" with by= is not yet ported')
 
         if by_ser is None:
             tbl = (x_ser.groupby(x_ser).size()
@@ -1339,11 +1617,20 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
             tbl = pd.crosstab(by_ser, x_ser)
             tbl = tbl.reindex(index=by_order, columns=x_order,
                               fill_value=0)
-            y_name = "Count"
+            if stat_x == "proportion":
+                # each group's distribution over x, so the groups are
+                #   compared whatever their sizes: every by row sums
+                #   to 1 (the bar chart took its own path above, the
+                #   100% stacked chart within each bar)
+                tot = tbl.sum(axis=1)
+                tbl = tbl.div(tot.where(tot != 0), axis=0).fillna(0)
+                y_name = "Proportion"
+            else:
+                y_name = "Count"
             if ylab is None:
-                ylab = f"Count of {x}"
+                ylab = f"{y_name} of {x}"
             if digits_d is None:
-                digits_d = 0
+                digits_d = 0 if stat_x == "count" else 2
 
     elif stat == "deviation":                # R analog: .agg()
         if by_ser is not None:
@@ -1468,6 +1755,7 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
             labels_decimals=labels_decimals,
             labels_size=0.90 if labels_size is None
                         else labels_size,
+            shares=(y_ser is None and stat_x == "proportion"),
         )
 
     if form == "radar":
@@ -1564,11 +1852,13 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
             ydf.columns = [str(c) for c in ydf.columns]
             cats = [str(c) for c in ydf.index]
             val_lab = (xlab if xlab else ylab_user if ylab_user
-                       else "Count" if y_ser is None else ylab)
+                       else ylab if (y_ser is not None
+                                     or stat_x == "proportion")
+                       else "Count")
             return _dot_paired(
                 cats, ydf.reset_index(drop=True), sort, sort_miss,
                 origin_x,
-                show_diff=not quiet_use and y_ser is None,
+                show_diff=y_ser is None, quiet=quiet,
                 x_name=x,
                 fill=fill, border=color, pt_size=pt_size,
                 x_lab=val_lab, y_lab=x, digits_d=digits_d,
@@ -1627,6 +1917,26 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
                 facet_name=facet_ttl, y_name=y_name, stat=stat)
         elif main == "":
             main = None
+        # a palette name in fill names the palette, not a color, as
+        #   for the bar chart. A sequential palette shades each slice
+        #   by its value off the palette's ramp, larger darker, as
+        #   for the treemap. R analog: Chart.R pie palette branch
+        if isinstance(fill, str) and fill in _palette_names():
+            from .hier_plotly import _HIER_SEQ
+            slices = list(tbl.columns if isinstance(tbl, pd.DataFrame)
+                          else tbl.index)
+            vals = (tbl.sum(axis=0) if isinstance(tbl, pd.DataFrame)
+                    else tbl).to_numpy(dtype=float)
+            if (fill.lower() in _HIER_SEQ and len(slices) > 1
+                    and np.ptp(vals) > 0):
+                from .getColors import getColors
+                ramp = [c[:7] for c in getColors(fill.lower(), n=256,
+                                                 quiet=True)]
+                pos = (vals - vals.min()) / np.ptp(vals)
+                fill = [ramp[i] for i in
+                        np.round(pos * (len(ramp) - 1)).astype(int)]
+            else:
+                fill = _color_range(fill, len(slices))
         return pie_plotly(
             tbl,
             x_name=x, y_name=y_name, by_name=by, main=main,
@@ -1650,8 +1960,16 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
     if (fill_split is not None or fill_scaled) \
             and isinstance(tbl, pd.Series):
         from .getColors import bar_fill_colors
-        fill = bar_fill_colors(tbl.to_numpy(dtype=float), fill,
-                               fill_split, fill_scaled, fill_chroma)
+        # one fill repeated over the bars is a single color; more
+        #   than two leave the hue to the theme, as R's .bc.main()
+        f_in = fill
+        if isinstance(fill, (list, tuple)):
+            uniq = list(dict.fromkeys(fill))
+            f_in = (uniq[0] if len(uniq) == 1
+                    else None if len(uniq) > 2 else uniq)
+        fill = bar_fill_colors(tbl.to_numpy(dtype=float), f_in,
+                               fill_split, fill_scaled, fill_chroma,
+                               theme=theme)
 
     fig = bc_plotly(
         tbl,
@@ -1687,5 +2005,30 @@ def Chart(x, y=None, data=None, filter=None, by=None, facet=None,
     return fig
 
 
+def _with_height(func):
+    """height= in inches, as lessR's Chart(height=), converted at
+    96 pixels per inch, so pdf_file= also writes that height.
+    None keeps the figure's own height."""
+    import functools
+
+    @functools.wraps(func)
+    def wrapper(*args, height=None, **kwargs):
+        if height is not None and (isinstance(height, bool) or
+                                   not isinstance(height, (int, float))
+                                   or height <= 0):
+            raise ValueError(
+                f"height is in inches, a positive number such as "
+                f"height=4, not {height!r}")
+        fig = func(*args, **kwargs)
+        if height is not None and hasattr(fig, "layout"):
+            fig.update_layout(height=round(96 * height))
+        return fig
+
+    return wrapper
+
+
 # font_size= scales all text of the returned figure
-Chart = font_scaled(Chart)
+from .style import with_theme as _with_theme  # noqa: E402
+from .utils import file_output  # noqa: E402
+Chart = file_output(_with_height(font_scaled(attach_stats(
+    _with_theme(Chart, own_param=True)))))