Plotting

Plot residues — prolif.plotting.residues

New in version 2.0.0.

prolif.plotting.residues.display_residues(mol: Molecule, residues_slice: slice | None = None, *, size: tuple[int, int] = (200, 140), mols_per_row: int = 4, use_svg: bool = True, sanitize: bool = True) → Any

Display a grid image of the residues in the molecule. The hydrogens are stripped and the 3D coordinates removed for a clearer visualisation.

Parameters:

• mol (prolif.Molecule) – The molecule to show residues from.

• residues_slice (slice | None = None) – Optionally, a slice of residues to display, e.g. slice(20) for the first 20 residues, or slice(<start>, <stop>, <step>) for a more complex selection.

• size (tuple[int, int] = (200, 140)) – Size of each residue image.

• mols_per_row (int = 4) – Number of residues displayed per row.

• use_svg (bool = True) – Generate an SVG or PNG image.

• sanitize (bool = True) – Sanitize the residues before displaying.

• versionchanged: (..) – 2.1.0: Added sanitize parameter that defaults to False for easier debugging.

Plot interactions as a barcode — prolif.plotting.barcode

New in version 2.0.0.

class prolif.plotting.barcode.Barcode(df: DataFrame)

Creates a barcode plot of interactions.

Parameters:

df (pandas.DataFrame) – The DataFrame as obtained from Fingerprint.to_dataframe()

COLORS

Dictionnary of colors used in the plot for interactions.

Type:

dict

display(figsize: tuple[int, int] = (8, 10), dpi: int = 100, interactive: bool = False, n_frame_ticks: int = 10, residues_tick_location: Literal['top', 'bottom'] = 'top', xlabel: str = 'Frame', subplots_kwargs: dict | None = None, tight_layout_kwargs: dict | None = None) → Axes

Generate and display the barcode plot.

Parameters:

• figsize (tuple[int, int] = (8, 10)) – Size of the matplotlib figure.

• dpi (int = 100) – DPI used for the matplotlib figure.

• interactive (bool) – Add hover interactivity to the plot (only relevant for notebooks). You may need to add %matplotlib notebook or %matplotlib ipympl for it to work as expected.

• n_frame_ticks (int = 10) – Number of ticks on the X axis. May use ±1 tick to have them evenly spaced.

• residues_tick_location (Literal["top", "bottom"] = "top") – Whether the Y ticks appear at the top or at the bottom of the series of interactions of each residue.

• xlabel (str = "Frame") – Label displayed for the X axis.

• subplots_kwargs (dict | None = None) – Other parameters passed to matplotlib.pyplot.subplots().

• tight_layout_kwargs (dict | None = None) – Other parameters passed to matplotlib.figure.Figure.tight_layout().

classmethod from_fingerprint(fp: Fingerprint) → Barcode

Creates a barcode object from a fingerprint.

Plot interactions in 3D — prolif.plotting.complex3d

New in version 2.0.0.

class prolif.plotting.complex3d.Complex3D(ifp: IFP, lig_mol: Molecule, prot_mol: Molecule, water_mol: Molecule | None = None)

Creates a py3Dmol plot of interactions.

Parameters:

• ifp (IFP) – The interaction dictionary for a single frame.

• lig_mol (Molecule) – The ligand molecule to display.

• prot_mol (Molecule) – The protein molecule to display.

• water_mol (Optional[Molecule]) – Additional molecule (e.g. waters) to display.

COLORS

Dictionnary of colors used in the plot for interactions.

Type:

dict

LIGAND_STYLE

Style object passed to 3Dmol.js for the ligand.

Type:

dict[str, dict] = {“stick”: {“colorscheme”: “cyanCarbon”}}

RESIDUES_STYLE

Style object passed to 3Dmol.js for the protein residues involved in interactions.

Type:

dict[str, dict] = {“stick”: {}}

PROTEIN_STYLE

Style object passed to 3Dmol.js for the entire protein.

Type:

dict[str, dict] = {“cartoon”: {“style”: “edged”}}

PEPTIDE_STYLE

Style object passed to 3Dmol.js for the ligand as a peptide if appropriate.

Type:

dict[str, dict] = “cartoon”: {“style”: “edged”, “colorscheme”: “cyanCarbon”}

PEPTIDE_THRESHOLD

Ligands with this number of residues or more will be displayed using PEPTIDE_STYLE in addition to the LIGAND_STYLE.

Type:

int = 5

LIGAND_DISPLAYED_ATOM

Which atom should be used to display an atom-to-atom interaction for the ligand. Refers to the order defined in the SMARTS pattern used in interaction definition. Interactions not specified here use 0 by default.

Type:

dict[str, int]

PROTEIN_DISPLAYED_ATOM

Same as LIGAND_DISPLAYED_ATOM for the protein.

Type:

dict[str, int]

LIGAND_RING_INTERACTIONS

Which interactions should be displayed using the centroid instead of using LIGAND_DISPLAYED_ATOM for the ligand.

Type:

set[str]

PROTEIN_RING_INTERACTIONS

Which interactions should be displayed using the centroid instead of using PROTEIN_DISPLAYED_ATOM for the protein.

Type:

set[str]

BRIDGED_INTERACTIONS

For bridged-interactions such as WaterBridge. The key is the interaction name, and the value is the name of the molecule in the metadata indices dictionary.

Type:

dict[str, str]

RESIDUE_HOVER_CALLBACK

JavaScript callback executed when hovering a residue involved in an interaction.

Type:

str

INTERACTION_HOVER_CALLBACK

JavaScript callback executed when hovering an interaction line.

Type:

str

DISABLE_HOVER_CALLBACK

JavaScript callback executed when the hovering event is finished.

Type:

str

.. versionchanged:: 2.1.0

Added water_mol parameter to the constructor to display waters involved in WaterBridge interactions. Added save_png method to save the current state of the 3D viewer to a PNG. Added remove_hydrogens parameter to the display and compare methods to remove non-polar hydrogens that aren’t involved in an interaction. Added only_interacting parameter to the display and compare methods to show all protein residues in the vicinity of the ligand, or only the ones participating in an interaction.

compare(other: Complex3D, *, size: tuple[int, int] = (900, 600), display_all: bool = False, linked: bool = True, color_unique: str | None = 'magentaCarbon', only_interacting: bool = True, remove_hydrogens: Union[bool, Literal['ligand', 'protein', 'water']] = True) → Complex3D

Displays the initial complex side-by-side with a second one for easier comparison.

Parameters:

• other (Complex3D) – Other Complex3D object to compare to.

• size (tuple[int, int] = (900, 600)) – The size of the py3Dmol widget view.

• display_all (bool = False) – Display all occurences for a given pair of residues and interaction, or only the shortest one. Not relevant if count=False in the Fingerprint object.

• linked (bool = True) – Link mouse interactions (pan, zoom, translate) on both views.

• color_unique (str | None = "magentaCarbon",) – Which color to use for residues that have interactions that are found in one complex but not the other. Use None to disable the color override.

• only_interacting (bool = True) – Whether to show all protein residues in the vicinity of the ligand, or only the ones participating in an interaction.

• remove_hydrogens (bool | Literal["ligand", "protein", "water"] = True) – Whether to remove non-polar hydrogens (unless they are involved in an interaction).

• versionadded: (..) – 2.0.1:

• versionchanged: (..) – 2.1.0: Added only_interacting=True and remove_hydrogens=True parameters. Non-polar hydrogen atoms that aren’t involved in interactions are now hidden. Added support for waters involved in WaterBridge interactions.

display(size: tuple[int, int] = (650, 600), display_all: bool = False, only_interacting: bool = True, remove_hydrogens: Union[bool, Literal['ligand', 'protein', 'water']] = True, sanitize: Union[bool, Literal['ligand', 'protein']] = 'protein') → Complex3D

Display as a py3Dmol widget view.

Parameters:

• size (tuple[int, int] = (650, 600)) – The size of the py3Dmol widget view.

• display_all (bool = False) – Display all occurences for a given pair of residues and interaction, or only the shortest one. Not relevant if count=False in the Fingerprint object.

• only_interacting (bool = True) – Whether to show all protein residues in the vicinity of the ligand, or only the ones participating in an interaction.

• remove_hydrogens (bool | Literal["ligand", "protein", "water"] = True) – Whether to remove non-polar hydrogens (unless they are involved in an interaction).

• sanitize (bool | Literal["ligand", "protein"] = "protein") – Whether to sanitize the RDKit molecules used for visualization. This is to avoid unkekulization issues that may arise when using the coordinates of the molecule.

Changed in version 2.1.0: Added only_interacting=True and remove_hydrogens=True parameters. Non-polar hydrogen atoms that aren’t involved in interactions are now hidden. Added support for waters involved in WaterBridge interactions.

Changed in version 2.2.0: Added sanitize parameter to allow sanitization of the RDKit molecules used for visualization, which can help avoid unkekulization issues when using the coordinates of the molecule directly.

classmethod from_fingerprint(fp: Fingerprint, lig_mol: Molecule, prot_mol: Molecule, water_mol: Molecule | None = None, *, frame: int) → Complex3D

Creates a py3Dmol plot of interactions.

Parameters:

• fp (prolif.fingerprint.Fingerprint) – The fingerprint object already executed using one of the run or run_from_iterable methods.

• frame (int) – The frame number chosen to select which interactions are going to be displayed.

• lig_mol (Molecule) – The ligand molecule to display.

• prot_mol (Molecule) – The protein molecule to display.

• water_mol (Optional[Molecule]) – Additional molecule (e.g. waters) to display.

static get_ring_centroid(mol: Molecule, indices: tuple[int, ...]) → Point3D

Get the centroid of a ring system.

save_png() → None

Saves the current state of the 3D viewer to a PNG. Not available outside of a notebook.

New in version 2.1.0.

Plot a Ligand Interaction Network — prolif.plotting.network

New in version 0.3.2.

Changed in version 2.0.0: Replaced LigNetwork.from_ifp with LigNetwork.from_fingerprint which works without requiring a dataframe with atom indices.

class prolif.plotting.network.lignetwork.LigNetwork(df: DataFrame, lig_mol: Mol, use_coordinates: bool = False, flatten_coordinates: bool = True, kekulize: bool = False, molsize: int = 35, rotation: float = 0, carbon: float = 0.16, use_segid: bool = False)

Creates a ligand interaction diagram

Parameters:

• df (pandas.DataFrame) – Dataframe with a 4-level index (ligand, protein, interaction, atoms) and weight and distance columns for values

• lig_mol (rdkit.Chem.rdChem.Mol) – Ligand molecule

• use_coordinates (bool) – If True, uses the coordinates of the molecule directly, otherwise generates 2D coordinates from scratch. See also flatten_coordinates.

• flatten_coordinates (bool) – If this is True and use_coordinates=True, generates 2D coordinates that are constrained to fit the 3D conformation of the ligand as best as possible.

• kekulize (bool) – Kekulize the ligand

• molsize (int) – Multiply the coordinates by this number to create a bigger and more readable depiction

• rotation (float) – Rotate the structure on the XY plane

• carbon (float) – Size of the carbon atom dots on the depiction. Use 0 to hide the carbon dots

• use_segid (bool) – If True, uses the segment ID as the chain identifier of residues.

COLORS

Dictionnary of colors used in the diagram. Subdivided in several dictionaries:

• “interactions”: mapping between interactions types and colors

• “atoms”: mapping between atom symbol and colors

• “residues”: mapping between residues types and colors

Type:

dict

RESIDUE_TYPES

Mapping between residue names (3 letter code) and types. The types are then used to define how each residue should be colored.

Type:

dict

Notes

You can customize the diagram by tweaking LigNetwork.COLORS and LigNetwork.RESIDUE_TYPES by adding or modifying the dictionaries inplace.

Changed in version 2.0.0: Replaced LigNetwork.from_ifp with LigNetwork.from_fingerprint which works without requiring a dataframe with atom indices. Replaced match3D parameter with use_coordinates and flatten_coordinates to give users more control and allow them to provide their own 2D coordinates. Added support for displaying peptides as the “ligand”. Changed the default color for VanDerWaals.

Changed in version 2.1.0: Added the show_interaction_data argument and exposed the fontsize in display.

display(**kwargs: Any) → LigNetwork

Prepare and display the network.

Parameters:

• width (str = "100%") –

• height (str = "500px") –

• fontsize (int = 20) –

• show_interaction_data (bool = False) –

classmethod from_fingerprint(fp: Fingerprint, ligand_mol: Mol, kind: Literal['aggregate', 'frame'] = 'aggregate', frame: int = 0, display_all: bool = False, threshold: float = 0.3, **kwargs: Any) → LigNetwork

Helper method to create a ligand interaction diagram from a Fingerprint object.

Notes

Two kinds of diagrams can be rendered: either for a designated frame or by aggregating the results on the whole IFP and optionnally discarding interactions that occur less frequently than a threshold. In the latter case (aggregate), only the group of atoms most frequently involved in each interaction is used to draw the edge.

Parameters:

• fp (prolif.fingerprint.Fingerprint) – The fingerprint object already executed using one of the run or run_from_iterable methods.

• lig (rdkit.Chem.rdChem.Mol) – Ligand molecule

• kind (str) – One of "aggregate" or "frame"

• frame (int) – Frame number (see ifp). Only applicable for kind="frame"

• display_all (bool) – Display all occurences for a given pair of residues and interaction, or only the shortest one. Only applicable for kind="frame". Not relevant if count=False in the Fingerprint object.

• threshold (float) – Frequency threshold, between 0 and 1. Only applicable for kind="aggregate"

• kwargs (object) – Other arguments passed to the LigNetwork class

Changed in version 2.0.0: Added the display_all parameter.

save(fp: Union[str, Path, TextIO], **kwargs: Any) → None

Save the network to an HTML file

Parameters:

fp (str or file-like object) – Name of the output file, or file-like object

save_png() → Any

Saves the current state of the ligplot to a PNG. Not available outside of a notebook.

Notes

Requires calling display or show first. The legend won’t be exported.

New in version 2.1.0.

show(filename: str, **kwargs: Any) → LigNetwork

Save the network as HTML and display the resulting file