mdciao.flare.freqs2chord

mdciao.flare.freqs2chord(freqs, res_idxs_pairs, fragments, fragment_names=None, iax=None, panelsize=10, fragment_colors=None, add_sigma=True, normalize_to_sigma=None, min_sigma=0, clockwise=True)

Coarse-grain the per-residue frequencies into a per-fragment chord-diagram.

Can be thought of as a coarse-grained flareplot, where residues belonging to the same fragments get turned into arcs instead of being plotted as individual dots. Each arc-length is proportional to the fragments’ overall number of contacts, NOT to the number of residues that the arc contains.

If fragments don’t participate in any contacts, they are hidden, i.e. the plot is always ‘sparse’

Curves connecting residue-pairs are squashed into chords connecting the arc. The opacity of each chord does NOT represent the underlying frequencies.

The main difference with mdciao.flare.freqs2flare is that the per-fragment number of contacts gets represented visually through the length the arc and that the chords don’t encode the number of underlying contacts.

This method uses the mpl_chord_diagram package by @tfardet with contributions from Guillermo Perez-Hernandez.

Parameters

  • freqs (iterable of floats) – A list of floats representing frequencies

  • res_idxs_pairs (list of pairs of integers, default is None) – The pairs of residue indices behind each freq entry in freqs. They can be any integers that could represent a residue. The only hard condition is that the set of np.unique(res_idxs_pairs) must be contained within fragments

  • fragments (a list of lists of integers) – These are the fragments used to coarse-grain the freqs. Any residue index of res_idxs_pairs that has a non-zero frequency associated to it in freqs has to appear in one (and only one) of the fragments.

  • fragment_names (list, default is None) – The fragment names

  • iax (Axes, default is None) – Parse an axis to draw on, otherwise one will be created using panelsize.

  • normalize_to_sigma (float, default is None) – If a float is provided, then the arcs of the chord-diagram can occupy the full 360% degrees of the circumference if, and only if, the sum over all per-fragment contacts (Sigma) aggregates to normalize_sigma. If they aggregate to a smaller value, then they will occupy a proportionately smaller portion of the circumference. If they aggregate to a larger value, then a error will be thrown. The default behavior (None) is to always occupy the full 360°, but this makes it hard to compare across different chord-diagrams for systems with different Sigmas, since they are scaled to 360° by default.

  • min_sigma (float, default is 0) – fragments with less contacts than this, i.e. aggregating to Sigma smaller than this, aren’t plotted. Please note that this cutoff applies only to the aggregated, per-fragment value, i.e. if enough individual contacts, each with frequencies < min_sigma, appear in one fragment and aggregate to a value > min_sigma, then this fragment is plotted. fragments dropped because of min_sigma, aren’t considered when computing how much of the circumference is occupied by the diagram, i.e. the Sigma used to normalize_to_sigma doesn’t include them.

  • panelsize (int, default is 10) – The panelsize for the plot, in inches

  • clockwise (bool, default is True) – Plot fragments (=arcs) clock-wise from 0° (3 o’clock), the same way that the flareplots do. If False, progress counter-clock-wise. The order in which the fragments are plotted is the order in which they appear in fragments, regardless of what indices they contain.

  • fragment_colors (iterable of color-likes) – The colors given to the arcs representing the fragments

  • add_sigma (bool, default is True) – Add the sum of freqs per fragment to the arc

Returns

  • iax (Axes)

  • non_zeros (list) – The idxs of fragments that have been plotted

  • plot_attribs (dict) – Objects of the plot, for the user to to manipulate further. Some attributes: “sigmas”, “fragment_names”, “fragment_labels”, “dots”, “r”. The attribute “dots” is a shim namedtuple with one single attribute, “radius”, for compatibility with downstream manipulations.