jarvisplot 2.1.2__tar.gz → 2.1.3__tar.gz

{jarvisplot-2.1.2 → jarvisplot-2.1.3}/JarvisPLOT.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: JarvisPLOT
-Version: 2.1.2
+Version: 2.1.3
 Summary: Jarvis-PLOT: YAML-driven plotting engine
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{jarvisplot-2.1.2 → jarvisplot-2.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: JarvisPLOT
-Version: 2.1.2
+Version: 2.1.3
 Summary: Jarvis-PLOT: YAML-driven plotting engine
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{jarvisplot-2.1.2 → jarvisplot-2.1.3}/jarvisplot/Figure/corrplot_runtime.py

@@ -45,10 +45,15 @@ GLYPHS = ("circle", "square", "ellipse", "color", "shade", "pie", "number")
 
 _TRIANGLES = ("full", "upper", "lower")
 
+#: What the tint may be told to mean.  `selected` is the author's own grouping,
+#: `alternate` the figure's own, `none` nothing.
+_STRIPES = ("alternate", "selected", "none")
+
 #: Formals resolved at config time.  They arrive because the user wrote them
 #: in the layer, and are dropped here rather than forwarded to matplotlib.
 _CONFIG_TIME = ("order", "hclust.method", "addrect", "col", "tl.pos", "tl.cex",
-                "tl.col", "tl.srt", "tl.offset", "cl.cex", "edge.numbers.cex")
+                "tl.col", "tl.srt", "tl.offset", "cl.cex", "edge.numbers.cex",
+                "stripe.variables")
 
 
 def _pop(kwargs: dict, name: str, default=None):
@@ -270,14 +275,25 @@ def _notch_vertices(n: int, side: str = "left", diag: bool = False):
     )
 
 
-def _shaded_variables(n: int, blocks=None) -> np.ndarray:
-    """Which variables carry the tint: alternate blocks, or alternate names.
+def _shaded_variables(n: int, blocks=None, selected=None) -> np.ndarray:
+    """Which variables carry the tint.
+
+    Three answers, and they say different things.  ``selected`` is an explicit
+    set of positions -- the author naming the variables that matter, so the
+    tint is *their* grouping and nothing is inferred.  Otherwise it is read off
+    the figure: alternate **blocks** when the clustering cut some, so the
+    shading says where one group ends and the next begins (which is what the
+    boxes were for), and alternate **names** when it did not.
 
-    A block is a run of adjacent positions cut from the clustering tree, so
-    tinting every other one makes the shading say where one group ends and the
-    next begins -- which is what the boxes were for.
+    ``selected`` arrives as positions, not names: the order is settled at
+    config time and only the order knows which position a name ended up at.
     """
     shaded = np.zeros(int(n), dtype=bool)
+    if selected is not None:
+        for position in selected:
+            if 0 <= int(position) < int(n):
+                shaded[int(position)] = True
+        return shaded
     if blocks:
         for position, (start, end) in enumerate(blocks):
             if position % 2 == 0:
@@ -728,9 +744,21 @@ def draw_corrplot(ax, **kwargs):
     # Diamond only.  See the stripe block below for why it is not decoration.
     stripe = _pop(kwargs, "stripe", "alternate")
     stripe = "none" if stripe is False else str(stripe).strip().lower()
-    if stripe not in ("alternate", "none"):
+    if stripe not in _STRIPES:
+        raise ValueError(
+            "corrplot stripe must be one of {}; got {!r}. `selected` takes the "
+            "variables to tint in `stripe.variables`.".format(
+                ", ".join(_STRIPES), stripe
+            )
+        )
+    # Positions, resolved from `stripe.variables` at config time -- see
+    # `core_runtime._corr_shaded_positions`.  The names cannot be resolved here
+    # because `order` has already moved them.
+    shaded_positions = kwargs.pop("__corr_shaded__", None)
+    if stripe == "selected" and shaded_positions is None:
         raise ValueError(
-            "corrplot stripe must be alternate or none; got {!r}.".format(stripe)
+            "corrplot stripe: selected needs stripe.variables -- the names to "
+            "tint. Without them the tint would say nothing."
         )
     stripe_color = _pop(kwargs, "stripe.col", "#EFEFEF")
     # Diamond only.  See `_edge_rules`: the rotated matrix has no top or bottom
@@ -883,7 +911,7 @@ def draw_corrplot(ax, **kwargs):
                 edge_color, clip, zorder + 40,
             )
 
-    if diamond and stripe == "alternate" and np.any(drawn):
+    if diamond and stripe != "none" and np.any(drawn):
         # Every other variable's cells, tinted.  Not decoration: a variable's
         # pairs run away from its name as a V, and at 40 names a reader
         # following one of those arms has nothing to hold on to.  The band is
@@ -899,7 +927,7 @@ def draw_corrplot(ax, **kwargs):
         #
         # The union of those variables' cells rather than one band each, so a
         # cell where two bands cross is filled once and the tint stays even.
-        shaded = _shaded_variables(n, blocks)
+        shaded = _shaded_variables(n, blocks, shaded_positions)
         band = shaded[index_x.astype(int)] | shaded[index_y.astype(int)]
         band &= drawn
         if np.any(band):
@@ -1091,7 +1119,7 @@ def draw_corrplot(ax, **kwargs):
     # block above), so a box around each of them would be the same fact drawn
     # twice, in the heaviest ink on the figure.  `addrect` still decides *what*
     # the blocks are; it just stops drawing them.
-    if blocks and not (diamond and stripe != "none"):
+    if blocks and not (diamond and stripe == "alternate"):
         for start, end in blocks:
             if diamond:
                 ax.add_patch(

{jarvisplot-2.1.2 → jarvisplot-2.1.3}/jarvisplot/cards/corrplot/diamond.json

@@ -498,7 +498,8 @@
         "type": {"type": "enum", "values": ["upper", "lower"], "default": "upper", "forbidden": ["full"]},
         "diag": {"type": "boolean", "default": true},
         "side": {"type": "enum", "values": ["left", "right"], "default": "right"},
-        "stripe": {"type": "enum", "values": ["alternate", "none"], "default": "alternate", "false_alias": "none"},
+        "stripe": {"type": "enum", "values": ["alternate", "selected", "none"], "default": "alternate", "false_alias": "none"},
+        "stripe.variables": {"type": "list_of_strings", "default": null, "requires": {"stripe": "selected"}},
         "order": {"type": "enum", "values": ["original", "AOE", "FPC", "hclust", "alphabet"], "default": "original"},
         "hclust.method": {"type": "enum", "values": ["single", "complete", "average", "weighted", "mcquitty", "median", "centroid", "ward.D", "ward.D2"], "default": "complete"},
         "addrect": {"type": "integer_or_null", "default": null, "requires": {"order": "hclust"}},

{jarvisplot-2.1.2 → jarvisplot-2.1.3}/jarvisplot/core_runtime.py

@@ -590,6 +590,47 @@ def _solve_corr_diamond(card, info, style, columns, axes_name):
     return geom, solved
 
 
+def _corr_shaded_positions(style: Mapping, columns, name: str):
+    """`stripe.variables` resolved against the order the figure ended up in.
+
+    It has to happen here and not at draw time.  The renderer sees positions,
+    and which position a variable holds is `order`'s answer, settled a moment
+    ago -- a name resolved against the *unordered* columns would tint a
+    different variable on every reordering and never say so.
+
+    A name that is not in the matrix is an error rather than a silent miss, for
+    the same reason: a tint that quietly did nothing is indistinguishable from
+    a tint that was not asked for.
+    """
+    stripe = style.get("stripe", "alternate")
+    stripe = "none" if stripe is False else str(stripe or "").strip().lower()
+    wanted = style.get("stripe.variables")
+    if wanted is None:
+        return None
+    if stripe != "selected":
+        raise ValueError(
+            "figure '{}' gives corrplot stripe.variables with stripe: {}. The "
+            "names are only read by stripe: selected; leaving them here would "
+            "draw the other tint and say nothing about them.".format(name, stripe)
+        )
+    if isinstance(wanted, str) or not isinstance(wanted, (list, tuple, set)):
+        raise ValueError(
+            "figure '{}' gives corrplot stripe.variables: {!r}. It takes a "
+            "list of variable names.".format(name, wanted)
+        )
+    at = {str(column): position for position, column in enumerate(columns)}
+    missing = [str(v) for v in wanted if str(v) not in at]
+    if missing:
+        raise ValueError(
+            "figure '{}' asks corrplot to tint {}, which {} not in the matrix. "
+            "The variables drawn are: {}.".format(
+                name, ", ".join(missing), "is" if len(missing) == 1 else "are",
+                ", ".join(str(c) for c in columns),
+            )
+        )
+    return sorted(at[str(v)] for v in wanted)
+
+
 def _as_corr_bool(value, default: bool = False) -> bool:
     if value is None:
         return default
@@ -1000,6 +1041,11 @@ def _prebuild_one(core, info: dict, card: Mapping) -> None:
         # but placed and sized by the solve.
         layer["style"]["__corr_number_mm__"] = geom.number_pad_mm
         layer["style"]["__corr_number_pt__"] = geom.number_size_pt
+        # `stripe.variables` names variables; the renderer draws positions, and
+        # only the order settled above knows which is which.
+        shaded = _corr_shaded_positions(style, columns, info.get("name", "?"))
+        if shaded is not None:
+            layer["style"]["__corr_shaded__"] = shaded
 
     if blocks:
         # The boxes are cuts of the tree the order came from, so they are

{jarvisplot-2.1.2 → jarvisplot-2.1.3}/jarvisplot/manual_cards/method_notes.yaml

@@ -62,7 +62,7 @@ corrplot:
     - "Reserved: only the [corrplot, matrix] or [corrplot, diamond] style card provides its axes (axcorr / axccorr)."
     - "No coordinates needed — x_index / y_index / rho are the transform's own output columns."
     - "style takes R's formals: method (circle|square|ellipse|color|shade|pie|number), type, diag, glyph.scale, outline, addgrid.col, plus the card's own ellipse.scale."
-    - "Use [corrplot, matrix] for the square matrix; [corrplot, diamond] keeps one triangle, rotates it 45 degrees, and adds side: left|right (default right, which puts the triangle on the left of the page) plus stripe: alternate|none."
+    - "Use [corrplot, matrix] for the square matrix; [corrplot, diamond] keeps one triangle, rotates it 45 degrees, and adds side: left|right (default right, which puts the triangle on the left of the page) plus stripe: alternate|selected|none. stripe: selected takes the variables to tint in stripe.variables, resolved against the solved order; diag: true|false is the self-correlation on the diagonal, on by default."
     - "order (original|AOE|FPC|hclust|alphabet) and addrect are resolved before the figure is built, then written into the transform's `columns`."
     - "sig.level switches on the significance test; unlike R no p.mat is needed, because the table carries n per pair."
     - "The glyph is sized from the solved cell and the coefficient text is back-solved from it, so both survive the 170 mm width clamp."

{jarvisplot-2.1.2 → jarvisplot-2.1.3}/jarvisplot/manual_cards/type-correlation-matrix.yaml

@@ -45,7 +45,9 @@ human:
         `style: [corrplot, diamond]` picks the other card: the same matrix as
         one triangle turned 45 degrees, names in a plain column of horizontal
         text, each variable's pairs a V rooted at its own name. Same formals,
-        plus `side: left | right` (default `right`, the triangle on the left of the page) and `stripe: alternate | none`.
+        plus `side: left | right` (default `right`, the triangle on the left of the page) and `stripe: alternate | selected | none`
+        (`selected` names the variables in `stripe.variables`), plus
+        `diag: true | false` for the self-correlation on the diagonal.
     - kind: yaml
       title: Minimal figure
       lexer: yaml

{jarvisplot-2.1.2 → jarvisplot-2.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "JarvisPLOT"
-version = "2.1.2"
+version = "2.1.3"
 description = "Jarvis-PLOT: YAML-driven plotting engine"
 readme = "README.md"
 requires-python = ">=3.10"

{jarvisplot-2.1.2 → jarvisplot-2.1.3}/tests/test_corrplot.py

@@ -1328,3 +1328,76 @@ def test_the_tint_is_the_bottom_layer_and_is_one_layer():
         if a.get_zorder() != pytest.approx(_TINT_ZORDER)
     ]
     assert above and min(above) > _TINT_ZORDER
+
+
+def test_stripe_selected_tints_the_variables_the_author_named():
+    from jarvisplot.Figure.corrplot_runtime import _shaded_variables
+
+    # positions, not names: the renderer never sees a name
+    picked = _shaded_variables(6, blocks=[[0, 2], [3, 5]], selected=[1, 4])
+    assert list(np.flatnonzero(picked)) == [1, 4]
+    # and it wins over the clustering, which is the point -- the tint stops
+    # being the figure's own grouping and becomes the author's
+    assert list(np.flatnonzero(_shaded_variables(6, blocks=[[0, 2], [3, 5]]))) == [0, 1, 2]
+
+
+def test_stripe_variables_are_resolved_against_the_solved_order():
+    # `order` has already moved the names by the time this runs, and only the
+    # order knows where each one ended up.  Resolved against the *unordered*
+    # columns the tint would land on a different variable every time the
+    # clustering changed, and never say so.
+    from jarvisplot.core_runtime import _corr_shaded_positions
+
+    ordered = ["c", "a", "d", "b"]
+    style = {"stripe": "selected", "stripe.variables": ["a", "b"]}
+    assert _corr_shaded_positions(style, ordered, "fig") == [1, 3]
+    # sorted, so the renderer gets positions in the order it draws them
+    assert _corr_shaded_positions(
+        {"stripe": "selected", "stripe.variables": ["b", "a"]}, ordered, "fig"
+    ) == [1, 3]
+    # nothing asked for, nothing resolved
+    assert _corr_shaded_positions({"stripe": "alternate"}, ordered, "fig") is None
+
+
+def test_a_tint_that_would_quietly_do_nothing_is_refused():
+    # A name not in the matrix, a list given to the wrong mode, and a mode
+    # given no list all have the same failure: a band that says nothing, and
+    # nothing on the page to show it was asked for.
+    from jarvisplot.core_runtime import _corr_shaded_positions
+
+    ordered = ["a", "b", "c"]
+    with pytest.raises(ValueError, match="not in the matrix"):
+        _corr_shaded_positions(
+            {"stripe": "selected", "stripe.variables": ["a", "zz"]}, ordered, "fig"
+        )
+    with pytest.raises(ValueError, match="only read by stripe: selected"):
+        _corr_shaded_positions(
+            {"stripe": "alternate", "stripe.variables": ["a"]}, ordered, "fig"
+        )
+    with pytest.raises(ValueError, match="takes a list"):
+        _corr_shaded_positions(
+            {"stripe": "selected", "stripe.variables": "a"}, ordered, "fig"
+        )
+    # and the renderer refuses the mode without the positions
+    with pytest.raises(ValueError, match="needs stripe.variables"):
+        draw_corrplot(_axes(3), __df__=_long_table(), __corr_layout__="diamond",
+                      type="upper", stripe="selected")
+
+
+def test_addrect_draws_its_boxes_again_once_the_tint_is_spoken_for():
+    # The boxes are dropped only because the shading is saying the same thing.
+    # With `selected` it is saying something else, so the clusters need them
+    # back or nothing on the figure says where they are.
+    from matplotlib.patches import Polygon
+
+    def boxes(**corrplot):
+        ax = _axes(6)
+        draw_corrplot(
+            ax, __df__=_long_table(), __corr_layout__="diamond", type="upper",
+            __corr_blocks__=[[0, 1], [2, 2]], __corr_label_mm__=8.0, **corrplot,
+        )
+        return [p for p in ax.patches if isinstance(p, Polygon)]
+
+    assert not boxes(stripe="alternate")
+    assert boxes(stripe="none")
+    assert boxes(stripe="selected", __corr_shaded__=[0])