{"id":42217857,"url":"https://github.com/sami-chaaban/alphascreen","last_synced_at":"2026-01-27T01:30:59.251Z","repository":{"id":62304519,"uuid":"538132064","full_name":"sami-chaaban/alphascreen","owner":"sami-chaaban","description":"Screen interactions with AlphaFold Multimer","archived":false,"fork":false,"pushed_at":"2025-03-10T16:18:38.000Z","size":1598,"stargazers_count":10,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-10T17:29:58.585Z","etag":null,"topics":["alphafold","alphafold-multimer","protein-protein-interaction"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sami-chaaban.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-18T14:17:30.000Z","updated_at":"2025-03-10T16:18:42.000Z","dependencies_parsed_at":"2024-10-29T23:42:47.374Z","dependency_job_id":null,"html_url":"https://github.com/sami-chaaban/alphascreen","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/sami-chaaban/alphascreen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sami-chaaban%2Falphascreen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sami-chaaban%2Falphascreen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sami-chaaban%2Falphascreen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sami-chaaban%2Falphascreen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sami-chaaban","download_url":"https://codeload.github.com/sami-chaaban/alphascreen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sami-chaaban%2Falphascreen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28795467,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T01:07:07.743Z","status":"ssl_error","status_checked_at":"2026-01-27T01:07:06.974Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alphafold","alphafold-multimer","protein-protein-interaction"],"created_at":"2026-01-27T01:30:58.776Z","updated_at":"2026-01-27T01:30:59.245Z","avatar_url":"https://github.com/sami-chaaban.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# alphascreen\n\n1. [Features](#features)\n2. [Workflow Overview](#workflow)\n3. [Installation](#installation)\n4. [Usage](#usage)\n    * [Job setup](#jobsetup)\n    * [Check runs](#checkruns)\n    * [Analysis](#analysis)\n5. [Troubleshooting](#troubleshooting)\n6. [License](#license)\n\n## Features\u003ca name=\"features\"\u003e\u003c/a\u003e\n\n* Fetches the fasta sequences of the uniprot IDs contained in a table of paired proteins.\n\n* Chops up the sequences so that they are of reasonable size for subsequent pairwise predictions.\n\n* Interprets the PAEs of the resulting predictions, only considering the region in the plot relating to the interaction.\n\n* Generates summaries, including a PDF showing the PAE plot next to snapshots of the models.\n\n## Workflow Overview\u003ca name=\"workflow\"\u003e\u003c/a\u003e\n\nFor a step-by-step workflow, see the [Usage](#usage) section.\n\n### Setting up the fasta files\n\nThis package generates fasta files for a set of interaction partners in order to run Alphafold predictions. The assumption is that your Alphafold implementation takes fasta files as input. The input to ```--parse``` is a table which includes two columns containing uniprot IDs for the interaction partners (column headers specified with ```--columnA``` and ```--columnB```). These tables can be generated manually or by a database (e.g. BioGRID). Acceptable extensions are .xlsx and .txt (tab-delimited, e.g. as output by BioGRID).\n\nThe command ```--parse``` fetches the sequences from Uniprot and fragments them before generating fasta files, which are stored in the *fastas* folder. Fragmenting the sequences (```--fragment```) helps keep the total sequence length short enough so the jobs don't run out of memory. An overlap is considered (```--overlap```) so that the fragmentation doesn't accidentally cut into an interaction interface. You can dimerize any or all proteins (```--dimerize```, ```--dimerize_all```, ```--dimerize_all_except```) and/or consider a specific stretch of sequence for a protein or set of proteins (```--consider```).\n\n```\nalphascreen --parse myproteinpairs.xlsx\n```\n\n### Running the predictions\n\nOne of the files that is output is a bash script (*runpredictions.bsh*) with a list of commands to run Alphafold on each of the generated fasta files on your machine/cluster. The syntax is set up for the LMB, and will therefore likely not be directly compatible with your implementation. You can sort this by either editing *runpredictions.bsh* or *jobsetup.py* so that the commands will work. If you do change this, make sure the results are output into the *results* directory, which is important for the analysis command ```--show_top``` to work. The package has only been tested on Colabfold 1.3.0, 1.4.0, and 1.5.2 (when parsing the results, it is assumed that the PDBs and PAE json filenames are those from Colabfold).\n\nImportant: The script will run all the jobs and relies on your queuing system to handle them!\n\n```\nbash runpredictions.bsh\n```\n\n### Analyzing the results\n\nThe default behaviour for analysis (```--show_top```) is to go through one result at a time and find the best PAE, only considering the region of the plot corresponding to the protein interaction you are screening for. After doing this for all the predictions, they are ranked relative to each other by again comparing their respective PAEs in the protein interaction region.\n\n```\nalphascreen --show_top 0.7\n```\n\nIf you want instead want to rank by local interaction score (LIS) (Kim et al., 2024), you can pass ```--rank_by lis```. While iptm and ptm can be used for ranking as well, alphascreen relies on your Alphafold/Colabfold implementation writing the iptm and ptm scores to a *scores.txt* file within the individual results directories. It should have the same number of lines as there are models, each line containing the information in this format:\n\n*iptm:0.09 ptm:0.62*\u003cbr\u003e\n*iptm:0.02 ptm:0.63*\u003cbr\u003e\n*...*\n\nThese values are just an example. Note the presence/absence of spaces and placement of colons.\n\n## Installation\u003ca name=\"installation\"\u003e\u003c/a\u003e\n\n* Set up a fresh conda environment with Python \u003e= 3.9: `conda create -n alphascreen python=3.10`\n\n* Activate the environment: `conda activate alphascreen`.\n\n* Install alphascreen: **`pip install alphascreen`**\n\n* Install pymol dependancies: **`conda install -c schrodinger pymol-bundle`**\n\n## Usage\u003ca name=\"usage\"\u003e\u003c/a\u003e\n\n### Job setup\u003ca name=\"jobsetup\"\u003e\u003c/a\u003e\n\nIf you have a list of potential interactors in two columns within a table (.txt or .xlsx):\n\n```\nalphascreen --parse filename [options]\n```\n\nFor example, the tab delimited Biogrid output *BIOGRID-GENE-111808-4.4.214.tab3.txt* looks like this:\n\n![BiogridExample](https://github.com/sami-chaaban/alphascreen/blob/main/examples/Biogrid.png?raw=true \"BiogridExample\")\n\nTo parse the file, run `alphascreen --parse BIOGRID-GENE-111808-4.4.214.tab3.txt`. The script will generate the following output:\n\n```\n\u003e\u003e Reading table...\n\n\u003e\u003e Removed 45 duplicated pairs...\n\n\u003e\u003e Getting sequences...\n\n!! Warning: there was a problem getting the Uniprot data for accessions:\n\n·· -\n\n\u003e\u003e Writing 157 Alphafold commands...\n\n\u003e\u003e Run the Alphafold jobs with \"bash runpredictions.bsh\"\n\nDone!\n\n```\n\nSometimes the uniprot ID is invalid, such as the dash (\"-\") referenced in the warning above. When finished, the script will have generated two folders (***fastas*** and ***results***), some general information files (***log.txt*** and ***uniprots.txt***), and the bash script to run the predictions (***runpredictions.bsh***). See below for additional options, such as dimerization, custom sequences, etc.\n\nIf you only have two proteins and want to generate fragmented predictions, you can simply run:\n\n```\nalphascreen --parse uniprot-id-1/uniprot-id-2 [options]\n```\n\n\n**Options**\n\n**```--columnA```** *```columnA-name```*\n\nName of column heading for uniprot IDs for the first set of interactors. Default is *SWISS-PROT Accessions Interactor A*, which is what BioGRID uses.\n\n**```--columnB```** *```columnB-name```*\n\nName of column heading for uniprot IDs for the second set of interactors. Default is *SWISS-PROT Accessions Interactor B*, which is what BioGRID uses.\n\n**```--fragment```** *```length```*\n\nApproximate fragment length. Default is 500. If you provided two uniprot IDs as input, you have the option to provide two fragment lengths here (*length1/length2*) corresponding to the fragment length of each uniprot ID.\n\n**```--overlap```** *```length```*\n\nSequence is extended by this amount on either side of slices. Default is 50.\n\n**```--exhaustive```**\n\nRun every protein in column A against every protein in column B, instead of just row by row. This is useful when you want to run everything in a list of proteins against each other, or one protein against many (see example of the latter below). In this case, create a table with two columns both containing the list of proteins, and use the *--exhaustive* option. Any duplicate pairs will be removed during parsing. To ignore proteins being predicted against themselves, use *--ignore_self*.\n\n\u003cimg src=\"https://github.com/sami-chaaban/alphascreen/blob/main/examples/Exhaustive.png\"  alt=\"ExhaustiveExample\" width=\"60%\" height=\"60%\"\u003e\n\n**```--ignore_self```**\n\nIgnore any instances of a protein being predicted against itself. Useful when using the *--exhaustive* option with two identical columns of proteins to predict everything against everything while ignoring self. This does not include dimerization.\n\n**```--dimerize```** *```uniprot-id```* or *```uniprot-ids.txt```*\n\nUniprot ID to dimerize (i.e. homodimerize). Alternatively, provide a text file (.txt) with a single column list of uniprot IDs to dimerize.\n\n**```--dimerize_all```**\n\nDimerize all proteins. You may have to reduce the fragment length if the total sequence length becomes too big.\n\n**```--dimerize_all_except```** *```uniprot-id```* or *```uniprot-ids.txt```*\n\nDimerize all proteins except the uniprot ID provided here. Alternatively, provide a text file (.txt) with a single column list of uniprot IDs to NOT dimerize. Everything else will be dimerized.\n\n**```--consider```** *```uniprot/start/end```* or *```consider.txt```*\n\nUniprot ID and sequence range to consider. Example: *Q86VS8/1/200* only considers amino acids 1-200 for uniprot ID Q86VS8. Alternatively, provide a text file with a single column list of sequences to consider with a similar syntax (*id/start/end*).\n\n**```--customids```** *```sequences.fasta```*\n\nProvide a fasta file to define custom IDs that you will use when running *--parse*. This is useful when your sequence is not present in uniprot database. The fasta file can contain multiple entries. Make sure the headers don't contain any dashes and have at most one underscore (working examples: *\u003eProteinA* or *\u003eProteinA_Tetrahymena*).\n\n**```--alphafold_exec```** *```alphafold-executable```*\n\nPath to script that runs Alphafold for writing the commands. Default is *colabfold4* as per the LMB cluster usage.\n\n**```--focus```** *```uniprot-id```*\n\nUniprot ID to focus on. This means that it will the first chain in any predictions that contain it.\n\n**```--dontwrite```**\n\nDon't write out any files and just show the relevant information. This is useful to check how many fastas will be generated from parsing and fragmenting.\n\n### Check runs\u003ca name=\"checkruns\"\u003e\u003c/a\u003e\n\n```\nalphascreen --check\n```\n\nCheck how many runs are finished so far and how many remain.\n\n```\nalphascreen --write_unfinished\n```\n\nCheck how many runs are finished so far and write out a new bash script with the remaining Alphafold commands (runpredictions-unfinished.bsh). This is useful when the jobs crash.\n\nBe careful not to run this while there are predictions in progress.\n\n### Analysis\u003ca name=\"analysis\"\u003e\u003c/a\u003e\n\n```\nalphascreen --show_top threshold [options]\n```\n\nGenerate summary files for the runs so far. For example, ```alphascreen --show_top 0.7``` will choose the model with the best interaction-site PAE for each prediction, and then rank all the predictions (also by the interaction-site PAE). Only those with scaled-PAEs higher than the threshold (e.g. 0.7) are output to a pdf. The ```--rank_by``` option below has more information on the scaled-PAE and LIS. To output all predictions, pass ```--show_all```. The PAEs-Models pdf will also contain a snapshot of the prediction (see troubleshooting below if you get a \"license\" watermark on the models). A table is also output (.xlsx) that can be used as input for a subsequent run of alphascreen if you need to test different parameters on just the top hits.\n\nHere is an example of one page from the PAEs-Models pdf:\n\n![AnalysisExample](https://github.com/sami-chaaban/alphascreen/blob/main/examples/Analysis.png?raw=true \"AnalysisExample\")\n\n```\nalphascreen --write_table [options]\n```\n\nLike ```--show_top```, but only outputs the table (.xlsx and .csv). No threshold value is considered; all predictions are ranked and output.\n\n**Options**\n\n**```--rank_by```** ```pae``` or ```lis``` or ```iptm``` or ```ptm```\n\nScore by which models are ranked (***pae***, ***lis***, ***iptm***, or ***ptm***). The default is *pae*. This is used for both choosing the best model in a prediction as well as ranking those chosen models in the summary files. The option ```pae``` will look for the deepest PAE valleys only in the parts of the plot that are interactions between **different** proteins. The PAE is scaled to be between 0 and 1 where higher values are better predictions (```--show_top 0.7``` is a good starting point).\n\nThe local interaction score (option ```lis```) (Kim et al., 2024) similarly analyzes those regions of the PAE (see the manuscript for more information). Great LIS scores are above 0.1 but the values can get quite small in some cases (```--rank_by lis --show_all``` is probably best).\n\nThe options ```iptm``` and ```ptm``` rely on a *scores.txt* file in each results directory (see explanation at the top) (in this case ```--rank_by iptm --show_top 0.3``` is a good starting point).\n\n**```--overwrite```**\n\nOverwrite .png snapshots that have already been generated, otherwise it will skip those to save time. This is only relevant for ``show_top``.\n\n## Troubleshooting\u003ca name=\"troubleshooting\"\u003e\u003c/a\u003e\n\n* If a \"license expired\" watermark appears on the model images in PAEs-Models.pdf, follow the instructions here to update your pymol license: https://pymol.org/dsc/ip/license/. You may have to be on your institute's VPN for the link to direct you to a download page rather than an invoice verification page.\n\n## License\u003ca name=\"license\"\u003e\u003c/a\u003e\n\nThis project is licensed under the MIT License - see the [LICENSE.txt](https://github.com/sami-chaaban/alphascreen/blob/main/LICENSE.txt) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsami-chaaban%2Falphascreen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsami-chaaban%2Falphascreen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsami-chaaban%2Falphascreen/lists"}