Chords¶

detroit.chord() → Chord¶

Constructs a new chord layout with the default settings.

Returns:: Chord object
Return type:: Chord

detroit.chord_transpose() → Chord¶

A transposed chord layout. Useful to highlight outgoing (rather than incoming) flows.

Returns:: Chord object
Return type:: Chord

detroit.chord_directed() → Chord¶

A chord layout for unidirectional flows. The chord from i to j is generated from the value in matrix[i][j] only.

Returns:: Chord object
Return type:: Chord

class detroit.chord.chord.Chord(directed: bool, transpose: bool)¶

Chord layout

Parameters:

directed (bool) – True for directed flow
transpose (bool) – True to transpose the specified matrix

__call__(matrix: list[list[float]]) → Chords¶

Computes the chord layout for the specified square matrix of size \(n \times n\), where the matrix represents the directed flow amongst a network (a complete digraph) of n nodes.

The return value of chord(matrix) is an array of chords, where each chord represents the combined bidirectional flow between two nodes i and j (where i may be equal to j) and is an object with the following properties:

source - the source subgroup
target - the target subgroup

Each source and target subgroup is also an object with the following properties:

index - the node index i
start_angle - the start angle in radians
end_angle - the end angle in radians
value - the flow value matrix[i][j]

The chords are typically passed to ribbon to display the network relationships.

The returned array includes only chord objects for which the value matrix[i][j] or matrix[j][i] is non-zero. Furthermore, the returned array only contains unique chords: a given chord ij represents the bidirectional flow from i to j and from j to i, and does not contain a duplicate chord ji; i and j are chosen such that the chord’s source always represents the larger of matrix[i][j] and matrix[j][i].

The chords array also defines a secondary array of length n, chords.groups, where each group represents the combined outflow for node i, corresponding to the elements matrix[i][0 ... n - 1], and is an object with the following properties:

index - the node index i
start_angle - the start angle in radians
end_angle - the end angle in radians
value - the total outgoing flow value for node i

The groups are typically passed to arc to produce a donut chart around the circumference of the chord layout.

Parameters:: matrix (list[list[float]]) – Square matrix of size \(n \times n\)
Returns:: Chords Object which behaves like a list and has Chords.groups attribute. Groups are typically passed to arc to produce a donut chart around the circumference of the chord layout.
Return type:: Chords

set_pad_angle(pad_angle: float) → Chord¶

Sets the pad angle between adjacent groups to the specified number in radians and returns this chord layout.

Parameters:: pad_angle (float) – Pad angle value
Returns:: Itself
Return type:: Chord

set_sort_groups(sort_groups: Callable[[float, float], float] | None = None) → Chord¶

Sets the group comparator to the specified function or None and returns this chord layout.

Parameters:: sort_groups (Callable[[float, float], float] | None) – Sort group function
Returns:: Itself
Return type:: Chord

set_sort_subgroups(sort_subgroups: Callable[[float, float], float] | None = None) → Chord¶

Sets the subgroup comparator to the specified function or None and returns this chord layout.

Parameters:: sort_subgroups (Callable[[float, float], float] | None) – Sort subgroups function
Returns:: Itself
Return type:: Chord

set_sort_chords(compare: Callable[[float, float], float] | None = None) → Chord¶

Sets the chord comparator to the specified function or None and returns this chord layout.

Parameters:: compare (Callable[[float, float], float] | None) – Compare function
Returns:: Itself
Return type:: Chord

class detroit.chord.chord.Chords(data: list[ChordItem], groups: list[ChordValue])¶

class detroit.chord.chord.ChordValue(index: int, start_angle: float, end_angle: float, value: float)¶

Chord subgroup

index¶

The node index i

Type:: int

start_angle¶

The start angle in radians

Type:: float

end_angle¶

The end angle in radians

Type:: float

value¶

The flow value matrix[i][j]

Type:: float

class detroit.chord.chord.ChordItem(source: ChordValue | None = None, target: ChordValue | None = None)¶

Chord object containing source and target subgroups

source¶

The source subgroup

Type:: ChordValue | None

target¶

The target subgroup

Type:: ChordValue | None