"""
Pie and Donut Charts
=====================

Part-of-whole composition, in the same visual language as the rest of a
figure set: the publiplots palette, the theme edge, and a legend that can
join a shared band. A pie is a one-level sunburst — ``x`` names the
wedge, ``y`` the value (omitted, rows are counted), and ``hue`` means
colour and nothing else.
"""

import pandas as pd
import publiplots as pp

df = pd.DataFrame({
    "kind": ["symptom", "admin", "lay_dx", "none"],
    "n": [52.2, 41.8, 6.0, 4.0],
})

# Not the default assignment: each category gets a colour the default
# palette would have given another one.
palette = {"symptom": "#8e8ec1", "admin": "#eeaa58",
           "lay_dx": "#e67e7e", "none": "#75b375"}

# %%
# A pie beside a bar panel
# ------------------------
# The case this plotter exists for. Both panels take the same ``palette``
# dict keyed on the same categories, so each category has one colour
# across the figure. ``barplot`` only maps ``palette`` through ``hue``,
# so the bar panel passes ``hue="kind"`` as well; the pie colours by its
# ``x`` column without being asked. ``annotate=True`` labels each wedge
# with its share of the whole, as a percentage; the two wedges too thin
# to hold theirs get them outside, on leader lines.

fig, axes = pp.subplots(ncols=2, axes_size=(50, 45))
pp.barplot(data=df, x="kind", y="n", hue="kind", palette=palette,
           legend=False, ax=axes[0])
pp.pieplot(data=df, x="kind", y="n", palette=palette, legend=False,
           ax=axes[1], annotate=True)
pp.show()

# %%
# One legend for both panels
# --------------------------
# Here the bars break each category down by year, and the pie shows the
# two years pooled. Both panels key colour on ``kind``, and each stashes
# a ``kind`` colour entry; a figure-level ``pp.legend`` band collects
# both and merges them by name, so ``kind`` is listed once, for both
# panels. Merging is by name, not by colour: where two panels draw the
# same label differently, the band keeps the first panel's swatch and,
# for a different fill or stroke width, warns. The shared ``palette``
# is what makes the merged key true of both panels.
#
# (A bar panel whose ``x`` is ``kind`` itself, as above, labels its
# categories on the axis and stashes no colour entry, so it has nothing
# to merge.)

yearly = pd.DataFrame({
    "year": ["2023"] * 4 + ["2024"] * 4,
    "kind": ["symptom", "admin", "lay_dx", "none"] * 2,
    "n": [24.1, 20.3, 3.2, 1.9, 28.1, 21.5, 2.8, 2.1],
})
fig, axes = pp.subplots(ncols=2, axes_size=(50, 45))
pp.legend(side="right")
pp.barplot(data=yearly, x="year", y="n", hue="kind", palette=palette,
           ax=axes[0])
pp.pieplot(data=yearly, x="kind", y="n", palette=palette, ax=axes[1])
pp.show()

# %%
# Counting rows
# -------------
# With ``y`` omitted, each wedge is the number of rows in its category,
# so a pie can be drawn straight from one-row-per-observation data.
# ``fmt=",.0f"`` labels the counts rather than the shares.

visits = pd.DataFrame({
    "kind": ["symptom"] * 12 + ["admin"] * 9 + ["lay_dx"] * 5
            + ["none"] * 4,
})
fig, ax = pp.subplots(axes_size=(50, 50))
pp.pieplot(data=visits, x="kind", palette=palette, ax=ax,
           annotate={"fmt": ",.0f"})
pp.show()

# %%
# A palette by name
# -----------------
# ``palette`` also takes a seaborn or publiplots palette name, assigned
# in category order.

fig, ax = pp.subplots(axes_size=(50, 50))
pp.pieplot(data=df, x="kind", y="n", palette="Set2", ax=ax)
pp.show()

# %%
# Wedge order
# -----------
# By default wedges follow the category order of the data — the same
# order a bar panel drawn from the same frame uses — running clockwise
# from twelve o'clock. ``sort=True`` orders them by descending value
# instead, and ``order=`` names the order outright. ``order=`` should
# list every category: one it leaves out is dropped and the rest
# renormalise to a full circle, with a warning.

severity = pd.DataFrame({
    "stage": ["mild", "moderate", "severe", "critical"],
    "n": [20.0, 45.0, 25.0, 10.0],
})
stage_palette = dict(zip(severity["stage"], pp.color_palette("pastel", 4)))

fig, axes = pp.subplots(ncols=4, axes_size=(36, 36))
pp.legend(side="right")
pp.barplot(data=severity, x="stage", y="n", hue="stage",
           palette=stage_palette, ax=axes[0], title="bars")
for label in axes[0].get_xticklabels():
    label.set(rotation=45, ha="right", rotation_mode="anchor")
pp.pieplot(data=severity, x="stage", y="n", palette=stage_palette,
           ax=axes[1], title="default")
pp.pieplot(data=severity, x="stage", y="n", palette=stage_palette,
           sort=True, ax=axes[2], title="sort=True")
pp.pieplot(data=severity, x="stage", y="n", palette=stage_palette,
           order=["severe", "mild", "critical", "moderate"], ax=axes[3],
           title="order=[...]")
pp.show()

# %%
# Legend order
# ------------
# ``hue_order`` reorders the legend's entries and nothing else: the
# wedges stay where the data order puts them, and every wedge keeps its
# colour.

fig, axes = pp.subplots(ncols=2, axes_size=(36, 36))
pp.pieplot(data=severity, x="stage", y="n", palette=stage_palette,
           ax=axes[0], title="default")
pp.pieplot(data=severity, x="stage", y="n", palette=stage_palette,
           hue_order=["critical", "severe", "moderate", "mild"],
           ax=axes[1], title="hue_order=[...]")
pp.show()

# %%
# Where the first wedge starts, and which way they run
# ------------------------------------------------------
# ``start_angle`` is the angle of the first wedge's leading edge, in
# degrees: 90 (the default) is twelve o'clock, 0 is three o'clock.
# ``direction`` is ``"clockwise"`` (the default) or
# ``"counterclockwise"``.

fig, axes = pp.subplots(ncols=3, axes_size=(36, 36))
pp.legend(side="right")
for ax, (start, direction) in zip(axes, [(90, "clockwise"),
                                         (0, "clockwise"),
                                         (90, "counterclockwise")]):
    pp.pieplot(data=severity, x="stage", y="n", palette=stage_palette,
               start_angle=start, direction=direction, ax=ax,
               title=f"{start}°, {direction}")
pp.show()

# %%
# A donut, with the total in the hole
# -----------------------------------
# ``donut`` is the inner radius as a fraction of the outer one.
# ``center_label`` takes a string, or a callable receiving the total, and
# is only drawn when ``donut`` is non-zero.

fig, ax = pp.subplots(axes_size=(50, 50))
pp.pieplot(data=df, x="kind", y="n", donut=0.55, palette=palette,
           center_label="{:,.0f}".format, ax=ax, annotate=True)
pp.show()

# %%
# Pulling wedges out
# ------------------
# ``pull`` is a fraction of the radius. A dict keyed by category pops
# out just those wedges — it is never positional — moving each along
# its own mid-ray with its shape unchanged. A single float explodes the
# whole chart evenly instead: every wedge moves out by the same
# distance ``t``, rim and inner edge alike, and every pair of neighbours
# ends up ``2t`` apart, the thin wedges as far from their neighbours as
# the wide ones. A pie opens a small hole at its centre to do it. ``gap``
# separates the wedges by a width in millimetres without moving them
# out: every pair of neighbours keeps it along the whole of the edge
# they share, in a pie or a donut. With a float ``pull`` the two add up.

fig, axes = pp.subplots(ncols=4, axes_size=(36, 36))
pp.legend(side="right")
pp.pieplot(data=df, x="kind", y="n", palette=palette,
           pull={"lay_dx": 0.15}, ax=axes[0],
           title='pull={"lay_dx": 0.15}')
pp.pieplot(data=df, x="kind", y="n", palette=palette, pull=0.05,
           ax=axes[1], title="pull=0.05")
pp.pieplot(data=df, x="kind", y="n", palette=palette, gap=1.0,
           ax=axes[2], title="gap=1.0")
pp.pieplot(data=df, x="kind", y="n", palette=palette, gap=1.0,
           donut=0.55, ax=axes[3], title="gap=1.0, donut=0.55")
pp.show()

# %%
# Collapsing the long tail
# -------------------------
# ``min_share`` merges every category below a threshold into one
# ``"Other"`` wedge. It applies only when at least two categories fall
# below it, so a single small category is never relabelled ``"Other"``
# on its own. ``min_share`` cannot be combined with ``order``: the
# ``"Other"`` bucket is not a category of the data, so it could not be
# named in an explicit order.

fig, ax = pp.subplots(axes_size=(50, 50))
pp.pieplot(data=df, x="kind", y="n", palette=palette, min_share=0.1,
           ax=ax, annotate=True)
pp.show()

# %%
# Labels inside, outside, or chosen per wedge
# ---------------------------------------------
# ``anchor="auto"`` (the default) measures each label against the room
# its own wedge has, and moves it outside, on a leader line, when it
# does not fit — the thin slivers below. ``"inside"`` and ``"outside"``
# force every label to one placement regardless of fit. An outside label
# is centred on its wedge's mid-ray, a little past the end of its line.
# The disc is the same size under all three: a label that leaves it
# extends past the axes rather than shrinking the pie. On their own
# mid-rays the 6.0% and 2.0% labels would just overlap, so under
# ``"outside"`` and ``"auto"`` they are nudged apart round the circle --
# by less than a degree each, their leaders leaning to follow -- until
# they are ``label_spacing`` (0.4mm) apart; the other labels stay on
# their mid-rays. "Crowded labels" below shows this at work on a long
# tail.
# Like a tick label, an outside label is a decoration: the axes title
# above it, and a legend beside it, step past it.

thin = pd.DataFrame({"kind": list("ABCD"), "n": [80.0, 12.0, 6.0, 2.0]})
fig, axes = pp.subplots(ncols=3, axes_size=(38, 38))
for ax, anchor in zip(axes, ["inside", "outside", "auto"]):
    pp.pieplot(data=thin, x="kind", y="n", legend=False, ax=ax)
    pp.annotate(ax, "wedge_values", anchor=anchor)
    ax.set_title(anchor)
pp.show()

# %%
# How far outside labels sit
# --------------------------
# ``offset`` is the length of the leader line from the rim, and
# ``leader_gap`` the space between its end and the label, both in
# millimetres (``pp.rcParams["pie.label_offset"]`` and
# ``pp.rcParams["pie.leader_gap"]``, ``2`` and ``0.8`` by default). The
# gap is the distance you see, from the end of the line to the nearest
# point of the label, so it is the same at every angle. Like tick
# labels, outside labels sit beyond the axes, so a larger offset leaves
# the disc as it is and grows the figure instead.

arms = pd.DataFrame({"arm": ["placebo", "low", "high"],
                     "n": [35.0, 40.0, 25.0]})
fig, axes = pp.subplots(ncols=3, axes_size=(36, 36))
for ax, (title, kws) in zip(axes, [("default", {}),
                                   ("offset=5", {"offset": 5}),
                                   ("leader_gap=2", {"leader_gap": 2})]):
    pp.pieplot(data=arms, x="arm", y="n", legend=False, ax=ax,
               annotate={"anchor": "outside", **kws}, title=title)
pp.show()

# %%
# Leader lines
# ------------
# ``leader`` sets how an outside label hangs off its wedge.
# ``"radial"`` (the default) carries the wedge's mid-ray on past the rim
# and centres the label on it. ``"elbow"`` bends the line into a short
# horizontal tail, ``elbow_length`` millimetres long (``2`` by default),
# and sets the label beside it, aligned away from the disc, so the text
# starts ``leader_gap`` past the end of its tail. Every leader starts
# on its own wedge's rim at the mid-ray, and elbow labels are not lined
# up into a column. ``None`` (or ``False``) draws no line and centres
# the label with its nearest point ``offset`` from the rim. The radial
# labels here each sit on their own mid-ray. The two thin wedges'
# elbow labels would touch there, so they are moved apart, 0.6mm each,
# up and down their column (see "Crowded labels"); and the unled ones,
# 0.375mm apart, are nudged about a hundredth of a degree to make 0.4mm.

fig, axes = pp.subplots(ncols=3, axes_size=(36, 36))
for ax, leader in zip(axes, ["radial", "elbow", None]):
    pp.pieplot(data=df, x="kind", y="n", palette=palette, legend=False,
               ax=ax, annotate={"anchor": "outside", "leader": leader},
               title=f"leader={leader!r}")
pp.show()

# %%
# The default style is ``pp.rcParams["pie.leader"]``, so a figure set can
# switch every pie at once. Here the donut from above, with every label
# outside and the rcParam set to ``"elbow"``; the last line puts the
# default back for the rest of this page.

default_leader = pp.rcParams["pie.leader"]
pp.rcParams["pie.leader"] = "elbow"
fig, ax = pp.subplots(axes_size=(50, 50))
pp.pieplot(data=df, x="kind", y="n", donut=0.55, palette=palette,
           center_label="{:,.0f}".format, ax=ax,
           annotate={"anchor": "outside"})
pp.show()
pp.rcParams["pie.leader"] = default_leader

# %%
# Crowded labels
# --------------
# A long tail puts several slivers side by side, and their outside
# labels would land on top of one another. ``avoid_overlap`` (on by
# default, ``pp.rcParams["pie.avoid_overlap"]``) moves them apart by as
# little as keeps every two labels ``label_spacing`` millimetres apart
# (``0.4`` by default, ``pp.rcParams["pie.label_spacing"]``), keeping
# their order. Elbow labels move up or down their column, and the
# elbow moves with them so the tail stays level; radial labels move
# round the circle, their leaders leaning to follow; labels with no
# leader move round the circle too. A label that crowds nothing stays
# exactly where it was, and no leader enters the disc. The top row is
# the same chart with ``avoid_overlap=False``.
#
# A radial or unled label moves at most as far round as its leader can
# lean without cutting back across the chart. Where the slivers need
# more room than that -- on a 25 to 40mm pie, four to six 0.5% wedges
# side by side near twelve or six o'clock, nine to eleven stacked near
# three or nine; more on a larger pie --
# the pie is drawn with elbow labels instead (next figure).

long_tail = pd.DataFrame({
    "kind": ["A", "B", "C", "D", "E", "F", "G", "H"],
    "n": [40.0, 30.0, 20.0, 5.0, 3.0, 1.0, 0.5, 0.5],
})
fig, axes = pp.subplots(nrows=2, ncols=3, axes_size=(36, 36),
                        hspace=10)
for row, avoid in zip(axes, [False, True]):
    for ax, leader in zip(row, ["radial", "elbow", None]):
        pp.pieplot(data=long_tail, x="kind", y="n", legend=False,
                   start_angle=30, ax=ax,
                   annotate={"anchor": "outside", "leader": leader,
                             "avoid_overlap": avoid})
        ax.set_title(f"leader={leader!r}\navoid_overlap={avoid}")
pp.show()

# %%
# The thirteen-wedge tail below, at 30mm, is too much for that room:
# with its slivers side by side at twelve o'clock, the bounded circle
# pass does not keep its radial labels apart. So although both panels
# ask for ``leader="radial"`` (the default), the left one comes out
# with elbow labels: whenever that pass does not clear every overlap,
# every outside label of the pie is laid out as an elbow label and
# spread up and down its column, with the ``offset``, ``leader_gap``
# and ``elbow_length`` in effect -- and with leader lines even if
# ``leader=None`` was asked for. That includes some pies a tight radial
# packing could hold, but only with leaders lying along the rim's
# tangent; elbow labels read better there. No warning is issued. Where
# the radial style matters more, ``min_share`` (right, ``0.02``) pools
# the slivers into one wedge, leaving labels the circle can keep apart;
# ``avoid_overlap=False`` keeps every label on its mid-ray, overlaps and
# all.

tail13 = pd.DataFrame({
    "kind": [f"k{i}" for i in range(13)],
    "n": [50.0, 20.0, 10.0, 5.0, 3.0, 2.0, 1.0, 1.0, 0.5, 0.5, 0.5, 0.3,
          0.2],
})
fig, axes = pp.subplots(ncols=2, axes_size=(30, 30))
for ax, pie_kws in zip(axes, [{}, {"min_share": 0.02}]):
    pp.pieplot(data=tail13, x="kind", y="n", legend=False, ax=ax,
               annotate={"anchor": "outside", "leader": "radial"},
               **pie_kws)
pp.show()

# %%
# Formatting and rotating the labels
# ----------------------------------
# The default label is the wedge's share of the total, as a percentage.
# Passing ``fmt`` as a format spec labels the raw value instead — here
# ``",.0f"`` for counts with a thousands separator. ``rotation`` takes
# degrees, or ``"tangential"`` (along the arc) or ``"radial"`` (along
# the spoke); either is flipped where needed so no label reads upside
# down.

cohort = pd.DataFrame({
    "site": ["north", "east", "south", "west", "central"],
    "patients": [4210.0, 3380.0, 2950.0, 2160.0, 1870.0],
})
fig, axes = pp.subplots(ncols=3, axes_size=(42, 42))
pp.legend(side="right")
for ax, rotation in zip(axes, [0, "tangential", "radial"]):
    pp.pieplot(data=cohort, x="site", y="patients", ax=ax,
               annotate={"fmt": ",.0f", "anchor": "inside",
                         "rotation": rotation},
               title=f"rotation={rotation!r}")
pp.show()

# %%
# Patterns
# --------
# ``hatch`` adds a texture, keyed by a column the same way ``hue`` is.
# Naming the wedge column itself (``hatch="kind"``) gives every wedge
# its own pattern on top of its own colour — useful when the figure may
# be printed in greyscale — and the patterns fold into the colour
# swatches of a single legend entry. Patterns come from
# ``pp.HATCH_PATTERNS``, at the density ``pp.set_hatch_mode`` sets,
# unless ``hatch_map`` names them; the dense ones below stay readable in
# the small legend swatches. Pattern strokes are drawn at the outline
# width, ``linewidth`` (see the last section).

hatches = {"symptom": "", "admin": "////", "lay_dx": "\\\\\\\\",
           "none": "...."}
fig, ax = pp.subplots(axes_size=(50, 50))
pp.pieplot(data=df, x="kind", y="n", palette=palette, hatch="kind",
           hatch_map=hatches, ax=ax)
pp.show()

# %%
# A pattern for a second column
# -----------------------------
# ``hatch`` may instead name a different column, as long as it is
# constant within each wedge. The pattern then carries a second piece of
# information, and gets a legend entry of its own with neutral swatches,
# since colour already means the wedge.

sourced = df.assign(source=["registry", "registry", "survey", "survey"])
fig, ax = pp.subplots(axes_size=(50, 50))
pp.pieplot(data=sourced, x="kind", y="n", palette=palette,
           hatch="source", hatch_map={"registry": "", "survey": "////"},
           ax=ax)
pp.show()

# %%
# Colouring by something other than the category
# -------------------------------------------------
# ``hue`` means colour and nothing else — unlike ``barplot``, where
# ``hue`` also controls how marks group, a wedge chart keeps its
# structure in ``x``. ``hue`` may name a column outside the one that
# defines the wedges, as long as it is constant within each wedge. Here
# four departments are coloured by the wing they belong to, so two
# wedges share each colour; ``hatch="dept"`` gives each department its
# own pattern, and the patterns their own legend entry, so the four stay
# apart.

staff = pd.DataFrame({
    "dept": ["cardio", "neuro", "billing", "records"],
    "wing": ["clinical", "clinical", "admin", "admin"],
    "n": [30.0, 24.0, 18.0, 12.0],
})
fig, ax = pp.subplots(axes_size=(50, 50))
pp.pieplot(data=staff, x="dept", y="n", hue="wing", hatch="dept",
           hatch_map={"cardio": "", "neuro": "////", "billing": "\\\\\\\\",
                      "records": "...."},
           palette={"clinical": "#75b375", "admin": "#8e8ec1"}, ax=ax)
pp.show()

# %%
# Colouring by a number
# ---------------------
# A numeric ``hue`` maps through a colormap, and the legend becomes a
# colorbar. As with a categorical ``hue``, the value must be constant
# within each wedge. ``palette`` names the colormap (``"viridis"``, or a
# matplotlib ``Colormap``); a dict or list raises, since a number has no
# discrete levels to assign colours to. Left unset, the colormap is a
# light ramp running from near-white up to ``color``. The colorbar shows
# the colormap at full strength, so both panels fill their wedges solid
# (``alpha=1``) to read against it. The ramp's lightest wedge would all
# but vanish into the page, so the left panel outlines its wedges in
# grey; viridis starts dark and needs no outline.

waits = df.assign(days=[3.0, 11.0, 26.0, 40.0])
fig, axes = pp.subplots(ncols=2, axes_size=(42, 42))
pp.pieplot(data=waits, x="kind", y="n", hue="days", color="#e67e7e",
           alpha=1, edgecolor="0.3", ax=axes[0], title='color="#e67e7e"')
pp.pieplot(data=waits, x="kind", y="n", hue="days", palette="viridis",
           alpha=1, ax=axes[1], title='palette="viridis"')
pp.show()

# %%
# Fill, outline and stroke width
# ------------------------------
# Wedges take the house style by default: a tinted fill behind a
# full-strength outline in the wedge's own colour. ``alpha`` sets the
# fill alone (``0`` leaves outlines only, ``1`` a solid fill);
# ``edgecolor`` outlines every wedge the same way regardless of fill;
# ``linewidth`` sets the outline width and the width of the pattern
# strokes too, in the wedges and their legend swatches alike: the key
# beside the hatched panel draws its patterns at 1.5.

fig, axes = pp.subplots(ncols=4, axes_size=(36, 36))
# The key is the hatched panel's, beside it, with its patterns at its
# stroke width. The colours are the same in every panel; only the
# hatched panel's key is collected because the panels draw their
# swatches in different styles.
pp.legend(axes=[axes[3]], anchor=axes[-1], side="right")
pp.pieplot(data=df, x="kind", y="n", palette=palette, legend=False,
           ax=axes[0], title="default")
pp.pieplot(data=df, x="kind", y="n", palette=palette, alpha=0,
           linewidth=1.5, legend=False, ax=axes[1],
           title="alpha=0, linewidth=1.5")
pp.pieplot(data=df, x="kind", y="n", palette=palette, alpha=1,
           edgecolor="white", linewidth=1.5, legend=False, ax=axes[2],
           title='alpha=1, linewidth=1.5\nedgecolor="white"')
pp.pieplot(data=df, x="kind", y="n", palette=palette, hatch="kind",
           hatch_map=hatches, linewidth=1.5, ax=axes[3],
           title="hatch, linewidth=1.5")
pp.show()