Adds how to run white noise, aloha, foldx and rdkit related objective functions

Author: miguelgondu

docs/protein-optimization/_toc.yml

@@ -20,14 +20,17 @@ parts:
   - caption: Some objective functions available
     chapters:
       - file: using_poli/objective_repository/white_noise.md
+      - file: using_poli/objective_repository/aloha.md
+      - file: using_poli/objective_repository/rdkit_qed.md
+      - file: using_poli/objective_repository/rdkit_logp.md
       - file: using_poli/objective_repository/foldx_stability.md
+      - file: using_poli/objective_repository/foldx_sasa.md
       - file: using_poli/objective_repository/super_mario_bros.md
-      - file: using_poli/objective_repository/small_molecule.md
   - caption: "Contributing"
     chapters:
     - file: contributing/a_new_problem.md
     - file: contributing/a_new_solver.md
-  - caption: "Appendix: Understanding FoldX"
+  - caption: "Appendix: Understanding foldx"
     chapters:
     - file: understanding_foldx/00-installing-foldx.md
     - file: understanding_foldx/01-single-mutation-using-foldx/index.ipynb

docs/protein-optimization/index.md

@@ -11,49 +11,85 @@ Our promise is: if you can run your objective function reliably in a `conda` env
 
 These are some objective functions available on `poli`. **For a full list**, check [getting started](./getting_started/getting_started.md).
 
+
+### Toy problems
+
 ::::{grid}
 :gutter: 3
 
 :::{grid-item-card} White noise
 :link: ./using_poli/objective_repository/white_noise.html
-:columns: 4
+:columns: 6
 White noise drawn from a unit Gaussian
 :::
 
 :::{grid-item-card} Aloha
 :link: ./using_poli/objective_repository/aloha.html
-:columns: 4
+:columns: 6
 A toy example about optimizing 5-letter words to spell "ALOHA"
 :::
 
-:::{grid-item-card} Protein Stability
-:link: ./using_poli/objective_repository/foldx_stability.html
-:columns: 4
-Stability of mutations of a wildtype using `foldx`
+::::
+
+### Small molecules
+
+::::{grid}
+:gutter: 3
+
+:::{grid-item-card} Quantitative Estimate of Druglikeness (QED)
+:link: ./using_poli/objective_repository/rdkit_qed.html
+:columns: 6
+Computing the QED using `RDKit`.
 :::
 
-:::{grid-item-card} Mario jumps
-:link: ./using_poli/objective_repository/super_mario_bros.html
-:columns: 4
-Optimizing the number of jumps on a Super Mario Bros level
+:::{grid-item-card} Log-solubility (LogP)
+:link: ./using_poli/objective_repository/rdkit_logp.html
+:columns: 6
+Computing the log-quotient of solubilities using `RDKit`.
+:::
+
+:::{grid-item-card} TDC oracles [WIP]
+:link: ./using_poli/objective_repository/tdc_oracles.html
+:columns: 6
+Some of the oracles provided by the Therapeutics Data Commons. [WIP]
+:::
+
+::::
+
+### Proteins
+
+::::{grid}
+:gutter: 3
+
+:::{grid-item-card} Protein Stability (using `foldx`)
+:link: ./using_poli/objective_repository/foldx_stability.html
+:columns: 6
+Stability of mutations of a wildtype using `foldx`
 :::
 
-:::{grid-item-card} Small molecule properties
-:link: ./using_poli/objective_repository/small_molecule.html
-:columns: 4
-Small molecule's synthesizability, druglikeness, and more. [WIP]
+:::{grid-item-card} Protein SASA score (using `foldx`)
+:link: ./using_poli/objective_repository/foldx_sasa.html
+:columns: 6
+Solvent accessibility of mutations of a wildtype using `foldx`
 :::
 
-:::{grid-item-card} RaSP
+:::{grid-item-card} Protein Stability (using `RaSP`) [WIP]
 :link: ./using_poli/objective_repository/RaSP.html
-:columns: 4
+:columns: 6
 Rapid Stability Predictions of single mutations from a wildtype. [WIP]
 :::
 
-:::{grid-item-card} TDC oracles
-:link: ./using_poli/objective_repository/tdc_oracles.html
-:columns: 4
-Some of the oracles provided by the Therapeutics Data Commons. [WIP]
+::::
+
+### Other
+
+::::{grid}
+:gutter: 3
+
+:::{grid-item-card} Mario jumps
+:link: ./using_poli/objective_repository/super_mario_bros.html
+:columns: 6
+Optimizing the number of jumps on a Super Mario Bros level
 :::
 
 ::::
@@ -66,31 +102,31 @@ On top of `poli`, we provide `poli-baselines`, a collection of **black-box optim
 
 :::{grid-item-card} Random Mutations
 :link: ./using_poli_baselines/random_mutations.html
-:columns: 4
+:columns: 6
 Optimizing a discrete sequence by performing random mutations
 :::
 
 :::{grid-item-card} NSGA-2
 :link: ./using_poli_baselines/nsga_2.html
-:columns: 4
+:columns: 6
 A Genetic algorithm for optimizing more than one metric [WIP]
 :::
 
 :::{grid-item-card} CMA-ES
 :link: ./using_poli_baselines/cma_es.html
-:columns: 4
+:columns: 6
 An evolutionary strategy for continuous problems [WIP]
 :::
 
 :::{grid-item-card} Latent Space Bayesian Optimization
 :link: ./using_poli_baselines/latent_space_bo.html
-:columns: 4
+:columns: 6
 Learning continuous representations and optimizing in latent space. [WIP]
 :::
 
 :::{grid-item-card} Graph GA
 :link: ./using_poli_baselines/graph_ga.html
-:columns: 4
+:columns: 6
 Graph Genetic Algorithms for small molecules. [WIP]
 :::
 

docs/protein-optimization/understanding_foldx/00-installing-foldx.md

@@ -1,3 +1,3 @@
-# Installing FoldX
+# Installing `foldx`
 
 [TODO: write]

docs/protein-optimization/using_poli/objective_repository/aloha.md

@@ -1,3 +1,29 @@
 # Aloha objective function
 
-[TODO: write]
+![Type of objective function: discrete](https://img.shields.io/badge/Input_type-discrete-blue)
+![Environment to run this objective function: poli base](https://img.shields.io/badge/Environment-poli____base-teal
+)
+
+## About
+
+This toy objective function takes 5-letter sequences (in all-caps) and returns the distance to the string "ALOHA".
+
+## Prerequisites
+
+None, this function should always run out-of-the-box
+
+## How to run
+
+```python
+import numpy as np
+from poli import objective_factory
+
+# How to create
+problem_info, f, x0, y0, run_info = objective_factory.create(name="aloha")
+
+# Example input:
+x = np.array([["A", "L", "O", "O", "F"]])  # must be of shape [b, L], in this case [1, 3].
+
+# Querying:
+print(f(x))  # Should be 3 (A, L, and the first O).
+```

docs/protein-optimization/using_poli/objective_repository/foldx_sasa.md

@@ -0,0 +1,94 @@
+# Protein solvent accessibility (using `foldx`)
+![Type of objective function: discrete](https://img.shields.io/badge/Type-discrete_inputs-blue)
+![Environment to run this objective function: poli protein](https://img.shields.io/badge/Environment-poli____protein-teal
+)
+
+## About
+
+This objective function returns the solvent accesible surface area (SASA) of a wildtype and its mutations using `foldx` and `biopython`.
+
+## Prerequisites
+
+- Have `foldx` installed, and available in your home directory. We expect the following files to be there:
+  - `~/foldx/foldx`: the binary. You might need to rename it.
+  - `~/foldx/rotabase.txt`: a text file necessary for `foldx` to run.
+- A `wildtype_pdb_file`: a (repaired) pdb file of the wildtype.
+
+## How to run
+
+You can either run this objective function in your current environment (assuming that you have the correct dependencies installed), or you can run it in an isolated environment.
+
+::::{tab-set}
+
+:::{tab-item} In current environment
+
+You will have to install the following two dependencies:
+
+```bash
+pip install biopython python-levenshtein
+```
+
+Then run
+
+```python
+from pathlib import Path
+
+import numpy as np
+
+from poli import objective_factory
+
+# The path to your wildtype pdb
+wildtype_pdb_file = Path("path/to/wildtype.pdb")
+
+# How to create
+problem_info, f, x0, y0, run_info = objective_factory.create(
+    name="foldx_sasa",
+    wildtype_pdb_file=wildtype_pdb_file
+)
+
+# Example input:
+print(x0)
+
+# Querying:
+print(y0)  # The stability of your wildtype
+```
+
+You could also pass an `alphabet: Dict[str, int]` to the create method. By default, [we use this encoding](https://github.com/MachineLearningLifeScience/poli/blob/44cad2a5c95f209aeb24d4893d162b3359ca91a3/src/poli/core/util/proteins/defaults.py#L1).
+
+:::
+
+:::{tab-item} In isolation
+
+If you want us to handle dependencies, run
+
+```python
+from pathlib import Path
+
+import numpy as np
+
+from poli import objective_factory
+
+# The path to your wildtype pdb
+wildtype_pdb_file = Path("path/to/wildtype.pdb")
+
+# How to create
+problem_info, f, x0, y0, run_info = objective_factory.create(
+    name="foldx_sasa",
+    wildtype_pdb_file=wildtype_pdb_file,
+    force_register=True,
+)
+
+# Example input:
+print(x0)
+
+# Querying:
+print(y0)  # The stability of your wildtype
+```
+
+```{warning}
+Registering the objective function in this way will create a `conda` environment called `poli__protein` with the relevant dependencies.
+```
+
+:::
+
+::::

docs/protein-optimization/using_poli/objective_repository/foldx_stability.md

@@ -1,3 +1,94 @@
-# Protein stability using `foldx`
+# Protein stability (using `foldx`)
+![Type of objective function: discrete](https://img.shields.io/badge/Type-discrete_inputs-blue)
+![Environment to run this objective function: poli protein](https://img.shields.io/badge/Environment-poli____protein-teal
+)
 
-[TODO: write]
+## About
+
+This objective function returns the stability (i.e. negative energy) using `foldx`.
+
+## Prerequisites
+
+- Have `foldx` installed, and available in your home directory. We expect the following files to be there:
+  - `~/foldx/foldx`: the binary. You might need to rename it.
+  - `~/foldx/rotabase.txt`: a text file necessary for `foldx` to run.
+- A `wildtype_pdb_file`: a (repaired) pdb file of the wildtype.
+
+## How to run
+
+You can either run this objective function in your current environment (assuming that you have the correct dependencies installed), or you can run it in an isolated environment.
+
+::::{tab-set}
+
+:::{tab-item} In current environment
+
+You will have to install the following two dependencies:
+
+```bash
+pip install biopython python-levenshtein
+```
+
+Then run
+
+```python
+from pathlib import Path
+
+import numpy as np
+
+from poli import objective_factory
+
+# The path to your wildtype pdb
+wildtype_pdb_file = Path("path/to/wildtype.pdb")
+
+# How to create
+problem_info, f, x0, y0, run_info = objective_factory.create(
+    name="foldx_stability",
+    wildtype_pdb_file=wildtype_pdb_file
+)
+
+# Example input:
+print(x0)
+
+# Querying:
+print(y0)  # The stability of your wildtype
+```
+
+You could also pass an `alphabet: Dict[str, int]` to the create method. By default, [we use this encoding](https://github.com/MachineLearningLifeScience/poli/blob/44cad2a5c95f209aeb24d4893d162b3359ca91a3/src/poli/core/util/proteins/defaults.py#L1).
+
+:::
+
+:::{tab-item} In isolation
+
+If you want us to handle dependencies, run
+
+```python
+from pathlib import Path
+
+import numpy as np
+
+from poli import objective_factory
+
+# The path to your wildtype pdb
+wildtype_pdb_file = Path("path/to/wildtype.pdb")
+
+# How to create
+problem_info, f, x0, y0, run_info = objective_factory.create(
+    name="foldx_stability",
+    wildtype_pdb_file=wildtype_pdb_file,
+    force_register=True,
+)
+
+# Example input:
+print(x0)
+
+# Querying:
+print(y0)  # The stability of your wildtype
+```
+
+```{warning}
+Registering the objective function in this way will create a `conda` environment called `poli__protein` with the relevant dependencies.
+```
+
+:::
+
+::::