|
| 1 | +<p align="center"> |
| 2 | + <br> |
| 3 | + <img height="90" src="biophi/common/web/static/img/logo-light/2x/biophi_logo@2x.png?raw=true?raw=true"> |
| 4 | + <br> |
| 5 | +</p> |
| 6 | + |
| 7 | +BioPhi is an open-source antibody design platform. |
| 8 | +It features methods for automated antibody humanization (Sapiens), humanness evaluation (OASis) and an interface for computer-assisted antibody sequence design. |
| 9 | + |
| 10 | +BioPhi is available at: [http://biophi.dichlab.org](http://biophi.dichlab.org) |
| 11 | + |
| 12 | +Learn more in the BioPhi, Sapiens and OASis in our pre-print: |
| 13 | + |
| 14 | +> TBD |
| 15 | +
|
| 16 | +## Running BioPhi on your machine |
| 17 | + |
| 18 | +If you don't want to use the [public BioPhi server](http://biophi.dichlab.org), you can run BioPhi on your own machine. |
| 19 | + |
| 20 | +<details> |
| 21 | +<summary>See more</summary> |
| 22 | + |
| 23 | +### 1. Download OASis database |
| 24 | + |
| 25 | +To run BioPhi with OASis humanness evaluation locally, |
| 26 | +you will need to download the OASis database (22GB uncompressed). |
| 27 | + |
| 28 | +### 2a. Run simplified server using Docker |
| 29 | + |
| 30 | +If you have [Docker](https://www.docker.com/products/docker-desktop), |
| 31 | +you can run a simplified BioPhi server using: |
| 32 | +```bash |
| 33 | +docker run TBD |
| 34 | +``` |
| 35 | + |
| 36 | +### 2b. Run simplified server using Conda |
| 37 | + |
| 38 | +You can also install BioPhi using [Bioconda](https://bioconda.github.io/user/install.html): |
| 39 | + |
| 40 | +```bash |
| 41 | +# Recommended: Create a separate BioPhi environment |
| 42 | +conda create -n biophi python=3.8 |
| 43 | +conda activate biophi |
| 44 | + |
| 45 | +# Install BioPhi |
| 46 | +conda install biophi |
| 47 | + |
| 48 | +# Run simplified BioPhi server (not for live deployment!) |
| 49 | +biophi web |
| 50 | +``` |
| 51 | + |
| 52 | +**Note:** This is simplified usage for local use only. See Deploying your own BioPhi server *(TODO LINK)* to learn about |
| 53 | +deploying BioPhi properly on a server. |
| 54 | + |
| 55 | +</details> |
| 56 | + |
| 57 | +## BioPhi command-line interface |
| 58 | + |
| 59 | +BioPhi also provides a command-line interface that enables bulk processing. |
| 60 | + |
| 61 | +<details> |
| 62 | + <summary>See more</summary> |
| 63 | + |
| 64 | +```bash |
| 65 | +TBD |
| 66 | +``` |
| 67 | + |
| 68 | +</details> |
| 69 | + |
| 70 | +## Contributing |
| 71 | + |
| 72 | +BioPhi is an open and extensible platform, contributions are welcome. |
| 73 | +Submit any feature requests on the [Issues](https://github.com/Merck/biophi/issues) page. |
| 74 | + |
| 75 | +## Development |
| 76 | + |
| 77 | +BioPhi is composed of three services that need to be running at the same time: |
| 78 | + |
| 79 | +- `web`: Flask web server that handles both the frontend and the backend of the web application |
| 80 | +- `celery`: Asynchronous worker service(s) that process long-running tasks |
| 81 | +- `redis`: In-memory database for storing celery queue tasks and results |
| 82 | + |
| 83 | +### Run BioPhi dev server through Docker Compose |
| 84 | + |
| 85 | +Running through Docker Compose is easiest in terms of setup, but web server autoreload is not supported, |
| 86 | +so you will have to restart the services after each code update. |
| 87 | + |
| 88 | +<details> |
| 89 | + <summary>See more</summary> |
| 90 | + |
| 91 | +#### 1. Install Docker |
| 92 | + |
| 93 | +See https://docs.docker.com/docker-for-mac/install/ |
| 94 | + |
| 95 | +#### 2. Build all images using Docker Compose |
| 96 | + |
| 97 | +```bash |
| 98 | +# Run using Makefile |
| 99 | +make docker-build |
| 100 | +# or directly using |
| 101 | +docker-compose build |
| 102 | +``` |
| 103 | + |
| 104 | +#### 3. Run all services using Docker Compose |
| 105 | + |
| 106 | +```bash |
| 107 | +# Run using Makefile |
| 108 | +make docker-run |
| 109 | +# or directly using |
| 110 | +docker-compose up |
| 111 | +``` |
| 112 | + |
| 113 | +To build and run, you can use: |
| 114 | +```bash |
| 115 | +# Run using Makefile |
| 116 | +make docker-build docker-run |
| 117 | +# or directly using |
| 118 | +docker-compose up --build |
| 119 | +``` |
| 120 | + |
| 121 | +#### 4. Handle code updates |
| 122 | + |
| 123 | +After your code is updated, you will need to stop the services, run build and start again. |
| 124 | +See the next section for info on running locally with flask auto-reload. |
| 125 | + |
| 126 | +</details> |
| 127 | + |
| 128 | + |
| 129 | +### Run BioPhi dev server using Conda |
| 130 | + |
| 131 | +Running each service locally using Conda will enable flask auto-reload, |
| 132 | +which is useful if you are going back and forth between your IDE and the browser. |
| 133 | + |
| 134 | +<details> |
| 135 | + <summary>See more</summary> |
| 136 | + |
| 137 | +#### 1. Install Conda |
| 138 | + |
| 139 | +Install [Conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/download.html) |
| 140 | +or one of the alternatives ([Miniconda](https://docs.conda.io/en/latest/miniconda.html), |
| 141 | +[Miniforge](https://github.com/conda-forge/miniforge)) |
| 142 | + |
| 143 | +#### 2. Install Redis server |
| 144 | + |
| 145 | +Install and run [Redis server](https://redis.io/download). |
| 146 | +On Mac, you can [install Redis using Brew](https://medium.com/@petehouston/install-and-config-redis-on-mac-os-x-via-homebrew-eb8df9a4f298). |
| 147 | + |
| 148 | +#### 3. Setup environment |
| 149 | + |
| 150 | +```bash |
| 151 | +# Install dependencies using the provided Makefile |
| 152 | +make env |
| 153 | +# Or directly using |
| 154 | +conda env create -n biophi-dev -f environment.yml |
| 155 | +conda activate biophi-dev |
| 156 | +pip install -e . |
| 157 | +``` |
| 158 | + |
| 159 | +#### 4. Run all services |
| 160 | + |
| 161 | +You will have to run each service in a separate terminal (Use Cmd+T to open a new tab): |
| 162 | + |
| 163 | +```bash |
| 164 | +# Run Redis server (this depends on your installation, the server might already be running) |
| 165 | +redis-server |
| 166 | + |
| 167 | +# In a separate terminal, run celery worker queue |
| 168 | +make celery |
| 169 | + |
| 170 | +# In a separate terminal, run flask web server |
| 171 | +make web |
| 172 | +``` |
| 173 | + |
| 174 | +See the provided |
| 175 | + |
| 176 | +#### 5. Handle code updates |
| 177 | + |
| 178 | +After your code is updated, the flask web service should refresh automatically. |
| 179 | +However, the celery service needs to be stopped and started manually, |
| 180 | +so you will need to do that if you update code that is executed from the workers. |
| 181 | +</details> |
| 182 | + |
| 183 | +## Deploying your own BioPhi server |
| 184 | + |
| 185 | +You can deploy your own internal BioPhi server. |
| 186 | +You will need to run the three separate services - the flask web server, |
| 187 | +the celery worker and the redis database. |
| 188 | + |
| 189 | +This will depend on your platform and your cloud provider, the easiest deployment is using [Docker Compose](https://docs.docker.com/compose/gettingstarted/) |
| 190 | +through the provided [docker-compose.yml](docker-compose.yml) file. |
| 191 | + |
| 192 | +## Acknowledgements |
| 193 | + |
| 194 | +BioPhi is based on antibody repertoires from the Observed Antibody Space: |
| 195 | + |
| 196 | +> Kovaltsuk, A., Leem, J., Kelm, S., Snowden, J., Deane, C. M., & 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 |
| 197 | +
|
| 198 | +Antibody numbering is performed using ANARCI: |
| 199 | + |
| 200 | +> Dunbar, J., & Deane, C. M. (2016). ANARCI: Antigen receptor numbering and receptor classification. Bioinformatics, 32(2), 298–300. https://doi.org/10.1093/bioinformatics/btv552 |
0 commit comments