Package: protein-cluster-conformers
Monomeric protein conformational state clusteringThese scripts can be used to cluster a parsed set of monomeric protein chains via a global conformational change metric based on CA distances. Once the peptide chains destined for clustering have been specified, a pairwise CA distance matrix for each chain is produced. Distance difference matrices are then generated, again, pairwise but between CA distance matrices here. Therefore, forNunique peptide chains,NCA distance matrices andN^2distance difference matrices are generated.Additional scripts are provided to cluster the chains based on distance-based scores calculated from all pairwise distance difference matricies, as well as scripts to produce dendrograms of the clustering results, swarm plots of the scores, and heatmaps for each distance difference matrix.Example input data is provided in thebenchmark_data/examplesfolder, including scripts to download and save data from thePDBe-KB's benchmark conformational state dataset. Example scripts are included inexamples, which run complete executions of the entire pipeline for a selection of structures from several difference UniProt accessions.For intructions on importingprotein-cluster-conformersinto your own Python code, refer to/tutorials/instructions.ipynb.Dependencies:protein-cluster-conformersrequires >=Python3.10 to run. Initialise virtual environment and install dependencies with:$cdcontact_map_difference
$python3.10-mvenvcluster_venv
$sourcecluster_venv/bin/activate
$python-mpipinstall-rrequirements.txtCLI: Clustering structuresTo cluster a set of protein structures, run thefind_clusters.pyscript:$pythonfind_conformers.py[-h][-v]-uUNIPROT-mMMCIF[MMCIF...][-sPATH_CLUSTERS]-cPATH_CA[-dPATH_DD][-gPATH_DENDROGRAM[PATH_DENDROGRAM...]][-wPATH_SWARM[PATH_SWARM...]][-oPATH_HISTOGRAM][-aPATH_ALPHA_FOLD]The following parameters can be parsed:requiredarguments:-uUNIPROT,--uniprotUNIPROTUniProtaccession-mMMCIF[MMCIF...],--mmcifMMCIF[MMCIF...]EnterlistofpathstommCIFsthatoverlapagivenUniProtsegment
optionalarguments:-h,--helpshowthishelpmessageandexit-v,--verboseIncreaseverbosity-sPATH_CLUSTERS,--path_clustersPATH_CLUSTERSPathtosaveclusteringresults-cPATH_CA,--path_caPATH_CAPathtosaveCAdistancematrices-dPATH_DD,--path_ddPATH_DDPathtosavedistancedifferencematrices-gPATH_DENDROGRAM[PATH_DENDROGRAM...],--path_dendrogramPATH_DENDROGRAM[PATH_DENDROGRAM...]Pathtosavedendrogramofclusteringresults-wPATH_SWARM[PATH_SWARM...],--path_swarmPATH_SWARM[PATH_SWARM...]Pathtosaveswarmplotofscores-oPATH_HISTOGRAM,--path_histogramPATH_HISTOGRAMPathtosavehistogramsofdistancedifferencemaps-aPATH_ALPHA_FOLD,--path_alpha_foldPATH_ALPHA_FOLDPathtosaveAlphaFoldDatabasestructureRun instructionsOption 1) Cluster onlyTo only cluster a set of monomeric protein structures that share part or all of the same UniProt sequence, run:$pythonfind_clusters.py-u"A12345"\-m/path/to/structure_1.cif[chains]\-m/path/to/structure_2.cif[chains]\...\-m/path/to/structure_N.cif[chains]\-s/path/to/save/clustering/results/The paths to each structure are parsed using the-mflag.Chain IDs (onlystruct_asym_idis currently recognised) should be given as space-delimited arguments after the path. Parse in multiple structures using consecutive-mflags. The UniProt accession must be parsed using the-uflag.Example: O34926$pythonfind_conformers.py-u"O34926"\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc3_updated.cifAB\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc5_updated.cifAB\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc6_updated.cifAB\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc7_updated.cifAB\-sbenchmark_data/examples/O34926/O34926_cluster_results/By default, the pipeline only clusters the parsed mmCIFs (and specified chains), saving clustering results to a CSV file in-sspecified directory.Option 2) Save matrices onlyTo save the matrices produced in the pipeline, simply specify the path in which to save them using the-cflag for CA distance matrices and the-dflag for CA distance difference matrices:$pythonfind_clusters.py-u"A12345"\-m/path/to/structure_1.cif[chains]\-m...\-s/path/to/save/cluster_results.csv\-c/path/to/save/CA/distance/matices\-d/path/to/save/distance/difference/matrices/These flags are mutually exclusive, meaning either or both can be used at the same time.Example: O34926$pythonfind_clusters.py-u"O34926"\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc3_updated.cifAB\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc5_updated.cifAB\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc6_updated.cifAB\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc7_updated.cifAB\-cbenchmark_data/examples/O34926_CA_distances\-dbenchmark_data/examples/O34926_distance_differences/Option 3) Render distance difference maps only2D histograms (heatmaps) can be rendered and saved for each CA distance difference matrix by specifying the save directory using the-oflag:$pythonfind_clusters.py-u"A12345"\-m/path/to/structure_1.cif[chains]\-m...\-o/path/to/save/distance/difference/2D/histograms/To save the histogram in the default directory (test/ouputs/dd_histograms), simply parse the-oflag without a path.The resulting plots are saved in PNG format (to save render time). E.g:Example: O34926$pythonrun_find_clusters.py-u"O34926"\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc3_updated.cifAB\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc5_updated.cifAB\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc6_updated.cifAB\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc7_updated.cifAB\-o./benchmark_data/examples/O34926/O34926_distance_difference_maps/Option 4) Render dendrogram onlyFrom the clustering results, a dendrogram can be rendered to show the relationships between all clustered chains. To save a dendrogram of the hierarchical clustering results, run:$pythonrun_find_clusters.py-u"A12345"\-m/path/to/structure_1.cif[chains]\-m...\-g/path/to/save/dendrogram/[pngsvg]where either apngorsvgfile type is saved. E.g.Example: O34926$pythonrun_find_clusters.py-u"O34926"\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc3_updated.cifAB\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc5_updated.cifAB\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc6_updated.cifAB\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc7_updated.cifAB\-gbenchmark_data/examples/O34926/O34926_cluster_results/pngsvgOption 5) Render swarm plotThe scores generated between pairwise structure comparisons can be plotted as a swarm plot by parsing the-wflag:$pythonrun_find_clusters.py-u"A12345"\-m/path/to/structure_1.cif[chains]\-m...\-w/path/to/save/swarm_plot/[pngsvg]Like rendering the dendrogram, the swarm plot can either be saved aspng,svgor both. E.g.Example: O34926$pythonfind_clusters.py-u"O34926"\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc3_updated.cifAB\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc5_updated.cifAB\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc6_updated.cifAB\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc7_updated.cifAB\-wbenchmark_data/examples/O34926/O34926_cluster_results/pngsvgOption 6) Include AlphaFold Database structure(s)By parsing in the-aflag,  the script will attempt to download and cluster the pre-generated AlphaFold structure, stored on theAlphaFold Database. You do not need to have downloaded the predicted AlphaFold structure already but must be connected to the internet. The structure will be saved$pythonfind_clusters.py-u"A12345"\-m/path/to/structure_1.cif[chains]\-m...\-aExample: O34926$pythonfind_clusters.py-u"O34926"\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc3_updated.cifAB\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc5_updated.cifAB\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc6_updated.cifAB\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc7_updated.cifAB\-aOption 7) Run allExample #1:O34926$pythonfind_conformers.py-u"O34926"\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc3_updated.cifAB\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc5_updated.cifAB\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc6_updated.cifAB\-mbenchmark_data/examples/O34926/O34926_updated_mmcif/3nc7_updated.cifAB\-cbenchmark_data/examples/O34926/O34926_ca_distances/\-dbenchmark_data/examples/O34926/O34926_distance_differences/\-sbenchmark_data/examples/O34926/O34926_cluster_results/\-obenchmark_data/examples/O34926/O34926_distance_difference_maps/\-gbenchmark_data/examples/O34926/O34926_cluster_results/pngsvg-aor use therun_O34926.shscript.$./run_O34926.shExample #2:P15291python3run_find_conformers.py-u"P15291"\-mbenchmark_data/examples/P15291/P15291_updated_mmcif/2fy7_updated.cifA\-mbenchmark_data/examples/P15291/P15291_updated_mmcif/2fya_updated.cifA\-mbenchmark_data/examples/P15291/P15291_updated_mmcif/2fyb_updated.cifA\-mbenchmark_data/examples/P15291/P15291_updated_mmcif/6fwu_updated.cifAB\-mbenchmark_data/examples/P15291/P15291_updated_mmcif/2fyc_updated.cifAB\-mbenchmark_data/examples/P15291/P15291_updated_mmcif/2fyd_updated.cifAB\-cbenchmark_data/examples/P15291/P15291_ca_distances/\-dbenchmark_data/examples/P15291/P15291_distance_differences/\-sbenchmark_data/examples/P15291/P15291_cluster_results/\-obenchmark_data/examples/P15291/P15291_distance_difference_maps/\-gbenchmark_data/examples/P15291/P15291_cluster_results/pngsvg-wbenchmark_data/examples/P15291/P15291_cluster_results/pngsvg-aor execute therun_P15291.shscript.$./run_P15291.shWhen imported into Orc, the arguments required to execute the clustering process correctly will be parsed into the class instance and related methods as lists generated from the preceding functions called by the existingprotein-superposepipeline.Run on benchmark datasetThe scripts above are called by therun_benchmark.pywrapper. To generate conformational clustering results for the included benchmark dataset, run:$pythoncluster_benchmark.pyThis will call therun_benchmark(...)functions included inca_distance.py,distance_difference.py,cluster.py,plot_distance_difference.py,plot_dendrogram.pyandplot_swarm_plot.py. No arguments need parsing into the script.Results will be saved in the./benchmark_data/folder.ContributingInstall developer dependencies:pipinstall-rdev-requirements.txtTo run unit tests on the package, the Pytest framework is recommented and can be performed with:pytest--cov=cluster_conformers--cov-report=html-vThe following dependencies will be required:pytest-covpytest-forkedpurest-xdist(optional)They are installed along with the main package dependencies inrequirements.txt.