Meeko: molecule parameterization and software interoperability for docking and beyond

Abstract

Molecule parametrization is an essential requirement to guarantee the accuracy of simulations. Parametrization includes a proper perception of chemical properties such as bonds, formal charges and protonation states. This includes large biological macromolecules, such as proteins and nucleic acids, and small molecules, such as ligands and co-factors. The structures of proteins and nucleic acids are challenging due to omission of several atoms from the structural model, and from the lack of connectivity and bond order information in the PDB and mmCIF file formats. For small molecules, the very large chemical diversity poses challenges for both validating correctness and providing accurate parameters. These challenges affect various modeling approaches like molecular docking and molecular dynamics. Moreover, several specialized methods (particularly in molecular docking) leverage specific chemical properties to add custom potentials, pseudo-atoms, or manipulate atomic connectivity. To address these challenges, we developed Meeko, a molecular parametrization Python package that leverages the widely used RDKit cheminformatics library for a chemically accurate description of the molecular representation. Small molecules are modeled as single RDKit molecules, and biological macromolecules as multiple RDKit molecules, one for each residue. Meeko is highly customizable and designed to be easily scriptable for high-throughput processing, replacing MGLTools for receptor and ligand preparation.

Introduction

Historically, processing of input structural data in the AutoDock suite was performed through the MGLTools software that supported AutoDock4⁽¹⁾, AutoDock Vina^(2,3) and more recently AutoDock-GPU⁽⁴⁾. However, MGLTools does not thoroughly validate input structures, allowing impossible valences in small organic molecules and missing atoms in proteins and nucleic acids, undermining accurate parameterization.

Alongside the need for an accurate chemical representation, there was also a need for a Python library that supports the assignment of a wide range of parameters. Many advanced and specialized methods have been developed to model specific processes during docking, which were implemented by extending the atom types of the AutoDock4 force field and by adding new interaction potentials. Some examples of such methods are hydrated docking⁽⁵⁾, macrocycle flexibility⁽⁶⁾, modeling of Zn2+ ion coordination⁽⁷⁾, and modeling of irreversible binding events⁽⁸⁾. Due to their advanced nature, these methods were implemented by writing dedicated auxiliary Python scripts that used few or none of the standard functionality provided by MGLTools. This is further complicated by the availability of multiple docking engines.

To address these issues, we developed Meeko, a Python package that provides structural and chemical perception for biological macromolecules and small organic molecules. To ensure a robust chemical representation, we chose RDKit as the underlying data structure for molecules because of its strong emphasis on chemical correctness. RDkit is widely used and has a large and active user community, with many users and developers who report issues, contribute new features, and fix existing bugs. Both the robustness and wide adoption of RDKit can enable seamless integration of AutoDock pipelines with other software that supports this library.

Design and Implementation

Traditionally, input processing relied on parsing structural files and assigning atom types based on atom names, which on one hand provided a unique mapping of atom parameters, but on the other relied on a strict adherence to standard naming conventions. Further complexity arises from the lack of an explicit connectivity description in widely used file formats such as the PDB format and its more modern variant mmCIF. More recently, there have been on-going efforts to move away from the traditional “atom label” approach, especially from the Open Force Field Initiative⁽⁹⁾.

Meeko has been designed to follow this paradigm, using RD-Kit functionalities and chemical perception to parse molecular graphs and use pattern matching methods (i.e. SMARTS) to assign molecular parameters. This provides two fundamental advantages in the way data is handled. First, input processing is robust because molecular connectivity and atomic elements are used in place of specific naming conventions, enabling the use of structure files coming from different sources and programs that use various atom-naming schemes. Second, the internal RDKit representation within Meeko has advanced chemical perception capabilities, supporting the development of methods that calculate specific properties and features in the input molecule.

A. The MoleculeSetup class.

The parametrization of molecules starts by creating a MoleculeSetup class (Fig. 1) that holds the RDKit molecule representation of the input structure. Small molecules and co-factors are directly modeled by one RDKit molecule. Proteins and nucleic acids are modeled by several connected RDKit molecules in a “polymer”, where each RDKit molecule represents one residue. The word residue describes the chemical subunits of biological macromolecules, such as protein amino acids, nucleotides, or co-factors. These polymers contain additional data that describes the polymeric connections between each residue.

Fig. 1.

Meeko acts as an interface between RDKit and AutoDock. The set of rules to parameterize an RDKit molecule, including SMARTS patterns for atom typing and choice of charge model, are stored in an instance of a MoleculePreparation class. That instance can be created once and process multiple RDKit molecules. To run a docking with AutoDock-Vina or AutoDock-GPU, the information in the MoleculeSetup is converted to the PDBQT format. Docking results can be converted back into RDKit molecules with the docked positions as long as the input PDBQT files were written by Meeko.

The MoleculeSetup class provides the API that is used to interrogate the underlying RDKit molecule. Meeko uses SMARTS patterns to assign parameters through RDKit substructure matching, including atomic (e.g., atom types) and bond properties (e.g., rotatability perception and torsional potentials). Similarly to what is done in the Open Force Field, SMARTS patterns are checked in increasing order of specificity, guaranteeing that initial and more generic parameters are always assigned, while more specific ones replace them when available. User-defined custom parameters can be easily specified through either Python dictionaries or JSON files. The MoleculeSetup class will then hold all parameters, providing a single data structure that enables consistency checks between parameters and a common interface to methods that read or write parameters.

Besides using SMARTS, the MoleculeSetup provides APIs to integrate with external sources and methods for generating atomic parameters. One example is the assignment of partial charges, which can be Gasteiger-Marsili charges⁽¹⁰⁾ computed using RDKit, or Espaloma⁽¹¹⁾ charges if the optional Espaloma package is installed. Additionally, charges can be simply extracted from input Mol2 or PQR files. Another example is the macrocycle ring detection algorithm, which is used for the parametrization of the flexible macrocycle docking method⁽⁶⁾. For that, Meeko implements a separate ring detection method that takes fused rings in consideration. This algorithm aids in selecting the bonds that are removed to open macrocyclic rings for conformational sampling.

B. The MoleculeSetup is used for macromolecule polymers.

To describe polymeric biological macromolecules, Meeko builds a Polymer data structure that contains a MoleculeSetup for each individual residue. During this process, the input structure is processed on a residue-by-residue basis, by comparing the input atoms with template RDKit molecules (Fig 2). This comparison uses the atoms and their connectivity, but not bond orders. The connectivity of the input is perceived at runtime based on interatomic distances. Residues with missing or excess heavy atoms (non-hydrogen atoms) or unexpected bonds to other residues are rejected, and must be either fixed or removed. Positions of hydrogens are preserved if hydrogens are present in the input, otherwise they are computed by RDKit. Bond-orders and formal charges are defined by the template RDKit molecule. This process validates the input structure and informs the user on how to fix problematic residues.

Fig. 2.

Polymer data structure and residue templates. The input positions and elements are parsed from a PDB or mmCIF file which omit the connectivity between atoms. There’s only one hydrogen atom. In the raw RDKit molecule, the connectivity between atoms is determined by RDKit using interatomic distances and assuming all bonds are single. The input hydrogen is the only hydrogen that exists as a real RDKit atom, and plays a role in identifying the correct template (HIE). The clean RDKit molecule contains all atoms in the residue that effectively constitute the model for simulation. All atoms are real RDKit atoms except for the hydrogens that take the place of an atom of an adjacent residue, which are not depicted. The molecule graph, including formal charges and bond orders, are copied from the matched template, and the atomic positions are sourced from the raw molecule. Hydrogen atoms and bonds highlighted in pink in the clean molecule originate from the template molecule, not from the raw molecule. The positions of these hydrogens are computed by RDKit. The padded molecule contains a few extra atoms to model the chemical environment of atoms near bonds to adjacent residues. Each residue template is associated with chemical reactions that pad each atom that is expected to form a bond with an adjacent residue. The reactions do not depend on what the adjacent residue is, enabling padding when there are missing residues in a structure. We refer to these as blunt endings. The instance of the molecule setup is created using the padded molecule.

Residue names are often associated with multiple templates, in a lookup group. For example, the histidine amino acid is defined in PDB files as HIS with no specific protonation state, but Meeko checks templates HID (neutral tautomer 1, hydrogen on Nd1), HIE (neutral tautomer 2, hydrogen on Ne2) and HIP (protonated, hydrogens on both Nd1 and Ne2). This is meant to preserve the protonation state set by external tools, such as reduce⁽¹²⁾, CHARMM-GUI⁽¹³⁾, or hydrogens manually added in a molecule viewer. This process is illustrated in Figure 2. The closest match is used if hydrogens are present, otherwise a default is used (e.g., HIE for histidine). Alternatively, specific templates can be set for given residues to impose a given protonation state, overriding existing hydrogens, for example to model the thiolate state (CYX- template) for a cysteine that has a thiol hydrogen in the input.

When matching templates, bonds with neighbor residues are also considered in order to take into account the molecular environment for correct parametrization. To do so, once extracted from the polymer, a padded copy of the residue molecule is created by adding a minimal set of atoms to mimic the chemical environment around the polymeric bonds (Fig. 2). At the time of writing, five types of predefined paddings are supported: two for peptide bonds (C- and N-terminus amino acids), two for phosphodiester bonds (3’ and 5’ ends in nucleic acids), and one for disulfide bonds in cysteines.

The built-in polymer parametrization template library includes (i) standard residues, (ii) modified residues from Amber’s residue libraries⁽¹⁴⁾, and (iii) entries from the Chemical Component Dictionary (CCD)⁽¹⁵⁾ that have the same residue name as other built-in residue templates. At the time of writing, the template library comprises of 812 residue templates, which include variations in protonation state.

For standard protein residues, the lookup group typically contains three backbone variants: one for residues that are in the middle of a chain, one for C-terminal residues with free carboxylate group, and one for N-terminal residue with free ammonium group. These are combined with sidechain variants with different protonation states. The templates of modified amino acids, such as sidechain phosphorylation, as well as the residue names used to look up the templates, were built from residue definitions of the Amber force field. Extending support for different sets of residue names consists in adding additional keys to the lookup groups, which can point to existing templates or to new ones. Adding templates and updating the lookup groups can be done both from the command line tool and from the Python API.

For nucleotides, only the main-chain form and three backbone variants are considered, which include the 3’-end variant that naturally terminates with a phosphate group, the 5’-end variant that naturally terminates with the 5’ alcohol group, and a non-natural form of 5’-end variants with a trailing phosphate group. For DNA residues, the built-in definitions came from library files that correspond to OL15⁽¹⁶⁾ and Parmbsc1⁽¹⁷⁾ force fields. For RNA residues, the built-in definitions cover the naturally occurring and modified nucleosides from all_modrna08⁽¹⁸⁾. Furthermore, Meeko includes the list of modified nucleotides from the Nucleic Acid Knowledgebase (NAKB) comprising 458 additional lookup groups and 1,783 distinct templates.

When templates are not available for specific residues, Meeko will try to fetch them automatically from the CCD using the residue name. When no parameters are available or cannot be found, a user-provided residue structure can be used. More details and instructions on this process are available in the software documentation available online.

C. JSON serialization of key data structures.

To support saving parameterized molecules to a filesystem, the key data structures, including the MoleculeSetup and the Polymer, can be serialized to JSON. When read from a filesystem and deserialized, the full state is recovered. Serialization and de-serialization is extensively tested to safeguard against data loss. During the development of Meeko some attributes have been added and removed from the MoleculeSetup and the Polymer, but newer versions of the software are backward-compatible with files written with older versions.

Results

Due to the architecture of Meeko and the reliance of chemical perception provided by RDKit, the tool has several advantages resulting from the possibility of inferring molecule properties through chemical perception.

D. Small molecules parametrization.

Parametrizing small molecules can be notoriously difficult due to the high heterogeneity of chemical and topological properties. In order to process them, Meeko uses the internal representation to assign atom and bond parameters using SMARTS patterns. Partial charges are assigned using either the Gasteiger⁽¹⁰⁾ or the Espaloma⁽¹¹⁾ models. Torsional potentials are optionally assigned using either the OpenFF force field or Espaloma. The classification of bonds as rotatable or not, which determines the conformational space to be sampled during docking, is also performed using SMARTS patterns and can be customized with user defined SMARTS. The method for sampling the conformations of macrocyclic rings during docking^(6,19), implemented in AutoDock-Vina and AutoDock-GPU, manipulates the MoleculeSetup data structure to add pseudo-atoms and redefine the set of rotatable bonds.

E. Atom-name independent parametrization.

Meeko can parse and parametrize most structures of proteins and nucleic acids, including perceiving most co-factors and non-standard residues, thanks to a large built-in library of residue templates, as well as automatic fetching from the Chemical Component Dictionary of the PDB. Bond orders and formal charges are defined in the residue templates, not inferred from the input structure, ensuring a correct chemical representation for non-standard residues and co-factors. Due to the reliance on chemical perception, Meeko can parse the output of tools that handle and modify the protonation state of macromolecules, like Reduce⁽¹²⁾, H++⁽²⁰⁾, PDB2PQR⁽²¹⁾, and PropKa)⁽²²⁾ by analyzing the position of the added explicit hydrogens independently from the atom naming (or lack thereof). This also includes structures that have been modified through interactive viewer sessions, where individual protonation states were manually curated.

F. Specialized methods.

Building upon the chemical perception provided by Meeko and the API to manipulate the molecular structures, it becomes straightforward to implement specialized methods and new force fields, facilitating the prototyping phase and reducing the time required to develop and test them. For example, SMARTS patterns can be used to define spatial constraints to perform anchored dockings, or combined with φ, θ and r spherical coordinates to add pseudo-atoms to desired chemical groups, e.g. for modeling dipoles using off-site partial charges.

Using these functionalities, previously developed advanced docking methods were reimplemented using the Meeko framework. This created a centralized implementation that supports all the existing (and possibly future) docking engines, and decreased code redundancy. Furthermore, these advanced docking methods can be combined seamlessly, allowing users to perform reactive docking⁽⁸⁾ simulations of flexible macrocycles⁽⁶⁾ using an explicitly hydrated docking model⁽⁵⁾.

G. Software interoperability.

Another advantage of the format-agnostic molecular representation provided by Meeko is that it is now possible to perform end-to-end molecular docking simulations using standardized molecular formats such as SDF. Through the use of RDKit, complete molecular representations can be used to write file outputs in SDF standard format. Using RDKit also opens up for integrating directly with the many programs that support RDKit, such as OpenFF and OpenMM, which enables the creation of automated pipelines integrating molecular dynamics simulations with high-throughput docking. Historically, this process has been severely limited by the use of the PDBQT file format for the AutoDock results. This format was derived from the original PDB format for the first AutoDock release⁽²³⁾, before more structured and standard formats like Mol2 and SDF files were available. The PDBQT format lacks connectivity, bond orders, non-polar hydrogens, and describes the molecule using a relatively small set of atom types from the AutoDock scoring function. Generating PDBQT files from other molecular file formats is a lossy process that makes it impossible to recover accurate bond orders, hindering future parametrization of the molecule. Meeko provides a backward-compatible PDBQT writer that can generate files for docking, but can mitigate this issue by embedding the SMILES in the PDBQT header, mapping the atoms in the PDBQT to those in the SMILES. Meeko processes this information and re-generates a complete RDKit molecule for the docked poses.

Another way in which Meeko mitigates the PDBQT short-comings is by interacting with the simulation engines within Python. For example, because recent versions of AutoDock Vina (>v.1.2)⁽³⁾ provide Python bindings for both input parsing and docking execution, it is possible to prepare calculations with Meeko without the need to write intermediate PDBQT input files, passing the file string content directly to the docking software. As a result, automated pipelines are more efficient, and script files are shorter and easily readable and modifiable. The ease of scripting extends to Python notebooks such as Jupyter notebooks and Google Colab, which are widely used to access remote computing and teaching tutorials. The streamlined parametrization process also facilitates the parametrization of large libraries of molecules, simplifying the setup of high-throughput virtual screenings. The serialization and de-serialization of the MoleculeSetup and Polymer data structures in the JSON format enables saving and loading these across different Python versions, which is not guaranteed with the pickle module in the Python standard library. Furthermore, the JSON format is human-readable and many programming languages have parsers that deserialize JSON into convenient data structures, facilitating access to parameters generated by Meeko.

Conclusions

Meeko addresses the need for a robust, reliable, and extensible parametrization tool for small organic molecules and biological macromolecules, especially for molecular docking simulations. To serve this purpose, it has been designed with a strong emphasis on chemical accuracy. Meeko uses the RDKit cheminformatics library, which implements strict checks to validate input molecules, supporting accurate assignment of various parameters including, but not limited to atom types, partial charges, and torsion potentials. It replaces MGLTools for receptor and ligand preparation.

Biological macromolecules are modeled as a collection of individual RDKit molecules, one for each residue. For proteins and nucleic acids, which often have missing parts, this enables Meeko to validate the input on a residue-by-residue basis, without relying on any convention for atom names. Whenever a residue does not the pass the stringent validation criteria, its processing is halted, giving the user the opportunity to fix the input structure.

The software architecture was designed with a focus on flexibility and extensibility, with the goal of streamlining the preparation of ligands and receptors while providing direct access to the underlying chemical structures with a well-documented API. This simplifies the automation through scripting, both for managing high-throughput virtual screenings and for interactive Python notebooks, such as Jupyter and Google Colab. Furthermore, it supports custom parameterization schemes that can be easily added through user-provided data. This flexibility has already proven valuable when reimplementing advanced docking methods that have been developed in the past for different docking engines.

The development of Meeko is part of an on-going effort to modernize and extend the AutoDock Suite as part of the Resource for Structure-Based Computational Drug Discovery and Design (RSCD3⁽²⁴⁾) to facilitate the adoption of molecular docking pipelines and their integration within other modeling software. Moreover, it has been designed to support and interface with the next generation of the AutoDock docking engine, which does not require the custom PDBQT file format and leverages Python bindings.

On a broader perspective, we envision Meeko will help research groups implement custom methodologies not only for molecular docking but potentially for other forms of molecular modeling, thanks to the reliance on the RDKit library which significantly enhances workflow integration across computational chemistry platforms.