Modules

PyMOL-PUB package consists of 3 modules:

• handle module (handles.py): provides a comprehensive set of operations for working with structured data, performing loading and saving operations, splicing and property assignment operations, and alignment-related calculations.

• layout module (layouts.py): is responsible for figure processing and rendering operations.

• config module (windows.py): provides a Graphical User Interface protocol, allowing users without programming experience to complete the production of publication-quality figures.

Handle Module

class molpub.handles.Monitor

Bases: object

class molpub.handles.Score(similar_type: str = 'RMSD', model_type: str = 'CA')

Bases: object

get_params()

Get the distance type and model type.

Returns:

distance type and model type.

Return type:

str, str

static get_rotation(candidate_structure, reference_structure)

Get the rotation matrix.

Parameters:

• candidate_structure (numpy.ndarray) – candidate structure represented by three-dimension position list.

• reference_structure (numpy.ndarray) – reference structure represented by three-dimension position list.

Returns:

rotation matrix.

Return type:

numpy.ndarray

static kabsch(candidate_structure: ndarray, reference_structure: ndarray, use_center: bool = True) → Iterator[tuple]

Rotate candidate structure unto reference structure using Kabsch algorithm based on each position.

Parameters:

• candidate_structure (numpy.ndarray) – candidate structure represented by three-dimension position list.

• reference_structure (numpy.ndarray) – reference structure represented by three-dimension position list.

• use_center (bool) – use center location.

Returns:

current index, total index, final candidate structure and reference structure.

Return type:

int, int, numpy.ndarray, numpy.ndarray

molpub.handles.similar(structure_1, structure_2, score_method, use_center: bool = True, metrics: Optional[float] = None) → tuple

Judge whether two structures are similar.

Parameters:

• structure_1 (numpy.ndarray) – molecule structure 1.

• structure_2 (numpy.ndarray) – molecule structure 2.

• score_method (molpub.handles.Score) – method to calculate the similarity score.

• use_center (bool) – use center location.

• metrics (float or None) – score metrics to determine whether any two structures are similarity.

Returns:

flag, rotated candidate structure, original reference structure, start location, structure is reversed.

Return type:

tuple[bool, numpy.ndarray, numpy.ndarray, int, bool]

molpub.handles.cluster(structures, score_method, use_center: bool = True, metrics: Optional[float] = None, merge_type: str = 'all') → list

Cluster the molecule structures.

Parameters:

• structures (numpy.ndarray) – structures (with the same size).

• score_method (molpub.handles.Score) – method to calculate the similarity score.

• use_center (bool) – use center location.

• metrics (float or None) – score metrics to determine whether any two structures are similarity.

• merge_type (str) – the type to determine one structure can merge into a structure group.

Returns:

structure index cluster flags.

Return type:

list

molpub.handles.align(structures, score_method, use_center: bool = True, metrics: Optional[float] = None, merge_type: str = 'all') → dict

Align the molecule structures.

Parameters:

• structures (numpy.ndarray) – structures (with the same size).

• score_method (molpub.handles.Score) – method to calculate the similarity score.

• use_center (bool) – use center location.

• metrics (float or None) – score metrics to determine whether any two structures are similarity.

• merge_type (str) – the type to determine one structure can merge into a structure group.

Returns:

alignment structure results.

Return type:

dict

molpub.handles.set_properties(structure_paths: list, molecule_type: str, property_type: Optional[str] = None, targets: Optional[list] = None, unit_values: Optional[dict] = None) → list

Set physicochemical properties for structures.

Parameters:

• structure_paths (list) – the path to load structure.

• molecule_type (str) – type of molecule, including DNA, RNA or AA (amino acid).

• property_type (str or None) – physicochemical type to emphasize, like polarity, electronegativity, hydrophobicity, etc.

• targets (list or None) – selected contents.

• unit_values (dict or None) – values of unit, provided by users or the given property type.

Returns:

property values.

Return type:

list

molpub.handles.set_difference(alignment_data: ndarray, model_type: str, calculation_type: str = 'average') → ndarray

Set difference information for a known chain.

Parameters:

• alignment_data (numpy.ndarray) – alignment structure data, format of which could be (chain number, chain length, 3).

• model_type (str) – model used by structures (N-CA-C-O / CA for proteins, 3SPN / C3’ for DNA and RNA sequences).

• calculation_type (str) – difference calculation, including average and maximum.

Returns:

difference values.

Return type:

numpy.ndarray

Note

If chain number is 2, the parameter ‘calculation_type’ is invalid. We provide the root mean squared error of each unit. Otherwise, we provide the average and maximum value of the root mean squared error of each unit.

molpub.handles.kmer(chain: str, structure: ndarray, sub_length: int) → Iterator[tuple]

Disassemble the entire chain into sub-segments of the given length.

Parameters:

• chain (str) – molecule chain.

• structure (numpy.ndarray) – molecule structure.

• sub_length (int) – length of sub-segment.

Returns:

sub chain and the corresponding sub structure.

Return type:

str, numpy.ndarray

molpub.handles.load_structure_from_file(file_path: str, molecule_type: str = 'AA') → tuple

Load structure data from file.

Parameters:

• file_path (str) – path to load file.

• molecule_type (str) – type of molecule data, which could be DNA, RNA or AA (amino acid).

Returns:

chains and their corresponding structures.

Return type:

dict, dict

molpub.handles.save_structure_to_file(chains: list, structures: ndarray, file_path: str, model_type: str = 'CA')

Save temporary structure to file.

Parameters:

• chains (list) – chains.

• structures (numpy.ndarray) – corresponding structures of chains.

• file_path (str) – path to save temp file.

• model_type (str) – model used by structures (N-CA-C-O / CA for proteins, 3SPN / C3 for DNA and RNA sequences).

Layout Module

class molpub.layouts.Figure(manuscript_format: str = 'Nature', column_format: Optional[int] = None, occupied_columns: int = 1, aspect_ratio: tuple = (1, 2), row_number: int = 1, column_number: int = 1, interval: tuple = (0, 0), dpi: Optional[int] = None, mathtext: bool = True)

Bases: object

static calculate_locations(layout: tuple)

Calculate the panel locations from layout.

Parameters:

layout (tuple) – picture segmentation method and specified location(x,y,order).

paste_bitmap(image: PngImageFile, locations: Optional[list] = None, layout: Optional[tuple] = None, zorder: Optional[int] = None, frame_off: bool = True, backgroundcolor: str = '#FFFFFF', positions: Optional[tuple] = None, linewidth: float = 1.0, transparent: bool = False, linecolor: str = '#000000')

Paste a bitmap in the figure or the panel in figure.

Parameters:

• image (PIL.PngImagePlugin.PngImageFile) – bitmap image.

• locations (list or None) – location in the panel (x,y,dx and dy: the scale of the whole picture).

• layout (tuple or None) – picture segmentation method and specified location(x,y,order).

• zorder (int or None) – order in which components are superimposed on each other.

• frame_off (bool) – draw frame for the image, no frame by default.

• backgroundcolor (str) – the background color for image panel.

• positions (tuple or None) – set the position of the image in the panel.

• linewidth (float) – the width of the frame.

• transparent (bool) – set a transparent background.

• linecolor (str) – the color of the frame.

save_figure(save_path: str)

Save the whole figure.

Parameters:

save_path (str) – the path of save figure.

set_image(image_path: Optional[str] = None, widget_type: Optional[str] = None, widget_attributes: Optional[str] = None, image_format: str = '.png', locations: Optional[list] = None, layout: Optional[tuple] = None, zorder: Optional[int] = None, frame_off: bool = True, backgroundcolor: str = '#FFFFFF', positions: Optional[tuple] = None, linewidth: float = 1.0, transparent: bool = False, linecolor: str = '#000000')

Put the structure image or widget with a specific size in a specific position of a panel.

Parameters:

• image_path (str or None) – path of structure image.

• widget_type (str or None) – widget type for painting.

• widget_attributes (tuple or None) – attributes of the selected widget.

• image_format (str or None) – format of structure image.

• locations (list or None) – location in the panel (x,y,dx and dy: the scale of the whole picture).

• layout (tuple or None) – picture segmentation method and specified location(x,y,order).

• zorder (int or None) – order in which components are superimposed on each other.

• frame_off (bool) – draw frame for the image, no frame by default.

• backgroundcolor (str) – the background color for image panel.

• positions (tuple or None) – set the position of the image in the panel.

• linewidth (float) – the width of the frame.

• transparent (bool) – set a transparent background.

• linecolor (str) – the color of the frame.

set_panel(function: Optional[function] = None, function_params: Optional[dict] = None, image_path: Optional[str] = None)

Paint a panel in a specific location.

Parameters:

• function (types.FunctionType or None) – painting function.

• function_params (dict or None) – parameters of the painting function.

• image_path (str or None) – path of structure image.

set_panel_grid(grid_params)

Set panel grid for the figure.

Parameters:

grid_params (dict) – grid location and occupy of figure.

set_text(annotation: str, font_size: int = 16, alignment: str = 'center', locations: Optional[list] = None, layout: Optional[tuple] = None, zorder: Optional[int] = None, weight: str = 'normal', color: str = '#000000', backgroundcolor: str = '#FFFFFF', positions: tuple = (0.0, 0.0), frame_off: bool = True, transparent: bool = False)

Put the text box with a specific size in a specific position of a panel.

Parameters:

• annotation (str) – text content.

• font_size (str) – font size.

• alignment (str) – horizontal alignment, accepting “center”, “right” and “left”.

• locations (list or None) – location in the panel (x,y, dx and dy: the scale of the whole image).

• layout (tuple or None) – picture segmentation method and specified location(x,y,order).

• zorder (int or None) – order in which components are superimposed on each other.

• weight (str) – font weight.

• color (str) – font color.

• backgroundcolor (str) – background color.

• positions (tuple) – set the position of the text in the panel.

• frame_off (bool) – draw frame for the text, no frame by default.

• transparent (bool) – set a transparent background.

class molpub.layouts.DefaultStructureImage(structure_paths: list)

Bases: object

clear()

Clear the PyMOL.

close()

Close the PyMOL.

load_pymol(load_path: str)

Load the PyMOL state.

Parameters:

load_path (str) – path to save file.

save(save_path: str, width: int = 640, ratio: float = 0.75, dpi: int = 1200)

Save the structure image.

Parameters:

• save_path (str) – path to save file.

• width (int) – width of the structure image.

• ratio (float) – the ratio of width to height.

• dpi (int) – dots per inch.

save_pymol(save_path: str)

Save the PyMOL state.

Parameters:

save_path (str) – path to save file.

set_cache(cache_contents: list)

Set cache contents of the structure.

Parameters:

cache_contents (list) – hidden contents.

set_shape(representation_plan: list, initial_representation: str = 'cartoon', independent_color: bool = False, closed_surface: bool = False)

Set the shape (or representation in PyMOL) of the structure.

Parameters:

• representation_plan (list) – the type of the visual structure.

• initial_representation (str) – if representation type is index, can optionally operate on the specified chain.

• independent_color (bool) – if independent_color is False, colors can leak into the open surface edge.

• closed_surface (bool) – if closed_surface is True, create a closed surface.

set_state(translate: Optional[list] = None, rotate: Optional[list] = None, inner_align: bool = False, target: Optional[str] = None, mobile: Optional[str] = None, only_rotate: bool = False)

Set the state of the structure.

Parameters:

• translate (list or None) – translate distances with x/y/z-axis.

• rotate (list or None) – rotate degree with x/y/z-axis.

• inner_align (bool) – align multiple structures through built-in interfaces (cmd.align).

• target (str or None) – the target (or template) name can be specified if the inner align is executed.

• mobile (str or None) – the mobile name can be specified if the inner align is executed.

• only_rotate (bool) – only rotation, no initialization.

set_zoom(zoom_contents: list, buffer: float = 0.0)

Set zoom contents of the structure.

Parameters:

• zoom_contents (list) – structure content that needs to be zoomed.

• buffer (float) – the buffer area size of the target structure.

class molpub.layouts.HighlightStructureImage(structure_paths: list)

Bases: DefaultStructureImage

set_color(coloring_plan: list, initial_color: str = '0xFFFFCC', edge_color: Optional[str] = None)

Set colors for the structure with the coloring plan in order.

Parameters:

• coloring_plan (list) – coloring plan for the structure.

• initial_color (str) – initial color in the structure.

• edge_color (str or None) – edge color of the structure if required.

class molpub.layouts.PropertyStructureImage(structure_paths: list)

Bases: DefaultStructureImage

set_color(target: str, properties: Optional[list] = None, color_map: str = 'rainbow', initial_color: str = '0xAAAAAA', edge_color: Optional[str] = None, gauge_strengthen: bool = False)

Set colors for the structure with its element properties.

Parameters:

• target (str) – coloring target select, including “range”, “segment”, “chain” and “model”.

• properties (list or None) – element properties of the structure.

• color_map (str) – coloring palette.

• initial_color (str) – initial color in the structure.

• edge_color (str or None) – edge color of the structure if required.

• gauge_strengthen (bool) – strengthen property differences through gauge changes (available in “cartoon”).

molpub.layouts.obtain_widget_icon(save_path: str, widget_type: str, params: dict, dpi: int = 1200)

Obtain the widget icon based on the predetermined setting.

Parameters:

• save_path (str) – the path of save icon.

• widget_type (str) – widget type including “arrow” and “rotation”.

• params (dict) – parameters of the widget.

• dpi (int) – dots per inch.