Package: ringtail
(Original artwork by Althea Hansel-Harris)RingtailPackage for creating SQLite database from virtual screening results, performing filtering, and exporting results. Compatible withAutoDock-GPUandAutoDock-Vina.Ringtail reads collections of Docking Log File (DLG) or PDBQT results from virtual screenings performed withAutoDock-GPUandAutoDock-Vina, respectively, and deposits them into
a SQLite database. It then allows for the filtering of results with numerous pre-defined filtering options, generation of a simple result scatterplot, export of
molecule SDFs, and export of CSVs of result data. Result file parsing is parallelized across the user's CPU.The publication describing the design, implementation, and features of Ringtail may be found in the JCIM paper:Ringtail: A Python Tool for Efficient Management and Storage of Virtual Screening Results.Althea T. Hansel-Harris, Diogo Santos-Martins, Niccolò Bruciaferri, Andreas F. Tillack, Matthew Holcomb, and Stefano Forli.Journal of Chemical Information and Modeling202363 (7), 1858-1864.
DOI: 10.1021/acs.jcim.3c00166If using Ringtail in your work, please cite this publication.Ringtail is developed by theForli labat theCenter for Computational Structural Biology (CCSB)atScripps Research.New in version 1.1:Significant filtering runtime improvements vs v1.0--summaryoption for getting quick overview of data across entire datasetSelection of dissimilar output ligands with Morgan fingerprint or interaction fingerprint clusteringSelect similar ligands from query ligand name in previous Morgan fingerprint or interaction finger clustering groupsOption for exporting stored receptor PDBQTsFilter by ligand substructureFilter by ligand substructure location in cartesian space--max_missoption now outputs union of interaction combinations by default, with--enumerate_interaction_combsoption to log passing ligands/poses for individual interaction combinationUpdating database written with v1.0.0 to work with v1.1.0If you have previously written a database with Ringtail v1.0.0, it will need to be updated to be compatible with filtering with v1.1.0. We have included a new scriptrt_db_v100_to_v110.pyto perform this updated. Please note that all existing bookmarks will be removed during the update. The usage is as follows:$ rt_db_v100_to_v110.py -d <v1.0.0 database 1 (required)> <v1.0.0 database 2+ (optional)>Multiple databases may be specified at once. The update may take a few minutes per database.README OutlineInstallationDefinitionsGetting Started TutorialScriptsrt_process_vs.py Documentationrt_compare.py DocumentationPython tutorialsInstallationIt is recommended that you create a new Conda environment for installing Ringtail. Ringtail requires the following non-standard dependencies:RDKitSciPyMatplotlibPandaschemicaliteMeeko(from the Forli Lab)Multiprocess(MacOS only)Installation (from PyPI)Please note that Ringtail requires Python 3.9 or 3.10.$pipinstallringtailIf using conda,pipinstalls the package in the active environment.
Also note that if using MacOS, you may need to install Multiprocess separately:$pipinstallmultiprocessInstallation (from source code)$ conda create -n ringtail python=3.10
$ conda activate ringtailAfter this, navigate to the desired directory for installing Ringtail and do the following:$ git clone git@github.com:forlilab/Ringtail.git
$ cd Ringtail
$ pip install .This will automatically fetch the required modules and install them into the current conda environment.If you wish to make the code for Ringtail editable without having to re-runpip install ., instead use$ pip install --editable .Test installationIf you would like to test your installation of Ringtail, a set of automated tests are included with the source code. To begin, you must install pytest in the Ringtail conda environment:$ pip install -U pytestNext, navigate to thetestsubdirectory within the cloned Ringtail directory and run pytest by simply calling$ pytestThe compounds used for the testing dataset were taken from theNCI Diversity Set V. The receptor used wasPDB: 4J8M.DefinitionsDLG: Docking Log File, output from AutoDock-GPU.PDBQT: Modified PDB format, used for receptors (input to AutoDock-GPU and Vina) and output ligand poses from AutoDock-Vina.Cluster: Each DLG contains a number of independent runs, usually 20-50. These independent poses are then clustered by RMSD, giving groups of similar poses called clusters.Pose: The predicted ligand shape and position for single run of a single ligand in a single receptor.Docking score: The predicited binding energy from AutoDock-GPU or Vina.Bookmark: The set of ligands or ligand poses from a virtual screening passing a given set of filters. Stored within a virtual screening database as a view.Ringtail:Drat, I'm not a cat!  Even though this eye-catching omnivore sports a few vaguely feline characteristics such as pointy ears, a sleek body, and a fluffy tail, the ringtail is really a member of the raccoon family.https://animals.sandiegozoo.org/animals/ringtailGetting StartedRingtail offers a wealth of database creation and filtering options. They are detailed at length below. This section will provide a quick overview of the basic usage of Ringtail from the command line. We will you the provided test data to create a database with default storage options and perform basic filtering of it.Let us begin in the Ringtail directory. First, we must navigate to the test data directory:$ cd test/test_data/Now, let us create a database containing the results from only group 1. Note that these files are DLGs. If we were using Vina PDBQTs, we would need to add--mode vina.$ rt_process_vs.py write --file_path group1By default, the database we have created is calledoutput.db. Let us now make a second database namedall_groups.dbcontaining all three groups:$ rt_process_vs.py write --file_path . --recursive --output_db all_groups.dbThe--recursiveoption tells Ringtail to scan the directories specified with--file_pathfor subdirectories containing output files (in this case, DLGs). This allowed all three group directories to be added to the database with a single --file_path option.Now that we have created the databases, we can filter them to pull out compounds of interest. Before we do that, let's find out a little more about the data contained within the database. For this, we can use the-s/--summaryoption:$rt_process_vs.py read --input_db all_groups.db -s

Total Stored Poses: 645
Total Unique Interactions: 183

Energy statistics:
min_docking_score: -7.93 kcal/mol
max_docking_score: -2.03 kcal/mol
1%_docking_score: -7.43 kcal/mol
10%_docking_score: -6.46 kcal/mol
min_leff: -0.62 kcal/mol
max_leff: -0.13 kcal/mol
1%_leff: -0.58 kcal/mol
10%_leff: -0.47 kcal/molWe could also have used the--summaryoption when writing the database to display this info at that time.Now, let us start filtering with a basic docking score cutoff of -6 kcal/mol:$ rt_process_vs.py read --input_db all_groups.db --eworst -6This produces an output logoutput_log.txtwith the names of ligands passing the filter, as well as their binding energies. Let's now do another round of filtering, this time with an energy percentile filter of 5 percent (top 5% of coumpounds by docking score). Each round of filtering is also stored in the database as a SQLite view, which we refer to as a "bookmark". We will also save this round of filtering with the bookmark name "ep5".$ rt_process_vs.py read --input_db all_groups.db --score_percentile 5 --log ep5_log.txt --bookmark_name ep5Now, let us further refine the set of molecules we just filtered. We will use an interaction filter for van der Waals interactions with V279 on the receptor:$ rt_process_vs.py read --input_db all_groups.db --filter_bookmark ep5 --van_der_waals A:VAL:279: --log ep5_vdwV279_log.txt --bookmark_name ep5_vdwV279We are now ready to export these molecules for visual inspection in your favorite molecular graphics program. We will create a new directoryep5_vdwV279_sdfsand store the exported molecule files there.$ mkdir ep5_vdwV279_sdfs
$ rt_process_vs.py read --input_db all_groups.db --bookmark_name ep5_vdwV279 --export_sdf_path ep5_vdwV279_sdfsNow we have our filtered molecules as SDF files ready for visual inspection!Example Filtering Timings (M1Pro MacBook, ~2 million ligands)Extended documentationScriptsThe Ringtail package includes two command line oriented scripts:rt_process_vs.pyandrt_compare.py. Both may be run with options specified in the command line and/or using options specified in a JSON-formatted file given with--config. Command line options override any conflicting options in the config file.rt_process_vs.pyserves as the primary script for the package and is used to both write docking files to a SQLite database and to perform filtering and export tasks on the database. It is designed to handle docking output files associated with a single virtual screening in a single database.rt_compare.pyis used to combine information across multiple virtual screenings (in separate databases) to allow or exclude the selection of ligands passing filters across multiple targets/models. This can be useful for filtering out promiscuous ligands, a technique commonly used in exerimental high-throughput screening. It may also be used if selection of ligands binding multiple protein structures/conformations/homologs are desired.rt_process_vs.py DocumentationUsage examplesAccess help message for rt_process_vs.pyrt_process_vs.py --helpAccess help message for rt_process_vs.py write modert_process_vs.py write --helpAccess help message for rt_process_vs.py read modert_process_vs.py read --helpCreate database named example.db from all input optionsrt_process_vs.py write --file lig1.dlg lig2.dlg --file_path path1/ path2 --file_list filelist1.txt filelist2.txt --output_db example.dbExample file listlig3.dlg
lig4.dlg.gz
rec1.pdbqtWrite and filter using a config filert_process_vs.py -c config_w.json write
rt_process_vs.py -c config_r.json readconfig_w.json:{
"file_path": "path1/",
"output_db": "example.db"
}config_r.json:{
"score_percentile": "0.1"
}Export results from a previous filtering as a CSVrt_process_vs.py write --file_path Files/
rt_process_vs.py read --input_db output.db --score_percentile 0.1 --bookmark_name filter1
rt_process_vs.py read --input_db output.db --export_bookmark_csv filter1Create scatterplot highlighting ligands passing filtersrt_process_vs.py write --file_path Files/
rt_process_vs.py read --input_db output.db --score_percentile 0.1 --bookmark_name filter1
rt_process_vs.py read --input_db output.db --bookmark_name filter1 --plotall_ligands_scatter.pngUsage DetailsThe script for writing a database and filtering isrt_process_vs.py.This is intended to be used for a set of DLGs/Vina PDBQTs pertaining to a single target and binding site. This may include multiple ligand libraries as long as the target and binding site is the same. Be cautious when adding results from multiple screening runs, since some target information is checked and some is not.One receptor PDBQT may also be saved to the database.The rt_process_vs.py script has two modes:writeandread. The desired mode must be specified in the command line before any other options are given (except-c [CONFIG]which is given first). Thewritemode is used to create a database for a virtual screening from ADGPU DLGs or Vina PDBQTs. After this initial run, a database is created and may be read directly by rt_process_vs.py inreadmode for subsequent filtering and export operations.Write ModeUpon calling rt_process_vs.py inwritemode for the first time, the user must specify where the program can find files to write to the newly-created database. This is done using the--file,--file_path, and/or--file_listoptions. Any combination of these options can be used, and multiple arguments for each are accepted. Compressed.gzfiles
are also accepted.When searching for result files in the directory specified with--file_path, rt_process_vs.py will search for files with the pattern*.dlg*by default. This may be changed with the--patternoption. Note also that, by default, Ringtail will only search the directory provided in--file_pathand not subdirectories. Subdirectory searching
is enabled with the--recursiveflag. If you are trying to read Vina PDBQTs, specify this with--mode vina. This will automatically change the file search pattern to*.pdbqt*. If the receptor PDBQT file is present in a directory being searched, itmustbe specified with--receptor_file.To add new files to an existing database, the--append_resultsflag can be used in conjuction with--input_dband--file,--file_path, and/or--file_listoptions. If one is concerned about adding duplicate results, the--duplicate_handlingoption can be used to specify how duplicate entries should be handled. However, this option makes database writing significantly slower.To overwrite an existing database, use the--overwriteflag.One receptor PDBQT, corresponding to that in the DLGs, may be saved to the database using the--save_receptorflag. This will store the receptor file itself in a binary format in the database. The user must specify the path to the receptor file with the--receptor_fileoption. Ringtail will also throw an exception if this flag is given but no receptor is found, if the name of the receptor in any DLG does not match the receptor file, or if this flag is used with a database that already has a receptor.--save_receptorcan be used to add a receptor to an existing database given with--input_db.--save_receptormay not be used with the--append_resultsoption.By default, the newly-created database will be namedoutput.db. This name may be changed with the--output_dboption.By default (for DLGs), Ringtail will store the best-scored (lowest energy) binding pose from the first 3 pose clusters in the DLG. For Vina, Ringtail will store the 3 best poses. The number of clusters/poses stored may be
changed with the--max_posesoption. The--store_all_posesflag may also be used to override--max_posesand store every pose from every file.ADGPU is capable of performing interaction analysis at runtime, with these results being stored in the database if present. If interaction analysis is not present in the input file (including Vina PDBQTs), it may be added by Ringtail with the--add_interactionsoption.This adds a signifcant increase to the total database write time.Distance cutoffs for the interactions are specified with the--interaction_cutoffsoption. Adding interactions requires that the receptor PDBQT be provided as an input by the user with the--receptor_fileoption.The--interaction_toleranceoption also allows the user to give more leeway for poses to pass given interaction filters. With this option, the interactions from poses withincangstrom RMSD of a cluster's top pose will be appended to the interactions for that top pose. The theory behind this is that this gives some sense of the "fuzziness" of a given binding pose, allowing the user to filter for interactions that may not be present for the top pose specifically, but could be easily accessible to it. When used as a flag, theinteraction_tolerancedefault is 0.8 angstroms. The user may also specify their own cutoff. This option is intended for use with DLGs from AD-GPU, which clusters output poses based on RMSD.Read modeInreadmode, an existing database is used to filter or export results.When filtering, a text log file will be created containing the results passing the given filter(s). The default log name isoutput_log.txtand by default will include the ligand name and docking score of every pose passing filtering criteria. The log name
may be changed with the--logoption and the information written to the log can be specified with--outfields. The full list of available output fields may be seen by using the--helpoption withreadmode (see example above).
By default, only the information for the top-scoring binding pose will be written to the log. If desired, each individual passing pose can be written by using the--output_all_posesflag. The passing results may also be ordered in the log file using the--order_resultsoption.No filtering is performed if no filters are given. If both--eworstand--score_percentileare used together, the--eworstcutoff alone is used. The same is true of--leworstand--le_percentile.In addition to the filtering options outlined in the table below, ligands passing given filters can be clustered to provide a reduced set of dissimilar ligands based on Morgan fingerprints (--mfpt_cluster) or interaction (--interaction_cluster) fingerprints. Dissimilarity is measured by Tanimoto distance and clustering is performed with the Butina clustering algorithm.When filtering, the passing results are saved as a view in the database. This view is namedpassing_resultsby default. The user can specify a name for the view using the--bookmark_nameoption. Data for poses in a view may be accessed later using the--data_from_bookmarkoption. Whenmax_miss> 0 is used, a view is created for each combination of interaction filters and is named<bookmark_name>_<n>where n is the index of the filter combination in the log file (indexing from 0).Filtering may take from seconds to minutes, depending on the size of the database, roughly scaling as O(n) for n database Results rows (i.e. stored poses). One may also filter over a previous bookmark specified with the--filter_bookmarkoption. If using this option, the bookmarks specified by--filter_bookmarkand--bookmark_namemust be different.While not quite a filtering option, the user can provide a ligand name from a previously-run clustering and re-output other ligands that were clustered with that query ligand with--find_similar_ligands. The user is prompted at runtime to choose a specific clustering group from which to re-output ligands. Filtering/clustering will be performed from the same command-line call prior to this similarity search, but all subsequent output tasks will be performed on the group of similar ligands obtained with this option unless otherwise specified.Other available outputsThe primary outputs fromrt_process_vs.pyare the database itself (writemode) and the filtering log file (readmode). There are several other output options as well, intended to allow the user to further explore the data from a virtual screening.The--plotflag generates a scatterplot of ligand efficiency vs docking score for the top-scoring pose from each ligand. Ligands passing the given filters or in the bookmark given with--bookmark_namewill be highlighted in red. The plot also includes histograms of the ligand efficiencies and binding energies. The plot is saved as[filters_file].pngif a--filters_fileis used, otherwise it is saved asout.png.The--pymolflag also generates a scatterplot of ligand efficiency vs docking score, but only for the ligands contained in the bookmark specified with--bookmark_name. It also launches a PyMol session and will display the ligands in PyMol when clicked on the scatterplot. N.B.: Some users may encounter aConnectionRefusedError. If this happens, try manually launching PyMol (pymol -R) in a separate terminal window.Using the--export_sdf_pathoption allows the user to specify a directory to save SDF files for ligands passing the given filters or in the bookmark given with--bookmark_name. The SDF will contain poses passing the filter/in the bookmark ordered by increasing docking score. Each ligand is written to its own SDF. This option enables the visualization of docking results, and includes any flexible/covalent ligands from the docking. The binding energies, ligand efficiencies, and interactions are also written as properties within the SDF file, with the order corresponding to the order of the pose order.If the user wishes to explore the data in CSV format, Ringtail provides two options for exporting CSVs. The first is--export_bookmark_csv, which takes a string for the name of a table or result bookmark in the database and returns the CSV of the data in that table. The file will be saved as<table_name>.csv.
The second option is--export_query_csv. This takes a string of a properly-formatted SQL query to run on the database, returning the results of that query asquery.csv. This option allows the user full, unobstructed access to all data in the database.As noted above, a bookmark may also be exported as a separate SQLite dabase with the--export_bookmark_dbflag.Finally, a receptor stored in the database may be re-exported as a PDBQT with the--export_receptoroption.Interaction filter formatting and optionsInteraction filtering requires interactions to be present in database.The--vdw,--hb, and--react_resinteraction filters must be specified in the orderCHAIN:RES:NUM:ATOM_NAME. Any combination of that information may be used, as long as 3 colons are present and the information ordering between the colons is correct. All desired interactions of a given type (e.g.--vdw) may be specified with a single option tag (--vdw=B:THR:276:,B:HIS:226:) or separate tags (--vdw=B:THR:276: --vdw=B:HIS:226:).The--max_missoption allows the user to filter by given interactions excluding up tomax_missinteractions. This givescombinations forninteraction filters andmmax_miss. By default, results will be given for the union of the interaction conbinations. Use with--enumerate_interaction_combsto log ligands/poses passing each separate interaction combination (can significantly increase runtime).The--smarts_idxyzoption may be used to filter for a specific ligand substructure (specified with a SMARTS string) to be placed within some distance of a given cartesian coordinate. The format for this option is"<SMARTS pattern: str>" <index of atom in SMARTS: int> <cutoff distance: float> <target x coord: float> <target y coord: float> <target z coord: float>.Exploring the database in the Command LineView the data contained within the database using a terminal, we recommend using theVisiData tool. In addition to command line visualization, this tool has a number of other feature, including ploting. Upon opening the database withvd, the terminal should look like this:In this example (made with DLGs), the database contains ~3 poses for 9999 discrete ligands. Each of the rows here is a separate table or view within the database. From this screen, you can easily perform the sanity checks outline below. One should note that the number of column displayed on the first screen is 1 greater than the actual number of columns in a table (the number is correct for views). To more fully explore a given table, one may use the arrow keys or mouse to navigate to it, then pressEnter/Returnto access that table/view. The user may then scroll horizontally with the arrow keys, or pressqto return up a level.Usingvdis particularly helpful to examine possible interactions of interest, stored within theInteraction_indicestable.To exit, return to the screen shown in the image above by pressingq, then pressqto exit.Data integrity sanity checksThere are a few quick checks the user can make to ensure that the data has been properly written from the input files to the database. Discrepancies may indicate an error occurred while writing the database or the input file format did not match that which Ringtail expected.The number of rows in theLigandstable should match the number of input ligand filesThe number of rows in theResultsandInteraction_bitvectorstables should matchNumber of columns in theInteractions_bitvectorstable should match the number of rows in theInteraction_indicestable + 1 (+2 if usingvd)The number of rows in theResultstable should be ~max_poses*number of filesand should be less than or equal to that number. For DLGs not every ligand may have up tomax_poses, which is why the number of rows is typically smaller thanmax_poses*number of DLGs.No ligand should have more thanmax_posesrows in theResultstable.If storing all poses, the number of rows in the Results table should match thenumber of ligands*number of output poses.Potential pitfallsAny PDBQT files specified through any of the input options in ADGPU mode will be read byrt_process_vs.pyas receptor files, even if the files actually represent ligands. Therefore, ligand PDBQT files should not be present in any directories given with--file_path.When writing from Vina PDBQTs, ensure there are no other PDBQTs (input or receptor) in directories specified with--file_pathUNLESS the receptor PDBQT is specified with the--receptor_fileoption.Occassionally, errors may occur during database reading/writing that corrupt the database. This may result in the database becoming locked. If this occurs it is recommended to delete the existing database and re-write it from scratch.If trying to read a database created with Ringtail v1.0.0 with a newer version of Ringtail, you may encounter errors related to changes to the internal database structure. If you encounter this, run the follow commands (example of database namedoutput.db:$ sqlite3 output.db
> ALTER TABLE Results RENAME energies_binding TO docking_score;
> ALTER TABLE Bookmarks ADD COLUMN filters;If you encounter further errors related to views/bookmarks, please contact the ForliLab.rt_process_vs.py supported argumentsArgumentDescriptionDefault valueRequires interactions--config-cConfiguration JSON file to specify new default options. Overridded by command lineno default--input_db-iDatabase file to use instead of creating new databaseno default--bookmark_name-sName for bookmark view in databasepassing_results--mode-mspecify AutoDock program used to generate results. Available options are "dlg" and "vina". Vina mode will automatically change --pattern to *.pdbqtdlg--summary-suPrint summary information about virtual screening data to STDOUT.FALSE--verbose-vFlag indicating that passing results should be printed to STDOUT. Will also include information about runtime progress.FALSE--debug-dFlag indicating that additional debugging information (e.g. error traceback) should be printed to STDOUT.FALSEWrite Mode--file-fDLG/Vina PDBQT file(s) to be read into databaseno default--file_path-fpPath(s) to files to read into databaseno default--file_list-flFile(s) with list of files to read into databaseno default--pattern-pSpecify pattern to search for when finding files*.dlg* / *.pdbqt* (vina mode)--recursive-rFlag to perform recursive subdirectory search on --file_path directory(s)FALSE--append_results-aAdd new docking files to existing database given with --input_dbFALSE--duplicate_handling-dhSpecify how dulicate results should be handled. May specify "ignore" or "replace". Unique results determined from ligand and target names and ligand pose.NB: use of duplicate handling causes increase in database writing timeNone--save_receptor-srFlag to specify that receptor file should be imported to database. Receptor file must also be specified with --receptor_fileFALSE--output_db-oName for output databaseoutput.db--overwrite-ovFlag to overwrite existing databaseFALSE--max_poses-mpNumber of clusters for which to store top-scoring pose (dlg) or number of poses (vina) to save in database3--store_all_poses-saFlag to indicate that all poses should be stored in databaseFALSE--interaction_tolerance-itAdds the interactions for poses within some tolerance RMSD range of the top pose in a cluster to that top pose. Can use as flag with default tolerance of 0.8, or give other value as desiredFALSE -> 0.8 (Å)Yes--add_interactions-aiFind interactions between ligands and receptor. Requires receptor PDBQT to be written.FALSE--interaction_cutoffs-icSpecify distance cutoffs for measuring interactions between ligand and receptor in angstroms. Give as string, separating cutoffs for hydrogen bonds and VDW with comma (in that order). E.g. '-ic 3.7,4.0' will set the cutoff for hydrogen bonds to 3.7 angstroms and for VDW to 4.0.3.7,4.0--receptor_file-rnUse with --save_receptor and/or --add_interactions. Give receptor PDBQT.None--max_proc-mprMaximum number of subprocesses to spawn during database writing.[# available CPUs]Read Mode--log-lName for log of filtered resultsoutput_log.txt--outfields-ofData fields to be written in output (log file and STDOUT). Ligand name always included.e--order_results-ordString for field by which the passing results should be ordered in log file.no default--output_all_poses-apFlag that if mutiple poses for same ligand pass filters, log all poses(OFF)--export_bookmark_csv-xsName of database result bookmark or table to be exported as CSV. Output as <table_name>.csvno default--export_query_csv-xqCreate csv of the requested SQL query. Output as query.csv. MUST BE PRE-FORMATTED IN SQL SYNTAX e.g. SELECT [columns] FROM [table] WHERE [conditions]no default--export_sdf_path-sdfPath for saving exported SDF files of ligand poses passing given filtering criteriano default--export_bookmark_db-xdbExport a database containing only the results found in the bookmark specified by --bookmark_name. Will save as <input_db>_<bookmark_name>.dbFALSE--data_from_bookmark-ndFlag that out_fields data should be written to log for results in given --bookmark_name. Requires no filters.FALSE--filter_bookmark-fbFilter over specified bookmark, not whole Results table.FALSE--find_similar_ligands-fslGiven query ligand name, find ligands previously clustered with that ligand. User prompted at runtime to choose cluster group of interest.no default--plot-pFlag to create scatterplot of ligand efficiency vs docking score for best pose of each ligand. Saves as [filters_file].png or out.png.FALSE--pymol-pyFlag to launch interactive LE vs Docking Score plot and PyMol session. Ligands in the bookmark specified with --bookmark_name will be ploted and displayed in PyMol when clicked on.FALSEPROPERTY FILTERS--eworst-eWorst energy value accepted (kcal/mol)no default--ebest-ebBest energy value accepted (kcal/mol)no default--leworst-leWorst ligand efficiency value acceptedno default--lebest-lebBest ligand efficiency value acceptedno default--score_percentile-peWorst energy percentile accepted. Give as percentage (1 for top 1%, 0.1 for top 0.1%)1.0--le_percentile-pleWorst ligand efficiency percentile accepted. Give as percentage (1 for top 1%, 0.1 for top 0.1%)no defaultLIGAND FILTERS--name-nSearch for specific ligand name. Multiple names joined by "OR". Multiple filters should be separated by commasno default--max_nr_atoms-mnaSpecify maximum number of heavy atoms a ligand may haveno default--smartsSMARTS pattern(s) for substructur matchingno default--smarts_idxyzSMARTS pattern, index of atom in SMARTS, cutoff distance, and target xyz coordinates. Finds poses in which the specified substructure atom is within the distance cutoff from the target locationno default--smarts_join-nlogical operator for multiple SMARTSORINTERACTION FILTERS--van_der_waals-vdwFilter for van der Waals interaction with given receptor information.no defaultYes--hydrogen_bond-hbFilter with hydrogen bonding interaction with given information. Does not distinguish between donating or acceptingno defaultYes--reactive_res-rFilter for reation with residue containing specified informationno defaultYes--hb_count-hcFilter for poses with at least this many hydrogen bonds. Does not distinguish between donating and acceptingno defaultYes--react_any-raFilter for poses with reaction with any residueFALSEYes--max_miss-mmWill filter given interaction filters excluding up to max_miss interactions. Results incombinations forninteraction filters andmmax_miss. Will log and output union of combinations unless used with--enumerate_interaction_combs.0Yes--enumerate_interactions_combs-eicWhen used with--max_miss> 0, will log ligands/poses passing each separate interaction filter combination as well as union of combinations. Can significantly increase runtime.FALSEYesPASSING RESULT CLUSTERING--mfpt_cluster-mfpcCluster ligands passing given filters based on the Tanimoto distances of the Morgan fingerprints. Will output ligand with best (lowest) ligand efficiency from each cluster. Uses Butina clustering algorithm0.5--interaction_cluster-ifpcCluster ligands passing given filters based on the Tanimoto distances of the interaction fingerprints. Will output ligand with best (lowest) ligand efficiency from each cluster. Uses Butina clustering algorithm0.5Yesrt_compare.py DocumentationThert_compare.pyscript is designed to be used with databases already made and filtered with thert_process_vs.pyscript. The script is used to select ligands which are shared between the given filter bookmark(s) of some virtual screenings (wanted) or exclusive to some screenings and not others (unwanted). The basic process of preparing to use this script and the concept behind it is thus:Let us assume that kinase1 is our target of interest. It has related proteins kinase1a and kinase1b. protein2 is an unrelated protein.Create a database for each virtual screening on each target (kinase1.db, kinase1a.db, kinase1b.db, protein2.db)Filter each database separately to get a set of virtual hits for each target. Each set of filters may be different as desired (e.g. change interaction filters for analogous residues). The bookmark within each database may be given as a single string (same bookmark name in every database) or multiple bookmark names (one per database) with the--bookmark_nameoption. If specifying multiple names, the order should match the order that the databases were provided in, beginning with wanted, then unwanted databases. The default name ispassing_results.Usert_compare.pyto find ligands that pass the filters for kinase1 but not kinase1a or kinase1b. This will create a log file of the same format as that output fromrt_process_vs.py.rt_compare.py --wanted kinase1.db --unwanted kinase1a.db kinase1b.dbOther usage examples and output options given below. For example, one can also select for potential dual-target ligands withrt_compare.py --wanted kinase1.db protein2.db --unwanted kinase1a.db kinase1b.dbUsage examplesAccess help message for rt_compare.pyrt_compare.py --helpSelect ligands found in "passing_results" bookmarks of vs1 but not vs2 or vs3rt_compare.py --wanted vs1.db --unwanted vs2.db vs3.dbSelect ligands found in "passing_results" bookmarks of vs1 and vs2 but not vs3 or vs4rt_compare.py --wanted vs1.db vs2.db --unwanted vs3.db vs4.dbSelect ligands found in "passing_results" bookmarks of every vs except vs4rt_compare.py --wanted vs1.db vs2.db vs3.db --unwanted vs4.dbSelect ligands found in "filter1" bookmarks of vs1 but not vs2rt_compare.py --wanted vs1.db --unwanted vs2.db --bookmark_name filter1Save bookmark of ligands found in "filter1" bookmarks of vs1 and vs2 but not vs3 or vs4 as "selective_bookmark" in vs1.dbrt_compare.py --wanted vs1.db vs2.db --unwanted vs3.db vs4.db --save_bookmark selective_bookmarkExport bookmark set of ligands found in "filter1" bookmarks of vs1 and vs2 but not vs3 or vs4 as CSVrt_compare.py --wanted vs1.db vs2.db --unwanted vs3.db vs4.db --export_csvrt_compare.py supported argumentsArgumentDescriptionDefault value--config-cConfiguration JSON file to specify new default options. Overridded by command lineno default--wanted-wDatabase files for which to include the intersection of ligands in bookmark_name(s) for all databases specified with this option.no default--unwanted-nDatabase files for which to exclude any ligands found in bookmark_name of any of the databases specified with this option.no default--bookmark_name-snName of bookmark to select ligands within. Must be present in all databases given.passing_results--log-lName for log fileselective_log.txt--save_bookmark-sSave the final selective bookmark as a view with given name in the first database specified with --wanted.no default--export_csv-xSave final selective bookmark as csv. Saved as [save_bookmark].csv or 'crossref.csv' if --save_bookmark not used.FALSEBrief python tutorialsMake sqlite database from current directoryfromringtailimportRingtailCoreopts=RingtailCore.get_defaults()RingtailCore.set_opts(opts,["storage_type","db_file","path","recursive"],["sqlite","example.db",[["."]],True])withRingtailCore(**opts)asrt_core:rt_core.add_results()Convert database tables to pandas dataframesfromringtailimportStorageManagerSQLite# make database manager with connection to SQLite file vs.dbwithStorageManagerSQLite("vs.db")asdbman:# fetch entire Results table as pandas dataframeresults_df=dbman.to_dataframe("Results")# fetch entire Ligands table as pandas dataframeligands_df=dbman.to_dataframe("Ligands")# fetch entire Receptors table as pandas dataframerec_df=dbman.to_dataframe("Receptors")# fetch entire Interaction Indices table as pandas dataframeinteraction_idx_df=dbman.to_dataframe("Interaction_indices")# fetch entire Interaction bitvectors table as pandas dataframeinteraction_bv_df=dbman.to_dataframe("Interaction_bitvectors")Make an ROC plot and calculate its AUC for a virtual screening with a file containing a list of known binders#!/usr/bin/env python# -*- coding: utf-8 -*-importnumpyasnpimportpandasaspdfromsklearn.metricsimportaucimportmatplotlib.pyplotaspltfromringtailimportRingtailCore,StorageManagerSQLite# make database manager with connection to SQLite file output.dbwithStorageManagerSQLite("output.db")asdbman:# fetch entire Results table as pandas dataframeresults_df=dbman.to_dataframe("Select LigName FROM Results GROUP BY LigName ORDER BY energies_binding",table=False)print(results_df)withopen("binders.txt",'r')asf:binders=[l.strip()forlinf.readlines()ifl!=""]num_actives=len(binders)num_decoys=len(results_df)-num_activesroc_tpr=[]roc_fpr=[]tp=0fp=0i=1forlinresults_df["LigName"]:print("Testing cutoff:",i)i+=1iflinbinders:tp+=1else:fp+=1roc_tpr.append(tp/num_actives)roc_fpr.append(fp/num_decoys)auc=auc(roc_fpr,roc_tpr)withopen("auc.txt",'w')asf:f.write(str(auc))plt.plot(roc_fpr,roc_tpr)x=np.linspace(0,1)plt.plot(x,x,linestyle="--")plt.xlabel("False Positive Rate")plt.ylabel("True Positive Rate")plt.show()