plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/styles/library.py

@@ -0,0 +1,397 @@
+"""Bundled styles: the defaults of common plotting libraries, in plot_io's settings.
+
+Libraries that specify points (matplotlib, seaborn, ggplot2 — R's linewidth L mm → L ×
+72.27 / 25.4 × 0.75 pt —, MATLAB, ggthemes) are written in points (``"0.8pt"``); Vega-Lite
+(altair) in px. matplotlib and seaborn values are read from the installed libraries'
+artists, the others from their documented defaults.
+"""
+
+from . import add_style
+
+
+def _pt(v: float) -> str:
+    """``v`` points, as a length (computed point values: R's line widths)."""
+    return f"{v!r}pt"
+
+
+#: An open "+" (two strokes): matplotlib's and MATLAB's outlier marker
+_PLUS = "M-0.5 0 H0.5 M0 -0.5 V0.5"
+
+# -- solid: the base of the library styles --------------------------------------------
+
+#: Solid bars, bar histograms, areas and violins, black-outlined boxes, markers without
+#: outline, named colors in the ``base`` variant: what the libraries draw (plot_io's
+#: defaults outline series in their color over a light fill, in the ``forest`` variant).
+add_style("solid", {
+    "Hist.shape": "bar",
+    "Bar.edge_width": 0.0,
+    "Bar.fill_opacity": 1.0,
+    "Box.edge_color": "black",
+    "Box.fill_opacity": 1.0,
+    "Box.median_width": 1.5,
+    "Box.max_width": "100%",                  # the whole slot: no cap
+    "Hist.outline": False,
+    "Violin.edge_color": "#333333",
+    "Violin.fill_opacity": 1.0,
+    "Area.fill_opacity": 0.85,
+    "Area.edge_width": 0.0,
+    "Pie.edge_color": "white",
+    "Pie.fill_opacity": 1.0,
+    "Bar.seam_color": "none",
+    "Pie.seam_color": "none",
+    "Marker.size": 5.0,                       # markers without outline
+    "Marker.edge_width": 0.0,
+    "Box.marker_size": 3.5,                   # outliers keep plot_io's
+    "Box.marker_edge_width": 0.5,
+    "Colorbar.extend_shape": "triangle",
+    "Axis.snap": False,                     # limits at the data plus padding
+    "color_variant": "base",                  # the libraries' colors, unchanged
+})
+
+# -- matplotlib (rcParams defaults, ≥ 2.0) --------------------------------------------
+
+add_style("matplotlib", {
+    "base": "solid",
+    "font_family": "DejaVu Sans, Bitstream Vera Sans, Arial, Helvetica, sans-serif",
+    "font_size": "10.0pt",
+    "Title.font_size": "1.2em",               # axes.titlesize: "large"
+    "line_width": "1.5pt",
+    "qualitative_map": "tab10",
+    "sequential_map": "viridis",
+    "diverging_map": "coolwarm",
+    "Plot.spines": "all",
+    "Title.pad": "6.0pt",
+    "MainTitle.font_size": "12.0pt",            # suptitle: "large", normal weight
+    "FigureTitle.font_weight": "normal",
+    "Axis.line_width": "0.8pt",
+    "Axis.tick_length": "3.5pt",
+    "Axis.minor_tick_length": "2.0pt",
+    "Axis.tick_width": "0.8pt",
+    "Axis.tick_pad": "3.5pt",
+    "Axis.label_pad": "4.0pt",
+    "Axis.grid_color": "#b0b0b0",
+    "Axis.grid_width": "0.8pt",
+    "Legend.frame": True,
+    "Legend.frame_color": "#cccccc",
+    "Legend.frame_width": "1.0pt",
+    "Legend.frame_opacity": 0.8,
+    "Legend.frame_radius": "3.0pt",
+    "Legend.row_height": "1.5em",
+    "Legend.inside": "best",                  # legend.loc: "best" (never outside)
+    "Scatter.size": "6.0pt",
+    "Line.marker_size": "6.0pt",
+    "Box.color": "none",
+    "Box.edge_width": "1.0pt",
+    "Box.median_color": "C1",
+    "Box.median_width": "1.0pt",
+    "Box.width": "50%",
+    "Box.marker_color": "none",
+    "Box.marker_edge_color": "black",
+    "Box.marker_edge_width": "1.0pt",
+    "Box.marker_size": "6.0pt",
+    "Colorbar.style": "bar",                  # fig.colorbar: location "right", shrink 1
+    "Colorbar.side": "right",
+    "Colorbar.frame": True,
+    "Colorbar.frame_color": "black",
+    "Colorbar.frame_width": "0.8pt",
+    "Violin.opacity": 0.3,                      # violinplot bodies: C0 at 0.3, no edge
+    "Violin.edge_width": "0.0pt",
+    "Violin.inner": False,
+    "Strip.size": "6.0pt",
+    "Swarm.size": "6.0pt",
+    "Pie.edge_width": "0.0pt",                    # wedges without edges
+})
+
+# -- seaborn (0.13: axes_style, plotting_context "notebook", "deep") ---------------------
+
+add_style("seaborn", {
+    "base": "solid",
+    "font_family": "Arial, DejaVu Sans, Liberation Sans, Bitstream Vera Sans, sans-serif",
+    "font_size": "12.0pt",
+    "text_color": "#262626",
+    "line_width": "1.5pt",
+    "qualitative_map": "deep",
+    "sequential_map": "rocket",
+    "diverging_map": "vlag",
+    "Plot.background": "#EAEAF2",
+    "Plot.spines": "none",
+    "Title.font_size": "12.0pt",
+    "Title.pad": "6.0pt",
+    "MainTitle.font_size": "14.4pt",
+    "FigureTitle.font_weight": "normal",
+    "Axis.tick_label_font_size": "11.0pt",
+    "Axis.tick_length": "0.0pt",
+    "Axis.tick_pad": "3.5pt",
+    "Axis.label_pad": "4.0pt",
+    "Axis.line_width": "1.25pt",
+    "Axis.grid": True,
+    "Axis.grid_color": "white",
+    "Axis.grid_width": "1.0pt",
+    "Legend.font_size": "11.0pt",
+    "Legend.frame": True,
+    "Legend.frame_color": "#cccccc",
+    "Legend.frame_width": "1.0pt",
+    "Legend.frame_opacity": 0.8,
+    "Legend.frame_radius": "3.0pt",
+    "Legend.row_height": "1.5em",
+    "Legend.inside": "best",                  # ax.legend: matplotlib's loc "best"
+    "Colorbar.style": "bar",                  # heatmap: figure.colorbar, right, full height
+    "Colorbar.side": "right",
+    "Scatter.size": "6.0pt",
+    "Scatter.edge_color": "white",
+    "Scatter.edge_width": "0.48pt",
+    "Line.marker_size": "6.0pt",
+    "Box.saturation": 0.75,
+    "Box.edge_color": "auto",
+    "Box.edge_width": "1.0pt",
+    "Box.median_width": "1.0pt",
+    "Box.marker_color": "none",
+    "Box.marker_edge_width": "1.0pt",
+    "Box.marker_size": "5.0pt",
+    "Bar.saturation": 0.75,                   # barplot: saturation .75, white 1 pt edges
+    "Bar.edge_color": "white",
+    "Bar.edge_width": "1.0pt",
+    "Bar.error_color": "#424242",
+    "Hist.fill_opacity": 0.75,                # histplot: alpha (opacity) .75, white edges
+    "Hist.edge_color": "white",
+    "Hist.edge_width": "1.0pt",
+    "Violin.saturation": 0.75,                # violinplot: edges and inner box #4c4c4c
+    "Violin.edge_color": "#4c4c4c",
+    "Violin.edge_width": "1.25pt",
+    "Strip.size": "5.0pt",                        # stripplot/swarmplot: s=25, no edge
+    "Strip.edge_width": "0.0pt",
+    "Swarm.size": "5.0pt",
+    "Swarm.edge_width": "0.0pt",
+    "Regression.line_width": "2.25pt",            # regplot: lw 1.5 × 1.5, band opacity .15
+    "Regression.band_opacity": 0.15,
+    "Regression.marker_size": "6.0pt",
+})
+
+# -- ggplot2 (theme_grey(base_size = 11), hue_pal, scale_colour_gradient) -----------------
+
+_GG_LINE = 0.5 * 72.27 / 25.4 * 0.75          # base_line_size 0.5 mm → 1.07 pt
+
+add_style("ggplot2", {
+    "base": "solid",
+    "Axis.sticky": False,                     # padding below bar baselines too
+    "font_family": "Helvetica, Arial, Liberation Sans, sans-serif",
+    "font_size": "11.0pt",
+    "line_width": _pt(_GG_LINE),
+    "qualitative_map": "hue",
+    "sequential_map": "ggplot2",
+    "diverging_map": ["#832424", "#FFFFFF", "#3A3A98"],    # scale_*_gradient2: muted red, blue
+    "Plot.background": "#EBEBEB",
+    "Plot.spines": "none",
+    "Title.font_size": "13.2pt",
+    "Title.align": "left",
+    "Title.pad": "5.5pt",
+    "MainTitle.font_size": "13.2pt",
+    "FigureTitle.font_weight": "normal",
+    "MainTitle.align": "left",
+    "Axis.tick_label_font_size": "8.8pt",
+    "Axis.tick_label_color": "#4D4D4D",
+    "Axis.tick_color": "#333333",
+    "Axis.tick_length": "2.75pt",
+    "Axis.tick_width": _pt(_GG_LINE),
+    "Axis.tick_pad": "2.2pt",
+    "Axis.label_pad": "2.75pt",
+    "Axis.grid": True,
+    "Axis.grid_color": "white",
+    "Axis.grid_width": _pt(_GG_LINE),
+    "Axis.minor_grid": True,
+    "Axis.minor_grid_width": _pt(_GG_LINE / 2),
+    "Legend.side": "right",
+    "Legend.align": "center",                 # legend.justification: "center"
+    "Legend.font_size": "8.8pt",
+    "Legend.glyph_length": "1.8em",
+    "Legend.row_height": "1.8em",
+    "Legend.pad": "11.0pt",
+    "Scatter.size": "4.3pt",
+    "Line.marker_size": "4.3pt",
+    "Box.color": "white",
+    "Box.edge_color": "#333333",
+    "Box.edge_width": _pt(_GG_LINE),
+    "Box.median_width": _pt(2 * _GG_LINE),
+    "Box.width": "75%",
+    "Box.cap_length": "0.0pt",
+    "Box.marker_color": "black",
+    "Box.marker_size": "4.3pt",
+    "plain_color": "black",                   # GeomPoint, GeomLine, GeomDensity: black
+    "Bar.plain_color": "#595959",             # GeomRect (geom_bar, geom_histogram): grey35
+    "Hist.plain_color": "#595959",
+    "Area.plain_color": "#333333",            # GeomArea, GeomRibbon: grey20
+    "Fill.plain_color": "#333333",
+    "Colorbar.style": "bar",                  # guide_colourbar, legend.position "right"
+    "Colorbar.side": "right",
+    "Colorbar.length": "86.4pt",              # 5 × legend.key.size (1.2 lines = 17.28 pt)
+    "Colorbar.thickness": "17.28pt",
+    "Colorbar.label_position": "top",         # vertical: title on top, hjust 0
+    "Colorbar.tick_color": "white",           # guide_colourbar: white ticks inside
+    "Colorbar.tick_direction": "in",
+    "Colorbar.tick_length": "2.0pt",
+    "Colorbar.mirror": True,
+    "Kde.line_width": "1.067pt",                  # geom_density: black, linewidth 0.5
+    "Violin.color": "white",                  # geom_violin: white fill, grey20 outline
+    "Violin.edge_width": "1.067pt",
+    "Violin.inner": False,
+    "Regression.color": "#3366FF",            # geom_smooth: #3366FF, linewidth 1
+    "Regression.line_width": "2.134pt",
+    "Regression.band_opacity": 0.4,
+    "Area.fill_opacity": 1.0,
+})
+
+# -- altair (Vega-Lite / Vega default config) -------------------------------------------
+
+add_style("altair", {
+    "base": "solid",
+    "font_family": "sans-serif",
+    "font_size": 10.0,                        # guide-label 10 px
+    "line_width": 2.0,                        # line strokeWidth 2 px
+    "qualitative_map": "tableau10",
+    "sequential_map": "ylgnbu",
+    "Plot.border_color": "#DDDDDD",           # view stroke
+    "Plot.border_width": 1.0,
+    "Title.font_size": 13.0,                  # group-title 13 px bold
+    "Title.font_weight": "bold",
+    "Title.pad": 4.0,
+    "MainTitle.font_size": 13.0,
+    "Axis.label_font_size": 11.0,                  # guide-title 11 px bold
+    "Axis.label_weight": "bold",
+    "Axis.line_color": "#888888",
+    "Axis.line_width": 1.0,
+    "Axis.tick_color": "#888888",
+    "Axis.tick_length": 5.0,
+    "Axis.tick_width": 1.0,
+    "Axis.tick_pad": 2.0,
+    "Axis.label_pad": 4.0,
+    "Axis.grid": True,
+    "Axis.grid_width": 1.0,
+    "Axis.padding": 0.0,
+    "Axis.snap": True,
+    "Axis.include_zero": "auto",
+    "Legend.side": "right",
+    "Legend.pad": 18.0,
+    "Colorbar.style": "bar",                  # gradient legend: orient right, vertical
+    "Colorbar.side": "right",
+    "Colorbar.length": 200.0,                 # gradientLength 200 px
+    "Colorbar.thickness": 16.0,               # gradientThickness 16 px
+    "Colorbar.label_position": "top",         # titleOrient "top"
+    "Scatter.size": 6.1333,                   # point size 30 px², stroke 2 px, not filled
+    "Scatter.fill": False,
+    "Scatter.edge_width": 2.0,
+    "Line.marker_size": 6.1333,
+    "Box.edge_width": 1.0,
+    "Box.median_color": "white",
+    "Box.median_width": 2.0,
+    "Box.width": "50%",
+    "Box.marker_edge_width": 2.0,
+    "Box.marker_size": 6.1333,
+    "Bar.width": "90%",                       # band scale paddingInner 0.1
+    "Hist.edge_color": "white",               # binSpacing 1 px
+    "Hist.edge_width": 1.0,
+    "Area.fill_opacity": 0.7,
+    "Pie.edge_width": 0.0,
+})
+
+# -- MATLAB (R2014b+ default property values) -------------------------------------------
+
+add_style("matlab", {
+    "base": "solid",
+    "font_family": "Helvetica, Arial, Liberation Sans, sans-serif",
+    "font_size": "10.0pt",
+    "text_color": "#262626",
+    "line_width": "0.5pt",
+    "qualitative_map": "matlab",
+    "sequential_map": "parula",
+    "Title.font_size": "11.0pt",
+    "Title.font_weight": "bold",
+    "Title.pad": "5.0pt",
+    "MainTitle.font_size": "11.0pt",            # sgtitle
+    "FigureTitle.font_weight": "normal",
+    "Axis.label_font_size": "11.0pt",
+    "Axis.line_width": "0.5pt",
+    "Axis.tick_direction": "in",
+    "Axis.tick_length": "3.2pt",
+    "Axis.tick_width": "0.5pt",
+    "Axis.grid_color": "#dbdbdb",
+    "Axis.padding": "0.0pt",
+    "Axis.snap": True,
+    "Legend.inside": "top_right",
+    "Legend.font_size": "9.0pt",
+    "Legend.frame": True,
+    "Legend.frame_color": "#262626",
+    "Legend.frame_width": "0.5pt",
+    "Scatter.size": "6.0pt",
+    "Scatter.fill": False,
+    "Scatter.edge_width": "0.5pt",
+    "Line.marker_size": "6.0pt",
+    "Box.color": "none",
+    "Box.edge_color": "#0000ff",
+    "Box.edge_width": "0.5pt",
+    "Box.median_color": "#ff0000",
+    "Box.median_width": "0.5pt",
+    "Box.whisker_color": "black",
+    "Box.whisker_style": "dashed",
+    "Box.width": "50%",
+    "Box.marker": _PLUS,
+    "Box.marker_color": "#ff0000",
+    "Box.marker_fill": False,
+    "Box.marker_edge_width": "0.5pt",
+    "Box.marker_size": "6.0pt",
+    "Colorbar.style": "bar",                  # Location "eastoutside": right, full height
+    "Colorbar.side": "right",
+    "Colorbar.frame": True,
+    "Colorbar.frame_color": "#262626",
+    "Bar.edge_color": "black",                # bar: black 0.5 edges
+    "Bar.edge_width": "0.5pt",
+    "Hist.fill_opacity": 0.6,                 # histogram: FaceAlpha 0.6, black edges
+    "Hist.edge_color": "black",
+    "Hist.edge_width": "0.5pt",
+    "Pie.edge_color": "black",
+    "Pie.edge_width": "0.5pt",
+})
+
+# -- Tufte (ggthemes theme_tufte, with a range frame) -----------------------------------
+
+add_style("tufte", {
+    "base": "solid",
+    "font_family": "serif",
+    "font_size": "11.0pt",
+    "MainTitle.font_size": "1.4rem",
+    "line_width": "0.5pt",
+    "qualitative_map": ["#000000", "#666666", "#999999", "#CCCCCC"],
+    "sequential_map": "#E6E6E6, black",      # 10 % ink at the low end: a count of 1 shows
+    "Title.font_size": "13.2pt",
+    "Title.align": "left",
+    "FigureTitle.font_weight": "normal",
+    "MainTitle.align": "left",
+    "Axis.tick_label_font_size": "8.8pt",
+    "Axis.tick_label_color": "#4D4D4D",
+    "Axis.tick_color": "#333333",
+    "Axis.line_color": "#333333",
+    "Axis.line_width": "0.5pt",
+    "Axis.tick_length": "2.75pt",
+    "Axis.tick_width": "0.5pt",
+    "Axis.spine_trim": True,
+    "Axis.spine_offset": "5.0pt",
+    "Legend.side": "right",
+    "Legend.align": "center",                 # ggplot2: legend.justification "center"
+    "plain_color": "black",                   # ggplot2's geoms (as ggplot2's style)
+    "Bar.plain_color": "#595959",
+    "Hist.plain_color": "#595959",
+    "Area.plain_color": "#333333",
+    "Fill.plain_color": "#333333",
+    "Colorbar.style": "bar",                  # guide_colourbar (as ggplot2's style)
+    "Colorbar.side": "right",
+    "Colorbar.length": "86.4pt",
+    "Colorbar.thickness": "17.28pt",
+    "Colorbar.label_position": "top",
+    "Scatter.size": "4.0pt",
+    "Box.color": "none",
+    "Box.edge_width": "0.5pt",
+    "Box.width": "30%",
+    "Box.cap_length": "0.0pt",
+    "Box.median_width": "0.5pt",
+    "Box.marker_color": "black",
+    "Box.marker_size": "2.0pt",
+})

plot_io/tables.py

@@ -0,0 +1,138 @@
+"""Columns from tables (``data=``) and grouping of series by a column (``group=``).
+
+``data`` is anything that returns a column for ``data[name]``: a dict of sequences, a
+pandas or polars data frame, a numpy structured array.  Columns are read through
+``__getitem__`` and ``to_numpy()`` when present, so no table library is imported.
+
+A call with ``group=labels`` is split into one series per group (a :class:`SeriesGroup`),
+each with the rows of every per-point argument that belong to it.
+"""
+
+import array
+import math
+import warnings
+from typing import Any
+
+__all__ = ["column", "has_column", "SeriesGroup", "MARKER_CYCLE", "LINE_STYLE_CYCLE"]
+
+MARKER_CYCLE = ("circle", "square", "triangle_up", "diamond", "triangle_down", "plus",
+                "cross", "triangle_left", "triangle_right")
+LINE_STYLE_CYCLE = ("solid", "dashed", "dotted", "dashdot")
+
+
+def has_column(data: Any, name: str) -> bool:
+    try:
+        columns = data.columns if hasattr(data, "columns") else None
+        if columns is not None and not callable(columns):
+            return name in list(columns)
+        names = getattr(getattr(data, "dtype", None), "names", None)
+        if names is not None:
+            return name in names
+        if hasattr(data, "keys"):
+            return name in data.keys()
+        data[name]
+        return True
+    except (KeyError, IndexError, TypeError, ValueError):
+        return False
+
+
+def column(data: Any, name: str) -> tuple[Any, list[Any] | None]:
+    """The column ``name`` of ``data`` and, for categorical columns (pandas
+    ``category``), the order of its categories."""
+    if not has_column(data, name):
+        raise ValueError(f"no column {name!r} in data")
+    from .columns import _order
+    v = data[name]
+    order = _order(v)
+    if hasattr(v, "to_numpy"):
+        v = v.to_numpy()
+    if hasattr(v, "dtype") and getattr(v.dtype, "kind", "") in "OUS":
+        v = v.tolist()
+    return v, order
+
+
+def is_missing(v: Any) -> bool:
+    return v is None or (isinstance(v, float) and math.isnan(v))
+
+
+def take(v: Any, idx: list[int]) -> Any:
+    """The items ``idx`` of a per-point argument."""
+    from .columns import Keys
+    if isinstance(v, Keys):
+        return v.take(idx)
+    if isinstance(v, (list, tuple)):
+        return [v[i] for i in idx]
+    kind = getattr(getattr(v, "dtype", None), "kind", "")
+    if kind in ("M", "m"):                            # numpy dates keep their type
+        return v[idx]
+    if kind in ("O", "U", "S"):
+        return [v[i] for i in idx]
+    try:
+        mv = memoryview(v)
+    except (TypeError, ValueError):
+        mv = None
+    if mv is not None and mv.ndim == 1 and not isinstance(v, (str, bytes)):
+        from . import kernels
+        return kernels.take(v, idx) if len(idx) else array.array("d")
+    if mv is not None and mv.ndim == 2:
+        rows: Any = v.tolist() if hasattr(v, "tolist") else mv.tolist()
+        return [tuple(rows[i]) for i in idx]
+    return [v[i] for i in idx]
+
+
+def group_keys(labels: Any, order: list[Any] | None, given: Any, missing: str) -> tuple[
+        list[Any], list[list[int]]]:
+    """Group keys in order and the row indices of each."""
+    keyed: dict[Any, list[int]] = {}
+    for i, lab in enumerate(labels):
+        if is_missing(lab):
+            if missing == "drop":
+                continue
+            lab = "nan"
+        keyed.setdefault(lab, []).append(i)
+    keys = list(keyed)
+    if given is not None:
+        given = list(given)
+        unknown = [k for k in keys if k not in given]
+        keys = [k for k in given if k in keyed] + unknown
+    elif order is not None:
+        keys = [k for k in order if k in keyed] + [k for k in keys if k not in order]
+    return keys, [keyed[k] for k in keys]
+
+
+class SeriesGroup(list):
+    """The series of a call with ``group=``, one per group, in group order.
+
+    ``set(**settings)`` applies to every member; ``group[label]`` is one member (an
+    integer index also works); ``labels`` lists the group labels.
+    """
+
+    def __init__(self, members: list[Any], labels: list[Any], title: Any = None) -> None:
+        super().__init__(members)
+        self.labels = labels
+        self.title = title
+
+    def __getitem__(self, key: Any) -> Any:
+        if isinstance(key, (int, slice)) and not (isinstance(key, int) and key in self.labels):
+            return super().__getitem__(key)
+        try:
+            return super().__getitem__(self.labels.index(key))
+        except ValueError:
+            raise KeyError(key) from None
+
+    def set(self, **settings: Any) -> "SeriesGroup":
+        for s in self:
+            s.set(**settings)
+        return self
+
+    @property
+    def plot(self) -> Any:
+        return self[0].plot if len(self) else None
+
+    def __repr__(self) -> str:
+        return f"SeriesGroup({', '.join(map(repr, self.labels))})"
+
+
+def color_name_warning(name: str) -> None:
+    warnings.warn(f"{name!r} is both a column and a color name; using the column",
+                  stacklevel=4)