cachai.chplot.chord

cachai.chplot.chord(corr_matrix, names=None, colors=None, *, ax=None, radius=1, position=(0, 0), optimize=True, filter=True, bezier_n=30, show_diag=False, threshold=0.1, node_linewidth=10, node_gap=0.1, node_labelpad=0.2, blend=True, blend_resolution=200, chord_linewidth=1, chord_alpha=0.7, off_alpha=0.1, positive_hatch=None, negative_hatch='---', fontsize=15, font=None, min_dist=np.float64(0.2617993877991494), scale='linear', max_rho=0.4, max_rho_radius=0.7, show_axis=False, legend=False, positive_label=None, negative_label=None, rasterized=False, **kwargs)

A Chord Diagram from a correlation matrix, with customizable threshold, style, and colors.

In science, high-dimensional data are common, the choice of visualization tools directly affects both interpretation and communication. Chord diagrams are particularly valuable for illustrating weighted, non-directional connections — such as (anti-)correlations — between variables, treating parameters as nodes and their correlations as links.

Parameters

corr_matrixnumpy.ndarray or pandas.DataFrame

Correlation matrix for the chord diagram. This matrix has to be 2-dimensional, not empty, symmetric, and filled just with int or float values.

names / nlist, optional

Names for each node (default: ‘Ni’ for the i-th node)

colors / clist, optional

Custom colors for nodes (default: seaborn hls palette)

axmatplotlib.axes.Axes, optional

Axes to plot on (default: current pyplot axis)

Returns

ChordDiagram

An instance of the ChordDiagram class

Other Parameters

radius / rfloat

Radius of the diagram (default: 1.0)

position / ptuple

Position of the center of the diagram (default: (0,0))

optimizebool

Whether to optimize node order (default: True)

filterbool

Whether to remove nodes with no correlation (default: True)

bezier_nint

Bezier curve resolution (default: 30)

show_diagbool

Show self-connections (default: False)

threshold / thfloat

Minimum correlation threshold to display (default: 0.1)

node_linewidth / nlwfloat

Line width for nodes (default: 10)

node_gap / ngapfloat

Gap between nodes (0-1) (default: 0.1)

node_labelpad / npadfloat

Label position adjustment (default: 0.2)

blendbool

Whether to blend chord colors (default: True)

blend_resolutionint

Color blend resolution (default: 200)

chord_linewidth / clwfloat

Line width for chords (default: 1)

chord_alpha / calphafloat

Alpha of the facecolor for chords (default: 0.7)

off_alphafloat

Alpha for non-highlighted chords (default: 0.1)

positive_hatchstr

Hatch for positive correlated chords (default: None)

negative_hatchstr

Hatch for negative correlated chords (default: ‘—‘)

fontsizeint

Label font size (default: 15)

fontdict or str

Label font parameters (default: None)

min_distfloat

Minimum angle distance from which apply radius rule (default: 15 [degrees])

scalestr

Scale use to set chord’s thickness, wheter “linear” or “log” (default: “linear”)

max_rhofloat

Maximum chord’s thickness (default: 0.4)

max_rho_radiusfloat

Maximum normalized radius of the chords relative to center (default: 0.7)

show_axisbool

Whether to show the axis (default: False)

legendbool

Adds default positive and negative labels in the legend (default: False)

positive_labelstr

Adds positive label in the legend (default: None)

negative_labelstr

Adds negative label in the legend (default: None)

rasterizedbool

Whether to force rasterized (bitmap) drawing for vector graphics output (default: False)

Examples

First, import cachai and the necessary libraries.

import matplotlib.pyplot as plt
import cachai.chplot as chp

The only mandatory parameter for chord() is the correlation matrix. Assuming you already have your matrix, this line will show the default plot (in some IDLEs you need to add plt.show()):

chp.chord(corr_matrix)

Now, if you want to add a legend distinguishing positive and negative correlations, just set legend=True. Check the next example:

plt.figure(figsize=(6,6))

chp.chord(corr_matrix,
          threshold=0.3,
          negative_hatch='///',
          legend=True,
          rasterized=True)

plt.legend(loc='center',bbox_to_anchor=[0.5,0],ncols=2,fontsize=13,handletextpad=0)
plt.show()

To see more examples on how to use chplot.chord() check out the examples section.

Methods

ChordDiagram.highlight_node(node, chords=None, alpha=None)

Highlights a specific node. This affects the node and all its chords. If you want to highlight only some chords in the node, you can indicate this with chords.

Nodes are indexed based on their circular arrangement around the origin (center of the Chord Diagram). Index 0 corresponds to the first node in the first quadrant, with numbering proceeding counterclockwise around the diagram. Chords within each node are also indexed counterclockwise, starting from the outermost chord.

Parameters

nodeint

Index of the node to highlight (starting in 0).

chordslist or array-like, optional

List of chord indices to highlight (default: all chords).

alphafloat, optional

Transparency level for highlighting.

ChordDiagram.highlight_chord(node, chord, alpha=None)

Highlights a specific chord connected to a particular node.

Parameters

nodeint

Index of the node where the chord originates.

chordint

Index of the chord to highlight (starting in 0).

alphafloat, optional

Transparency level for highlighting.

ChordDiagram.set_chord_alpha(alpha)

Sets the transparency level for all chords in the diagram.

Parameters

alphafloat

Transparency value applied to all chords.