chord_links

Trees & flows · used in the chord cookbook recipe

Minimal call

df = {"a": [1, 2, 1, 5, 3], "b": [4, 6, 8, 7, 9]}

c = pt.chart(df, aes(x1="a", x2="b"), xlabel="position")
c.add_chord_links(color="#4C72B0", width=1.5)
c.yticks([])

Docstring

Custom artist: chord_links — pairwise arcs between two x-positions.

Same call works in two coordinate setups:

- In Cartesian (no coord, or any affine coord) the artist emits half-ellipse
  arcs above ``y=0`` from ``x1`` to ``x2`` — a classic arc diagram. The
  bulge defaults to a semicircle (height = ``|x2 − x1| / 2``), so the
  chart's ``ylim`` autoscales to fit. Pair with ``c.yticks([])`` for the
  clean arc-diagram look.

- Attached to a ``CircularCoordinate`` via its ``inner=`` slot, the same
  artist draws Bezier chords through the central disc — the Circos-style
  link visual. The disc sub-coord ignores y data; chord endpoints land at
  the disc boundary (``r = 1`` of the sub-coord = ``r_inner`` of the rings)
  and curve through the canvas center.

Color follows the standard convention: ``aes(color="col")`` maps a
column (categorical → palette); a bare ``color="#hex"`` is a literal.

Sector handling:

- **Intra-sector** links (both endpoints in the same sector): pass the
  sector tag once on the layout via ``c.sectors(spec, column="chrom")``;
  ``x1`` and ``x2`` both pick it up.
- **Cross-sector** links: map per-endpoint sector-tag columns
  ``aes(x1_sector="src_chrom", x2_sector="dst_chrom")`` on the call. The
  layout-level ``column=`` is then optional. ``x1_sector`` /
  ``x2_sector`` are consumed by the sector remap and never reach the
  artist.

The chrome renderer auto-suppresses inter-sector divider walls when
this artist is active (via ``crosses_sectors=True``) — walls cutting
through a cross-sector curve read as a layering bug. Sector *labels*
still render.