diff --git a/docs/source/cli_arguments.rst b/docs/source/cli_arguments.rst index 7dca8e7..131a59c 100644 --- a/docs/source/cli_arguments.rst +++ b/docs/source/cli_arguments.rst @@ -1,6 +1,22 @@ -CLI Arguments -============= +Command Line Options +==================== +The various command line options for running HBDesigner are described in detail below. For some general advice for how to use these options to maximize the success rate of HBDesigner, see the `Usage Advice`_ section at the end of this page. .. argparse:: :module: hbdesigner.inference.parsers - :func: get_hbdes_parser \ No newline at end of file + :func: get_hbdes_parser + +Usage Advice +------------ + +At larger ``--n_res``, packing is harder, so you will get fewer good designs per ``--n_samples``. This means you might want to increase ``--n_samples`` when increasing ``--n_res``. Here is a good place to start: + +.. code-block:: bash + + --n_res=2, --n_samples=100 + --n_res=3, --n_samples=200 + --n_res=4, --n_samples=500 + --n_res=5, --n_samples=500 + --n_res=6, --n_samples=1000 + +Smaller amino acids, especially SER and THR, have notably higher success rates. This means that, if you don't care what amino acids are in your network, you can get higher success rates using ``--guide_seq SXX``, ``--guide_seq TXX``, etc. \ No newline at end of file diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst new file mode 100644 index 0000000..6ce31a9 --- /dev/null +++ b/docs/source/examples/index.rst @@ -0,0 +1,71 @@ +HBDesigner Examples +=================== + +Several examples of how to use HBDesigner have been included in this repository, you can find them in the ``examples`` folder. Descriptions of these examples can be found below. + +Running the Examples +-------------------- + +Input structures +^^^^^^^^^^^^^^^^ + +HBDesigner takes a ``.pdb`` file as its primary input. It can have a sequence and/or sidechains on it, but they will be removed to create a PolyGLY backbone before use. + +If you want to design intra-chain or monomer networks, you should include only the chain you wish to design. + +If you want to design inter-chain or interface networks, you should include only the chains forming the interface you wish to design. + +Output files +^^^^^^^^^^^^ +HBDesigner produces two kinds of output: +- PDB files named "HBDes_rank_N.pdb", where N is the rank calculated by HBDesigner. Lower ranks are "better". +- A CSV file named "HBDes_stats.csv", which includes all of the scores and residue IDs of all designed networks. This includes networks that passed the scoring filters but didn't make the ``--top_k`` cutoff. + +HBDesigner will only output networks that pass all of its scoring filters and meet its definition of 'successful'. A 'successful' design meets the following criteria: + +- All network residues must be engaged in at least 1 sidechain-sidechain H-bond +- All network residues must form a single contiguous network +- The network passes the minimum thresholds for saturation, BUHs, BUPHs, etc. (see :doc:`../cli_arguments` for how to set these thresholds) + +After filtering, HBDesigner will rank the remaining networks using various score terms, with the following priority: + +1. ``buried_unsat_Hpol`` (buried unsatisfied polar H atoms): the fewer the better. +2. ``saturation``: the fraction of total h-bonding "capacity" that is being used across all network residue sc atoms: the higher the better. +3. HBond Score (``HB_Score_full``): the change in Rosetta energy provided by the designed network, calculated against an identical PolyG backbone: the lower (more negative) the better. + +This setup has a few implications: + +- It is possible for HBDesigner to return 0 networks, if given a hard enough task and/or few enough tries at it. If this happens, try increasing ``--n_samples``. + +- If HBDesigner finds more networks than ``--top_k`` allows, it will only return the ``--top_k`` "best" according to the ranking scheme. If you want more outputs, increase ``--top_k``. + +.. important:: + It is assumed that you will be running these examples in their respective subdirectories in the ``examples`` folder. The examples use relative paths to access the necessary files, so if you run them from a different location you will need to adjust the paths accordingly. + + These examples also assume that you have access to 8 CPU nodes to use as 'workers' for HBDesigner. If you have access to fewer, then you will need to adjust the values of ``n_workers`` in the shell scripts before running. + +If you have installed HBDesigner using uv, conda, mamba, or pip you can run these examples via + +.. code-block:: bash + + ./.sh + +(Though you will need to make sure you have the appropriate environment activated if you installed via conda/mamba/uv.) + +However, if you installed HBDesigner via pixi, you will need to run the examples via + +.. code-block:: bash + + pixi run --manifest-path=/pyproject.toml .sh + +You can see a full example of this in the ``monomer`` directory. + +.. toctree:: + :maxdepth: 1 + :caption: Explanation of the Examples: + + monomer.md + interface_design.md + postprocessing.md + +For more information about the options used in these examples, see :doc:`../cli_arguments`. \ No newline at end of file diff --git a/docs/source/examples/interface_design.md b/docs/source/examples/interface_design.md new file mode 100644 index 0000000..3eb67e9 --- /dev/null +++ b/docs/source/examples/interface_design.md @@ -0,0 +1,45 @@ +# Interface Design + +If provided with an interface, HBDesigner will automatically try to design a network across it. This can be used for either one-sided or two-sided interface design. The one-sided case requires one or more "anchor residue(s)" on the target strand(s). + +## Symmetric Design +Once more than one chain is involved in the hydrogen bonding network, symmetry can be taken into account. HBDesigner has limited support for symmetric design across protein-protein interfaces. To do this, we offer two complementary approaches: "lazy" and "strict" symmetry: + +```{warning} +Symmetric design is still experimental and has not been validated when used in combination with conditioning features. +``` + +### Lazy symmetry +In a 'lazy' symmetry scenario, HBDesigner designs asymmetric networks then attempts to symmetrize them across any symmetric chains. This is best for when the network itself doesn't necessarily need to be symmetric, but the sequence symmetry needs to be preserved across the interface. + +### Strict symmetry +For 'strict' symmetry, HBDesigner explicitly designs symmetric networks where all symmetric residues must contribute to the network and must interact with the symmetric copies of themselves. + +```{note} +For strict symmetry to work well the designable residues must be oriented very close to the plane of symmetry. +``` + +For a system that is N-wise symmetric, the provided value of `n_res` must be divisible by N. For example, for a homotrimer the valid choices for `n_res` are 3, 6, etc. + +--- +## Examples + +Examples of using HBDesigner to design hydrogen bonding networks for protein interfaces can be found in examples/interface. The following examples use the 1YRK PDB file located in the `interface` folder. You can find its entry on the RCSB [here](https://www.rcsb.org/structure/1YRK). This structure is composed of two chains and a ligand. Chain A is a protein kinase while chain B is a 13-residue peptide. The ligand is acetic acid. + +- One-sided: `interface/one_sided` + - Residue B5 (serine) is selected as an anchor residue - this residue will be part of any designed hydrogen bonding networks + - Chain B is omitted - HBDesigner cannot choose residues from chain B in this calculation, except for those specified by `anchor_res` +- Two-sided: `interface/two_sided` + - This example does not have any special options. HBDesigner recognizes that multiple chains are provided, and will automatically design a network between them. + +The following examples use PDB files that are located in their individual folders: +- Lazy Symmetry: `interface/symm_lazy` + - System of interest: [10GS](https://www.rcsb.org/structure/10GS), a dimer with C2 symmetry + - The only extra option that needs to be provided for 'lazy' symmetry is `symm_chains` which tells HBDesigner which chains should be symmetrized. +- Strict Symmetry: `interface/symm_strict` + - System of interest [5J0K](https://www.rcsb.org/structure/5J0K), a dimer with C2 symmetry - the provided structure has been cleaned + - The [Rosetta](https://github.com/RosettaCommons/rosetta) script, [`make_symmdef_file.pl`](https://github.com/RosettaCommons/rosetta/blob/main/source/src/apps/public/symmetry/make_symmdef_file.pl) was used to create the provided `.symm` file. + ```{important} + The use of Rosetta requires a [license](https://github.com/RosettaCommons/rosetta/blob/main/LICENSE.md) + ``` + - The addition of the `symm_chains` argument is required to tell HBDesigner which chains should be symmetrized. \ No newline at end of file diff --git a/docs/source/examples/monomer.md b/docs/source/examples/monomer.md new file mode 100644 index 0000000..85f57b3 --- /dev/null +++ b/docs/source/examples/monomer.md @@ -0,0 +1,59 @@ +# Monomer Design +The types of examples in `monomer` include: +- [Unconditional Monomer Design](#unconditional_monomer_design) +- [Sequence Conditioning](#sequence_conditioning) +- [Virtual Guide Atom Conditioning](#virtual_guide_atom_conditioning) +- [Omitting Amino Acids](#omitting_amino_acids) +- [Pixi Example](#pixi_example) + +All of these examples use the provided 1PGA PDB file. You can find out more about this structure [here](https://www.rcsb.org/structure/1PGA). + +(unconditional_monomer_design)= +## Unconditional Monomer Design +You will want to perform unconditional monomer design if you: +- want to create networks on a monomer +- do not have specific amino acids that need to be used to create these networks + +Unconditional monomer design only requires: +- `--pdb` (a PDB file of your input structure) +- `--n_res` (The number of residues in the completed network(s)) +- `--n_samples` (The number of samples to generate before packing and scoring) +- `--n_workers` (The number of CPUs that can be used for packing) + +You can run this example by `cd`-ing into `examples/monomer/unconditional` and running the shell script located there. + +For the requested 200 samples, it is typical for only ~10 to 'succeed' based on the packing and scoring procedures. Each of the generated designs should have 3 non-glycine residues, as was specified by `n_res`. + +(sequence_conditioning)= +## Sequence Conditioning +Sequence conditioning can be used to specify which amino acid(s) are used to form the hydrogen bonding network, including partial or ambiguous (e.g., "Either ASN or GLN") specifications. This is specified with a comma-separated list of amino acid groups. + +Aside from the arguments discussed above, the only additional argument required for conditional sequence design is `guide_seq`. This option specifies what amino acids can be used when designing the hydrogen bonding network. + +Three sequence conditioning examples are provided: +- `monomer/sequence_conditioning_full`: + `S,N,T` is passed to `guide_seq` resulting in designs that use those three amino acids specifically. +- `monomer/sequence_conditioning_partial`: + `X,T,X` is passed to `guide_seq` resulting in designs that have at least one threonine residue in each design. There are no restrictions on what the other two residues can be. +- `monomer/sequence_conditioning_ambiguous`: + `S,N|Q,T` is passed to `guide_seq` resulting in designs that have S, N **or** Q, and T in any order. + +(virtual_guide_atom_conditioning)= +## Virtual Guide Atom Conditioning +Guide atoms can be used to specify an approximate location for the hydrogen bonding network. Given a list of residues in the input structure, HBDesigner will place a 'guide atom' in the centroid of the C-betas of these residues. + +You can find an example of this in `monomer/guide_atom_conditioning`. The only additional argument needed, besides those discussed in the [Unconditional Monomer Design section](#unconditional_monomer_design), is `guide_res`. + +(omitting_amino_acids)= +## Omitting Amino Acids +The `monomer/omit_AA` example shows how to omit amino acids from hydrogen bonding networks designed by HBDesigner. The addition of the argument `omit-AA` will prevent any of the amino acids specified from the user from being included in the designs. + +(pixi_example)= +## Pixi Example +An example has been included here see how to run HBDesigner with [Pixi](https://pixi.prefix.dev/latest/). The same command line arguments can be used but now +```bash +pixi run --manifest-path= +``` +will need to be added before the rest of the command. + +This is only relevant when pixi was used to install HBDesigner. \ No newline at end of file diff --git a/docs/source/examples/postprocessing.md b/docs/source/examples/postprocessing.md new file mode 100644 index 0000000..ae36a6b --- /dev/null +++ b/docs/source/examples/postprocessing.md @@ -0,0 +1,8 @@ +# Postprocessing +We provide a helper script called `merge_networks.py` that attempts to naively combine output networks by checking for sequence overlap and clashes. This is NOT an exhaustive sweep, so it will not return ALL possible networks, but a subset from a rapid sampling procedure. For example usage, see `examples/postprocessing/run_merge.sh`. + +When doing one-sided interface design, we may want to graft our output network back onto the wildtype target for downstream modeling. We provide a helper script called `graft_seq.py` to do this. For example usage, see `examples/postprocessing/run_graft.sh` + +The most common use for HBDesigner outputs is as input for traditional sequence design. To do this, we use LigandMPNN to design the remaining sequence, keeping the HBDesigner network residues fixed. For an example of this, see `examples/postprocessing/run_mpnn.sh`. + +These scripts pull from the resources in the other example directories. \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 0d603dc..872a78d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -6,15 +6,17 @@ HBDesigner Documentation ======================== -Welcome to the official documentation for [HBDesigner](https://github.com/Kuhlman-Lab/HBDesigner). +Welcome to the official documentation for `HBDesigner `_. HBDesigner is a machine learning tool that designs highly-connected hydrogen bonding networks based on user-defined constraints and an input protein backbone. -Make sure to read through the [HBDesigner README](https://github.com/Kuhlman-Lab/HBDesigner/blob/main/README.md) for an overview of the tool, its features, and how to get started. +Make sure to read through the `HBDesigner README `_ for an overview of the tool, its features, and how to get started. .. toctree:: :maxdepth: 1 :caption: Contents: cli_arguments.rst - installation_guide.md \ No newline at end of file + installation_guide.md + models.md + examples/index.rst \ No newline at end of file diff --git a/docs/source/installation_guide.md b/docs/source/installation_guide.md index 6c39b84..05e0b64 100644 --- a/docs/source/installation_guide.md +++ b/docs/source/installation_guide.md @@ -1,40 +1,13 @@ -# Installation Guide +# Installation Issues -## Contents +See the [README](https://github.com/Kuhlman-Lab/HBDesigner/blob/main/README.md) for information about the various ways to install HBDesigner. - ---- -## Installation with Conda - -### GPU - -### CPU - ---- -## Installation with Mamba - -### GPU - -### CPU - ---- -## Installation with uv - -### GPU - -### CPU - ---- -## Installation with pixi - -### GPU -### CPU +These installation methods assume a system that is running CUDA 12.8 or greater, but have options for CUDA 12.4. If you are running on a system that has a version of CUDA below 12.4 or a CUDA version too recent to be compatible with CUDA 12.8, continue reading for advice for how to adapt the environment files for your system. (cuda_version)= ## Adjusting for the CUDA version available on your system -The various installation files (`env.yaml`, `pyproject.toml`) were created for systems running CUDA 12.8. -If your system has a more recent version of CUDA (e.g. 13.0) then these installation files may still work correctly. See the [Common Issues](#common-issues) section below if you are having trouble. +If your system has a more recent version of CUDA (e.g. 13.0) then these installation files will likely still work correctly. See the [Common Issues](#common-issues) section below if you are having trouble. If your system has an older version of CUDA, then there are several dependencies you may need to change: - The PyTorch source: @@ -48,7 +21,7 @@ If your system has an older version of CUDA, then there are several dependencies --extra-index-url https://download.pytorch.org/whl/cu124 --find-links https://data.pyg.org/whl/torch-2.6.0+cu124.html ``` - You can find the correct link to use [here](https://pytorch.org/get-started/previous-versions/). + You can find the correct link to use for your torch/CUDA combination [here](https://pytorch.org/get-started/previous-versions/). - The torch version will need to be changed: ```bash torch==2.8.0+cu128 @@ -77,15 +50,14 @@ If your system has an older version of CUDA, then there are several dependencies - torch-cluster - torch-scatter - You may need to find a version of triton that works with your PyTorch/CUDA combination, or you might be able to remove the version requirement from the triton listing. For CUDA 12.4, `triton==3.2.0` works. -- --- (common-issues)= ## Common Issues ### `ImportError: /lib64/libm.so.6: version `GLIBC_2.27' not found` -If you are seeing this, it is most likely because your CUDA version and the YAML or TOML file you are using to install the dependencies do not match. See [the previous section](#cuda_version) to modify your file for the CUDA version you have access to. +If you are seeing this, it is most likely because your CUDA version and CUDA version the HBDesigner dependencies are expecting do not match. See [the previous section](#cuda_version) to modify your file for the CUDA version you have access to. ### `Segmentation Fault (core dumped)` -This can be caused by a variety of different things, including a CUDA version mismatch. If you haven't already modified your TOML or YAML file, see [the previous section](#cuda_version). -If you have updated these files, try adding the `dev` requirements to you installation instructions. +This can be caused by a variety of different things, including a CUDA version mismatch. If you haven't already modified your environment file to customize it for your particular system, see [the previous section](#cuda_version). +If you have updated these files, try adding the `dev` requirements to your installation. diff --git a/docs/source/models.md b/docs/source/models.md new file mode 100644 index 0000000..67338d6 --- /dev/null +++ b/docs/source/models.md @@ -0,0 +1,10 @@ +# Model Weights + +There are several checkpoint files in the `model_weights` directory that can be used with HBDesigner or you can supply your own. You can use the `design_model`, `design_model_ckpt`, or `packing_model_ckpt` command line options to specify which checkpoint file you want to use for the various operations HBDesigner performs. + +Here we will briefly describe the various checkpoint files and their uses. + +- `design_020.pt`: Default design checkpoint. It is the high-noise option for the two provided design models. It is best for sampling small networks (2-3 residues) and can give greater sample diversity. +- `design_002.pt`: Low-noise model and is best for large (4+ residues) networks and is more precise than `design_020.pt`. +- `pack.pt`: Provided model for packing calculations. +- `pippack_model_x_ckpt.pt`: These three models were used for benchmarking purposes and are not recommended for general use. \ No newline at end of file diff --git a/examples/README.md b/examples/README.md index 1a20bb1..9e40782 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,181 +1,5 @@ # Quick start: HBDesigner examples for different design scenarios -## Unconditional Monomer Design -This is the simplest possible design case - we want networks on a monomer or interface, but we don't care where or what amino acids are used. +Within this directory there are several examples for different use cases of HBDesigner. All the required files are present in these directories. It is assumed that the `run_hbdes.sh` will be run from their individual directories - the paths in these files wil need to be changed if otherwise. -- Unconditional monomer: `monomer/unconditional` - -## Interface Design -If provided with an interface, HBDesigner will automatically try to design a network across it. This can be used for either one-sided or two-sided interface design. The one-sided case requires one or more "anchor residue(s)" on the target strand(s). - -- Two-sided: `interface/two_sided` -- One-sided: `interface/one_sided` - -## Symmetric Design: -HBDesigner has limited support for symmetric design across protein-protein interfaces. To do this, we offer two complementary approaches: "lazy" and "strict" symmetry. "Lazy" symmetry designs asymmetric networks, then tries to symmetrize them across any symmetric chains. This is useful for cases where you don't care if your network itself is symmetric, just that you preserve sequence symmetry across the interface. Lazy symmetry can be run on Cn symmetric assemblies for networks of any size. "Strict" symmetry explicitly designs symmetric networks where all symmetric residues must contribute to the network and interact with symmetric copies of themselves. This is difficult to satisfy unless the designable residues are oriented very close to the plane of symmetry. Strict symmetry for N-wise symmetry must be given a `--n_res` that is divisible by N (e.g., if designing a homotrimer, `--n_res` can be `3,6,etc.`). Symmetric design is still experimental and has not been validated when used in combination with conditioning features. - -- Lazy: `interface/symm_lazy` -- Strict: `interface/symm_strict` - -## Sequence Conditioning -We can use sequence conditioning to specify which amino acid(s) are used, including partial or ambiguous (e.g., "Either ASN or GLN") specifications. This is specified with a comma-separated list of amino acid groups, as shown below. - -- Full sequence conditioning (`S,N,T`): `monomer/sequence_conditioning_full` -- Partial sequence conditioning (`X,N,X`): `monomer/sequence_conditioning_partial` -- Ambiguous sequence conditioning (`S,N|Q,T`): `monomer/sequence_conditioning_ambiguous` - -## Virtual Guide Atom Conditioning -We can use virtual guide atom conditioning to specify an approximate location for our network. For convenience, users can provide a list of residues, and HBDesigner will use the centroid of their C-betas as the guide atom. - -- Virtual guide atom conditioning: `monomer/guide_atom_conditioning` - -# More details: HBDesigner inference settings - -## Input and Output files: -HBDesigner takes a `.pdb` file as its primary input. It can have a sequence and/or sidechains on it, but they will be removed to create a PolyGLY backbone before use. -- If you want to design intra-chain or monomer networks, you should include only the chain you wish to design. -- If you want to design inter-chain or interface networks, you should include only the chains forming the interface you wish to design. - -HBDesigner produces two kinds of output: -- PDB files named "HBDes_rank_N.pdb", where N is the rank calculated by HBDesigner. Lower ranks are "better". -- A CSV file named "HBDes_stats.csv", which includes all of the scores and residue IDs of all designed networks. This includes networks that passed the scoring filters but didn't make the `--top_k` cutoff. - -HBDesigner will only output networks that pass all of its scoring filters and meet its definition of 'successful'. A 'successful' design meets the following criteria: -- All network residues must be engaged in at least 1 sidechain-sidechain H-bond -- All network residues must form a single contiguous network -- The network passes the minimum thresholds for saturation, BUHs, BUPHs, etc. (see `Scoring parameters` below) - -After filtering, HBDesigner will rank the remaining networks using various score terms, with the following priority: -1) buried_unsat_Hpol (buried unsatisfied polar H atoms): the fewer the better. -2) saturation: the fraction of total h-bonding "capacity" that is being used across all network residue sc atoms: the higher the better. -3) HBond Score (HB_Score_full): the change in Rosetta energy provided by the designed network, calculated against an identical PolyG backbone: the lower (more negative) the better. - -This setup has a few implications: -- It is possible for HBDesigner to return 0 networks, if given a hard enough task and/or few enough tries at it. If this happens, try increasing `--n_samples`. -- If HBDesigner finds more networks than `--top_k` allows, it will only return the `--top_k` "best" according to the ranking scheme. If you want more outputs, increase `--top_k`. - -## Basic input parameters: -These are the minimal input params that you should consider setting for any design run. They have a large impact on performance and runtime. -``` -# Path to input PDB file. Needs to be specified for each run. ---pdb /path/to/1ABC.pdb - -# Number of residues you want in your completed network(s). HBDesigner is trained to produce networks of 2-6 residues. ---n_res 3 - -# Path to output directory to save results. If left blank, HBDesigner will use the current working directory. ---out_dir /path/to/output/ - -# Number of CPUs the script can use for packing. Good values are 8-24, higher values will run faster, up to a point of saturation. -# This should match the --cpus-per-task param if running as a SLURM job. ---n_workers 16 - -# Number of unique samples to generate before packing/scoring. Good values are 100-500, but higher values are useful if initial runs fail to find networks. ---n_samples 200 - -# Number of top (best scoring, see below section for details) designs to save. Good values are 5-25, depending on your use case. ---top_k 5 - -# If needed, model checkpoint paths can be specified as follows: ---design_model_ckpt /path/to/model_weights/design_020.pt ---packing_model_ckpt /path/to/model_weights/pack.pt - -# If running on a CPU include ---cpu -``` - -## Usage Advice -At larger `--n_res`, packing is harder, so you will get fewer good designs per `--n_samples`. This means you might want to increase `--n_samples` when increasing `--n_res`. Here is a good place to start: -``` ---n_res=2, --n_samples=100 ---n_res=3, --n_samples=200 ---n_res=4, --n_samples=500 ---n_res=5, --n_samples=500 ---n_res=6, --n_samples=1000 -``` -Smaller amino acids, especially SER and THR, have notably higher success rates. This means that, if you don't care what amino acids are in your network, you can get higher success rates using --guide_seq SXX, --guide_seq TXX, etc. - -## Postprocessing -We provide a helper script called `merge_networks.py` that attempts to naively combine output networks by checking for sequence overlap and clashes. This is NOT an exhaustive sweep, so it will not return ALL possible networks, but a subset from a rapid sampling procedure. For example usage, see `examples/postprocessing/run_merge.sh`. - -When doing one-sided interface design, we may want to graft our output network back onto the wildtype target for downstream modeling. We provide a helper script called `graft_seq.py` to do this. For example usage, see `examples/postprocessing/run_graft.sh` - -The most common use for HBDesigner outputs is as input for traditional sequence design. To do this, we use LigandMPNN to design the remaining sequence, keeping the HBDesigner network residues fixed. For an example of this, see `examples/postprocessing/run_mpnn.sh`. - -### Conditioning parameters: -These are extra (optional) params you can use to help guide the model toward making specific types of networks more often. -``` -# Sequence conditioning tells the model which amino acid types to include in the network. -# Use 1-letter abbreviations, with "X" representing "any polar". -# Note: the number of residues listed must match --n_res. ---guide_seq S,T,H # this means "make 3-res networks with a SER, a THR, and a HIS." ---guide_seq H,X # this means "make 2-res networks with a HIS and ANY polar." ---guide_seq H,H,X # this means "make 3-res networks with 2x HIS and 1x ANY polar." ---guide_seq X,X # this means "make 2-res networks with 2x ANY polar." ---guide_seq S|T,H # this means "make 2-res networks with (either a SER or a THR) and a HIS. - -# Virtual guide atom conditioning tells the model where to build its networks. -# To use this, provide a list of residues which will be used to triangulate the virtual guide atom position. -# If enabled, the "guide atom" will be represented as a virtual atom (atomid: V1, resid: ORI) in the output .pdb files. ---guide_res A45,A49,B34 - -# Enable a hard distance cutoff to prevent the model from straying too far from the guide atom. -# This is usually overkill for most cases, but can be useful if you're really particular about where the network should be placed. ---guide_radius 10. # this disables design for any res with Cb >10A from the guide atom. - -# Provide 'anchor' residue(s) around which to design a network. ---anchor_res B5 # Design networks using the residue B5 as an anchor, so all networks must contain this residue. -``` - -### Other sampling parameters: -These are useful for enforcing sufficient burial and/or network sequence diversity. -``` -# Enable a hard burial cutoff to prevent the model from using surface residues. ---min_burial 4.0 # this disables design for any res with <4.0 weighted sidechain neighbors (too solvent-exposed) - -# Select only networks with a certain number of core residues. ---min_core_res 1 # this rejects any networks with <1 core residue present - -# Temperature range to use for sampling procedure. Good values are 0.1 to 1.0. -# Lower values will adhere to conditioning better but will be less diverse, so generation may take longer. ---T_range 0.3 1.0 - -# Set a fixed seed for random number generation. Off by default. -# Rosetta energy values may still vary slightly, but model sampling should be consistent. ---seed 42 -``` - -### Scoring parameters: -These are useful if you have very specific scoring criteria you want to enforce in your output networks (saturation, ) -``` -# Set max number of buried unsatisfied heavy polar atoms allowed. Lower is more selective. ---max_BUNs 1 - -# Set max number of buried unsatisfied polar heavy atoms allowed. Lower is more selective. ---max_BUPHs 1 - -# Set min saturation level allowed. Higher is more selective. ---min_sat 0.7 - -# Set maximum Rosetta energy considered a successful hydrogen bond. Lower is more selective. ---max_hb_energy -0.5 -``` - -### Symmetry and assembly parameters: -``` -# Select certain chains for design. HBDesigner will run on these chains, then paste them back in to the original assembly. -# By default, HBDesigner will run on all chains provided. If an interface is present, it will focus on interface networks. ---sel_chains A,B - -# Symmetrize output networks after design. Useful for designing homooligomer interfaces. ---symm_chains A,B # Tie chains A and B together. - -# Symmetry definition file (from Rosetta), required for 'strict' symmetry (see example above). ---symm_file 5JOK.symm - -# Turn off design for one or more chains. ---omit_chains B,C # Turn off chain B and C design options. - -# Omit certain amino acids ---omit_AA K,R # don't use LYS or ARG in any networks. -``` +For detailed information about each example see the[HBDesigner Examples documentation](https://rosettacommons.github.io/HBDesigner/examples/index.html). For more information on the HBDesigner command line options see the [Command Line Options](https://rosettacommons.github.io/HBDesigner/cli_arguments.html). \ No newline at end of file diff --git a/examples/interface/one_sided/run_hbdes.sh b/examples/interface/one_sided/run_hbdes.sh old mode 100644 new mode 100755 diff --git a/examples/interface/symm_lazy/run_hbdes.sh b/examples/interface/symm_lazy/run_hbdes.sh old mode 100644 new mode 100755 diff --git a/examples/interface/symm_strict/run_hbdes.sh b/examples/interface/symm_strict/run_hbdes.sh old mode 100644 new mode 100755 diff --git a/examples/interface/two_sided/run_hbdes.sh b/examples/interface/two_sided/run_hbdes.sh old mode 100644 new mode 100755 diff --git a/examples/monomer/guide_atom_conditioning/run_hbdes.sh b/examples/monomer/guide_atom_conditioning/run_hbdes.sh old mode 100644 new mode 100755 diff --git a/examples/monomer/omit_AA/run_hbdes.sh b/examples/monomer/omit_AA/run_hbdes.sh old mode 100644 new mode 100755 diff --git a/examples/monomer/run_with_pixi/run_hbdes.sh b/examples/monomer/run_with_pixi/run_hbdes.sh old mode 100644 new mode 100755 index 8e8faf2..6975e83 --- a/examples/monomer/run_with_pixi/run_hbdes.sh +++ b/examples/monomer/run_with_pixi/run_hbdes.sh @@ -1,17 +1,5 @@ #!/bin/bash -#SBATCH -J run_hbdesigner -#SBATCH -p kuhlab -#SBATCH -N 1 -#SBATCH -n 1 -#SBATCH --cpus-per-task=16 -#SBATCH --mem=32g -#SBATCH -t 00:10:00 -#SBATCH --qos gpu_access -#SBATCH --gres=gpu:1 - -source ~/.bashrc - pixi run --manifest-path=../../../pyproject.toml run_hbdesigner \ --pdb ../1PGA.pdb \ --n_workers 8 \ diff --git a/examples/monomer/sequence_conditioning_ambiguous/run_hbdes.sh b/examples/monomer/sequence_conditioning_ambiguous/run_hbdes.sh old mode 100644 new mode 100755 diff --git a/examples/monomer/sequence_conditioning_full/run_hbdes.sh b/examples/monomer/sequence_conditioning_full/run_hbdes.sh old mode 100644 new mode 100755 diff --git a/examples/monomer/sequence_conditioning_partial/run_hbdes.sh b/examples/monomer/sequence_conditioning_partial/run_hbdes.sh old mode 100644 new mode 100755 diff --git a/examples/monomer/unconditional/run_hbdes.sh b/examples/monomer/unconditional/run_hbdes.sh old mode 100644 new mode 100755 diff --git a/examples/postprocessing/run_graft.sh b/examples/postprocessing/run_graft.sh old mode 100644 new mode 100755 diff --git a/examples/postprocessing/run_merge.sh b/examples/postprocessing/run_merge.sh old mode 100644 new mode 100755 diff --git a/examples/postprocessing/run_mpnn.sh b/examples/postprocessing/run_mpnn.sh old mode 100644 new mode 100755 diff --git a/hbdesigner/inference/parsers.py b/hbdesigner/inference/parsers.py index e14b0b8..9ab167a 100644 --- a/hbdesigner/inference/parsers.py +++ b/hbdesigner/inference/parsers.py @@ -32,12 +32,13 @@ def convert_arg_line_to_args(self, arg_line: str) -> Sequence[str]: def get_hbdes_parser() -> FileArgumentParser: parser = FileArgumentParser( - description="Parser for HBDesigner inference config files." + prog='run_hbdesigner', + description="Required and optional arguments for running HBDesigner. For help on individual arguments, run with the --help flag or refer to the documentation." ) # Filepaths parser.add_argument( - "--pdb", type=str, required=True, help="Input PDB file to process." + "--pdb", type=str, required=True, help="Relative file path to and name of the PDB file to process. Example: --pdb /path/to/1ABC.pdb" ) parser.add_argument( "--design_model", @@ -50,14 +51,14 @@ def get_hbdes_parser() -> FileArgumentParser: parser.add_argument( "--cpu", action="store_true", - help="Run inference on CPU by loading CPU-specific YAML configs.", + help="Run inference only on CPU by loading CPU-specific YAML configs. This is not recommended, as it will be much slower than running on GPU, but is available for users without access to a CUDA-enabled GPU. By default, the script will attempt to run on GPU if available.", ) parser.add_argument( "--out_dir", type=str, required=False, default=os.getcwd(), - help="Output directory for saving new files. Defaults to current working directory.", + help="Relative path to output directory for saving new files. Defaults to current working directory. If the given directory does not exist, it will be created. Output files include designed HBNet PDB files and a summary CSV file with design metrics for each network.", ) # Runtime optimization params parser.add_argument( @@ -65,7 +66,7 @@ def get_hbdes_parser() -> FileArgumentParser: type=int, required=False, default=1, - help="Workers for parallelization (packing). Default is 1. More workers will speed up predictions.", + help="Workers for parallelization during packing. Default is 1. More workers will speed up predictions, typical values are between 8 and 24. The number available will depend on the number of CPU nodes you have allocated.", ) # Sampling params parser.add_argument( @@ -73,14 +74,14 @@ def get_hbdes_parser() -> FileArgumentParser: type=int, required=False, default=100, - help="Number of unique samples to generate. Default is 100. More samples will increase diversity but also increase inference time.", + help="Number of unique samples to generate before packing/scoring. Default is 100, typical values are 100-500 but higher values can be used if initial runs fail to form networks. More samples will increase diversity but also increase inference time.", ) parser.add_argument( "--top_k", type=int, required=False, default=5, - help="How many unique samples to keep after ranking. Default is 5.", + help="How many unique samples to keep after ranking. Default is 5, typical values 5-25.", ) parser.add_argument( "--n_res", @@ -88,7 +89,7 @@ def get_hbdes_parser() -> FileArgumentParser: required=False, choices=range(2, 7), default=2, - help="Size of desired HBNet, in residues. Default is 2. Valid range is 2-6.", + help="Size of desired HBNet (the number of residues you want in your completed network(s)), in residues. Default is 2. Valid range is 2-6 (inclusive).", ) parser.add_argument( "--T_range", @@ -103,7 +104,7 @@ def get_hbdes_parser() -> FileArgumentParser: type=float, required=False, default=0.0, - help="Minimum burial for designable positions, as calculated by Rosetta's sidechain neighbor algorithm. Defaults to 0.0.", + help="Minimum burial for designable positions, as calculated by Rosetta's sidechain neighbor algorithm. Defaults to 0.0. See https://docs.rosettacommons.org/docs/latest/scripting_documentation/RosettaScripts/ResidueSelectors/ResidueSelectors#residueselectors_conformation-dependent-residue-selectors_layerselector or https://docs.rosettacommons.org/docs/latest/rosetta_basics/scoring/BuriedUnsatPenalty#algorithm for more information.", ) # Conditional information parser.add_argument( @@ -119,8 +120,8 @@ def get_hbdes_parser() -> FileArgumentParser: type=float, required=False, default=1e6, - help="Hard constraint on designable positions based on Cb distance " - "(Angstrom) from guide atom. Off by default.", + help="Hard distance constraint on designable positions based on Cb distance " + "(Angstrom) from guide atom. Off by default. Typically not necessary, but can be used to force location of designed network in difficult cases.", ) parser.add_argument( "--guide_seq", @@ -135,14 +136,14 @@ def get_hbdes_parser() -> FileArgumentParser: type=int, required=False, default=0, - help="Maximum buried unsats to allow in the network. Default is 0. Raising this will make filtering more permissive. ", + help="Maximum buried unsatisfied hydrogen atoms (BUNs, buried but not participating in a hydrogen bond) to allow in the network. Default is 0. Raising this will make filtering more permissive. ", ) parser.add_argument( "--max_BUPHs", type=int, required=False, default=5, - help="Maximum buried unsat polar Hs to allow in the network. Default is 5. Raising this will make filtering more permissive. ", + help="Maximum buried unsatisfied polar hydrogen atoms (BUPHs, buried but not participating in a hydrogen bond) to allow in the network. Default is 5. Raising this will make filtering more permissive. ", ) parser.add_argument( "--min_sat", @@ -156,7 +157,7 @@ def get_hbdes_parser() -> FileArgumentParser: type=float, required=False, default=0.0, - help="Maximum h-bond energy to allow in the network. Default is 0.0. Raising this will make filtering more permissive.", + help="Maximum hydrogen bond energy to allow in the network. Default is 0.0. Raising this will make filtering more permissive.", ) # Parsing params parser.add_argument( @@ -164,21 +165,21 @@ def get_hbdes_parser() -> FileArgumentParser: type=str, required=False, default=None, - help="Option to symmetrize output networks for convenience. Specify symmetric chains as 'A,B;C,D' etc.", + help="Option to symmetrize output networks after design for convenience. Specify symmetric chains as 'A,B;C,D' to symmetrize A with B and C with D. If you wanted to symmetrize all four together, the input would be 'A,B,C,D'. By default, no symmetrization will be performed. ", ) parser.add_argument( "--symm_file", type=str, required=False, default=None, - help="Symmetry file to use for symmetrization. Only used for strict symmetry." + help="Symmetry file (.symm) to use for symmetrization. Only used for strict symmetry. You can use Rosetta's make_symmdef_file.pl script to generate a .symm file from your PDB." ) parser.add_argument( "--sel_chains", required=False, type=str, default=None, - help="Option to select specific chain(s) to run HBDesigner on. Format: 'A,C'. Off by default (will use all chains).", + help="Option to select specific chain(s) to run HBDesigner on. Format: 'A,C'. Off by default (will use all chains). This option removes chains from the input file *before* they are passed to HBDesigner. HBDesigner will then graft chain B back in so the output still contains both chains.", ) parser.add_argument( "--min_core_res", @@ -192,7 +193,7 @@ def get_hbdes_parser() -> FileArgumentParser: required=False, type=str, default=None, - help="Comma-separated list of residues to use as anchor residues during design, in PDB chain/resnum format. Example: 'A12,B13,B49'." + help="Comma-separated list of residues to use as anchor residues during design, in PDB chain/resnum format. Example: 'A12,B13,B49'. All networks will contain the anchor residue(s)." ) parser.add_argument( "--max_hb_score", @@ -206,7 +207,7 @@ def get_hbdes_parser() -> FileArgumentParser: required=False, type=str, default=None, - help="Comma-separated list of chains to omit from design. Residues in these chains will not be eligible for use in designed networks. Example: A,C." + help="Comma-separated list of chains to omit from design. Residues in these chains will not be eligible for use in designed networks. Example: A,C. This option allows HBDesigner to see all of the chains (even the omitted ones) but prevents HBDesigner from using residues in the omitted chains to form the hydrogen bonding network. This is different from the --sel_chains option, which removes the omitted chains from the input file entirely (i.e. HBDesigner will not even see the omitted chains)." ) parser.add_argument( "--omit_AA", @@ -220,21 +221,21 @@ def get_hbdes_parser() -> FileArgumentParser: required=False, type=int, default=None, - help="Random seed for reproducible sampling. Default is no seed.", + help="Random seed for reproducible sampling. Default is no seed. Note that due to the use of parallelization and Rosetta scoring, results may not be exactly reproducible even with a set seed. Running with parallelization turned off ('n_workers' set to 0) will increase the likelihood of similar results between runs, but small energy changes will still be seen from Rosetta.", ) parser.add_argument( "--design_model_ckpt", required=False, type=str, default=None, - help="Path to custom design model checkpoint. If not specified, will use default checkpoint for the specified design model (e.g. 'design_020')." + help="Path to and file name of custom design model checkpoint. If not specified, will use default checkpoint for the specified design model (e.g. '/path/to/model_weights/design_020')." ) parser.add_argument( "--packing_model_ckpt", required=False, type=str, default=None, - help="Path to custom packing model checkpoint. If not specified, will use default checkpoint." + help="Path to and file name of custom packing model checkpoint. If not specified, will use default checkpoint." ) return parser diff --git a/hbdesigner/scripts/README.md b/hbdesigner/scripts/README.md index bbcafaf..00450d8 100644 --- a/hbdesigner/scripts/README.md +++ b/hbdesigner/scripts/README.md @@ -28,7 +28,7 @@ To preprocess the full dataset, run this for all 243 "chunks" of 1000 assemblies source ~/.bashrc mamba activate hbdesigner -python extract_hbnet.py \ +python extract_hbnets.py \ --data_dir /data/pdb_2021aug02/preprocessed \ --chunk $SLURM_ARRAY_TASK_ID \ --chunk_size 1000 @@ -58,7 +58,7 @@ python evaluate_hbdesigner.py \ --design_ckpt $design_ckpt # Packing-only evaluation -python evaluate_packer.py \ +python evaluate_hbpacker.py \ --pack_config $cfg \ --pack_ckpt $ckpt \ --num_workers 8 \