mdciao.flare.freqs2flare

mdciao.flare.freqs2flare(freqs, res_idxs_pairs, fragments=None, sparse_residues=False, sparse_fragments=False, exclude_neighbors=1, freq_cutoff=0, iax=None, fragment_names=None, center=array([0, 0]), r=1, mute_fragments=None, anchor_fragments=None, SS=None, panelsize=10, angle_offset=0, highlight_residxs=None, select_residxs=None, top=None, colors=True, fontsize=None, shortenAAs=True, aa_offset=0, markersize=None, bezier_linecolor='k', plot_curves_only=False, textlabels=True, padding=[1, 1, 1], lw=5, signed_colors=None, subplot=False, aura=None, coarse_grain=False)

Plot contact frequencies as flare plots.

The residues are plotted as dots lying on a circle of radius r, with Bezier curves of variable opacity connecting the dots. The curve opacity represents the contact frequency, freq, between two residues.

For more info see the links here mdciao.flare.

One can control separately what residues and what curves ultimately get shown, allowing for “contactless” residues to still appear as dots in the circle. This is very helpful to highlight the molecular topology. For example, it’s useful to show an entire TM-helix even if only the residues in its middle have contacts. Furthermore, it allows for re-use of a “background” of residues on top of which different sets of curves (e.g. with different colors) can be plotted.

  • which/how residues get plotted:

    • res_idxs_pairs is the primary source of which residues will be plotted, its length matches the length the freqs object.

    • fragments is used to a) expand the initial residue list (if needed) and b) split the residues into fragments when placing the dots on the flareplot.

    • sparse_residues can modify res_idxs_pairs, either by looking at non-zero freqs or by direct input (see below)

    • sparse_fragments is analogous, but with fragments

    • highlight_residxs show the labels of these residues in red

  • which/how residues get connected with bezier curves:

    • exclude_neighbors do not plot curves connecting neighbors

    • freq_cutoff do not plot curves with associated freq below this cutoff

    • select_residxs plot only the curves where these residues appear

    • mute_fragments do not plot curves from/to this fragment

    • anchor_fragments only plot curves from/to this fragment

Parameters

  • freqs (numpy.ndarray) –

    The contact frequency to show in the flareplot. The opacity of the bezier curves connecting residue pairs will be proportional to this number. Can have different shapes:

    • (n) n is the number of residue pairs in res_idxs_pairs

    • (m,n) m is the number of frames, in this case, an average over m will be done automatically.

    If you already have an mdciao.contacts.ContactGroup-object, simply pass the result of calling mdciao.contacts.ContactGroup.frequency_per_contact (with a given cutoff)

  • res_idxs_pairs (iterable of pairs) – pairs of residue indices for the above N contact frequencies. If you already have an mdciao.contacts.ContactGroup-object, simply pass the result of calling mdciao.contacts.ContactGroup.res_idxs_pairs

  • fragments (list of lists of integers, default is None) – The residue indices to be drawn as a circle for the flareplot. These are the dots that will be plotted on that circle regardless of how many contacts they appear in. 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

  • sparse_residues (boolean, default is False) –

    Show only those residues that appear in the initial res_idxs_pairs

    Note

    There is a development option for this argument where a residue list is passed, meaning, show these residues regardless of any other option that has been passed. Perhaps this changes in the future.

  • sparse_fragments (boolean, default is False) – Same as sparse_residues, but with fragments. When sparse_residues isn’t False, this option has no effect.

  • exclude_neighbors (int, default is 1) – Do not show contacts where the partners are separated by these many residues. If no top is passed, the neighborhood-condition is checked using residue serial-numbers, assuming the molecule only has one long peptidic-chain.

  • freq_cutoff (float, default is 0) – Contact frequencies lower than this value will not be shown

  • iax (Axes) –

    Parse an axis to draw on, otherwise one will be created using panelsize. In case you want to re-use the same cirlce of residues as a background to plot different sets of freqs, YOU HAVE TO USE THE SAME fragments and sparse values

    on all calls, else the

    bezier lines will be placed erroneously.

  • fragment_names (iterable of strings, default is None) – The names of the fragments used in fragments

  • center (np.ndarray, default is [0,0]) – In axis units, where the flareplot will be centered around

  • r (float, default is 1) – In axis units, the radius of the flareplot

  • mute_fragments (iterable of integers, default is None) – Curves involving these fragments will be hidden. Fragments are expressed as indices of fragments

  • anchor_fragments (iterable of integers, default is None) –

    Curves not involving these fragments will be not be shown, i.e. it is the complementary

    of mute_fragments. Both cannot be passed simultaneously.

  • SS (any, default is None) –

    Can be several things: * Array containing secondary structure (ss) information to

    be included in the flareplot. Indexed by residue index, i.e. it can also be a dictionary as long as SS[idx] returns the SS for residue with that residue idx

    • Path to filename, will be passed to

    mdciao.utils.residue_and_atom.get_SS, check the docs there

  • panelsize (float, default is 10) – Size in inches of the panel (=figsize in matplotlib). Will be ignored if a pre-existing axis object is parsed

  • angle_offset (float, default is 0) – In degrees, where the flareplot “begins”. Zero is xy = [1,0]

  • highlight_residxs (iterable of ints, default is None) – Show the labels for these residues in red

  • select_residxs (iterable of ints, default is None) – Only the residues here can be connected with a Bezier curve

  • top (Topology object, default is None) – If provided a top, residue names (e.g. GLU30) will be used instead of residue indices. Will fail if the residue indices in res_idxs_pairs can not be used to call top.residue(ii)

  • colors (boolean, default is True) –

    Color control. Can take different inputs

    • True: use one different color per segment

    • False: defaults to gray

    • str or char: use that color for all residues (e.g. “r” or “red”)

    • A list of strings of len = number of drawn residues, which is equal to len(np.hstack(fragments))

    • A list of strings of len = len(fragments)

    Any other length will produce an error

  • fontsize (float, default is None) – Currently, the fontsize is internally computed as a function of the dotsize, since the space available for the labels is determined by the dotsize. There’s plans for user control in the future, but until then NotImplementedError will be thrown

  • shortenAAs (boolean, default is True) – Use short AA-codes, e.g. E30 for GLU30. Only has effect if a topology is parsed

  • aa_offset (int, default is 0) – Add this number to the resSeq value

  • markersize (float, default is None) – The size of the dots. It is internally optimized to have adjacent dots fill the available space without overlapping among them. There’s plans for user control in the future, but until then NotImplementedError will be thrown

  • bezier_linecolor (color-like, default is 'k') – The color of the bezier curves connecting the residues. Can be a character, string or RGB value (not RGBA)

  • plot_curves_only (bool, default is False) – Only plot the curves connecting the dots, but not the dots themselves or any other annotation. (labels, fragment names or SS information). The same caution as iax applies.

  • textlabels (bool or array_like, default is True) –

    How to label the residue dots. Gets passed directly to mdciao.flare.circle_plot_residues. Options are:

    • True: the dots representing the residues will get a label automatically, either their serial index or the residue name, e.g. GLU30, if a top was passed.

    • False: no labeling

    • array_like : will be passed as replacement_labels to mdciao.flare.add_fragmented_residue_labels

  • padding (iterable of len 3, default is [1,1,1]) –

    The padding, expressed as empty dot positions. Each number is used for:

    • the beginning of the flareplot, before the first residue

    • between fragments

    • at the end of the plot, after the last residue

  • lw (float, default is None) – Line width of the contact lines

  • signed_colors (dict, default is None) – Provide a color dictionary, e.g. {-1:”b”, +1:”r”} to give different colors to positive and negative alpha values. If None, defaults to bezier_linecolor

  • subplot (bool, default is False) – If True, the method checks if iax is the last axis in a figure (=all other panels have been already drawn) and then transfers the last plot’s fontsizes and linewidths to panels (if possible). It will help produce more homogeneous plots when heuristics about font-sizing fail

  • aura (iterable, default is None) – Scalar array, indexed with residue indices, e.g. RMSF, SASA, conv. degree… It will be drawn as an aura around the flareplot.

  • coarse_grain (bool, default is False) – If True, will use the fragment definitions of fragments and/or sparse_fragments to coarse grain the frequencies into per-fragment frequencies and show them as a chord-diagram wrapping around freqs2chord Check there for more info

Returns

  • iax (Axes) – You can do iax.figure.savefig(“figure.png”) to save the figure. Checkout savefig for more options

  • plotted_pairs (2D np.ndarray)

  • plot_attribs (dict) – Objects of the plot if the user wants to manipulate them further or re-use some attributes: “bezier_lw”, “bezier_curves”, “fragment_labels”, “dot_labels”, “dots”, “SS_labels”