{"id":13752319,"url":"https://github.com/Merck/BioPhi","last_synced_at":"2025-05-09T19:31:58.477Z","repository":{"id":42663985,"uuid":"390730203","full_name":"Merck/BioPhi","owner":"Merck","description":"BioPhi is an open-source antibody design platform. It features methods for automated antibody humanization (Sapiens), humanness evaluation (OASis) and an interface for computer-assisted antibody sequence design.","archived":false,"fork":false,"pushed_at":"2025-05-09T14:36:59.000Z","size":15042,"stargazers_count":179,"open_issues_count":30,"forks_count":47,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-05-09T15:39:10.869Z","etag":null,"topics":["antibody","humanization","humanness","oasis","sapiens"],"latest_commit_sha":null,"homepage":"https://biophi.dichlab.org/","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/Merck.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":"2021-07-29T13:18:02.000Z","updated_at":"2025-05-09T14:37:02.000Z","dependencies_parsed_at":"2023-02-18T04:45:53.823Z","dependency_job_id":"e2a36b8f-97ea-43a9-a4ff-578b1fa56236","html_url":"https://github.com/Merck/BioPhi","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Merck%2FBioPhi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Merck%2FBioPhi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Merck%2FBioPhi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Merck%2FBioPhi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Merck","download_url":"https://codeload.github.com/Merck/BioPhi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253312296,"owners_count":21888615,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["antibody","humanization","humanness","oasis","sapiens"],"created_at":"2024-08-03T09:01:03.634Z","updated_at":"2025-05-09T19:31:57.447Z","avatar_url":"https://github.com/Merck.png","language":"Python","readme":"\u003cp align=\"center\"\u003e\n    \u003cbr\u003e\n    \u003cimg height=\"90\" src=\"biophi/common/web/static/img/logo-light/2x/biophi_logo@2x.png?raw=true?raw=true\"\u003e\n    \u003cbr\u003e\n    \u003cbr\u003e\n    \u003ca href=\"https://github.com/Merck/BioPhi/actions/workflows/python-package-conda.yml\"\u003e\n    \u003cimg src=\"https://github.com/Merck/BioPhi/actions/workflows/python-package-conda.yml/badge.svg\"\n        alt=\"Build \u0026 Test\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://anaconda.org/bioconda/biophi\"\u003e\n        \u003cimg src=\"https://img.shields.io/conda/dn/bioconda/biophi.svg?style=flag\u0026label=BioConda%20install\u0026color=green\"\n            alt=\"BioConda Install\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/Merck/BioPhi/releases\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/v/release/Merck/BioPhi?include_prereleases\"\n            alt=\"Latest GitHub release\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://twitter.com/intent/follow?screen_name=BioPhi\"\u003e\n        \u003cimg src=\"https://img.shields.io/twitter/follow/BioPhi?style=social\u0026logo=twitter\"\n            alt=\"follow on Twitter\"\u003e\u003c/a\u003e    \n\u003c/p\u003e\n\nBioPhi is an open-source antibody design platform. \nIt features methods for automated antibody humanization (Sapiens), humanness evaluation (OASis) and an interface for computer-assisted antibody sequence design.\n\nLearn more in the BioPhi, Sapiens and OASis in our publication:\n\n\u003e David Prihoda, Jad Maamary, Andrew Waight, Veronica Juan, Laurence Fayadat-Dilman, Daniel Svozil \u0026 Danny A. Bitton (2022) \n\u003e BioPhi: A platform for antibody design, humanization, and humanness evaluation based on natural antibody repertoires and deep learning, mAbs, 14:1, DOI: https://doi.org/10.1080/19420862.2021.2020203\n\nThe university-hosted BioPhi web server is available at: [http://biophi.dichlab.org](http://biophi.dichlab.org)\n\nFor more information about the Sapiens antibody language model, see the [Sapiens repository](https://github.com/Merck/Sapiens)\n\nThe data and notebooks supporting the analysis are found in the [BioPhi-2021-publication repository](https://github.com/Merck/BioPhi-2021-publication)\n\n## Intro video\n\n\u003ca href=\"http://www.youtube.com/watch?v=JNfU4cR1hgI\" target=\"_blank\" title=\"BioPhi Intro Video\"\u003e\n    \u003cimg src=\"https://biophi.dichlab.org/static/img/preview.png\" alt=\"BioPhi Intro Video\" height=\"350\"\u003e\n\u003c/a\u003e\n\n## Contributing\n\nBioPhi is an open and extensible platform, contributions are welcome. \n\nIf you have ideas about what to improve or which tools could be integrated, please submit\nany feature requests using the [Issues](https://github.com/Merck/biophi/issues) tab.\n\n## Running BioPhi on your machine\n\nIf you don't want to use the [public BioPhi server](http://biophi.dichlab.org), you can run BioPhi on your own machine.\n\n### 1. Download OASis database\n\nTo run BioPhi with OASis humanness evaluation locally, \nyou will need to download and unzip the\n[OASis database file (22GB uncompressed)](https://zenodo.org/record/5164685).\n\n```bash\n# Download database file\nwget https://zenodo.org/record/5164685/files/OASis_9mers_v1.db.gz\n# Unzip\ngunzip OASis_9mers_v1.db.gz\n```\n\n### 2. Install BioPhi using Conda\n\nYou can install BioPhi using [Conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/download.html) \nor one of the alternatives ([Miniconda](https://docs.conda.io/en/latest/miniconda.html), \n[Miniforge](https://github.com/conda-forge/miniforge)).\n\nInstall BioPhi using:\n\n```bash\n# Recommended: Create a separate BioPhi environment\nconda create -n biophi python=3.9\nconda activate biophi\n\n# Install BioPhi \n# Using Bioconda and Conda-Forge channels\nconda install biophi -c bioconda -c conda-forge --override-channels\n```\n\nIf conda installation fails, you can try running using Docker. See [Run BioPhi using provided Docker image](https://github.com/Merck/BioPhi#run-biophi-using-provided-docker-image).\n\n### 3. Run simplified server\n\n```bash\n# Set up path to OASis database (downloaded and unzipped)\nexport OASIS_DB_PATH=/path/to/downloaded/OASis_9mers_v1.db\n\n# Run simplified BioPhi server (not for live deployment!)\nbiophi web\n```\n\n**Note:** This is simplified usage for local use only. \nSee [Deploying your own BioPhi server](#deploying-your-own-biophi-server) section below \nto learn about deploying BioPhi properly on a server.\n\n## Run BioPhi using provided Docker image\n\nFirst, download OASis DB as described above.\n\nThen, run a simplified BioPhi server using the provided Docker image:\n\n```bash\ndocker run \\\n    -v /your/absolute/path/to/oasis/directory/:/data \\\n    -e OASIS_DB_PATH=/data/OASis_9mers_v1.db \\\n    -p 5000:5000 \\\n    quay.io/biocontainers/biophi:1.0.5--pyhdfd78af_0 \\\n    biophi web --host 0.0.0.0\n```\n\nThe application will be accessible at [localhost:5000](http://localhost:5000).\n\n**Note:** This is simplified usage for local use only. \nSee [Deploying your own BioPhi server](#deploying-your-own-biophi-server) section below \nto learn about deploying BioPhi properly on a server.\n\n## BioPhi command-line interface\n\nBioPhi also provides a command-line interface that enables bulk processing.\n\n\u003cdetails\u003e\n    \u003csummary\u003eSee more\u003c/summary\u003e\n\n```bash\n# Get humanized FASTA\n# Expected input: Both chains of each antibody should have the same ID\n#                 with an optional _VL/_VH or _HC/_LC suffix\nbiophi sapiens mabs.fa --fasta-only --output humanized.fa\n\n# Run full humanization \u0026 humanness evaluation pipeline\nbiophi sapiens mabs.fa \\\n    --oasis-db path/to/downloaded/OASis_9mers_v1.db \\\n    --output humanized/\n\n# Get the Sapiens probability matrix (score of each residue at each position)\nbiophi sapiens mabs.fa --scores-only --output scores.csv\n\n# Get mean Sapiens score (one score for each sequence)\nbiophi sapiens mabs.fa --mean-score-only --output scores.csv\n\n# Get OASis humanness evaluation\nbiophi oasis mabs.fa \\\n    --oasis-db path/to/downloaded/OASis_9mers_v1.db \\\n    --output oasis.xlsx\n```\n  \n\u003c/details\u003e\n\n## Development\n\nBioPhi is composed of three services that need to be running at the same time:\n\n- `web`: Flask web server that handles both the frontend and the backend of the web application\n- `celery`: Asynchronous worker service(s) that process long-running tasks\n- `redis`: In-memory database for storing celery queue tasks and results\n\n### Run BioPhi dev server through Docker Compose\n\nRunning through Docker Compose is easiest in terms of setup, but web server autoreload is not supported,\nso you will have to restart the services after each code update.\n\n\u003cdetails\u003e\n    \u003csummary\u003eSee more\u003c/summary\u003e\n\n#### 1. Install Docker\n\nSee https://docs.docker.com/get-docker/\n\n#### 2. Clone this repository\n    \nDownload or clone this repository using:\n    \n```bash\ngit clone https://github.com/Merck/BioPhi.git\n```   \n\n#### 3. Download OASis DB\n\nDownload OASis database as described above. Put it in local `data/` dir inside the project folder.\n    \n#### 4. Build all images using Docker Compose    \n    \n```bash\n# Open BioPhi directory\ncd BioPhi    \n# Build docker image using Makefile\nmake docker-build\n# or directly using\ndocker-compose build\n```\n\n#### 4. Run all services using Docker Compose\n\n```bash\n# Run using Makefile\nmake docker-run\n# or directly using\ndocker-compose up\n```\n\nThe application will be accessible at [localhost:5000](http://localhost:5000).\n\nTo build and run, you can use:\n```bash\n# Run using Makefile\nmake docker-build docker-run\n# or directly using\ndocker-compose up --build\n```\n\n#### 5. Handle code updates\n\nAfter your code is updated, you will need to stop the services, run build and start again. \nSee the next section for info on running locally with flask auto-reload.\n\n\u003c/details\u003e\n\n\n### Run BioPhi dev server using Conda\n\nRunning each service locally using Conda will enable flask auto-reload, \nwhich is useful if you are going back and forth between your IDE and the browser.\n\n\u003cdetails\u003e\n    \u003csummary\u003eSee more\u003c/summary\u003e\n\n#### 1. Install Conda\n\nInstall [Conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/download.html) \nor one of the alternatives ([Miniconda](https://docs.conda.io/en/latest/miniconda.html), \n[Miniforge](https://github.com/conda-forge/miniforge))\n\n#### 2. Install Redis server\n\nInstall and run [Redis server](https://redis.io/download). \nOn Mac, you can [install Redis using Brew](https://medium.com/@petehouston/install-and-config-redis-on-mac-os-x-via-homebrew-eb8df9a4f298).\n    \n#### 3. Clone this repository\n    \nDownload or clone this repository using:\n    \n```bash\ngit clone https://github.com/Merck/BioPhi.git\n```   \n\n#### 4. Download OASis DB\n\nDownload OASis database as described above.\n \n#### 5. Setup environment\n\n```bash\n# Open BioPhi directory\ncd BioPhi    \n# Install dependencies using the provided Makefile\nmake env\n# Or directly using\nconda env create -n biophi -f environment.yml\nconda activate biophi\npip install -e . --no-deps\n```\n\n#### 6. Run all services\n\nYou will have to run each service in a separate terminal (Use Cmd+T to open a new tab):\n\n```bash\n# Run Redis server (this depends on your installation, the server might already be running)\nredis-server\n\n# In a separate terminal, run celery worker queue\nexport OASIS_DB_PATH=/path/to/OASis_9mers_v1.db\nmake celery\n\n# In a separate terminal, run flask web server\nexport OASIS_DB_PATH=/path/to/OASis_9mers_v1.db\nmake web\n```\n\nSee the provided \n\n#### 7. Handle code updates\n\nAfter your code is updated, the flask web service should refresh automatically. \nHowever, the celery service needs to be stopped and started manually, \nso you will need to do that if you update code that is executed from the workers.\n\u003c/details\u003e\n\n## Deploying your own BioPhi server\n\nYou can deploy your own internal BioPhi server. \nYou will need to run the three separate services - the flask web server, \nthe celery worker and the redis database.\n\nThis will depend on your platform and your cloud provider, the easiest deployment is using [Docker Compose](https://docs.docker.com/compose/gettingstarted/)\nthrough the provided [docker-compose.yml](docker-compose.yml) file.\n\nFor 🐧 Ubuntu deployment, feel free to copy the deployment configs used on the public university server: [lich-uct/biophi.dichlab.org](https://github.com/lich-uct/biophi.dichlab.org)\n\n## Acknowledgements\n\nBioPhi is based on antibody repertoires from the Observed Antibody Space:\n\n\u003e Kovaltsuk, A., Leem, J., Kelm, S., Snowden, J., Deane, C. M., \u0026 Krawczyk, K. (2018). Observed Antibody Space: A Resource for Data Mining Next-Generation Sequencing of Antibody Repertoires. The Journal of Immunology, 201(8), 2502–2509. https://doi.org/10.4049/jimmunol.1800708\n\nAntibody numbering is performed using ANARCI:\n\n\u003e Dunbar, J., \u0026 Deane, C. M. (2016). ANARCI: Antigen receptor numbering and receptor classification. Bioinformatics, 32(2), 298–300. https://doi.org/10.1093/bioinformatics/btv552\n","funding_links":[],"categories":["Ranked by starred repositories"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMerck%2FBioPhi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMerck%2FBioPhi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMerck%2FBioPhi/lists"}