DISI - User contributions [en]

Dockopt (pydock3 script)

2024-05-06T06:53:20Z

Ianscottknight: /* Subcommand: run */

''dockopt'' allows the generation of many different docking configurations which are then evaluated & analyzed in parallel using a specified job scheduler (e.g. Slurm). If you are a Shoichet Lab user, please see a special section for you, below.

To use DOCK 3.8, you must first license it and install it.
[[DOCK 3.8:How to install pydock3]]

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable and declare default environmental variables:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/env.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/env.sh

== Subcommand: ''new'' ==

Prepare rec.pdb, xtal-lig.pdb as described in Bender, 2021. https://pubmed.ncbi.nlm.nih.gov/34561691/
Or download pre-preared sample files from dudez2022.docking.org.

Be sure that you are in the directory containing the required input files:
* ''rec.pdb'' or ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''actives.tgz''
* ''decoys.tgz''

Note the inclusion of ''actives.tgz'' and ''actives.tgz''. Each of these is a tarball of DB2 files, which may be optionally gzipped (with extension .db2.gz). Each tarball represents a binary class for the binary classification task that the docking model is trained on. The positive class (actives) contains the molecules that you want the docking model to preferentially assign ''favorable'' docking scores to. The negative class (decoys) contains the molecules that you want the docking model to preferentially assign ''unfavorable'' scores to. The most common strategy is to use a set of known ligands as the actives and a larger set of property-matched decoys for the decoys (a decoy-to-active ratio of 50:1 is standard), but other strategies are supported. For example, to create a docking model that preferentially assigns favorable scores to agonists over antagonists, a set of agonists can be used as the actives and a set of antagonists can be used for the decoys.

Therefore, you need to build the molecules yourself (see: https://tldr.docking.org/start/build3d38). Each tarball should contain only DB2 files. For example, if one has a directory ''actives/'' containing only DB2 files to use as the actives, then ''acitves.tgz'' should be created as follows:

cd actives/
tar -czf actives.tgz *.db2*

Similarly, for a directory ''decoys/'' containing only DB2 files to use as decoys, ''decoys.tgz'' should be created as follows:

cd decoys/
tar -czf decoys.tgz *.db2*

To create the file structure for your dockopt job, simply type

pydock3 dockopt - new

By default, the job directory is named ''dockopt_job''. To specify a different name, use the "--job_dir_name" flag. E.g.:

pydock3 dockopt - new --job_dir_name=dockopt_job_2

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''retrodock_jobs'': individual retrodock jobs for each docking configuration

The key difference between the working directories of ''blastermaster'' and ''dockopt'' is that the working directory of ''dockopt'' may contain multiple variants of the blaster files (suffixed by a number, e.g. "box_1"). These variant files are used to create the different docking configurations specified by the multi-valued entries of ''dockopt_config.yaml''. They are created efficiently, such that the same variant used in multiple docking configurations is not created more than once.

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the dockopt job.

* ''rec.pdb''
* ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb'' or ''rec.crg.pdb''. Either is required, but not both. If both are present, only ''rec.crg.pdb'' is used.
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''dockopt_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of dockopt.

'''Note:''' The ''dockopt_config.yaml'' file differs from the ''blastermaster_config.yaml'' file in that every parameter of the former may accept either a single value or a ''list of comma-separated values'', which indicates a pool of values to attempt for that parameter. Multiple such multi-valued parameters may be provided, and all unique resultant docking configurations will be attempted.

Single-valued YAML line format:

distance_to_surface: 1.0

Multi-valued YAML line format:

distance_to_surface: [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]

== Environmental variables ==

=== TMPDIR ===

Designate where temporary job files should be placed. E.g.:

export TMPDIR=/scratch

==== Note for UCSF researchers ====

On the Wynton cluster, ''/scratch'' only exists on development nodes (not log nodes). Therefore, we recommend running on development nodes (see: https://wynton.ucsf.edu/hpc/get-started/development-prototyping.html). E.g.:

ssh dev1
export TMPDIR=/scratch

If a log node must be used, then ''/wynton/scratch'' may be used:

ssh log1
export TMPDIR=/wynton/scratch

=== job scheduler environmental variables ===

In order for ''dockopt'' to know which scheduler it should use, please configure the following environmental variables according to which one of the job schedulers you have.

==== Slurm ====

E.g., on the UCSF Shoichet Lab Gimel cluster (on any node other than 'gimel' itself, such as 'gimel5'):

export SBATCH_EXEC=/usr/bin/sbatch
export SQUEUE_EXEC=/usr/bin/squeue

==== SGE ====

On most clusters using SGE the following should be correct:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/default/common/settings.sh

===== Note for UCSF researchers =====

The following is necessary on the UCSF Wynton cluster:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/wynton/common/settings.sh

== Subcommand: ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run ''dockopt'':
cd <JOB_DIR_NAME>
pydock3 dockopt - run <JOB_SCHEDULER_NAME> [--retrodock_job_timeout_minutes=None] [--retrodock_job_max_reattempts=0] [--extra_submission_cmd_params_str=None] [--export_decoys_mol2=False]

where <JOB_SCHEDULER_NAME> is one of:
* ''sge''
* ''slurm''

This will execute the many dockopt subroutines in sequence. Once this is done, the retrodock jobs for all created docking configurations are run in parallel via the scheduler. The state of the program will be printed to standard output as it runs.

Once the dockopt job is complete, the following files will be generated in the job directory:
* ''report.html'': contains (1) a histogram of the performance of all tested docking configurations compared against a distribution of the performance of a random classifier, so as to show whether the test docking configurations are significantly better than ones that can be produced by a random classifier. This is necessary due to the fact that many configurations are being tested. Hence, a Bonferroni correction is applied to the significance threshold, dividing p=0.01 by the number of tested configurations. (2) ROC, charge, and energy plots of the top docking configurations, comparing actives vs. decoys, (3) box plots of enrichment for every multi-valued config parameter, and (4) heatmaps of enrichment for every pair of multi-valued config parameters.
* ''results.csv'': parameter values, criterion values, and other information about each docking configuration.

In addition, some number of the best retrodock jobs will be copied to their own sub-directory ''best_retrodock_jobs/''.

Within each sub-directory of ''best_retrodock_jobs/'', there are:
* ''dockfiles/'': parameters files and ''INDOCK'' for given docking configuration
* ''output/'': contains:
** sub-directories ''actives/'' (containing ''OUTDOCK'' and ''test.mol2'' files) and ''decoys/'' (containing just ''OUTDOCK'')
* plot images (e.g., ''roc.png'')

'''Note:''' by default, a mol2 file is exported only for actives, not for decoys, in order to prevent disk space issues.

Dockopt (pydock3 script)

2024-05-05T23:20:31Z

Ianscottknight:

''dockopt'' allows the generation of many different docking configurations which are then evaluated & analyzed in parallel using a specified job scheduler (e.g. Slurm). If you are a Shoichet Lab user, please see a special section for you, below.

To use DOCK 3.8, you must first license it and install it.
[[DOCK 3.8:How to install pydock3]]

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable and declare default environmental variables:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/env.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/env.sh

== Subcommand: ''new'' ==

Prepare rec.pdb, xtal-lig.pdb as described in Bender, 2021. https://pubmed.ncbi.nlm.nih.gov/34561691/
Or download pre-preared sample files from dudez2022.docking.org.

Be sure that you are in the directory containing the required input files:
* ''rec.pdb'' or ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''actives.tgz''
* ''decoys.tgz''

Note the inclusion of ''actives.tgz'' and ''actives.tgz''. Each of these is a tarball of DB2 files, which may be optionally gzipped (with extension .db2.gz). Each tarball represents a binary class for the binary classification task that the docking model is trained on. The positive class (actives) contains the molecules that you want the docking model to preferentially assign ''favorable'' docking scores to. The negative class (decoys) contains the molecules that you want the docking model to preferentially assign ''unfavorable'' scores to. The most common strategy is to use a set of known ligands as the actives and a larger set of property-matched decoys for the decoys (a decoy-to-active ratio of 50:1 is standard), but other strategies are supported. For example, to create a docking model that preferentially assigns favorable scores to agonists over antagonists, a set of agonists can be used as the actives and a set of antagonists can be used for the decoys.

Therefore, you need to build the molecules yourself (see: https://tldr.docking.org/start/build3d38). Each tarball should contain only DB2 files. For example, if one has a directory ''actives/'' containing only DB2 files to use as the actives, then ''acitves.tgz'' should be created as follows:

cd actives/
tar -czf actives.tgz *.db2*

Similarly, for a directory ''decoys/'' containing only DB2 files to use as decoys, ''decoys.tgz'' should be created as follows:

cd decoys/
tar -czf decoys.tgz *.db2*

To create the file structure for your dockopt job, simply type

pydock3 dockopt - new

By default, the job directory is named ''dockopt_job''. To specify a different name, use the "--job_dir_name" flag. E.g.:

pydock3 dockopt - new --job_dir_name=dockopt_job_2

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''retrodock_jobs'': individual retrodock jobs for each docking configuration

The key difference between the working directories of ''blastermaster'' and ''dockopt'' is that the working directory of ''dockopt'' may contain multiple variants of the blaster files (suffixed by a number, e.g. "box_1"). These variant files are used to create the different docking configurations specified by the multi-valued entries of ''dockopt_config.yaml''. They are created efficiently, such that the same variant used in multiple docking configurations is not created more than once.

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the dockopt job.

* ''rec.pdb''
* ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb'' or ''rec.crg.pdb''. Either is required, but not both. If both are present, only ''rec.crg.pdb'' is used.
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''dockopt_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of dockopt.

'''Note:''' The ''dockopt_config.yaml'' file differs from the ''blastermaster_config.yaml'' file in that every parameter of the former may accept either a single value or a ''list of comma-separated values'', which indicates a pool of values to attempt for that parameter. Multiple such multi-valued parameters may be provided, and all unique resultant docking configurations will be attempted.

Single-valued YAML line format:

distance_to_surface: 1.0

Multi-valued YAML line format:

distance_to_surface: [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]

== Environmental variables ==

=== TMPDIR ===

Designate where temporary job files should be placed. E.g.:

export TMPDIR=/scratch

==== Note for UCSF researchers ====

On the Wynton cluster, ''/scratch'' only exists on development nodes (not log nodes). Therefore, we recommend running on development nodes (see: https://wynton.ucsf.edu/hpc/get-started/development-prototyping.html). E.g.:

ssh dev1
export TMPDIR=/scratch

If a log node must be used, then ''/wynton/scratch'' may be used:

ssh log1
export TMPDIR=/wynton/scratch

=== job scheduler environmental variables ===

In order for ''dockopt'' to know which scheduler it should use, please configure the following environmental variables according to which one of the job schedulers you have.

==== Slurm ====

E.g., on the UCSF Shoichet Lab Gimel cluster (on any node other than 'gimel' itself, such as 'gimel5'):

export SBATCH_EXEC=/usr/bin/sbatch
export SQUEUE_EXEC=/usr/bin/squeue

==== SGE ====

On most clusters using SGE the following should be correct:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/default/common/settings.sh

===== Note for UCSF researchers =====

The following is necessary on the UCSF Wynton cluster:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/wynton/common/settings.sh

== Subcommand: ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run ''dockopt'':
cd <JOB_DIR_NAME>
pydock3 dockopt - run <JOB_SCHEDULER_NAME> [--retrodock_job_timeout_minutes=None] [--retrodock_job_max_reattempts=0] [--extra_submission_cmd_params_str=None] [--export_negatives_mol2=False]

where <JOB_SCHEDULER_NAME> is one of:
* ''sge''
* ''slurm''

This will execute the many dockopt subroutines in sequence. Once this is done, the retrodock jobs for all created docking configurations are run in parallel via the scheduler. The state of the program will be printed to standard output as it runs.

Once the dockopt job is complete, the following files will be generated in the job directory:
* ''report.html'': contains (1) a histogram of the performance of all tested docking configurations compared against a distribution of the performance of a random classifier, so as to show whether the test docking configurations are significantly better than ones that can be produced by a random classifier. This is necessary due to the fact that many configurations are being tested. Hence, a Bonferroni correction is applied to the significance threshold, dividing p=0.01 by the number of tested configurations. (2) ROC, charge, and energy plots of the top docking configurations, comparing actives vs. decoys, (3) box plots of enrichment for every multi-valued config parameter, and (4) heatmaps of enrichment for every pair of multi-valued config parameters.
* ''results.csv'': parameter values, criterion values, and other information about each docking configuration.

In addition, some number of the best retrodock jobs will be copied to their own sub-directory ''best_retrodock_jobs/''.

Within each sub-directory of ''best_retrodock_jobs/'', there are:
* ''dockfiles/'': parameters files and ''INDOCK'' for given docking configuration
* ''output/'': contains:
** sub-directories ''actives/'' (containing ''OUTDOCK'' and ''test.mol2'' files) and ''decoys/'' (containing just ''OUTDOCK'')
* plot images (e.g., ''roc.png'')

'''Note:''' by default, a mol2 file is exported only for actives, not for decoys, in order to prevent disk space issues.

Dockopt (pydock3 script)

2024-05-05T23:18:14Z

Ianscottknight: /* Subcommand: new */

''dockopt'' allows the generation of many different docking configurations which are then evaluated & analyzed in parallel using a specified job scheduler (e.g. Slurm). If you are a Shoichet Lab user, please see a special section for you, below.

To use DOCK 3.8, you must first license it and install it.
[[DOCK 3.8:How to install pydock3]]

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable and declare default environmental variables:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/env.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/env.sh

== Subcommand: ''new'' ==

Prepare rec.pdb, xtal-lig.pdb as described in Bender, 2021. https://pubmed.ncbi.nlm.nih.gov/34561691/
Or download pre-preared sample files from dudez2022.docking.org.

Be sure that you are in the directory containing the required input files:
* ''rec.pdb'' or ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''actives.tgz''
* ''decoys.tgz''

Note the inclusion of ''actives.tgz'' and ''actives.tgz''. Each of these is a tarball of DB2 files, which may be optionally gzipped (with extension .db2.gz). Each tarball represents a binary class for the binary classification task that the docking model is trained on. The positive class (actives) contains the molecules that you want the docking model to preferentially assign ''favorable'' docking scores to. The negative class (decoys) contains the molecules that you want the docking model to preferentially assign ''unfavorable'' scores to. The most common strategy is to use a set of known ligands as the actives and a larger set of property-matched decoys for the decoys (a decoy-to-active ratio of 50:1 is standard), but other strategies are supported. For example, to create a docking model that preferentially assigns favorable scores to agonists over antagonists, a set of agonists can be used as the actives and a set of antagonists can be used for the decoys.

Therefore, you need to build the molecules yourself (see: https://tldr.docking.org/start/build3d38). Each tarball should contain only DB2 files. For example, if one has a directory ''actives/'' containing only DB2 files to use as the actives, then ''acitves.tgz'' should be created as follows:

cd actives/
tar -czf actives.tgz *.db2*

Similarly, for a directory ''decoys/'' containing only DB2 files to use as decoys, ''decoys.tgz'' should be created as follows:

cd decoys/
tar -czf decoys.tgz *.db2*

To create the file structure for your dockopt job, simply type

pydock3 dockopt - new

By default, the job directory is named ''dockopt_job''. To specify a different name, use the "--job_dir_name" flag. E.g.:

pydock3 dockopt - new --job_dir_name=dockopt_job_2

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''retrodock_jobs'': individual retrodock jobs for each docking configuration

The key difference between the working directories of ''blastermaster'' and ''dockopt'' is that the working directory of ''dockopt'' may contain multiple variants of the blaster files (suffixed by a number, e.g. "box_1"). These variant files are used to create the different docking configurations specified by the multi-valued entries of ''dockopt_config.yaml''. They are created efficiently, such that the same variant used in multiple docking configurations is not created more than once.

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the dockopt job.

* ''rec.pdb''
* ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb'' or ''rec.crg.pdb''. Either is required, but not both. If both are present, only ''rec.crg.pdb'' is used.
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''dockopt_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of dockopt.

'''Note:''' The ''dockopt_config.yaml'' file differs from the ''blastermaster_config.yaml'' file in that every parameter of the former may accept either a single value or a ''list of comma-separated values'', which indicates a pool of values to attempt for that parameter. Multiple such multi-valued parameters may be provided, and all unique resultant docking configurations will be attempted.

Single-valued YAML line format:

distance_to_surface: 1.0

Multi-valued YAML line format:

distance_to_surface: [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]

== Environmental variables ==

=== TMPDIR ===

Designate where temporary job files should be placed. E.g.:

export TMPDIR=/scratch

==== Note for UCSF researchers ====

On the Wynton cluster, ''/scratch'' only exists on development nodes (not log nodes). Therefore, we recommend running on development nodes (see: https://wynton.ucsf.edu/hpc/get-started/development-prototyping.html). E.g.:

ssh dev1
export TMPDIR=/scratch

If a log node must be used, then ''/wynton/scratch'' may be used:

ssh log1
export TMPDIR=/wynton/scratch

=== job scheduler environmental variables ===

In order for ''dockopt'' to know which scheduler it should use, please configure the following environmental variables according to which one of the job schedulers you have.

==== Slurm ====

E.g., on the UCSF Shoichet Lab Gimel cluster (on any node other than 'gimel' itself, such as 'gimel5'):

export SBATCH_EXEC=/usr/bin/sbatch
export SQUEUE_EXEC=/usr/bin/squeue

==== SGE ====

On most clusters using SGE the following should be correct:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/default/common/settings.sh

===== Note for UCSF researchers =====

The following is necessary on the UCSF Wynton cluster:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/wynton/common/settings.sh

== Subcommand: ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run ''dockopt'':
cd <JOB_DIR_NAME>
pydock3 dockopt - run <JOB_SCHEDULER_NAME> [--retrodock_job_timeout_minutes=None] [--retrodock_job_max_reattempts=0] [--extra_submission_cmd_params_str=None] [--export_negatives_mol2=False]

where <JOB_SCHEDULER_NAME> is one of:
* ''sge''
* ''slurm''

This will execute the many dockopt subroutines in sequence. Once this is done, the retrodock jobs for all created docking configurations are run in parallel via the scheduler. The state of the program will be printed to standard output as it runs.

Once the dockopt job is complete, the following files will be generated in the job directory:
* ''report.html'': contains (1) a histogram of the performance of all tested docking configurations compared against a distribution of the performance of a random classifier, so as to show whether the test docking configurations are significantly better than ones that can be produced by a random classifier. This is necessary due to the fact that many configurations are being tested. Hence, a Bonferroni correction is applied to the significance threshold, dividing p=0.01 by the number of tested configurations. (2) ROC, charge, and energy plots of the top docking configurations, comparing positive class molecules vs. negative class molecules, (3) box plots of enrichment for every multi-valued config parameter, and (4) heatmaps of enrichment for every pair of multi-valued config parameters.
* ''results.csv'': parameter values, criterion values, and other information about each docking configuration.

In addition, some number of the best retrodock jobs will be copied to their own sub-directory ''best_retrodock_jobs/''.

Within each sub-directory of ''best_retrodock_jobs/'', there are:
* ''dockfiles/'': parameters files and ''INDOCK'' for given docking configuration
* ''output/'': contains:
** sub-directories ''positives/'' (containing ''OUTDOCK'' and ''test.mol2'' files) and ''negatives/'' (containing just ''OUTDOCK'')
* plot images (e.g., ''roc.png'')

'''Note:''' by default, a mol2 file is exported only for positives, not for negatives, in order to prevent disk space issues.

Dockopt (pydock3 script)

2024-05-05T23:11:22Z

Ianscottknight:

''dockopt'' allows the generation of many different docking configurations which are then evaluated & analyzed in parallel using a specified job scheduler (e.g. Slurm). If you are a Shoichet Lab user, please see a special section for you, below.

To use DOCK 3.8, you must first license it and install it.
[[DOCK 3.8:How to install pydock3]]

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable and declare default environmental variables:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/env.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/env.sh

== Subcommand: ''new'' ==

Prepare rec.pdb, xtal-lig.pdb as described in Bender, 2021. https://pubmed.ncbi.nlm.nih.gov/34561691/
Or download pre-preared sample files from dudez2022.docking.org.

Be sure that you are in the directory containing the required input files:
* ''rec.pdb'' or ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''positives.tgz''
* ''negatives.tgz''

Note the inclusion of ''positives.tgz'' and ''negatives.tgz''. Each of these is a tarball of DB2 files, which may be optionally gzipped (with extension .db2.gz). Each tarball represents a binary class for the binary classification task that the docking model is trained on. The positive class contains the molecules that you want the docking model to preferentially assign ''favorable'' docking scores to. The negative class contains the molecules that you want the docking model to preferentially assign ''unfavorable'' scores to. The most common strategy is to use a set of known ligands as the positive class and a larger set of property-matched decoys for the negative class (a decoy-to-active ratio of 50:1 is standard), but other strategies are supported. For example, to create a docking model that preferentially assigns favorable scores to agonists over antagonists, a set of agonists can be used as the positive class and a set of antagonists can be used for the negative class.

Therefore, you need to build the molecules yourself (see: https://tldr.docking.org/start/build3d38). Each tarball should contain only DB2 files. For example, if one has a directory ''actives/'' containing only DB2 files to use as the positive class, then ''positives.tgz'' should be created as follows:

cd actives/
tar -czf positives.tgz *.db2*

Similarly, for a directory ''decoys/'' containing only DB2 files to use as the negative class, ''negatives.tgz'' should be created as follows:

cd decoys/
tar -czf negatives.tgz *.db2*

To create the file structure for your dockopt job, simply type

pydock3 dockopt - new

By default, the job directory is named ''dockopt_job''. To specify a different name, use the "--job_dir_name" flag. E.g.:

pydock3 dockopt - new --job_dir_name=dockopt_job_2

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''retrodock_jobs'': individual retrodock jobs for each docking configuration

The key difference between the working directories of ''blastermaster'' and ''dockopt'' is that the working directory of ''dockopt'' may contain multiple variants of the blaster files (suffixed by a number, e.g. "box_1"). These variant files are used to create the different docking configurations specified by the multi-valued entries of ''dockopt_config.yaml''. They are created efficiently, such that the same variant used in multiple docking configurations is not created more than once.

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the dockopt job.

* ''rec.pdb''
* ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb'' or ''rec.crg.pdb''. Either is required, but not both. If both are present, only ''rec.crg.pdb'' is used.
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''dockopt_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of dockopt.

'''Note:''' The ''dockopt_config.yaml'' file differs from the ''blastermaster_config.yaml'' file in that every parameter of the former may accept either a single value or a ''list of comma-separated values'', which indicates a pool of values to attempt for that parameter. Multiple such multi-valued parameters may be provided, and all unique resultant docking configurations will be attempted.

Single-valued YAML line format:

distance_to_surface: 1.0

Multi-valued YAML line format:

distance_to_surface: [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]

== Environmental variables ==

=== TMPDIR ===

Designate where temporary job files should be placed. E.g.:

export TMPDIR=/scratch

==== Note for UCSF researchers ====

On the Wynton cluster, ''/scratch'' only exists on development nodes (not log nodes). Therefore, we recommend running on development nodes (see: https://wynton.ucsf.edu/hpc/get-started/development-prototyping.html). E.g.:

ssh dev1
export TMPDIR=/scratch

If a log node must be used, then ''/wynton/scratch'' may be used:

ssh log1
export TMPDIR=/wynton/scratch

=== job scheduler environmental variables ===

In order for ''dockopt'' to know which scheduler it should use, please configure the following environmental variables according to which one of the job schedulers you have.

==== Slurm ====

E.g., on the UCSF Shoichet Lab Gimel cluster (on any node other than 'gimel' itself, such as 'gimel5'):

export SBATCH_EXEC=/usr/bin/sbatch
export SQUEUE_EXEC=/usr/bin/squeue

==== SGE ====

On most clusters using SGE the following should be correct:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/default/common/settings.sh

===== Note for UCSF researchers =====

The following is necessary on the UCSF Wynton cluster:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/wynton/common/settings.sh

== Subcommand: ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run ''dockopt'':
cd <JOB_DIR_NAME>
pydock3 dockopt - run <JOB_SCHEDULER_NAME> [--retrodock_job_timeout_minutes=None] [--retrodock_job_max_reattempts=0] [--extra_submission_cmd_params_str=None] [--export_negatives_mol2=False]

where <JOB_SCHEDULER_NAME> is one of:
* ''sge''
* ''slurm''

This will execute the many dockopt subroutines in sequence. Once this is done, the retrodock jobs for all created docking configurations are run in parallel via the scheduler. The state of the program will be printed to standard output as it runs.

Once the dockopt job is complete, the following files will be generated in the job directory:
* ''report.html'': contains (1) a histogram of the performance of all tested docking configurations compared against a distribution of the performance of a random classifier, so as to show whether the test docking configurations are significantly better than ones that can be produced by a random classifier. This is necessary due to the fact that many configurations are being tested. Hence, a Bonferroni correction is applied to the significance threshold, dividing p=0.01 by the number of tested configurations. (2) ROC, charge, and energy plots of the top docking configurations, comparing positive class molecules vs. negative class molecules, (3) box plots of enrichment for every multi-valued config parameter, and (4) heatmaps of enrichment for every pair of multi-valued config parameters.
* ''results.csv'': parameter values, criterion values, and other information about each docking configuration.

In addition, some number of the best retrodock jobs will be copied to their own sub-directory ''best_retrodock_jobs/''.

Within each sub-directory of ''best_retrodock_jobs/'', there are:
* ''dockfiles/'': parameters files and ''INDOCK'' for given docking configuration
* ''output/'': contains:
** sub-directories ''positives/'' (containing ''OUTDOCK'' and ''test.mol2'' files) and ''negatives/'' (containing just ''OUTDOCK'')
* plot images (e.g., ''roc.png'')

'''Note:''' by default, a mol2 file is exported only for positives, not for negatives, in order to prevent disk space issues.

Calculate ECFP4 using RDKit

2024-02-09T20:12:29Z

Ianscottknight:

1. Clone the ChemInfTools repository:
git clone https://github.com/docking-org/ChemInfTools.git

2. Ensure that you have sourced a python3 environment. E.g.,
source /nfs/soft/ian/python3.8.5.sh

3. Run the script:
python ChemInfTools/utils/teb_chemaxon_cheminf_tools/generate_chemaxon_fingerprints_py3.py <SMILES_FILE> <OUTFILE_PREFIX>

Calculate ECFP4 using RDKit

2024-02-09T20:11:50Z

Ianscottknight:

1. git clone https://github.com/docking-org/ChemInfTools.git

2. Ensure that you have sourced a python3 environment. E.g.,
source /nfs/soft/ian/python3.8.5.sh
3. python ChemInfTools/utils/teb_chemaxon_cheminf_tools/generate_chemaxon_fingerprints_py3.py <SMILES_FILE> <OUTFILE_PREFIX>

Calculate ECFP4 using RDKit

2024-02-09T20:11:22Z

Ianscottknight: Created page with "1. git clone https://github.com/docking-org/ChemInfTools.git 2. Ensure that you have sourced a python3 environment E.g., source /nfs/soft/ian/python3.8.5.sh 3. python ChemInfTools/utils/teb_chemaxon_cheminf_tools/generate_chemaxon_fingerprints_py3.py <SMILES_FILE> <OUTFILE_PREFIX>"

1. git clone https://github.com/docking-org/ChemInfTools.git
2. Ensure that you have sourced a python3 environment
E.g.,
source /nfs/soft/ian/python3.8.5.sh
3. python ChemInfTools/utils/teb_chemaxon_cheminf_tools/generate_chemaxon_fingerprints_py3.py <SMILES_FILE> <OUTFILE_PREFIX>

Dockopt (pydock3 script)

2024-02-01T19:54:56Z

Ianscottknight:

''dockopt'' allows the generation of many different docking configurations which are then evaluated & analyzed in parallel using a specified job scheduler (e.g. Slurm). If you are a Shoichet Lab user, please see a special section for you, below.

To use DOCK 3.8, you must first license it and install it.
[[DOCK 3.8:How to install pydock3]]

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable and declare default environmental variables:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/env.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/env.sh

== ''new'' ==

Prepare rec.pdb, xtal-lig.pdb as described in Bender, 2021. https://pubmed.ncbi.nlm.nih.gov/34561691/
Or download pre-preared sample files from dudez2022.docking.org.

Be sure that you are in the directory containing the required input files:
* ''rec.pdb'' or ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''positives.tgz''
* ''negatives.tgz''

Note the inclusion of ''positives.tgz'' and ''negatives.tgz''. Each of these is a tarball of DB2 files, which may be optionally gzipped (with extension .db2.gz). Each tarball represents a binary class for the binary classification task that the docking model is trained on. The positive class contains the molecules that you want the docking model to preferentially assign ''favorable'' docking scores to. The negative class contains the molecules that you want the docking model to preferentially assign ''unfavorable'' scores to. The most common strategy is to use a set of known ligands as the positive class and a larger set of property-matched decoys for the negative class (a decoy-to-active ratio of 50:1 is standard), but other strategies are supported. For example, to create a docking model that preferentially assigns favorable scores to agonists over antagonists, a set of agonists can be used as the positive class and a set of antagonists can be used for the negative class.

Therefore, you need to build the molecules yourself (see: https://tldr.docking.org/start/build3d38). Each tarball should contain only DB2 files. For example, if one has a directory ''actives/'' containing only DB2 files to use as the positive class, then ''positives.tgz'' should be created as follows:

cd actives/
tar -czf positives.tgz *.db2*

Similarly, for a directory ''decoys/'' containing only DB2 files to use as the negative class, ''negatives.tgz'' should be created as follows:

cd decoys/
tar -czf negatives.tgz *.db2*

To create the file structure for your dockopt job, simply type

pydock3 dockopt - new

By default, the job directory is named ''dockopt_job''. To specify a different name, use the "--job_dir_name" flag. E.g.:

pydock3 dockopt - new --job_dir_name=dockopt_job_2

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''retrodock_jobs'': individual retrodock jobs for each docking configuration

The key difference between the working directories of ''blastermaster'' and ''dockopt'' is that the working directory of ''dockopt'' may contain multiple variants of the blaster files (suffixed by a number, e.g. "box_1"). These variant files are used to create the different docking configurations specified by the multi-valued entries of ''dockopt_config.yaml''. They are created efficiently, such that the same variant used in multiple docking configurations is not created more than once.

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the dockopt job.

* ''rec.pdb''
* ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb'' or ''rec.crg.pdb''. Either is required, but not both. If both are present, only ''rec.crg.pdb'' is used.
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''dockopt_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of dockopt.

'''Note:''' The ''dockopt_config.yaml'' file differs from the ''blastermaster_config.yaml'' file in that every parameter of the former may accept either a single value or a ''list of comma-separated values'', which indicates a pool of values to attempt for that parameter. Multiple such multi-valued parameters may be provided, and all unique resultant docking configurations will be attempted.

Single-valued YAML line format:

distance_to_surface: 1.0

Multi-valued YAML line format:

distance_to_surface: [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]

== Environmental variables ==

=== TMPDIR ===

Designate where temporary job files should be placed. E.g.:

export TMPDIR=/scratch

==== Note for UCSF researchers ====

On the Wynton cluster, ''/scratch'' only exists on development nodes (not log nodes). Therefore, we recommend running on development nodes (see: https://wynton.ucsf.edu/hpc/get-started/development-prototyping.html). E.g.:

ssh dev1
export TMPDIR=/scratch

If a log node must be used, then ''/wynton/scratch'' may be used:

ssh log1
export TMPDIR=/wynton/scratch

=== job scheduler environmental variables ===

In order for ''dockopt'' to know which scheduler it should use, please configure the following environmental variables according to which one of the job schedulers you have.

==== Slurm ====

E.g., on the UCSF Shoichet Lab Gimel cluster (on any node other than 'gimel' itself, such as 'gimel5'):

export SBATCH_EXEC=/usr/bin/sbatch
export SQUEUE_EXEC=/usr/bin/squeue

==== SGE ====

On most clusters using SGE the following should be correct:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/default/common/settings.sh

===== Note for UCSF researchers =====

The following is necessary on the UCSF Wynton cluster:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/wynton/common/settings.sh

== ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run ''dockopt'':
cd <JOB_DIR_NAME>
pydock3 dockopt - run <JOB_SCHEDULER_NAME> [--retrodock_job_timeout_minutes=None] [--retrodock_job_max_reattempts=0] [--extra_submission_cmd_params_str=None] [--export_negatives_mol2=False]

where <JOB_SCHEDULER_NAME> is one of:
* ''sge''
* ''slurm''

This will execute the many dockopt subroutines in sequence. Once this is done, the retrodock jobs for all created docking configurations are run in parallel via the scheduler. The state of the program will be printed to standard output as it runs.

Once the dockopt job is complete, the following files will be generated in the job directory:
* ''report.html'': contains (1) a histogram of the performance of all tested docking configurations compared against a distribution of the performance of a random classifier, so as to show whether the test docking configurations are significantly better than ones that can be produced by a random classifier. This is necessary due to the fact that many configurations are being tested. Hence, a Bonferroni correction is applied to the significance threshold, dividing p=0.01 by the number of tested configurations. (2) ROC, charge, and energy plots of the top docking configurations, comparing positive class molecules vs. negative class molecules, (3) box plots of enrichment for every multi-valued config parameter, and (4) heatmaps of enrichment for every pair of multi-valued config parameters.
* ''results.csv'': parameter values, criterion values, and other information about each docking configuration.

In addition, some number of the best retrodock jobs will be copied to their own sub-directory ''best_retrodock_jobs/''.

Within each sub-directory of ''best_retrodock_jobs/'', there are:
* ''dockfiles/'': parameters files and ''INDOCK'' for given docking configuration
* ''output/'': contains:
** sub-directories ''positives/'' (containing ''OUTDOCK'' and ''test.mol2'' files) and ''negatives/'' (containing just ''OUTDOCK'')
* plot images (e.g., ''roc.png'')

'''Note:''' by default, a mol2 file is exported only for positives, not for negatives, in order to prevent disk space issues.

DOCK 3.8:How to build a release

2024-01-26T22:55:34Z

Ianscottknight:

This page describes the formal definition of a release of the [https://dock.compbio.ucsf.edu/ ''UCSF DOCK''] software suite

1. Build desired version of [[pydock3]] Python package (e.g., build pip-installable wheel file using [[Python Poetry|poetry]]).

2. Clone desired version of [[dock3]] program.

3. Incorporate the fruits of (1) and (2) into [[DOCK3.8]] repository housing an arsenal of scripts (e.g., 3D build scripts, post-processing scripts) that are essential for following the [https://www.nature.com/articles/s41596-021-00597-z published Nature protocol].

A particular commit of the DOCK3.8 repository formally becomes a particular distribution of [https://dock.compbio.ucsf.edu/ ''UCSF DOCK''] software when the commit is tagged with the distribution's [https://semver.org/ semantic version (e.g., DOCK3.8 v1.2.0)]. Note that ''pydock3'' and ''dock3'' are separately versioned from ''DOCK3.8''.

[[Category:DOCK 3.8]]

DOCK 3.8:How to build a release

2024-01-26T08:47:06Z

Ianscottknight:

This page describes the formal definition of a release of the [https://dock.compbio.ucsf.edu/ ''UCSF DOCK''] software suite

1. Build desired version of [[pydock3]] Python package (e.g., build pip-installable wheel file using [[Python Poetry|poetry]]).
2. Clone desired version of [[dock3]] program.
3. Incorporate the fruits of (1) and (2) into [[DOCK3.8]] repository housing an arsenal of scripts (e.g., 3D build scripts, post-processing scripts) that are essential for following the [https://www.nature.com/articles/s41596-021-00597-z published Nature protocol].

A particular commit of the DOCK3.8 repository formally becomes a particular distribution of [https://dock.compbio.ucsf.edu/ ''UCSF DOCK''] software when the commit is tagged with the distribution's [https://semver.org/ semantic version (e.g., DOCK3.8 v1.2.0)]. Note that ''pydock3'' and ''dock3'' are separately versioned from ''DOCK3.8''.

[[Category:DOCK 3.8]]

DOCK 3.8:How to build a release

2024-01-26T08:08:52Z

Ianscottknight:

This page describes how to take the three github repos, combine them, and create a tarball for public use.

1. Build desired version of [[pydock3]] Python package (e.g., build pip-installable wheel file using [[Python Poetry|poetry]]).
2. Clone desired version of [[dock3]] program.
3. Incorporate fruits of (1) and (2) into [[UCSF_DOCK]] repository housing legacy scripts that remain essential to established protocols (e.g., build scripts, post-processing scripts).

A particular commit of the UCSF_DOCK repository becomes a particular distribution of ''UCSF DOCK'' software when the repository is assigned a tag of its [https://semver.org/ semantic version (e.g., v1.2.3)].

[[Category:DOCK 3.8]]

DOCK 3.8:How to build a release

2024-01-26T07:47:50Z

Ianscottknight:

This page describes how to take the three github repos, combine them, and create a tarball for public use.

1. Build desired version of [[pydock3]] Python package (e.g., build pip-installable wheel file using [[Python Poetry|poetry]]).
2. Clone desired version of [[dock3]] program.
3. Incorporate fruits of (1) and (2) into [[DOCKBASE]] repository housing legacy scripts that remain essential to established protocols (e.g., build scripts, post-processing scripts).

The assignment of a semantic version to a particular commit of DOCKBASE

[[Category:DOCK 3.8]]

SUBDOCK DOCK3.8

2023-12-28T02:59:11Z

Ianscottknight: /* What's New? */

Important note- although DOCK 3.8 is in the header of this article, SUBDOCK is perfectly capable of running DOCK 3.7 workloads, though some features of DOCK 3.8 will not be taken advantage of.

== Installing ==

<nowiki>
git clone https://github.com/docking-org/SUBDOCK.git</nowiki>

'''IMPORTANT: subdock.bash expects to live in the same directory as rundock.bash!!!'''

subdock.bash is located @ subdock.bash relative to the repository root.

subdock.bash can be called directly from any location- it is not sensitive to the current working directory.

== What's New? ==

Compared to older scripts, SUBDOCK is easier to use, has more features, and is much more flexible!

==== December 2022 ====

* All jobs platforms (e.g slurm, sge) are supported on the same script

* GNU Parallel is now supported as a jobs platform! Ideal for small-scale local testing. https://www.gnu.org/software/parallel/

* Subdock can now be run on both db2.gz individual files & db2.tgz packages. A batch_size can be set for both types, allowing for more flexibility.

* Arguments can be provided environmentally, e.g "export KEY=VALUE" or on the command line e.g "--key=value"

* Subdock now prints out a superscript to copy-paste on success, convenient for re-submission.

* Fully restartable on all jobs platforms! See below section for an explanation on what this means, why it matters, and instructions on usage.

* INDOCK version header is automatically corrected, as are any file paths referenced by INDOCK.

==== May 2023 ====

* You can provide http(s) URLs to dockable files as your input in lieu of file paths!

* Charity engine is now supported as a jobs platform! More instructions for using this further down. (https://www.charityengine.com/)

* Subdock will automatically detect if your jobs failed- no need to use an extra script to check if your jobs have actually finished or not

==== May 2023 ====

* A [[DOCK3R]] image is now used instead of a DOCK executable, in order to avoid pathological misbehavior witnessed on different systems.

== Supported Platforms ==

There are four platforms currently supported:

# SLURM
# SGE (Sun Grid Engine)
#* '''note for BKS lab: the SGE queue on gimel does not have python3, your jobs will not work!'''
# GNU Parallel (for local runs- ideal for testing)
# Charity Engine

One of these platforms must be specified- SLURM is the default. These platforms can be set by the
<nowiki>
--use-slurm=true
--use-sge=true
--use-parallel=true
--use-charity=true</nowiki>
Arguments, respectively

==== Using Charity Engine ====

To use charity engine, you must have access to an executable of the charity engine CLI, as well as GNU parallel.

Additionally, you must provide your charity authentication details in the form of the CHARITY_AUTHKEY or --charity-authkey variable.

WIP, more specific instructions to come.

== Supported File Types ==

DOCK can be run on individual db2.gz files or db2.tgz tar packages.

The file type can be specified via the --use-db2=true or --use-db2-tgz=true arguments. db2.tgz is the default

Each job dispatched by SUBDOCK will consume BATCH_SIZE files, where BATCH_SIZE is equal to --use-db2-batch-size or --use-db2-tgz-batch-size depending on which file type is chosen.

The number of jobs dispatched by SUBDOCK is equal to ceil(N / BATCH_SIZE), where N is the total number of input files.

== Restartability ==

'''ONLY APPLICABLE FOR DOCK 3.8+!'''

Restartability means that we can impose arbitrary time limits on how long our jobs can run *without* losing our progress. Time limits can be as large or as small as we want them to be, even as little as a few minutes per job! This flexibility lets docking jobs efficiently fill in the gaps between longer-running jobs on the same ecosystem, thus they will be preferentially treated by whichever system is in charge of scheduling.

=== How to use for your Job Platform ===

On SLURM, runtime can be defined with the "--time" argument, e.g:

<nowiki>subdock.bash --use-slurm=true --use-slurm-args="--time=00:30:00"</nowiki>

This will allow our job to run for 30 minutes before progress is saved & copied out.

On GNU parallel this is accomplished with "--timeout", e.g:

<nowiki>subdock.bash --use-parallel=true --use-parallel-args="--timeout 1800"</nowiki>

On SGE, the same can be achieved using the s_rt and h_rt parameters, e.g:

<nowiki>subdock.bash --use-sge=true --use-sge-args="-l s_rt=00:29:30 -l h_rt=00:30:00"</nowiki>

This tells SGE to warn the job 30 seconds prior to the 30 minute hard limit.
GNU and SLURM platforms will provide a hard-coded 30 seconds notice, whereas this notice period must be manually defined for SGE jobs.

=== How to continue jobs ===

Run subdock.bash again with the same parameters (particularly EXPORT_DEST, INPUT_SOURCE, USE_DB2, USE_DB2_TGZ, USE_DB2_BATCH_SIZE, and USE_DB2_TGZ_BATCH_SIZE) to restart your jobs! If you saved the superscript SUBDOCK spits out on successful submission, you can simply call that.

You'll know there is no more work to be done if SUBDOCK prints "all N jobs complete!", SUBDOCK will also tell you what proportion of jobs have not yet completed on each submission.

Output files are appended with a suffix indicating how many times the docking task has been resubmitted, e.g OUTDOCK.0 for the first attempt, OUTDOCK.1 for the second, etc.

Be careful not to overlap your submissions- there are no guardrails in place to prevent this from happening if you are not careful.

== Full Example - All Steps ==

This example assumes you have access to a DOCK executable and an installed scheduling system (SGE/SLURM/Parallel), but nothing else.

1. Source subdock code from github
<nowiki>
git clone https://github.com/docking-org/SUBDOCK.git</nowiki>

2. Fetch dockfiles from DUDE-Z- we will use DRD4 for this example.
<nowiki>
# note- SUBDOCK automatically detects your DOCK version & corrects the INDOCK header accordingly
wget -r --reject="index.html*" -nH --cut-dirs=2 -l1 --no-parent https://dudez.docking.org/DOCKING_GRIDS_AND_POSES/DRD4/dockfiles/</nowiki>

3a. Get db2 database subset sample via ZINC-22. Example provided below:
<nowiki>
wget http://files.docking.org/zinc22/zinc-22l/H17/H17P050/a/H17P050-N-laa.db2.tgz
wget http://files.docking.org/zinc22/zinc-22l/H17/H17P050/a/H17P050-N-lab.db2.tgz
wget http://files.docking.org/zinc22/zinc-22l/H17/H17P050/a/H17P050-N-lac.db2.tgz</nowiki>

You can select a db2 database subset via cartblanche22.docking.org- for wget-able files, choose the DOCK37 (*.db2.tgz) format, with URL download type. Multiple download types are supported, for example if you are on Wynton you can download Wynton file paths- removing the need to download the files yourself.

3b. If you downloaded the db2.tgz files yourself, create an sdi.in file from your database subset, which will serve as a list of files to evaluate. For example:
<nowiki>
find $PWD -type f -name '*.db2.tgz' > sdi.in</nowiki>

4. Export the parameters we just prepared as environment variables. '''You need a DOCK executable!''' This can be found via our download server if you have a license, otherwise lab members can directly pull https://github.com/docking-org/dock3.git. On BKS cluster, some curated executables have been prepared with labels @ /nfs/soft/dock/versions/dock38/executables. DOCK 3.7 executables may be found here as well!

<nowiki>
export INPUT_SOURCE=$PWD/sdi.in
export EXPORT_DEST=$PWD/output
export DOCKFILES=$PWD/dockfiles
export DOCKEXEC=/nfs/soft/dock/versions/dock38/executables/dock38_nogist</nowiki>

5. Choose a platform. You must select only one platform - mixing and matching is not supported.
<nowiki>
export USE_SLURM=true|...
export USE_SGE=true|...
export USE_PARALLEL=true|...</nowiki>

Any value other than exactly "true" will be interpreted as false.

6a. Run docking!
<nowiki>
bash ~/SUBDOCK/subdock.bash</nowiki>

6b. You can also use command line arguments instead of environment export, if desired. These can be mixed and matched.
<nowiki>
export DOCKEXEC=$PWD/DOCK/ucsfdock/docking/DOCK/dock64
bash ~/SUBDOCK/subdock.bash --input-source=$PWD/sdi.in --export-dest=$PWD/output --dockfiles=$PWD/dockfiles --use-slurm=true</nowiki>

7. After executing subdock, it will print out a convenient "superscript" to copy & paste, for any future re-submissions.

== Mixing DOCK 3.7 and DOCK 3.8 - known problems ==

'''Headline: Though SUBDOCK is compatible with DOCK 3.7, and will allow docking of ligands built for 3.8 in 3.7, it is NOT RECOMMENDED to do this without using a specially prepared 3.7 executable!'''

If you're running DOCK 3.8 against recently built ligands, you may encounter error messages that look like this:
<nowiki> 1 2 bonds with error
Error. newlist is not big enough</nowiki>

Or worse, like this:
<nowiki> Warning. tempconf = 0
1597 -> 0 -> 0</nowiki>

The latter error messages have the potential to cause some serious damage, as they are emitted very frequently & may consume excessive disk space. SUBDOCK will check for these messages periodically during DOCK's runtime & kill the process if they are found.

If you are on 3.8 and are encountering these messages still, use the dock38_nogist executable described in [[How_to_install_DOCK_3.8#Prebuilt_Executable]]. This version voids the code related to the GIST scoring function, which is responsible for these errors.

If you are using 3.7 still, it is possible to prepare a version that keeps everything the same, except without the dangerous "tempconf" message.

== SUBDOCK help splash - all argument descriptions & defaults ==
<nowiki>
[user@machine SUBDOCK]$ ./subdock.bash --help
SUBDOCK! Run docking workloads via job controller of your choice
=================required arguments=================
expected env arg: EXPORT_DEST, --export-dest
arg description: nfs output destination for OUTDOCK and test.mol2.gz files

expected env arg: INPUT_SOURCE, --input-source
arg description: nfs directory containing one or more .db2.tgz files OR a file containing a list of db2.tgz files

expected env arg: DOCKFILES, --dockfiles
arg description: nfs directory containing dock related files and INDOCK configuration for docking run

expected env arg: DOCKEXEC, --dockexec
arg description: nfs path to dock executable

=================job controller settings=================
optional env arg missing: USE_SLURM, --use-slurm
arg description: use slurm
defaulting to false

optional env arg missing: USE_SLURM_ARGS, --use-slurm-args
arg description: addtl arguments for SLURM sbatch command
defaulting to

optional env arg missing: USE_SGE, --use-sge
arg description: use sge
defaulting to false

optional env arg missing: USE_SGE_ARGS, --use-sge-args
arg description: addtl arguments for SGE qsub command
defaulting to

optional env arg missing: USE_PARALLEL, --use-parallel
arg description: use GNU parallel
defaulting to false

optional env arg missing: USE_PARALLEL_ARGS, --use-parallel-args
arg description: addtl arguments for GNU parallel command
defaulting to

=================input settings=================
optional env arg missing: USE_DB2_TGZ, --use-db2-tgz
arg description: dock db2.tgz tar files
defaulting to true

optional env arg missing: USE_DB2_TGZ_BATCH_SIZE, --use-db2-tgz-batch-size
arg description: how many db2.tgz to evaluate per batch
defaulting to 1

optional env arg missing: USE_DB2, --use-db2
arg description: dock db2.gz individual files
defaulting to false

optional env arg missing: USE_DB2_BATCH_SIZE, --use-db2-batch-size
arg description: how many db2.gz to evaluate per batch
defaulting to 100

=================addtl job configuration=================
optional env arg missing: MAX_PARALLEL, --max-parallel
arg description: max jobs allowed to run in parallel
defaulting to -1

optional env arg missing: SHRTCACHE, --shrtcache
arg description: temporary local storage for job files
defaulting to /scratch

optional env arg missing: LONGCACHE, --longcache
arg description: longer term storage for files shared between jobs
defaulting to /scratch

=================miscellaneous=================
optional env arg missing: SUBMIT_WAIT_TIME, --submit-wait-time
arg description: how many seconds to wait before submitting
defaulting to 5

optional env arg missing: USE_CACHED_SUBMIT_STATS, --use-cached-submit-stats
arg description: only check completion for jobs submitted in the latest iteration. Faster re-submission, but will ignore jobs that have been manually reset
defaulting to false
</nowiki>

[[Category:DOCK_3.8]]

Blastermaster (pydock3 script)

2023-12-12T07:49:01Z

Ianscottknight:

''blastermaster'' allows the generation of a specific docking configuration for a given receptor and ligand.

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' command:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/python3.8.5.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/python3.8.5.sh

== ''new'' ==

First you need to create the file structure for your blastermaster job. To do so, simply type

pydock3 blastermaster - new

By default, the job directory is named ''blastermaster_job''. To specify a different name, type

pydock3 blastermaster - new <JOB_DIR_NAME>

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''dockfiles'': output files (DOCK parameter files & INDOCK)

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the blastermaster job.

* ''rec.pdb''
* ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb''
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, then copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''blastermaster_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of blastermaster.

== ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run blastermaster:
cd <JOB_DIR_NAME>
pydock3 blastermaster - run

This will execute the many blastermaster subroutines in sequence. The state of the program will be printed to standard output as it runs.

Dockopt (pydock3 script)

2023-09-02T04:35:59Z

Ianscottknight:

''dockopt'' allows the generation of many different docking configurations which are then evaluated & analyzed in parallel using a specified job scheduler (e.g. Slurm). If you are a Shoichet Lab user, please see a special section for you, below.

To use DOCK 3.8, you must first license it and install it.
[[DOCK 3.8:How to install pydock3]]

== ''new'' ==

Prepare rec.pdb, xtal-lig.pdb as described in Bender, 2021. https://pubmed.ncbi.nlm.nih.gov/34561691/
Or download pre-preared sample files from dudez2022.docking.org.

Be sure that you are in the directory containing the required input files:
* ''rec.pdb'' or ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''positives.tgz''
* ''negatives.tgz''

Note the inclusion of ''positives.tgz'' and ''negatives.tgz''. Each of these is a tarball of DB2 files, which may be optionally gzipped (with extension .db2.gz). Each tarball represents a binary class for the binary classification task that the docking model is trained on. The positive class contains the molecules that you want the docking model to preferentially assign ''favorable'' docking scores to. The negative class contains the molecules that you want the docking model to preferentially assign ''unfavorable'' scores to. The most common strategy is to use a set of known ligands as the positive class and a larger set of property-matched decoys for the negative class (a decoy-to-active ratio of 50:1 is standard), but other strategies are supported. For example, to create a docking model that preferentially assigns favorable scores to agonists over antagonists, a set of agonists can be used as the positive class and a set of antagonists can be used for the negative class.

Therefore, you need to build the molecules yourself (see: https://tldr.docking.org/start/build3d38). Each tarball should contain only DB2 files. For example, if one has a directory ''actives/'' containing only DB2 files to use as the positive class, then ''positives.tgz'' should be created as follows:

cd actives/
tar -czf positives.tgz *.db2*

Similarly, for a directory ''decoys/'' containing only DB2 files to use as the negative class, ''negatives.tgz'' should be created as follows:

cd decoys/
tar -czf negatives.tgz *.db2*

To create the file structure for your dockopt job, simply type

pydock3 dockopt - new

By default, the job directory is named ''dockopt_job''. To specify a different name, use the "--job_dir_name" flag. E.g.:

pydock3 dockopt - new --job_dir_name=dockopt_job_2

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''retrodock_jobs'': individual retrodock jobs for each docking configuration

The key difference between the working directories of ''blastermaster'' and ''dockopt'' is that the working directory of ''dockopt'' may contain multiple variants of the blaster files (suffixed by a number, e.g. "box_1"). These variant files are used to create the different docking configurations specified by the multi-valued entries of ''dockopt_config.yaml''. They are created efficiently, such that the same variant used in multiple docking configurations is not created more than once.

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the dockopt job.

* ''rec.pdb''
* ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb'' or ''rec.crg.pdb''. Either is required, but not both. If both are present, only ''rec.crg.pdb'' is used.
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''dockopt_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of dockopt.

'''Note:''' The ''dockopt_config.yaml'' file differs from the ''blastermaster_config.yaml'' file in that every parameter of the former may accept either a single value or a ''list of comma-separated values'', which indicates a pool of values to attempt for that parameter. Multiple such multi-valued parameters may be provided, and all unique resultant docking configurations will be attempted.

Single-valued YAML line format:

distance_to_surface: 1.0

Multi-valued YAML line format:

distance_to_surface: [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]

== Environmental variables ==

=== TMPDIR ===

Designate where temporary job files should be placed. E.g.:

export TMPDIR=/scratch

==== Note for UCSF researchers ====

On the Wynton cluster, ''/scratch'' only exists on development nodes (not log nodes). Therefore, we recommend running on development nodes (see: https://wynton.ucsf.edu/hpc/get-started/development-prototyping.html). E.g.:

ssh dev1
export TMPDIR=/scratch

If a log node must be used, then ''/wynton/scratch'' may be used:

ssh log1
export TMPDIR=/wynton/scratch

=== job scheduler environmental variables ===

In order for ''dockopt'' to know which scheduler it should use, please configure the following environmental variables according to which one of the job schedulers you have.

==== Slurm ====

E.g., on the UCSF Shoichet Lab Gimel cluster (on any node other than 'gimel' itself, such as 'gimel5'):

export SBATCH_EXEC=/usr/bin/sbatch
export SQUEUE_EXEC=/usr/bin/squeue

==== SGE ====

On most clusters using SGE the following should be correct:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/default/common/settings.sh

===== Note for UCSF researchers =====

The following is necessary on the UCSF Wynton cluster:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/wynton/common/settings.sh

== ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run ''dockopt'':
cd <JOB_DIR_NAME>
pydock3 dockopt - run <JOB_SCHEDULER_NAME> [--retrodock_job_timeout_minutes=None] [--retrodock_job_max_reattempts=0] [--extra_submission_cmd_params_str=None] [--export_negatives_mol2=False]

where <JOB_SCHEDULER_NAME> is one of:
* ''sge''
* ''slurm''

This will execute the many dockopt subroutines in sequence. Once this is done, the retrodock jobs for all created docking configurations are run in parallel via the scheduler. The state of the program will be printed to standard output as it runs.

Once the dockopt job is complete, the following files will be generated in the job directory:
* ''report.html'': contains (1) a histogram of the performance of all tested docking configurations compared against a distribution of the performance of a random classifier, so as to show whether the test docking configurations are significantly better than ones that can be produced by a random classifier. This is necessary due to the fact that many configurations are being tested. Hence, a Bonferroni correction is applied to the significance threshold, dividing p=0.01 by the number of tested configurations. (2) ROC, charge, and energy plots of the top docking configurations, comparing positive class molecules vs. negative class molecules, (3) box plots of enrichment for every multi-valued config parameter, and (4) heatmaps of enrichment for every pair of multi-valued config parameters.
* ''results.csv'': parameter values, criterion values, and other information about each docking configuration.

In addition, some number of the best retrodock jobs will be copied to their own sub-directory ''best_retrodock_jobs/''.

Within each sub-directory of ''best_retrodock_jobs/'', there are:
* ''dockfiles/'': parameters files and ''INDOCK'' for given docking configuration
* ''output/'': contains:
** sub-directories ''positives/'' (containing ''OUTDOCK'' and ''test.mol2'' files) and ''negatives/'' (containing just ''OUTDOCK'')
* plot images (e.g., ''roc.png'')

'''Note:''' by default, a mol2 file is exported only for positives, not for negatives, in order to prevent disk space issues.

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable and declare default environmental variables:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/env.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/env.sh

TLDR:decoygen

2023-08-29T20:25:17Z

Ianscottknight:

== Purpose ==
Create decoys for [[Retrospective Docking|retrospective docking]] by the method used to create the [[DUDE-Z Dataset|DUDE-Z dataset]]. See https://dudez.docking.org for sample data of known actives and their corresponding decoys for 43 targets.

== Inputs ==
* Ligands provided in smiles format (actives.smi)
* Current default parameters are shown in the following decoy_generation.in file:
See [[Generating_decoys_(Reed%27s_way)]] for an explanation of what these parameters mean and how DUDE-Z works.

PROTONATE YES
MWT 0 125
LOGP 0 3.6
RB 0 5
HBA 0 4
HBD 0 3
CHARGE 0 0
LIGAND TC RANGE 0.0 0.35
MINIMUM DECOYS PER LIGAND 20
DECOYS PER LIGAND 50
MAXIMUM TC BETWEEN DECOYS 0.8
TANIMOTO YES

'''If you wish to overwrite decoy_generation.in, please download it, edit and submit.'''

== Outputs ==
* List of decoys

== Notes ==

TLDR:dude-z

2023-08-29T20:16:45Z

Ianscottknight: Ianscottknight moved page TLDR:dude-z to TLDR:decoygen: Naming the decoy generation pipeline `dude-z` doesn't really make sense given that DUDE-Z is a dataset. I am guessing that the original logic behind this was that the pipeline was used to help create DUDE-Z. Still, the data types `pipeline` and `dataset` are distinct, therefore justifying this name change.

#REDIRECT [[TLDR:decoygen]]

TLDR:decoygen

2023-08-29T20:16:45Z

== Purpose ==
Assemble decoys for docking using the DUDEZ approach. See https://dudez.docking.org for sample data

== Inputs ==
* Ligands provided in smiles format (actives.smi)
* Current default parameters are shown in the following decoy_generation.in file:
See https://wiki.docking.org/index.php/Generating_decoys_(Reed%27s_way) for an explanation of what these parameters mean and how DUDE-Z works.

PROTONATE YES
MWT 0 125
LOGP 0 3.6
RB 0 5
HBA 0 4
HBD 0 3
CHARGE 0 0
LIGAND TC RANGE 0.0 0.35
MINIMUM DECOYS PER LIGAND 20
DECOYS PER LIGAND 50
MAXIMUM TC BETWEEN DECOYS 0.8
TANIMOTO YES
'''If you wish to overwrite decoy_generation.in, please download it, edit and submit.'''

== Outputs ==
* List of decoys
== Notes ==

DOCK3.8:Pydock3

2023-08-24T01:51:04Z

Ianscottknight:

''pydock3'' is a Python package wrapping the [[DOCK|DOCK Fortran program]] that provides tools to help standardize and automate the computational methods employed in molecular docking. It is a natural successor to DOCK Blaster, originally published in 2009, and blastermaster.py, part of the [[DOCK 3.7]] release in 2012.

[[File:Pydock3 logo.png|thumb]]

Scripts included in ''pydock3'':
* ''dockopt'': generate many different docking configurations, perform retrospective docking on them in parallel using a specified job scheduler (e.g. Slurm), and analyze the results.
* ''blastermaster'': generate a specific docking configuration for a given receptor and ligand, intended for use by experts who wish to tune the docking model themselves. This is a direct successor of blastermaster.py from DOCK 3.7.

A [[docking configuration|'''docking configuration''']] is a unique set of (1) DOCK parameter files (e.g., ''matching_spheres.sph''), (2) an INDOCK file, and (3) a DOCK executable.

= Installation =

See: [[DOCK 3.8:How to install pydock3]].

= Instructions =

== ''blastermaster'' ==

See: [[blastermaster (pydock3 script)]].

== ''dockopt'' ==

See: [[dockopt (pydock3 script)]].

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/python3.8.5.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/python3.8.5.sh

[[Category:DOCK 3.8]]
[[Category:DOCK Blaster]]

DOCK3.8:Pydock3

2023-08-24T01:46:12Z

Ianscottknight:

''pydock3'' is a Python package wrapping the [[DOCK|DOCK Fortran program]] that provides tools to help standardize and automate the computational methods employed in molecular docking. It is a natural successor to DOCK Blaster, originally published in 2009, and blastermaster.py, part of the [[DOCK 3.7]] release in 2012.

[[Pydock3_logo.png]]

Scripts included in ''pydock3'':
* ''dockopt'': generate many different docking configurations, perform retrospective docking on them in parallel using a specified job scheduler (e.g. Slurm), and analyze the results.
* ''blastermaster'': generate a specific docking configuration for a given receptor and ligand, intended for use by experts who wish to tune the docking model themselves. This is a direct successor of blastermaster.py from DOCK 3.7.

A [[docking configuration|'''docking configuration''']] is a unique set of (1) DOCK parameter files (e.g., ''matching_spheres.sph''), (2) an INDOCK file, and (3) a DOCK executable.

= Installation =

See: [[DOCK 3.8:How to install pydock3]].

= Instructions =

== ''blastermaster'' ==

See: [[blastermaster (pydock3 script)]].

== ''dockopt'' ==

See: [[dockopt (pydock3 script)]].

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/python3.8.5.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/python3.8.5.sh

[[Category:DOCK 3.8]]
[[Category:DOCK Blaster]]

File:Pydock3 logo.png

2023-08-24T01:44:22Z

Ianscottknight:

pydock3 logo

Dockopt (pydock3 script)

2023-07-27T22:31:21Z

Ianscottknight:

''dockopt'' allows the generation of many different docking configurations which are then evaluated & analyzed in parallel using a specified job scheduler (e.g. Slurm). If you are a Shoichet Lab user, please see a special section for you, below.

To use DOCK 3.8, you must first license it and install it.
[[DOCK 3.8:How to install pydock3]]

== ''new'' ==

Prepare rec.pdb, xtal-lig.pdb as described in Bender, 2021. https://pubmed.ncbi.nlm.nih.gov/34561691/
Or download pre-preared sample files from dudez2022.docking.org.

Be sure that you are in the directory containing the required input files:
* ''rec.pdb'' or ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''positives.tgz''
* ''negatives.tgz''

Note the inclusion of ''positives.tgz'' and ''negatives.tgz''. Each of these is a tarball of DB2 files, which may be optionally gzipped (with extension .db2.gz). Each tarball represents a binary class for the binary classification task that the docking model is trained on. The positive class contains the molecules that you want the docking model to preferentially assign ''favorable'' docking scores to. The negative class contains the molecules that you want the docking model to preferentially assign ''unfavorable'' scores to. The most common strategy is to use a set of known ligands as the positive class and a larger set of property-matched decoys for the negative class (a decoy-to-active ratio of 50:1 is standard), but other strategies are supported. For example, to create a docking model that preferentially assigns favorable scores to agonists over antagonists, a set of agonists can be used as the positive class and a set of antagonists can be used for the negative class.

Therefore, you need to build the molecules yourself (see: https://tldr.docking.org/start/build3d38). Each tarball should contain only DB2 files. For example, if one has a directory ''actives/'' containing only DB2 files to use as the positive class, then ''positives.tgz'' should be created as follows:

cd actives/
tar -czf positives.tgz *.db2*

Similarly, for a directory ''decoys/'' containing only DB2 files to use as the negative class, ''negatives.tgz'' should be created as follows:

cd decoys/
tar -czf negatives.tgz *.db2*

To create the file structure for your dockopt job, simply type

pydock3 dockopt - new [--job_dir_name=dockopt_job]

By default, the job directory is named ''dockopt_job''. To specify a different name, use the "--job_dir_name" flag. E.g.:

pydock3 dockopt - new --job_dir_name=dockopt_job_2

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''retrodock_jobs'': individual retrodock jobs for each docking configuration

The key difference between the working directories of ''blastermaster'' and ''dockopt'' is that the working directory of ''dockopt'' may contain multiple variants of the blaster files (suffixed by a number, e.g. "box_1"). These variant files are used to create the different docking configurations specified by the multi-valued entries of ''dockopt_config.yaml''. They are created efficiently, such that the same variant used in multiple docking configurations is not created more than once.

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the dockopt job.

* ''rec.pdb''
* ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb'' or ''rec.crg.pdb''. Either is required, but not both. If both are present, only ''rec.crg.pdb'' is used.
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''dockopt_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of dockopt.

'''Note:''' The ''dockopt_config.yaml'' file differs from the ''blastermaster_config.yaml'' file in that every parameter of the former may accept either a single value or a ''list of comma-separated values'', which indicates a pool of values to attempt for that parameter. Multiple such multi-valued parameters may be provided, and all unique resultant docking configurations will be attempted.

Single-valued YAML line format:

distance_to_surface: 1.0

Multi-valued YAML line format:

distance_to_surface: [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]

== Environmental variables ==

=== TMPDIR ===

Designate where temporary job files should be placed. E.g.:

export TMPDIR=/scratch

==== Note for UCSF researchers ====

On the Wynton cluster, ''/scratch'' only exists on development nodes (not log nodes). Therefore, we recommend running on development nodes (see: https://wynton.ucsf.edu/hpc/get-started/development-prototyping.html). E.g.:

ssh dev1
export TMPDIR=/scratch

If a log node must be used, then ''/wynton/scratch'' may be used:

ssh log1
export TMPDIR=/wynton/scratch

=== job scheduler environmental variables ===

In order for ''dockopt'' to know which scheduler it should use, please configure the following environmental variables according to which one of the job schedulers you have.

==== Slurm ====

E.g., on the UCSF Shoichet Lab Gimel cluster (on any node other than 'gimel' itself, such as 'gimel5'):

export SBATCH_EXEC=/usr/bin/sbatch
export SQUEUE_EXEC=/usr/bin/squeue

==== SGE ====

On most clusters using SGE the following should be correct:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/default/common/settings.sh

===== Note for UCSF researchers =====

The following is necessary on the UCSF Wynton cluster:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/wynton/common/settings.sh

== ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run ''dockopt'':
cd <JOB_DIR_NAME>
pydock3 dockopt - run <JOB_SCHEDULER_NAME> [--retrodock_job_timeout_minutes=None] [--retrodock_job_max_reattempts=0] [--extra_submission_cmd_params_str=None] [--export_negatives_mol2=False]

where <JOB_SCHEDULER_NAME> is one of:
* ''sge''
* ''slurm''

This will execute the many dockopt subroutines in sequence. Once this is done, the retrodock jobs for all created docking configurations are run in parallel via the scheduler. The state of the program will be printed to standard output as it runs.

Once the dockopt job is complete, the following files will be generated in the job directory:
* ''report.html'': contains (1) a histogram of the performance of all tested docking configurations compared against a distribution of the performance of a random classifier, so as to show whether the test docking configurations are significantly better than ones that can be produced by a random classifier. This is necessary due to the fact that many configurations are being tested. Hence, a Bonferroni correction is applied to the significance threshold, dividing p=0.01 by the number of tested configurations. (2) ROC, charge, and energy plots of the top docking configurations, comparing positive class molecules vs. negative class molecules, (3) box plots of enrichment for every multi-valued config parameter, and (4) heatmaps of enrichment for every pair of multi-valued config parameters.
* ''results.csv'': parameter values, criterion values, and other information about each docking configuration.

In addition, some number of the best retrodock jobs will be copied to their own sub-directory ''best_retrodock_jobs/''.

Within ''best_retrodock_jobs/'', there are the following files and sub-directories:
* ''dockfiles/'': parameters files and ''INDOCK'' for given docking configuration
* ''output/'': contains:
** joblist
** sub-directories ''positives/'' (containing ''OUTDOCK'' and ''test.mol2'' files) and ''negatives/'' (containing just ''OUTDOCK'')
** log files for the retrodock jobs
* plot images (e.g., ''roc.png'')

'''Note:''' by default, a mol2 file is exported only for positives, not for negatives, in order to prevent disk space issues.

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable and declare default environmental variables:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/env.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/env.sh

Blastermaster (pydock3 script)

2023-06-09T18:52:21Z

Ianscottknight:

''blastermaster'' allows the generation of a specific docking configuration for a given receptor and ligand.

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/python3.8.5.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/python3.8.5.sh

== ''new'' ==

First you need to create the file structure for your blastermaster job. To do so, simply type

pydock3 blastermaster - new

By default, the job directory is named ''blastermaster_job''. To specify a different name, type

pydock3 blastermaster - new <JOB_DIR_NAME>

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''dockfiles'': output files (DOCK parameter files & INDOCK)

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the blastermaster job.

* ''rec.pdb''
* ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb''
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, then copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''blastermaster_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of blastermaster.

== ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run blastermaster:
cd <JOB_DIR_NAME>
pydock3 blastermaster - run

This will execute the many blastermaster subroutines in sequence. The state of the program will be printed to standard output as it runs.

Dockopt (pydock3 script)

2023-06-05T19:15:07Z

Ianscottknight:

''dockopt'' allows the generation of many different docking configurations which are then evaluated & analyzed in parallel using a specified job scheduler (e.g. Slurm). If you are a Shoichet Lab user, please see a special section for you, below.

To use DOCK 3.8, you must first license it and install it.
[[DOCK 3.8:How to install pydock3]]

== ''new'' ==

Prepare rec.pdb, xtal-lig.pdb as described in Bender, 2021. https://pubmed.ncbi.nlm.nih.gov/34561691/
Or download pre-preared sample files from dudez2022.docking.org.

Be sure that you are in the directory containing the required input files:
* ''rec.pdb'' or ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''positives.tgz''
* ''negatives.tgz''

Note the inclusion of ''positives.tgz'' and ''negatives.tgz''. Each of these is a tarball of DB2 files, which may be optional gzipped (with extension .db2.gz). Each tarball represents a binary class for the binary classification task that the docking model is trained on. The positive class contains the molecules that you want the docking model to preferentially assign ''favorable'' docking scores to. The negative class contains the molecules that you want the docking model to preferentially assign ''unfavorable'' scores to. The most common strategy is to use a set of known ligands as the positive class and a larger set of property-matched decoys for the negative class (a decoy-to-active ratio of 50:1 is standard), but other strategies are supported. For example, to create a docking model that preferentially assigns favorable scores to agonists over antagonists, a set of agonists can be used as the positive class and a set of antagonists can be used for the negative class.

Therefore, you need to build the molecules yourself (see: https://tldr.docking.org/start/build3d38). Each tarball should contain only DB2 files. For example, if one has a directory ''actives/'' containing only DB2 files to use as the positive class, then ''positives.tgz'' should be created as follows:

cd actives/
tar -czf positives.tgz *.db2*

Similarly, for a directory ''decoys/'' containing only DB2 files to use as the negative class, ''negatives.tgz'' should be created as follows:

cd decoys/
tar -czf negatives.tgz *.db2*

To create the file structure for your dockopt job, simply type

pydock3 dockopt - new [--job_dir_name=dockopt_job]

By default, the job directory is named ''dockopt_job''. To specify a different name, use the "--job_dir_name" flag. E.g.:

pydock3 dockopt - new --job_dir_name=dockopt_job_2

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''retrodock_jobs'': individual retrodock jobs for each docking configuration

The key difference between the working directories of ''blastermaster'' and ''dockopt'' is that the working directory of ''dockopt'' may contain multiple variants of the blaster files (suffixed by a number, e.g. "box_1"). These variant files are used to create the different docking configurations specified by the multi-valued entries of ''dockopt_config.yaml''. They are created efficiently, such that the same variant used in multiple docking configurations is not created more than once.

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the dockopt job.

* ''rec.pdb''
* ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb'' or ''rec.crg.pdb''. Either is required, but not both. If both are present, only ''rec.crg.pdb'' is used.
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''dockopt_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of dockopt.

'''Note:''' The ''dockopt_config.yaml'' file differs from the ''blastermaster_config.yaml'' file in that every parameter of the former may accept either a single value or a ''list of comma-separated values'', which indicates a pool of values to attempt for that parameter. Multiple such multi-valued parameters may be provided, and all unique resultant docking configurations will be attempted.

Single-valued YAML line format:

distance_to_surface: 1.0

Multi-valued YAML line format:

distance_to_surface: [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]

== Environmental variables ==

=== TMPDIR ===

Designate where temporary job files should be placed. E.g.:

export TMPDIR=/scratch

==== Note for UCSF researchers ====

On the Wynton cluster, ''/scratch'' only exists on development nodes (not log nodes). Therefore, we recommend running on development nodes (see: https://wynton.ucsf.edu/hpc/get-started/development-prototyping.html). E.g.:

ssh dev1
export TMPDIR=/scratch

If a log node must be used, then ''/wynton/scratch'' may be used:

ssh log1
export TMPDIR=/wynton/scratch

=== job scheduler environmental variables ===

In order for ''dockopt'' to know which scheduler it should use, please configure the following environmental variables according to which one of the job schedulers you have.

==== Slurm ====

E.g., on the UCSF Shoichet Lab Gimel cluster (on any node other than 'gimel' itself, such as 'gimel5'):

export SBATCH_EXEC=/usr/bin/sbatch
export SQUEUE_EXEC=/usr/bin/squeue

==== SGE ====

On most clusters using SGE the following should be correct:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/default/common/settings.sh

===== Note for UCSF researchers =====

The following is necessary on the UCSF Wynton cluster:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/wynton/common/settings.sh

== ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run ''dockopt'':
cd <JOB_DIR_NAME>
pydock3 dockopt - run <JOB_SCHEDULER_NAME> [--retrodock_job_timeout_minutes=None] [--retrodock_job_max_reattempts=0] [--extra_submission_cmd_params_str=None] [--export_negatives_mol2=False]

where <JOB_SCHEDULER_NAME> is one of:
* ''sge''
* ''slurm''

This will execute the many dockopt subroutines in sequence. Once this is done, the retrodock jobs for all created docking configurations are run in parallel via the scheduler. The state of the program will be printed to standard output as it runs.

Once the dockopt job is complete, the following files will be generated in the job directory:
* ''report.html'': contains (1) a histogram of the performance of all tested docking configurations compared against a distribution of the performance of a random classifier, so as to show whether the test docking configurations are significantly better than ones that can be produced by a random classifier. This is necessary due to the fact that many configurations are being tested. Hence, a Bonferroni correction is applied to the significance threshold, dividing p=0.01 by the number of tested configurations. (2) ROC, charge, and energy plots of the top docking configurations, comparing positive class molecules vs. negative class molecules, (3) box plots of enrichment for every multi-valued config parameter, and (4) heatmaps of enrichment for every pair of multi-valued config parameters.
* ''results.csv'': parameter values, criterion values, and other information about each docking configuration.

In addition, some number of the best retrodock jobs will be copied to their own sub-directory ''best_retrodock_jobs/''.

Within ''best_retrodock_jobs/'', there are the following files and sub-directories:
* ''dockfiles/'': parameters files and ''INDOCK'' for given docking configuration
* ''output/'': contains:
** joblist
** sub-directories ''positives/'' (containing ''OUTDOCK'' and ''test.mol2'' files) and ''negatives/'' (containing just ''OUTDOCK'')
** log files for the retrodock jobs
* plot images (e.g., ''roc.png'')

'''Note:''' by default, a mol2 file is exported only for positives, not for negatives, in order to prevent disk space issues.

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable and declare default environmental variables:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/env.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/env.sh

Dockopt (pydock3 script)

2023-06-05T03:43:04Z

Ianscottknight:

''dockopt'' allows the generation of many different docking configurations which are then evaluated & analyzed in parallel using a specified job scheduler (e.g. Slurm). If you are a Shoichet Lab user, please see a special section for you, below.

To use DOCK 3.8, you must first license it and install it.
[[DOCK 3.8:How to install pydock3]]

== ''new'' ==

Prepare rec.pdb, xtal-lig.pdb as described in Bender, 2021. https://pubmed.ncbi.nlm.nih.gov/34561691/
Or download pre-preared sample files from dudez2022.docking.org.

Be sure that you are in the directory containing the required input files:
* ''rec.pdb'' or ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''positives.tgz''
* ''negatives.tgz''

Note the inclusion of ''positives.tgz'' and ''negatives.tgz''. Each of these is a tarball of DB2 files, which may be optional gzipped (with extension .db2.gz). Each tarball represents a binary class for the binary classification task that the docking model is trained on. The positive class contains the molecules that you want the docking model to preferentially assign ''favorable'' docking scores to. The negative class contains the molecules that you want the docking model to preferentially assign ''unfavorable'' scores to. The most common strategy is to use a set of known ligands as the positive class and a larger set of property-matched decoys for the negative class (a decoy-to-active ratio of 50:1 is standard), but other strategies are supported. For example, to create a docking model that preferentially assigns favorable scores to agonists over antagonists, a set of agonists can be used as the positive class and a set of antagonists can be used for the negative class.

Therefore, you need to build the molecules yourself (see: https://tldr.docking.org/start/build3d38). Each tarball should contain only DB2 files. For example, if one has a directory ''actives/'' containing only DB2 files to use as the positive class, then ''positives.tgz'' should be created as follows:

cd actives/
tar -czf positives.tgz *.db2*

Similarly, for a directory ''decoys/'' containing only DB2 files to use as the negative class, ''negatives.tgz'' should be created as follows:

cd decoys/
tar -czf negatives.tgz *.db2*

To create the file structure for your dockopt job, simply type

pydock3 dockopt - new [--job_dir_name=dockopt_job]

By default, the job directory is named ''dockopt_job''. To specify a different name, use the "--job_dir_name" flag. E.g.:

pydock3 dockopt - new --job_dir_name=dockopt_job_2

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''retrodock_jobs'': individual retrodock jobs for each docking configuration

The key difference between the working directories of ''blastermaster'' and ''dockopt'' is that the working directory of ''dockopt'' may contain multiple variants of the blaster files (suffixed by a number, e.g. "box_1"). These variant files are used to create the different docking configurations specified by the multi-valued entries of ''dockopt_config.yaml''. They are created efficiently, such that the same variant used in multiple docking configurations is not created more than once.

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the dockopt job.

* ''rec.pdb''
* ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb'' or ''rec.crg.pdb''. Either is required, but not both. If both are present, only ''rec.crg.pdb'' is used.
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''dockopt_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of dockopt.

'''Note:''' The ''dockopt_config.yaml'' file differs from the ''blastermaster_config.yaml'' file in that every parameter of the former may accept either a single value or a ''list of comma-separated values'', which indicates a pool of values to attempt for that parameter. Multiple such multi-valued parameters may be provided, and all unique resultant docking configurations will be attempted.

Single-valued YAML line format:

distance_to_surface: 1.0

Multi-valued YAML line format:

distance_to_surface: [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]

== Environmental variables ==

=== TMPDIR ===

Designate where temporary job files should be placed. E.g.:

export TMPDIR=/scratch

==== Note for UCSF researchers ====

On the Wynton cluster, ''/scratch'' only exists on development nodes (not log nodes). Therefore, we recommend running on development nodes (see: https://wynton.ucsf.edu/hpc/get-started/development-prototyping.html). E.g.:

ssh dev1
export TMPDIR=/scratch

If a log node must be used, then ''/wynton/scratch'' may be used:

ssh log1
export TMPDIR=/wynton/scratch

=== job scheduler environmental variables ===

In order for ''dockopt'' to know which scheduler it should use, please configure the following environmental variables according to which one of the job schedulers you have.

==== Slurm ====

E.g., on the UCSF Shoichet Lab Gimel cluster (on any node other than 'gimel' itself, such as 'gimel5'):

export SBATCH_EXEC=/usr/bin/sbatch
export SQUEUE_EXEC=/usr/bin/squeue

==== SGE ====

On most clusters using SGE the following should be correct:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/default/common/settings.sh

===== Note for UCSF researchers =====

The following is necessary on the UCSF Wynton cluster:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/wynton/common/settings.sh

== ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run ''dockopt'':
cd <JOB_DIR_NAME>
pydock3 dockopt - run <JOB_SCHEDULER_NAME> [--retrodock_job_timeout_minutes=None] [--retrodock_job_max_reattempts=0] [--extra_submission_cmd_params_str=None] [--export_negatives_mol2=False]

where <JOB_SCHEDULER_NAME> is one of:
* ''sge''
* ''slurm''

This will execute the many dockopt subroutines in sequence. Once this is done, the retrodock jobs for all created docking configurations are run in parallel via the scheduler. The state of the program will be printed to standard output as it runs.

Once the dockopt job is complete, the following files will be generated in the job directory:
* ''report.html'': contains (1) a histogram of the performance of all tested docking configurations compared against a distribution of the performance of a random classifier, so as to show whether the test docking configurations are significantly better than ones that can be produced by a random classifier. This is necessary due to the fact that many configurations are being tested. Hence, a Bonferroni correction is applied to the significance threshold, dividing p=0.01 by the number of tested configurations. (2) ROC, charge, and energy plots of the top docking configurations, comparing positive class molecules vs. negative class molecules, (3) box plots of enrichment for every multi-valued config parameter, and (4) heatmaps of enrichment for every pair of multi-valued config parameters.
* ''results.csv'': parameter values, criterion values, and other information about each docking configuration.

In addition, some number of the best retrodock jobs will be copied to their own sub-directory ''best_retrodock_jobs/''.

Within ''best_retrodock_jobs/'', there are the following files and sub-directories:
* ''dockfiles/'': parameters files and INDOCK for given docking configuration
* ''output/'': contains:
** joblist
** sub-directories ''1/'' for positives and ''2/'' for negatives (the former containing OUTDOCK and test.mol2 files, the latter containing just OUTDOCK)
** log files for the retrodock jobs
* ''roc.png'': the ROC enrichment curve (log-scaled x-axis) for given docking configuration

'''Note:''' by default, a mol2 file is exported only for positives (''output/1/''), not for negatives (''output/2/''), in order to prevent disk space issues.

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable and declare default environmental variables:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/env.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/env.sh

Dockopt (pydock3 script)

2023-06-05T01:49:17Z

Ianscottknight:

''dockopt'' allows the generation of many different docking configurations which are then evaluated & analyzed in parallel using a specified job scheduler (e.g. Slurm). If you are a Shoichet Lab user, please see a special section for you, below.

To use DOCK 3.8, you must first license it and install it.
[[DOCK 3.8:How to install pydock3]]

== ''new'' ==

Prepare rec.pdb, xtal-lig.pdb as described in Bender, 2021. https://pubmed.ncbi.nlm.nih.gov/34561691/
Or download pre-preared sample files from dudez2022.docking.org.

Be sure that you are in the directory containing the required input files:
* ''rec.pdb'' or ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''positives.tgz''
* ''negatives.tgz''

Note the inclusion of ''positives.tgz'' and ''negatives.tgz''. Each of these is a tarball of DB2 files. Each tarball represents a binary class for the binary classification task that the docking model is trained on. The positive class contains the molecules that you want the docking model to preferentially assign ''favorable'' docking scores to. The negative class contains the molecules that you want the docking model to preferentially assign ''unfavorable'' scores to. The most common strategy is to use a set of known ligands as the positive class and a larger set of property-matched decoys for the negative class (a decoy-to-active ratio of 50:1 is standard), but other strategies are supported. For example, to create a docking model that preferentially assigns favorable scores to agonists over antagonists, a set of agonists can be used as the positive class and a set of antagonists can be used for the negative class.

Therefore, you need to build the molecules yourself (see: https://tldr.docking.org/start/build3d38). Each tarball should contain only DB2 files. For example, if one has a directory ''actives/'' containing only DB2 files to use as the positive class, then ''positives.tgz'' should be created as follows:

cd actives/
tar -czf positives.tgz *.db2*

Similarly, for a directory ''decoys/'' containing only DB2 files to use as the negative class, ''negatives.tgz'' should be created as follows:

cd decoys/
tar -czf negatives.tgz *.db2*

To create the file structure for your dockopt job, simply type

pydock3 dockopt - new [--job_dir_name=dockopt_job]

By default, the job directory is named ''dockopt_job''. To specify a different name, use the "--job_dir_name" flag. E.g.:

pydock3 dockopt - new --job_dir_name=dockopt_job_2

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''retrodock_jobs'': individual retrodock jobs for each docking configuration

The key difference between the working directories of ''blastermaster'' and ''dockopt'' is that the working directory of ''dockopt'' may contain multiple variants of the blaster files (suffixed by a number, e.g. "box_1"). These variant files are used to create the different docking configurations specified by the multi-valued entries of ''dockopt_config.yaml''. They are created efficiently, such that the same variant used in multiple docking configurations is not created more than once.

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the dockopt job.

* ''rec.pdb''
* ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb'' or ''rec.crg.pdb''. Either is required, but not both. If both are present, only ''rec.crg.pdb'' is used.
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''dockopt_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of dockopt.

'''Note:''' The ''dockopt_config.yaml'' file differs from the ''blastermaster_config.yaml'' file in that every parameter of the former may accept either a single value or a ''list of comma-separated values'', which indicates a pool of values to attempt for that parameter. Multiple such multi-valued parameters may be provided, and all unique resultant docking configurations will be attempted.

Single-valued YAML line format:

distance_to_surface: 1.0

Multi-valued YAML line format:

distance_to_surface: [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]

== Environmental variables ==

=== TMPDIR ===

Designate where temporary job files should be placed. E.g.:

export TMPDIR=/scratch

==== Note for UCSF researchers ====

On the Wynton cluster, ''/scratch'' only exists on development nodes (not log nodes). Therefore, we recommend running on development nodes (see: https://wynton.ucsf.edu/hpc/get-started/development-prototyping.html). E.g.:

ssh dev1
export TMPDIR=/scratch

If a log node must be used, then ''/wynton/scratch'' may be used:

ssh log1
export TMPDIR=/wynton/scratch

=== job scheduler environmental variables ===

In order for ''dockopt'' to know which scheduler it should use, please configure the following environmental variables according to which one of the job schedulers you have.

==== Slurm ====

E.g., on the UCSF Shoichet Lab Gimel cluster (on any node other than 'gimel' itself, such as 'gimel5'):

export SBATCH_EXEC=/usr/bin/sbatch
export SQUEUE_EXEC=/usr/bin/squeue

==== SGE ====

On most clusters using SGE the following should be correct:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/default/common/settings.sh

===== Note for UCSF researchers =====

The following is necessary on the UCSF Wynton cluster:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/wynton/common/settings.sh

== ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run ''dockopt'':
cd <JOB_DIR_NAME>
pydock3 dockopt - run <JOB_SCHEDULER_NAME> [--retrodock_job_timeout_minutes=None] [--retrodock_job_max_reattempts=0] [--extra_submission_cmd_params_str=None] [--export_negatives_mol2=False]

where <JOB_SCHEDULER_NAME> is one of:
* ''sge''
* ''slurm''

This will execute the many dockopt subroutines in sequence. Once this is done, the retrodock jobs for all created docking configurations are run in parallel via the scheduler. The state of the program will be printed to standard output as it runs.

Once the dockopt job is complete, the following files will be generated in the job directory:
* ''report.html'': contains (1) a histogram of the performance of all tested docking configurations compared against a distribution of the performance of a random classifier, so as to show whether the test docking configurations are significantly better than ones that can be produced by a random classifier. This is necessary due to the fact that many configurations are being tested. Hence, a Bonferroni correction is applied to the significance threshold, dividing p=0.01 by the number of tested configurations. (2) ROC, charge, and energy plots of the top docking configurations, comparing positive class molecules vs. negative class molecules, (3) box plots of enrichment for every multi-valued config parameter, and (4) heatmaps of enrichment for every pair of multi-valued config parameters.
* ''results.csv'': parameter values, criterion values, and other information about each docking configuration.

In addition, some number of the best retrodock jobs will be copied to their own sub-directory ''best_retrodock_jobs/''.

Within ''best_retrodock_jobs/'', there are the following files and sub-directories:
* ''dockfiles/'': parameters files and INDOCK for given docking configuration
* ''output/'': contains:
** joblist
** sub-directories ''1/'' for positives and ''2/'' for negatives (the former containing OUTDOCK and test.mol2 files, the latter containing just OUTDOCK)
** log files for the retrodock jobs
* ''roc.png'': the ROC enrichment curve (log-scaled x-axis) for given docking configuration

'''Note:''' by default, a mol2 file is exported only for positives (''output/1/''), not for negatives (''output/2/''), in order to prevent disk space issues.

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable and declare default environmental variables:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/env.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/env.sh

Dockopt (pydock3 script)

2023-06-05T01:45:13Z

Ianscottknight:

''dockopt'' allows the generation of many different docking configurations which are then evaluated & analyzed in parallel using a specified job scheduler (e.g. Slurm). If you are a Shoichet Lab user, please see a special section for you, below.

To use DOCK 3.8, you must first license it and install it.
[[DOCK 3.8:How to install pydock3]]

== ''new'' ==

Prepare rec.pdb, xtal-lig.pdb as described in Bender, 2021. https://pubmed.ncbi.nlm.nih.gov/34561691/
Or download pre-preared sample files from dudez2022.docking.org.

Be sure that you are in the directory containing the required input files:
* ''rec.pdb'' or ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''positives.tgz''
* ''negatives.tgz''

Note the inclusion of ''positives.tgz'' and ''negatives.tgz''. Each of these is a tarball of .db2 files. Each tarball represents a binary class for the binary classification task that the docking model is trained on. The positive class contains the molecules that you want the docking model to preferentially assign ''favorable'' docking scores to. The negative class contains the molecules that you want the docking model to preferentially assign ''unfavorable'' scores to. The most common strategy is to use a set of known ligands as the positive class and a larger set of property-matched decoys for the negative class (a decoy-to-active ratio of 50:1 is standard), but other strategies are supported. For example, to create a docking model that preferentially assigns favorable scores to agonists over antagonists, a set of agonists can be used as the positive class and a set of antagonists can be used for the negative class.

Therefore, you need to build the molecules yourself (see: https://tldr.docking.org/start/build3d38). Each tarball should contain only DB2 files. For example, if one has a directory ''actives/'' of active molecules to use as the positives for a DockOpt job, then the following would be how to create ''positives.tgz'':

cd actives/
tar -czf positives.tgz *.db2*

Similarly, for a directory ''decoys/'' of corresponding decoy molecules, one can create ''negatives.tgz'' as follows:

cd decoys/
tar -czf negatives.tgz *.db2*

To create the file structure for your dockopt job, simply type

pydock3 dockopt - new [--job_dir_name=dockopt_job]

By default, the job directory is named ''dockopt_job''. To specify a different name, use the "--job_dir_name" flag. E.g.:

pydock3 dockopt - new --job_dir_name=dockopt_job_2

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''retrodock_jobs'': individual retrodock jobs for each docking configuration

The key difference between the working directories of ''blastermaster'' and ''dockopt'' is that the working directory of ''dockopt'' may contain multiple variants of the blaster files (suffixed by a number, e.g. "box_1"). These variant files are used to create the different docking configurations specified by the multi-valued entries of ''dockopt_config.yaml''. They are created efficiently, such that the same variant used in multiple docking configurations is not created more than once.

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the dockopt job.

* ''rec.pdb''
* ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb'' or ''rec.crg.pdb''. Either is required, but not both. If both are present, only ''rec.crg.pdb'' is used.
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''dockopt_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of dockopt.

'''Note:''' The ''dockopt_config.yaml'' file differs from the ''blastermaster_config.yaml'' file in that every parameter of the former may accept either a single value or a ''list of comma-separated values'', which indicates a pool of values to attempt for that parameter. Multiple such multi-valued parameters may be provided, and all unique resultant docking configurations will be attempted.

Single-valued YAML line format:

distance_to_surface: 1.0

Multi-valued YAML line format:

distance_to_surface: [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]

== Environmental variables ==

=== TMPDIR ===

Designate where temporary job files should be placed. E.g.:

export TMPDIR=/scratch

==== Note for UCSF researchers ====

On the Wynton cluster, ''/scratch'' only exists on development nodes (not log nodes). Therefore, we recommend running on development nodes (see: https://wynton.ucsf.edu/hpc/get-started/development-prototyping.html). E.g.:

ssh dev1
export TMPDIR=/scratch

If a log node must be used, then ''/wynton/scratch'' may be used:

ssh log1
export TMPDIR=/wynton/scratch

=== job scheduler environmental variables ===

In order for ''dockopt'' to know which scheduler it should use, please configure the following environmental variables according to which one of the job schedulers you have.

==== Slurm ====

E.g., on the UCSF Shoichet Lab Gimel cluster (on any node other than 'gimel' itself, such as 'gimel5'):

export SBATCH_EXEC=/usr/bin/sbatch
export SQUEUE_EXEC=/usr/bin/squeue

==== SGE ====

On most clusters using SGE the following should be correct:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/default/common/settings.sh

===== Note for UCSF researchers =====

The following is necessary on the UCSF Wynton cluster:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/wynton/common/settings.sh

== ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run ''dockopt'':
cd <JOB_DIR_NAME>
pydock3 dockopt - run <JOB_SCHEDULER_NAME> [--retrodock_job_timeout_minutes=None] [--retrodock_job_max_reattempts=0] [--extra_submission_cmd_params_str=None] [--export_negatives_mol2=False]

where <JOB_SCHEDULER_NAME> is one of:
* ''sge''
* ''slurm''

This will execute the many dockopt subroutines in sequence. Once this is done, the retrodock jobs for all created docking configurations are run in parallel via the scheduler. The state of the program will be printed to standard output as it runs.

Once the dockopt job is complete, the following files will be generated in the job directory:
* ''report.html'': contains (1) a histogram of the performance of all tested docking configurations compared against a distribution of the performance of a random classifier, so as to show whether the test docking configurations are significantly better than ones that can be produced by a random classifier. This is necessary due to the fact that many configurations are being tested. Hence, a Bonferroni correction is applied to the significance threshold, dividing p=0.01 by the number of tested configurations. (2) ROC, charge, and energy plots of the top docking configurations, comparing positive class molecules vs. negative class molecules, (3) box plots of enrichment for every multi-valued config parameter, and (4) heatmaps of enrichment for every pair of multi-valued config parameters.
* ''results.csv'': parameter values, criterion values, and other information about each docking configuration.

In addition, some number of the best retrodock jobs will be copied to their own sub-directory ''best_retrodock_jobs/''.

Within ''best_retrodock_jobs/'', there are the following files and sub-directories:
* ''dockfiles/'': parameters files and INDOCK for given docking configuration
* ''output/'': contains:
** joblist
** sub-directories ''1/'' for positives and ''2/'' for negatives (the former containing OUTDOCK and test.mol2 files, the latter containing just OUTDOCK)
** log files for the retrodock jobs
* ''roc.png'': the ROC enrichment curve (log-scaled x-axis) for given docking configuration

'''Note:''' by default, a mol2 file is exported only for positives (''output/1/''), not for negatives (''output/2/''), in order to prevent disk space issues.

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable and declare default environmental variables:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/env.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/env.sh

Dockopt (pydock3 script)

2023-06-05T01:44:02Z

Ianscottknight:

''dockopt'' allows the generation of many different docking configurations which are then evaluated & analyzed in parallel using a specified job scheduler (e.g. Slurm). If you are a Shoichet Lab user, please see a special section for you, below.

To use DOCK 3.8, you must first license it and install it.
[[DOCK 3.8:How to install pydock3]]

== ''new'' ==

Prepare rec.pdb, xtal-lig.pdb as described in Bender, 2021. https://pubmed.ncbi.nlm.nih.gov/34561691/
Or download pre-preared sample files from dudez2022.docking.org.

Be sure that you are in the directory containing the required input files:
* ''rec.pdb'' or ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''positives.tgz''
* ''negatives.tgz''

Note the inclusion of ''positives.tgz'' and ''negatives.tgz''. Each of these is a tarball of .db2 files. Each tarball represents a binary class for the binary classification task that the docking model is trained on. The positive class contains the molecules that you want the docking model to preferentially assign ''favorable'' docking scores to. The negative class contains the molecules that you want the docking model to preferentially assign ''unfavorable'' scores to. The most common strategy is to use a set of known ligands as the positive class and a larger set of property-matched decoys for the negative class (a decoy-to-active ratio of 50:1 is standard), but other strategies are supported. For example, to create a docking model that preferentially assigns favorable scores to agonists over antagonists, a set of agonists can be used as the positive class and a set of antagonists can be used for the negative class.

Therefore, you need to build the molecules yourself (see: https://tldr.docking.org/start/build3d38). Each tarball should contain only DB2 files. For example, if one has a directory ''actives/'' of active molecules to use as the positives for a DockOpt job, then the following would be how to create ''positives.tgz'':

cd actives/
tar -czf positives.tgz *.db2*

Similarly, for a directory ''decoys/'' of corresponding decoy molecules, one can create ''negatives.tgz'' as follows:

cd decoys/
tar -czf negatives.tgz *.db2*

To create the file structure for your dockopt job, simply type

pydock3 dockopt - new

By default, the job directory is named ''dockopt_job''. To specify a different name, use the "--job_dir_name" flag. E.g.:

pydock3 dockopt - new --job_dir_name=dockopt_job_2

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''retrodock_jobs'': individual retrodock jobs for each docking configuration

The key difference between the working directories of ''blastermaster'' and ''dockopt'' is that the working directory of ''dockopt'' may contain multiple variants of the blaster files (suffixed by a number, e.g. "box_1"). These variant files are used to create the different docking configurations specified by the multi-valued entries of ''dockopt_config.yaml''. They are created efficiently, such that the same variant used in multiple docking configurations is not created more than once.

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the dockopt job.

* ''rec.pdb''
* ''rec.crg.pdb''
* ''xtal-lig.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb'' or ''rec.crg.pdb''. Either is required, but not both. If both are present, only ''rec.crg.pdb'' is used.
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''dockopt_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of dockopt.

'''Note:''' The ''dockopt_config.yaml'' file differs from the ''blastermaster_config.yaml'' file in that every parameter of the former may accept either a single value or a ''list of comma-separated values'', which indicates a pool of values to attempt for that parameter. Multiple such multi-valued parameters may be provided, and all unique resultant docking configurations will be attempted.

Single-valued YAML line format:

distance_to_surface: 1.0

Multi-valued YAML line format:

distance_to_surface: [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]

== Environmental variables ==

=== TMPDIR ===

Designate where temporary job files should be placed. E.g.:

export TMPDIR=/scratch

==== Note for UCSF researchers ====

On the Wynton cluster, ''/scratch'' only exists on development nodes (not log nodes). Therefore, we recommend running on development nodes (see: https://wynton.ucsf.edu/hpc/get-started/development-prototyping.html). E.g.:

ssh dev1
export TMPDIR=/scratch

If a log node must be used, then ''/wynton/scratch'' may be used:

ssh log1
export TMPDIR=/wynton/scratch

=== job scheduler environmental variables ===

In order for ''dockopt'' to know which scheduler it should use, please configure the following environmental variables according to which one of the job schedulers you have.

==== Slurm ====

E.g., on the UCSF Shoichet Lab Gimel cluster (on any node other than 'gimel' itself, such as 'gimel5'):

export SBATCH_EXEC=/usr/bin/sbatch
export SQUEUE_EXEC=/usr/bin/squeue

==== SGE ====

On most clusters using SGE the following should be correct:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/default/common/settings.sh

===== Note for UCSF researchers =====

The following is necessary on the UCSF Wynton cluster:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/wynton/common/settings.sh

== ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run ''dockopt'':
cd <JOB_DIR_NAME>
pydock3 dockopt - run <JOB_SCHEDULER_NAME> [--retrodock_job_timeout_minutes=None] [--retrodock_job_max_reattempts=0] [--extra_submission_cmd_params_str=None] [--export_negatives_mol2=False]

where <JOB_SCHEDULER_NAME> is one of:
* ''sge''
* ''slurm''

This will execute the many dockopt subroutines in sequence. Once this is done, the retrodock jobs for all created docking configurations are run in parallel via the scheduler. The state of the program will be printed to standard output as it runs.

Once the dockopt job is complete, the following files will be generated in the job directory:
* ''report.html'': contains (1) a histogram of the performance of all tested docking configurations compared against a distribution of the performance of a random classifier, so as to show whether the test docking configurations are significantly better than ones that can be produced by a random classifier. This is necessary due to the fact that many configurations are being tested. Hence, a Bonferroni correction is applied to the significance threshold, dividing p=0.01 by the number of tested configurations. (2) ROC, charge, and energy plots of the top docking configurations, comparing positive class molecules vs. negative class molecules, (3) box plots of enrichment for every multi-valued config parameter, and (4) heatmaps of enrichment for every pair of multi-valued config parameters.
* ''results.csv'': parameter values, criterion values, and other information about each docking configuration.

In addition, some number of the best retrodock jobs will be copied to their own sub-directory ''best_retrodock_jobs/''.

Within ''best_retrodock_jobs/'', there are the following files and sub-directories:
* ''dockfiles/'': parameters files and INDOCK for given docking configuration
* ''output/'': contains:
** joblist
** sub-directories ''1/'' for positives and ''2/'' for negatives (the former containing OUTDOCK and test.mol2 files, the latter containing just OUTDOCK)
** log files for the retrodock jobs
* ''roc.png'': the ROC enrichment curve (log-scaled x-axis) for given docking configuration

'''Note:''' by default, a mol2 file is exported only for positives (''output/1/''), not for negatives (''output/2/''), in order to prevent disk space issues.

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable and declare default environmental variables:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/env.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/env.sh

Dockopt (pydock3 script)

2023-06-05T01:42:46Z

Ianscottknight:

''dockopt'' allows the generation of many different docking configurations which are then evaluated & analyzed in parallel using a specified job scheduler (e.g. Slurm). If you are a Shoichet Lab user, please see a special section for you, below.

To use DOCK 3.8, you must first license it and install it.
[[DOCK 3.8:How to install pydock3]]

== ''new'' ==

Prepare rec.pdb, xtal-lig.pdb as described in Bender, 2021. https://pubmed.ncbi.nlm.nih.gov/34561691/
Or download pre-preared sample files from dudez2022.docking.org.

Be sure that you are in the directory containing the required input files:
* ''rec.pdb''
* ''xtal-lig.pdb''
* ''positives.tgz''
* ''negatives.tgz''

Note the inclusion of ''positives.tgz'' and ''negatives.tgz''. Each of these is a tarball of .db2 files. Each tarball represents a binary class for the binary classification task that the docking model is trained on. The positive class contains the molecules that you want the docking model to preferentially assign ''favorable'' docking scores to. The negative class contains the molecules that you want the docking model to preferentially assign ''unfavorable'' scores to. The most common strategy is to use a set of known ligands as the positive class and a larger set of property-matched decoys for the negative class (a decoy-to-active ratio of 50:1 is standard), but other strategies are supported. For example, to create a docking model that preferentially assigns favorable scores to agonists over antagonists, a set of agonists can be used as the positive class and a set of antagonists can be used for the negative class.

Therefore, you need to build the molecules yourself (see: https://tldr.docking.org/start/build3d38). Each tarball should contain only DB2 files. For example, if one has a directory ''actives/'' of active molecules to use as the positives for a DockOpt job, then the following would be how to create ''positives.tgz'':

cd actives/
tar -czf positives.tgz *.db2*

Similarly, for a directory ''decoys/'' of corresponding decoy molecules, one can create ''negatives.tgz'' as follows:

cd decoys/
tar -czf negatives.tgz *.db2*

To create the file structure for your dockopt job, simply type

pydock3 dockopt - new

By default, the job directory is named ''dockopt_job''. To specify a different name, use the "--job_dir_name" flag. E.g.:

pydock3 dockopt - new --job_dir_name=dockopt_job_2

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''retrodock_jobs'': individual retrodock jobs for each docking configuration

The key difference between the working directories of ''blastermaster'' and ''dockopt'' is that the working directory of ''dockopt'' may contain multiple variants of the blaster files (suffixed by a number, e.g. "box_1"). These variant files are used to create the different docking configurations specified by the multi-valued entries of ''dockopt_config.yaml''. They are created efficiently, such that the same variant used in multiple docking configurations is not created more than once.

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the dockopt job.

* ''rec.pdb''
* ''xtal-lig.pdb''
* ''rec.crg.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb'' or ''rec.crg.pdb''. Either is required, but not both. If both are present, only ''rec.crg.pdb'' is used.
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''dockopt_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of dockopt.

'''Note:''' The ''dockopt_config.yaml'' file differs from the ''blastermaster_config.yaml'' file in that every parameter of the former may accept either a single value or a ''list of comma-separated values'', which indicates a pool of values to attempt for that parameter. Multiple such multi-valued parameters may be provided, and all unique resultant docking configurations will be attempted.

Single-valued YAML line format:

distance_to_surface: 1.0

Multi-valued YAML line format:

distance_to_surface: [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]

== Environmental variables ==

=== TMPDIR ===

Designate where temporary job files should be placed. E.g.:

export TMPDIR=/scratch

==== Note for UCSF researchers ====

On the Wynton cluster, ''/scratch'' only exists on development nodes (not log nodes). Therefore, we recommend running on development nodes (see: https://wynton.ucsf.edu/hpc/get-started/development-prototyping.html). E.g.:

ssh dev1
export TMPDIR=/scratch

If a log node must be used, then ''/wynton/scratch'' may be used:

ssh log1
export TMPDIR=/wynton/scratch

=== job scheduler environmental variables ===

In order for ''dockopt'' to know which scheduler it should use, please configure the following environmental variables according to which one of the job schedulers you have.

==== Slurm ====

E.g., on the UCSF Shoichet Lab Gimel cluster (on any node other than 'gimel' itself, such as 'gimel5'):

export SBATCH_EXEC=/usr/bin/sbatch
export SQUEUE_EXEC=/usr/bin/squeue

==== SGE ====

On most clusters using SGE the following should be correct:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/default/common/settings.sh

===== Note for UCSF researchers =====

The following is necessary on the UCSF Wynton cluster:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/wynton/common/settings.sh

== ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run ''dockopt'':
cd <JOB_DIR_NAME>
pydock3 dockopt - run <JOB_SCHEDULER_NAME> [--retrodock_job_timeout_minutes=None] [--retrodock_job_max_reattempts=0] [--extra_submission_cmd_params_str=None] [--export_negatives_mol2=False]

where <JOB_SCHEDULER_NAME> is one of:
* ''sge''
* ''slurm''

This will execute the many dockopt subroutines in sequence. Once this is done, the retrodock jobs for all created docking configurations are run in parallel via the scheduler. The state of the program will be printed to standard output as it runs.

Once the dockopt job is complete, the following files will be generated in the job directory:
* ''report.html'': contains (1) a histogram of the performance of all tested docking configurations compared against a distribution of the performance of a random classifier, so as to show whether the test docking configurations are significantly better than ones that can be produced by a random classifier. This is necessary due to the fact that many configurations are being tested. Hence, a Bonferroni correction is applied to the significance threshold, dividing p=0.01 by the number of tested configurations. (2) ROC, charge, and energy plots of the top docking configurations, comparing positive class molecules vs. negative class molecules, (3) box plots of enrichment for every multi-valued config parameter, and (4) heatmaps of enrichment for every pair of multi-valued config parameters.
* ''results.csv'': parameter values, criterion values, and other information about each docking configuration.

In addition, some number of the best retrodock jobs will be copied to their own sub-directory ''best_retrodock_jobs/''.

Within ''best_retrodock_jobs/'', there are the following files and sub-directories:
* ''dockfiles/'': parameters files and INDOCK for given docking configuration
* ''output/'': contains:
** joblist
** sub-directories ''1/'' for positives and ''2/'' for negatives (the former containing OUTDOCK and test.mol2 files, the latter containing just OUTDOCK)
** log files for the retrodock jobs
* ''roc.png'': the ROC enrichment curve (log-scaled x-axis) for given docking configuration

'''Note:''' by default, a mol2 file is exported only for positives (''output/1/''), not for negatives (''output/2/''), in order to prevent disk space issues.

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable and declare default environmental variables:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/env.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/env.sh

Dockopt (pydock3 script)

2023-06-05T01:39:26Z

Ianscottknight:

''dockopt'' allows the generation of many different docking configurations which are then evaluated & analyzed in parallel using a specified job scheduler (e.g. Slurm). If you are a Shoichet Lab user, please see a special section for you, below.

To use DOCK 3.8, you must first license it and install it.
[[DOCK 3.8:How to install pydock3]]

== ''new'' ==

Prepare rec.pdb, xtal-lig.pdb as described in Bender, 2021. https://pubmed.ncbi.nlm.nih.gov/34561691/
Or download pre-preared sample files from dudez2022.docking.org.

Be sure that you are in the directory containing the required input files:
* ''rec.pdb''
* ''xtal-lig.pdb''
* ''positives.tgz''
* ''negatives.tgz''

Note the inclusion of ''positives.tgz'' and ''negatives.tgz''. Each of these is a tarball of .db2 files. Each tarball represents a binary class for the binary classification task that the docking model is trained on. The positive class contains the molecules that you want the docking model to preferentially assign ''favorable'' docking scores to. The negative class contains the molecules that you want the docking model to preferentially assign ''unfavorable'' scores to. The most common strategy is to use a set of known ligands as the positive class and a larger set of property-matched decoys for the negative class (a decoy-to-active ratio of 50:1 is standard), but other strategies are supported. For example, to create a docking model that preferentially assigns favorable scores to agonists over antagonists, a set of agonists can be used as the positive class and a set of antagonists can be used for the negative class.

Therefore, you need to build the molecules yourself (see: https://tldr.docking.org/start/build3d38). Each tarball should contain only DB2 files. For example, if one has a directory of active molecules ''actives/'' to use as the positives for a DockOpt job, then the following would be how to create ''positives.tgz'':

cd actives/
tar -czf positives.tgz *.db2*

Similarly, for a directory of corresponding decoy molecules ''decoys/'', one can create ''negatives.tgz'' as follows:

cd decoys/
tar -czf negatives.tgz *.db2*

To create the file structure for your dockopt job, simply type

pydock3 dockopt - new

By default, the job directory is named ''dockopt_job''. To specify a different name, use the "--job_dir_name" flag. E.g.:

pydock3 dockopt - new --job_dir_name=dockopt_job_2

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''retrodock_jobs'': individual retrodock jobs for each docking configuration

The key difference between the working directories of ''blastermaster'' and ''dockopt'' is that the working directory of ''dockopt'' may contain multiple variants of the blaster files (suffixed by a number, e.g. "box_1"). These variant files are used to create the different docking configurations specified by the multi-valued entries of ''dockopt_config.yaml''. They are created efficiently, such that the same variant used in multiple docking configurations is not created more than once.

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the dockopt job.

* ''rec.pdb''
* ''xtal-lig.pdb''
* ''rec.crg.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb'' or ''rec.crg.pdb''. Either is required, but not both. If both are present, only ''rec.crg.pdb'' is used.
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''dockopt_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of dockopt.

'''Note:''' The ''dockopt_config.yaml'' file differs from the ''blastermaster_config.yaml'' file in that every parameter of the former may accept either a single value or a ''list of comma-separated values'', which indicates a pool of values to attempt for that parameter. Multiple such multi-valued parameters may be provided, and all unique resultant docking configurations will be attempted.

Single-valued YAML line format:

distance_to_surface: 1.0

Multi-valued YAML line format:

distance_to_surface: [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]

== Environmental variables ==

=== TMPDIR ===

Designate where temporary job files should be placed. E.g.:

export TMPDIR=/scratch

==== Note for UCSF researchers ====

On the Wynton cluster, ''/scratch'' only exists on development nodes (not log nodes). Therefore, we recommend running on development nodes (see: https://wynton.ucsf.edu/hpc/get-started/development-prototyping.html). E.g.:

ssh dev1
export TMPDIR=/scratch

If a log node must be used, then ''/wynton/scratch'' may be used:

ssh log1
export TMPDIR=/wynton/scratch

=== job scheduler environmental variables ===

In order for ''dockopt'' to know which scheduler it should use, please configure the following environmental variables according to which one of the job schedulers you have.

==== Slurm ====

E.g., on the UCSF Shoichet Lab Gimel cluster (on any node other than 'gimel' itself, such as 'gimel5'):

export SBATCH_EXEC=/usr/bin/sbatch
export SQUEUE_EXEC=/usr/bin/squeue

==== SGE ====

On most clusters using SGE the following should be correct:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/default/common/settings.sh

===== Note for UCSF researchers =====

The following is necessary on the UCSF Wynton cluster:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/wynton/common/settings.sh

== ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run ''dockopt'':
cd <JOB_DIR_NAME>
pydock3 dockopt - run <JOB_SCHEDULER_NAME> [--retrodock_job_timeout_minutes=None] [--retrodock_job_max_reattempts=0] [--extra_submission_cmd_params_str=None] [--export_negatives_mol2=False]

where <JOB_SCHEDULER_NAME> is one of:
* ''sge''
* ''slurm''

This will execute the many dockopt subroutines in sequence. Once this is done, the retrodock jobs for all created docking configurations are run in parallel via the scheduler. The state of the program will be printed to standard output as it runs.

Once the dockopt job is complete, the following files will be generated in the job directory:
* ''report.html'': contains (1) a histogram of the performance of all tested docking configurations compared against a distribution of the performance of a random classifier, so as to show whether the test docking configurations are significantly better than ones that can be produced by a random classifier. This is necessary due to the fact that many configurations are being tested. Hence, a Bonferroni correction is applied to the significance threshold, dividing p=0.01 by the number of tested configurations. (2) ROC, charge, and energy plots of the top docking configurations, comparing positive class molecules vs. negative class molecules, (3) box plots of enrichment for every multi-valued config parameter, and (4) heatmaps of enrichment for every pair of multi-valued config parameters.
* ''results.csv'': parameter values, criterion values, and other information about each docking configuration.

In addition, some number of the best retrodock jobs will be copied to their own sub-directory ''best_retrodock_jobs/''.

Within ''best_retrodock_jobs/'', there are the following files and sub-directories:
* ''dockfiles/'': parameters files and INDOCK for given docking configuration
* ''output/'': contains:
** joblist
** sub-directories ''1/'' for positives and ''2/'' for negatives (the former containing OUTDOCK and test.mol2 files, the latter containing just OUTDOCK)
** log files for the retrodock jobs
* ''roc.png'': the ROC enrichment curve (log-scaled x-axis) for given docking configuration

'''Note:''' by default, a mol2 file is exported only for positives (''output/1/''), not for negatives (''output/2/''), in order to prevent disk space issues.

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable and declare default environmental variables:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/env.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/env.sh

Dockopt (pydock3 script)

2023-06-05T01:27:51Z

Ianscottknight:

''dockopt'' allows the generation of many different docking configurations which are then evaluated & analyzed in parallel using a specified job scheduler (e.g. Slurm). If you are a Shoichet Lab user, please see a special section for you, below.

To use DOCK 3.8, you must first license it and install it.
[[DOCK 3.8:How to install pydock3]]

== ''new'' ==

Prepare rec.pdb, xtal-lig.pdb as described in Bender, 2021. https://pubmed.ncbi.nlm.nih.gov/34561691/
Or download pre-preared sample files from dudez2022.docking.org.

Be sure that you are in the directory containing the required input files:
* ''rec.pdb''
* ''xtal-lig.pdb''
* ''positives.tgz''
* ''negatives.tgz''

Note the inclusion of ''positives.tgz'' and ''negatives.tgz''. Each of these is a tarball of a directory containing .db2 files. Therefore, you need to build the molecules yourself (see: https://tldr.docking.org/start/build3d38). Each tarball should contain only DB2 files. For example, if one has a directory of active molecules ''actives/'' to use as the positives for a DockOpt job, then the following would be how to create ''positives.tgz'':

cd actives/
tar -czf positives.tgz *.db2*

Similarly, for a directory of corresponding decoy molecules ''decoys/'', one can create ''negatives.tgz'' as follows:

cd decoys/
tar -czf negatives.tgz *.db2*

To create the file structure for your dockopt job, simply type

pydock3 dockopt - new

By default, the job directory is named ''dockopt_job''. To specify a different name, use the "--job_dir_name" flag. E.g.:

pydock3 dockopt - new --job_dir_name=dockopt_job_2

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''retrodock_jobs'': individual retrodock jobs for each docking configuration

The key difference between the working directories of ''blastermaster'' and ''dockopt'' is that the working directory of ''dockopt'' may contain multiple variants of the blaster files (suffixed by a number, e.g. "box_1"). These variant files are used to create the different docking configurations specified by the multi-valued entries of ''dockopt_config.yaml''. They are created efficiently, such that the same variant used in multiple docking configurations is not created more than once.

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the dockopt job.

* ''rec.pdb''
* ''xtal-lig.pdb''
* ''rec.crg.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb'' or ''rec.crg.pdb''. Either is required, but not both. If both are present, only ''rec.crg.pdb'' is used.
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''dockopt_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of dockopt.

'''Note:''' The ''dockopt_config.yaml'' file differs from the ''blastermaster_config.yaml'' file in that every parameter of the former may accept either a single value or a ''list of comma-separated values'', which indicates a pool of values to attempt for that parameter. Multiple such multi-valued parameters may be provided, and all unique resultant docking configurations will be attempted.

Single-valued YAML line format:

distance_to_surface: 1.0

Multi-valued YAML line format:

distance_to_surface: [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]

== Environmental variables ==

=== TMPDIR ===

Designate where temporary job files should be placed. E.g.:

export TMPDIR=/scratch

==== Note for UCSF researchers ====

On the Wynton cluster, ''/scratch'' only exists on development nodes (not log nodes). Therefore, we recommend running on development nodes (see: https://wynton.ucsf.edu/hpc/get-started/development-prototyping.html). E.g.:

ssh dev1
export TMPDIR=/scratch

If a log node must be used, then ''/wynton/scratch'' may be used:

ssh log1
export TMPDIR=/wynton/scratch

=== job scheduler environmental variables ===

In order for ''dockopt'' to know which scheduler it should use, please configure the following environmental variables according to which one of the job schedulers you have.

==== Slurm ====

E.g., on the UCSF Shoichet Lab Gimel cluster (on any node other than 'gimel' itself, such as 'gimel5'):

export SBATCH_EXEC=/usr/bin/sbatch
export SQUEUE_EXEC=/usr/bin/squeue

==== SGE ====

On most clusters using SGE the following should be correct:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/default/common/settings.sh

===== Note for UCSF researchers =====

The following is necessary on the UCSF Wynton cluster:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/wynton/common/settings.sh

== ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run ''dockopt'':
cd <JOB_DIR_NAME>
pydock3 dockopt - run <JOB_SCHEDULER_NAME> [--retrodock_job_timeout_minutes=None] [--retrodock_job_max_reattempts=0] [--extra_submission_cmd_params_str=None] [--export_negatives_mol2=False]

where <JOB_SCHEDULER_NAME> is one of:
* ''sge''
* ''slurm''

This will execute the many dockopt subroutines in sequence. Once this is done, the retrodock jobs for all created docking configurations are run in parallel via the scheduler. The state of the program will be printed to standard output as it runs.

Once the dockopt job is complete, the following files will be generated in the job directory:
* ''report.html'': contains (1) a histogram of the performance of all tested docking configurations compared against a distribution of the performance of a random classifier, so as to show whether the test docking configurations are significantly better than ones that can be produced by a random classifier. This is necessary due to the fact that many configurations are being tested. Hence, a Bonferroni correction is applied to the significance threshold, dividing p=0.01 by the number of tested configurations. (2) ROC, charge, and energy plots of the top docking configurations, comparing positive class molecules vs. negative class molecules, (3) box plots of enrichment for every multi-valued config parameter, and (4) heatmaps of enrichment for every pair of multi-valued config parameters.
* ''results.csv'': parameter values, criterion values, and other information about each docking configuration.

In addition, some number of the best retrodock jobs will be copied to their own sub-directory ''best_retrodock_jobs/''.

Within ''best_retrodock_jobs/'', there are the following files and sub-directories:
* ''dockfiles/'': parameters files and INDOCK for given docking configuration
* ''output/'': contains:
** joblist
** sub-directories ''1/'' for positives and ''2/'' for negatives (the former containing OUTDOCK and test.mol2 files, the latter containing just OUTDOCK)
** log files for the retrodock jobs
* ''roc.png'': the ROC enrichment curve (log-scaled x-axis) for given docking configuration

'''Note:''' by default, a mol2 file is exported only for positives (''output/1/''), not for negatives (''output/2/''), in order to prevent disk space issues.

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable and declare default environmental variables:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/env.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/env.sh

Dockopt (pydock3 script)

2022-12-06T04:30:43Z

Ianscottknight:

''dockopt'' allows the generation of many different docking configurations which are then evaluated & analyzed in parallel using a specified job scheduler (e.g. Slurm).

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/python3.8.5.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/python3.8.5.sh

== ''init'' ==

Be sure that you are in the directory containing the required input files:
* ''rec.pdb''
* ''xtal-lig.pdb''
* ''actives.tgz''
* ''decoys.tgz''

Note the inclusion of ''actives.tgz'' and ''decoys.tgz''. Each of these is a tarball of a directory containing .db2 files. Therefore, you need to build the molecules yourself.

To create the file structure for your dockopt job, simply type

pydock3 dockopt - init

By default, the job directory is named ''dockopt_job''. To specify a different name, use the "--job_dir_name" flag. E.g.:

pydock3 dockopt - init --job_dir_name=dockopt_job_2

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''retrodock_jobs'': individual retrodock jobs for each docking configuration

The key difference between the working directories of ''blastermaster'' and ''dockopt'' is that the working directory of ''dockopt'' may contain multiple variants of the blaster files (prefixed by a number, e.g. "1_box"). These variant files are used to create the different docking configurations specified by the multi-valued entries of ''dockopt_config.yaml''. They are created efficiently, such that the same variant used in multiple docking configurations is not created more than once.

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the dockopt job.

* ''rec.pdb''
* ''xtal-lig.pdb''
* ''rec.crg.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb''
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''dockopt_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of dockopt.

'''Note:''' The ''dockopt_config.yaml'' file differs from the ''blastermaster_config.yaml'' file in that every parameter of the former may accept either a single value or a ''list of comma-separated values'', which indicates a pool of values to attempt for that parameter. Multiple such multi-valued parameters may be provided, and all unique resultant docking configurations will be attempted.

Single-valued YAML line format:

distance_to_surface: 1.0

Multi-valued YAML line format:

distance_to_surface: [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]

== Environmental variables ==

=== TMPDIR ===

Designate where temporary job files should be placed. E.g.:

export TMPDIR=/scratch

==== Note for UCSF researchers ====

On the Wynton cluster, ''/scratch'' only exists on dev nodes (not log nodes). However, ''/wynton/scratch'' exists on both log nodes and dev nodes. Therefore, we recommend:
export TMPDIR=/wynton/scratch

=== job scheduler environmental variables ===

In order for ''dockopt'' to know which scheduler it should use, please configure the following environmental variables according to which one of the job schedulers you have.

==== Slurm ====

E.g., on the UCSF Shoichet Lab Gimel cluster (on any node other than 'gimel' itself, such as 'gimel5'):

export SBATCH_EXEC=/usr/bin/sbatch
export SQUEUE_EXEC=/usr/bin/squeue

==== SGE ====

On most clusters using SGE the following should be correct:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/default/common/settings.sh

===== Note for UCSF researchers =====

The following is necessary on the UCSF Wynton cluster:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/wynton/common/settings.sh

== ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run ''dockopt'':
cd <JOB_DIR_NAME>
pydock3 dockopt - run <JOB_SCHEDULER_NAME> [--retrodock_job_timeout_minutes=None] [--retrodock_job_max_reattempts=0]

where <JOB_SCHEDULER_NAME> is one of:
* ''sge''
* ''slurm''

This will execute the many dockopt subroutines in sequence, except for the retrodock jobs run on each docking configuration, which are run in parallel via the scheduler. The state of the program will be printed to standard output as it runs.

Once the dockopt job is complete, the following files will be generated in the job directory:
* ''dockopt_job_report.pdf'': contains (1) roc.png of best retrodock job, (2) box plots of enrichment for every multi-valued config parameter, and (3) heatmaps of enrichment for every pair of multi-valued config parameters
* ''dockopt_job_results.csv'': enrichment metrics for each docking configuration

In addition, the best retrodock job will be copied to its own sub-directory ''best_retrodock_job/''.

Within best_retrodock_job, there are the following files and sub-directories:
* ''dockfiles/'': parameters files and INDOCK for given docking configuration
* ''output/'': contains:
** joblist
** sub-directories ''1/'' for actives and ''2/'' for decoys (the former containing OUTDOCK and test.mol2 files, the latter containing just OUTDOCK)
** log files for the retrodock jobs
* ''roc.png'': the ROC enrichment curve (log-scaled x-axis) for given docking configuration

'''Note:''' by default, a mol2 file is exported only for actives (''output/1/''), not for decoys (''output/2/''), in order to prevent disk space issues.

Dockopt (pydock3 script)

2022-11-22T03:05:39Z

Ianscottknight: /* Environmental variables */

''dockopt'' allows the generation of many different docking configurations which are then evaluated & analyzed in parallel using a specified job scheduler (e.g. Slurm).

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/python3.8.5.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/python3.8.5.sh

== ''init'' ==

First you need to create the file structure for your dockopt job. To do so, simply type

pydock3 dockopt - init

By default, the job directory is named ''dockopt_job''. To specify a different name, type

pydock3 dockopt - init [--job_dir_name="dockopt_job"]

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''retrodock_jobs'': individual retrodock jobs for each docking configuration

The key difference between the working directories of ''blastermaster'' and ''dockopt'' is that the working directory of ''dockopt'' may contain multiple variants of the blaster files (prefixed by a number, e.g. "1_box"). These variant files are used to create the different docking configurations specified by the multi-valued entries of ''dockopt_config.yaml''. They are created efficiently, such that the same variant used in multiple docking configurations is not created more than once.

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the dockopt job.

* ''rec.pdb''
* ''xtal-lig.pdb''
* ''rec.crg.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb''
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''dockopt_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of dockopt.

'''Note:''' The ''dockopt_config.yaml'' file differs from the ''blastermaster_config.yaml'' file in that every parameter of the former may accept either a single value or a ''list of comma-separated values'', which indicates a pool of values to attempt for that parameter. Multiple such multi-valued parameters may be provided, and all unique resultant docking configurations will be attempted.

Single-valued YAML line format:

distance_to_surface: 1.0

Multi-valued YAML line format:

distance_to_surface: [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]

== Environmental variables ==

=== TMPDIR ===

Designate where temporary job files should be placed. E.g.:

export TMPDIR=/scratch

==== Note for UCSF researchers ====

On the Wynton cluster, ''/scratch'' only exists on dev nodes (not log nodes). However, ''/wynton/scratch'' exists on both log nodes and dev nodes. Therefore, we recommend:
export TMPDIR=/wynton/scratch

=== job scheduler environmental variables ===

In order for ''dockopt'' to know which scheduler it should use, please configure the following environmental variables according to which one of the job schedulers you have.

==== Slurm ====

E.g., on the UCSF Shoichet Lab Gimel cluster (on any node other than 'gimel' itself, such as 'gimel5'):

export SBATCH_EXEC=/usr/bin/sbatch
export SQUEUE_EXEC=/usr/bin/squeue

==== SGE ====

On most clusters using SGE the following should be correct:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/default/common/settings.sh

===== Note for UCSF researchers =====

The following is necessary on the UCSF Wynton cluster:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub
export SGE_SETTINGS=/opt/sge/wynton/common/settings.sh

== ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run ''dockopt'':
cd <JOB_DIR_NAME>
pydock3 dockopt - run <JOB_SCHEDULER_NAME> [--retrodock_job_timeout_minutes=None] [--retrodock_job_max_reattempts=0]

where <JOB_SCHEDULER_NAME> is one of:
* ''sge''
* ''slurm''

This will execute the many dockopt subroutines in sequence, except for the retrodock jobs run on each docking configuration, which are run in parallel via the scheduler. The state of the program will be printed to standard output as it runs.

Once the dockopt job is complete, the following files will be generated in the job directory:
* ''dockopt_job_report.pdf'': contains (1) roc.png of best retrodock job, (2) box plots of enrichment for every multi-valued config parameter, and (3) heatmaps of enrichment for every pair of multi-valued config parameters
* ''dockopt_job_results.csv'': enrichment metrics for each docking configuration

In addition, the best retrodock job will be copied to its own sub-directory ''best_retrodock_job/''.

Within best_retrodock_job, there are the following files and sub-directories:
* ''dockfiles/'': parameters files and INDOCK for given docking configuration
* ''output/'': contains:
** joblist
** sub-directories ''1/'' for actives and ''2/'' for decoys (the former containing OUTDOCK and test.mol2 files, the latter containing just OUTDOCK)
** log files for the retrodock jobs
* ''roc.png'': the ROC enrichment curve (log-scaled x-axis) for given docking configuration

'''Note:''' by default, a mol2 file is exported only for actives (''output/1/''), not for decoys (''output/2/''), in order to prevent disk space issues.

Dockopt (pydock3 script)

2022-11-22T03:01:45Z

Ianscottknight: /* Environmental variables */

''dockopt'' allows the generation of many different docking configurations which are then evaluated & analyzed in parallel using a specified job scheduler (e.g. Slurm).

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/python3.8.5.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/python3.8.5.sh

== ''init'' ==

First you need to create the file structure for your dockopt job. To do so, simply type

pydock3 dockopt - init

By default, the job directory is named ''dockopt_job''. To specify a different name, type

pydock3 dockopt - init [--job_dir_name="dockopt_job"]

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''retrodock_jobs'': individual retrodock jobs for each docking configuration

The key difference between the working directories of ''blastermaster'' and ''dockopt'' is that the working directory of ''dockopt'' may contain multiple variants of the blaster files (prefixed by a number, e.g. "1_box"). These variant files are used to create the different docking configurations specified by the multi-valued entries of ''dockopt_config.yaml''. They are created efficiently, such that the same variant used in multiple docking configurations is not created more than once.

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the dockopt job.

* ''rec.pdb''
* ''xtal-lig.pdb''
* ''rec.crg.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb''
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''dockopt_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of dockopt.

'''Note:''' The ''dockopt_config.yaml'' file differs from the ''blastermaster_config.yaml'' file in that every parameter of the former may accept either a single value or a ''list of comma-separated values'', which indicates a pool of values to attempt for that parameter. Multiple such multi-valued parameters may be provided, and all unique resultant docking configurations will be attempted.

Single-valued YAML line format:

distance_to_surface: 1.0

Multi-valued YAML line format:

distance_to_surface: [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]

== Environmental variables ==

Designate where temporary job files should be placed. E.g.:

export TMPDIR=/scratch

=== Note for UCSF researchers ===

On the Wynton cluster, ''/scratch'' only exists on dev nodes (not log nodes). However, ''/wynton/scratch'' exists on both log nodes and dev nodes. Therefore, we recommend:
export TMPDIR=/wynton/scratch

In order for ''dockopt'' to know which scheduler it should use, please configure the following environmental variables according to which one of the job schedulers you have.

=== Slurm ===

E.g., on the UCSF Shoichet Lab Gimel cluster (on any node other than 'gimel' itself, such as 'gimel5'):

export SBATCH_EXEC=/usr/bin/sbatch
export SQUEUE_EXEC=/usr/bin/squeue

=== SGE ===

E.g., on the UCSF Wynton cluster:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub

The following is necessary on the UCSF Wynton cluster:

export SGE_SETTINGS=/opt/sge/wynton/common/settings.sh

On most clusters using SGE, this will probably be:

export SGE_SETTINGS=/opt/sge/default/common/settings.sh

== ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run ''dockopt'':
cd <JOB_DIR_NAME>
pydock3 dockopt - run <JOB_SCHEDULER_NAME> [--retrodock_job_timeout_minutes=None] [--retrodock_job_max_reattempts=0]

where <JOB_SCHEDULER_NAME> is one of:
* ''sge''
* ''slurm''

This will execute the many dockopt subroutines in sequence, except for the retrodock jobs run on each docking configuration, which are run in parallel via the scheduler. The state of the program will be printed to standard output as it runs.

Once the dockopt job is complete, the following files will be generated in the job directory:
* ''dockopt_job_report.pdf'': contains (1) roc.png of best retrodock job, (2) box plots of enrichment for every multi-valued config parameter, and (3) heatmaps of enrichment for every pair of multi-valued config parameters
* ''dockopt_job_results.csv'': enrichment metrics for each docking configuration

In addition, the best retrodock job will be copied to its own sub-directory ''best_retrodock_job/''.

Within best_retrodock_job, there are the following files and sub-directories:
* ''dockfiles/'': parameters files and INDOCK for given docking configuration
* ''output/'': contains:
** joblist
** sub-directories ''1/'' for actives and ''2/'' for decoys (the former containing OUTDOCK and test.mol2 files, the latter containing just OUTDOCK)
** log files for the retrodock jobs
* ''roc.png'': the ROC enrichment curve (log-scaled x-axis) for given docking configuration

'''Note:''' by default, a mol2 file is exported only for actives (''output/1/''), not for decoys (''output/2/''), in order to prevent disk space issues.

DOCK3.8:Pydock3

2022-11-09T06:54:19Z

Ianscottknight:

''pydock3'' is a Python package wrapping the [[DOCK|DOCK Fortran program]] that provides tools to help standardize and automate the computational methods employed in molecular docking. It is a natural successor to DOCK Blaster, originally published in 2009, and blastermaster.py, part of the [[DOCK 3.7]] release in 2012.

Scripts included in ''pydock3'':
* ''dockopt'': generate many different docking configurations, perform retrospective docking on them in parallel using a specified job scheduler (e.g. Slurm), and analyze the results.
* ''blastermaster'': generate a specific docking configuration for a given receptor and ligand, intended for use by experts who wish to tune the docking model themselves. This is a direct successor of blastermaster.py from DOCK 3.7.

A [[docking configuration|'''docking configuration''']] is a unique set of (1) DOCK parameter files (e.g., ''matching_spheres.sph''), (2) an INDOCK file, and (3) a DOCK executable.

= Installation =

See: [[DOCK 3.8:How to install pydock3]].

= Instructions =

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/python3.8.5.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/python3.8.5.sh

== ''blastermaster'' ==

See: [[blastermaster (pydock3 script)]].

== ''dockopt'' ==

See: [[dockopt (pydock3 script)]].

[[Category:DOCK 3.8]]
[[Category:DOCK Blaster]]

Dockopt (pydock3 script)

2022-10-28T07:17:17Z

Ianscottknight:

''dockopt'' allows the generation of many different docking configurations which are then evaluated & analyzed in parallel using a specified job scheduler (e.g. Slurm).

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/python3.8.5.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/python3.8.5.sh

== ''init'' ==

First you need to create the file structure for your dockopt job. To do so, simply type

pydock3 dockopt - init

By default, the job directory is named ''dockopt_job''. To specify a different name, type

pydock3 dockopt - init [--job_dir_name="dockopt_job"]

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''retrodock_jobs'': individual retrodock jobs for each docking configuration

The key difference between the working directories of ''blastermaster'' and ''dockopt'' is that the working directory of ''dockopt'' may contain multiple variants of the blaster files (prefixed by a number, e.g. "1_box"). These variant files are used to create the different docking configurations specified by the multi-valued entries of ''dockopt_config.yaml''. They are created efficiently, such that the same variant used in multiple docking configurations is not created more than once.

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the dockopt job.

* ''rec.pdb''
* ''xtal-lig.pdb''
* ''rec.crg.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb''
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''dockopt_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of dockopt.

'''Note:''' The ''dockopt_config.yaml'' file differs from the ''blastermaster_config.yaml'' file in that every parameter of the former may accept either a single value or a ''list of comma-separated values'', which indicates a pool of values to attempt for that parameter. Multiple such multi-valued parameters may be provided, and all unique resultant docking configurations will be attempted.

Single-valued YAML line format:

distance_to_surface: 1.0

Multi-valued YAML line format:

distance_to_surface: [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]

== Environmental variables ==

Designate where temporary job files should be placed. E.g.:

export TMPDIR=/scratch

In order for ''dockopt'' to know which scheduler it should use, please configure the following environmental variables according to which one of the job schedulers you have.

=== Slurm ===

E.g., on the UCSF Shoichet Lab Gimel cluster (on any node other than 'gimel' itself, such as 'gimel5'):

export SBATCH_EXEC=/usr/bin/sbatch
export SQUEUE_EXEC=/usr/bin/squeue

=== SGE ===

E.g., on the UCSF Wynton cluster:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub

The following is necessary on the UCSF Wynton cluster:

export SGE_SETTINGS=/opt/sge/wynton/common/settings.sh

On most clusters using SGE, this will probably be:

export SGE_SETTINGS=/opt/sge/default/common/settings.sh

== ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run ''dockopt'':
cd <JOB_DIR_NAME>
pydock3 dockopt - run <JOB_SCHEDULER_NAME> [--retrodock_job_timeout_minutes=None] [--retrodock_job_max_reattempts=0]

where <JOB_SCHEDULER_NAME> is one of:
* ''sge''
* ''slurm''

This will execute the many dockopt subroutines in sequence, except for the retrodock jobs run on each docking configuration, which are run in parallel via the scheduler. The state of the program will be printed to standard output as it runs.

Once the dockopt job is complete, the following files will be generated in the job directory:
* ''dockopt_job_report.pdf'': contains (1) roc.png of best retrodock job, (2) box plots of enrichment for every multi-valued config parameter, and (3) heatmaps of enrichment for every pair of multi-valued config parameters
* ''dockopt_job_results.csv'': enrichment metrics for each docking configuration

In addition, the best retrodock job will be copied to its own sub-directory ''best_retrodock_job/''.

Within best_retrodock_job, there are the following files and sub-directories:
* ''dockfiles/'': parameters files and INDOCK for given docking configuration
* ''output/'': contains:
** joblist
** sub-directories ''1/'' for actives and ''2/'' for decoys (the former containing OUTDOCK and test.mol2 files, the latter containing just OUTDOCK)
** log files for the retrodock jobs
* ''roc.png'': the ROC enrichment curve (log-scaled x-axis) for given docking configuration

'''Note:''' by default, a mol2 file is exported only for actives (''output/1/''), not for decoys (''output/2/''), in order to prevent disk space issues.

Dockopt (pydock3 script)

2022-10-19T23:45:49Z

Ianscottknight:

''dockopt'' allows the generation of many different docking configurations which are then evaluated & analyzed in parallel using a specified job scheduler (e.g. Slurm).

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/python3.8.5.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/python3.8.5.sh

== ''init'' ==

First you need to create the file structure for your dockopt job. To do so, simply type

pydock3 dockopt - init

By default, the job directory is named ''dockopt_job''. To specify a different name, type

pydock3 dockopt - init <JOB_DIR_NAME>

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''retrodock_jobs'': individual retrodock jobs for each docking configuration

The key difference between the working directories of ''blastermaster'' and ''dockopt'' is that the working directory of ''dockopt'' may contain multiple variants of the blaster files (prefixed by a number, e.g. "1_box"). These variant files are used to create the different docking configurations specified by the multi-valued entries of ''dockopt_config.yaml''. They are created efficiently, such that the same variant used in multiple docking configurations is not created more than once.

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the dockopt job.

* ''rec.pdb''
* ''xtal-lig.pdb''
* ''rec.crg.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb''
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''dockopt_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of dockopt.

'''Note:''' The ''dockopt_config.yaml'' file differs from the ''blastermaster_config.yaml'' file in that every parameter of the former may accept either a single value or a ''list of comma-separated values'', which indicates a pool of values to attempt for that parameter. Multiple such multi-valued parameters may be provided, and all unique resultant docking configurations will be attempted.

Single-valued YAML line format:

distance_to_surface: 1.0

Multi-valued YAML line format:

distance_to_surface: [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]

== Environmental variables ==

Designate where temporary job files should be placed. E.g.:

export TMPDIR=/scratch

In order for ''dockopt'' to know which scheduler it should use, please configure the following environmental variables according to which one of the job schedulers you have.

=== Slurm ===

E.g., on the UCSF Shoichet Lab Gimel cluster (on any node other than 'gimel' itself, such as 'gimel5'):

export SBATCH_EXEC=/usr/bin/sbatch
export SQUEUE_EXEC=/usr/bin/squeue

=== SGE ===

E.g., on the UCSF Wynton cluster:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub

The following is necessary on the UCSF Wynton cluster:

export SGE_SETTINGS=/opt/sge/wynton/common/settings.sh

On most clusters using SGE, this will probably be:

export SGE_SETTINGS=/opt/sge/default/common/settings.sh

== ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run ''dockopt'':
cd <JOB_DIR_NAME>
pydock3 dockopt - run <JOB_SCHEDULER_NAME> [--retrodock_job_timeout_minutes=None] [--retrodock_job_max_reattempts=0]

where <JOB_SCHEDULER_NAME> is one of:
* ''sge''
* ''slurm''

This will execute the many dockopt subroutines in sequence, except for the retrodock jobs run on each docking configuration, which are run in parallel via the scheduler. The state of the program will be printed to standard output as it runs.

Once the dockopt job is complete, the following files will be generated in the job directory:
* ''dockopt_job_report.pdf'': contains (1) roc.png of best retrodock job, (2) box plots of enrichment for every multi-valued config parameter, and (3) heatmaps of enrichment for every pair of multi-valued config parameters
* ''dockopt_job_results.csv'': enrichment metrics for each docking configuration

In addition, the best retrodock job will be copied to its own sub-directory ''best_retrodock_job/''.

Within best_retrodock_job, there are the following files and sub-directories:
* ''dockfiles/'': parameters files and INDOCK for given docking configuration
* ''output/'': contains:
** joblist
** sub-directories ''1/'' for actives and ''2/'' for decoys (the former containing OUTDOCK and test.mol2 files, the latter containing just OUTDOCK)
** log files for the retrodock jobs
* ''roc.png'': the ROC enrichment curve (log-scaled x-axis) for given docking configuration

'''Note:''' by default, a mol2 file is exported only for actives (''output/1/''), not for decoys (''output/2/''), in order to prevent disk space issues.

Blastermaster (pydock3 script)

2022-10-11T23:40:43Z

Ianscottknight:

''blastermaster'' allows the generation of a specific docking configuration for a given receptor and ligand.

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/python3.8.5.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/python3.8.5.sh

== ''init'' ==

First you need to create the file structure for your blastermaster job. To do so, simply type

pydock3 blastermaster - init

By default, the job directory is named ''blastermaster_job''. To specify a different name, type

pydock3 blastermaster - init <JOB_DIR_NAME>

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''dockfiles'': output files (DOCK parameter files & INDOCK)

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the blastermaster job.

* ''rec.pdb''
* ''xtal-lig.pdb''
* ''rec.crg.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb''
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, then copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''blastermaster_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of blastermaster.

== ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run blastermaster:
cd <JOB_DIR_NAME>
pydock3 blastermaster - run

This will execute the many blastermaster subroutines in sequence. The state of the program will be printed to standard output as it runs.

Dockopt (pydock3 script)

2022-10-11T23:40:04Z

Ianscottknight:

''dockopt'' allows the generation of many different docking configurations which are then evaluated & analyzed in parallel using a specified job scheduler (e.g. Slurm).

== Note for UCSF Shoichet Lab members ==

''pydock3'' is already installed on the following clusters. You can source the provided Python environment scripts to expose the ''pydock3'' executable:

=== Wynton ===

source /wynton/group/bks/soft/python_envs/python3.8.5.sh

=== Gimel ===

Only nodes other than ''gimel'' itself are supported, e.g., ''gimel5''.

ssh gimel5
source /nfs/soft/ian/python3.8.5.sh

== ''init'' ==

First you need to create the file structure for your dockopt job. To do so, simply type

pydock3 dockopt - init

By default, the job directory is named ''dockopt_job''. To specify a different name, type

pydock3 dockopt - init <JOB_DIR_NAME>

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''retrodock_jobs'': individual retrodock jobs for each docking configuration

The key difference between the working directories of ''blastermaster'' and ''dockopt'' is that the working directory of ''dockopt'' may contain multiple variants of the blaster files (prefixed by a number, e.g. "1_box"). These variant files are used to create the different docking configurations specified by the multi-valued entries of ''dockopt_config.yaml''. They are created efficiently, such that the same variant used in multiple docking configurations is not created more than once.

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the dockopt job.

* ''rec.pdb''
* ''xtal-lig.pdb''
* ''rec.crg.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb''
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''dockopt_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of dockopt.

'''Note:''' The ''dockopt_config.yaml'' file differs from the ''blastermaster_config.yaml'' file in that every parameter of the former may accept either a single value or a ''list of comma-separated values'', which indicates a pool of values to attempt for that parameter. Multiple such multi-valued parameters may be provided, and all unique resultant docking configurations will be attempted.

Single-valued YAML line format:

distance_to_surface: 1.0

Multi-valued YAML line format:

distance_to_surface: [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]

== Environmental variables ==

Designate where temporary job files should be placed. E.g.:

export TEMP_STORAGE_PATH=/scratch

In order for ''dockopt'' to know which scheduler it should use, please configure the following environmental variables according to which one of the job schedulers you have.

=== Slurm ===

E.g., on the UCSF Shoichet Lab Gimel cluster (on any node other than 'gimel' itself, such as 'gimel5'):

export SBATCH_EXEC=/usr/bin/sbatch
export SQUEUE_EXEC=/usr/bin/squeue

=== SGE ===

E.g., on the UCSF Wynton cluster:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub

The following is necessary on the UCSF Wynton cluster:

export SGE_SETTINGS=/opt/sge/wynton/common/settings.sh

On most clusters using SGE, this will probably be:

export SGE_SETTINGS=/opt/sge/default/common/settings.sh

== ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run ''dockopt'':
cd <JOB_DIR_NAME>
pydock3 dockopt - run <JOB_SCHEDULER_NAME> [--retrodock_job_timeout_minutes=None] [--retrodock_job_max_reattempts=0]

where <JOB_SCHEDULER_NAME> is one of:
* ''sge''
* ''slurm''

This will execute the many dockopt subroutines in sequence, except for the retrodock jobs run on each docking configuration, which are run in parallel via the scheduler. The state of the program will be printed to standard output as it runs.

Once the dockopt job is complete, the following files will be generated in the job directory:
* ''dockopt_job_report.pdf'': contains (1) roc.png of best retrodock job, (2) box plots of enrichment for every multi-valued config parameter, and (3) heatmaps of enrichment for every pair of multi-valued config parameters
* ''dockopt_job_results.csv'': enrichment metrics for each docking configuration

In addition, the best retrodock job will be copied to its own sub-directory ''best_retrodock_job/''.

Within best_retrodock_job, there are the following files and sub-directories:
* ''dockfiles/'': parameters files and INDOCK for given docking configuration
* ''output/'': contains:
** joblist
** sub-directories ''1/'' for actives and ''2/'' for decoys (the former containing OUTDOCK and test.mol2 files, the latter containing just OUTDOCK)
** log files for the retrodock jobs
* ''roc.png'': the ROC enrichment curve (log-scaled x-axis) for given docking configuration

'''Note:''' by default, a mol2 file is exported only for actives (''output/1/''), not for decoys (''output/2/''), in order to prevent disk space issues.

How to compile DOCK

2022-10-07T16:55:25Z

Ianscottknight: /* gfortran instructions */

== compiling dock3.8 ==

Note- not every machine will have the prerequisite development libraries installed to compile DOCK fortran code. It is best to log into our "psi" machine, which is known to have the prerequisite libraries. Note: git will not work from psi, so you will need to have the code you would like to compile accessible via the NFS.

ssh $USER@psi

Wynton development nodes are also a good place to compile with gfortran. For PGF you will always need to log into our psi machine.

=== gfortran instructions ===

'''Note:''' in search.f and search_multi_cluster.f you need to (1) uncomment the lines that are commented with "for gfortran" and (2) comment out the lines that are commented with "for portland group".

gfortran is a widely available compiler that is preinstalled on all lab machines. In order to compile with gfortran, start from the base directory of DOCK and follow these instructions:

cd dock3/src/libfgz
COMPILER=gfortran make
cd ../i386
COMPILER=gfortran make

You should now have a bunch of .o object files as well as a dock64 executable in the i386 directory. If you want to compile a debug build add DEBUG=1 before make, and if you want to compile for a different architecture prefix make with SIZE=[32|64]

If you mistakenly compile something (wrong compiler or the like) you can clean up the files produced from compilation with "make clean". Don't worry about the error messages you may get from this, something is a little fishy with our makefile.

It may be necessary to run make twice due to an odd error with the version.f file.

=== pgf instructions ===

'''Note:''' in search.f and search_multi_cluster.f you need to (1) comment out the lines that are commented with "for gfortran" and (2) uncomment the lines that are commented with "for portland group".

PGF or the Portland Group compiler is the premium option for fortran compilation. In order to compile with pgf you must log onto the psi machine, where the license and installation is located.

ssh $USER@psi

Set up the compilation environment through the following script:

bash # if you are not already on bash
export PATH=/nfs/soft/pgi/current/linux86-64/12.10/bin:$PATH
source /nfs/home/tbalius/zzz.virtualenvs/virtualenv-1.9.1/myVEonGimel/bin/activate
source /nfs/soft/pgi/env.sh

The instructions to compile are identical to those for gfortran, the only difference being you need to set COMPILER=pgf, e.g

cd dock3/src/libfgz
COMPILER=pgf make
cd ../i386
COMPILER=pgf make

You can add DEBUG, SIZE etc. options just like gfortran.

Sometimes there is an odd error with the licensing server that causes compilation to fail. I don't remember exactly I fixed this in the past, but I believe it had to do with restarting the license service via systemctl.

It may be necessary to run make twice due to an odd error with the version.f file.

== compiling dock3.7 ==

1. log into psi (portland fortran compiler is on psi)
2. export PATH=/nfs/soft/pgi/current/linux86-64/12.10/bin:$PATH
3. source Trent's virual environment (source /nfs/home/tbalius/zzz.virtualenvs/virtualenv-1.9.1/myVEonGimel/bin/activate)
4. source /nfs/soft/pgi/env.csh

== DOCK 3.7 ==

Frist you need the source code:
* lab members and other developers may check out dock from [[Github]]
* others can request the distrabution here [http://dock.compbio.ucsf.edu/Online_Licensing/dock_license_application.html]
=== compiling dock ===

To compile DOCK go to path/DOCK/src/i386
make
make DEBUG=1
make SIZE=32 [64]
make clean

Note:
*To compile with portland group compilers
** go to a machine were pgf linsence is installed (sgehead1 or psi).

*To add a file for compilation, add the xxxx.f file to path/DOCK/src/ and add xxxx.o to i386/Makefile object list.
=== debuging dock ===
Debugging :

pgdbg path/DOCK/src/i386/dock_prof64

=== profiling dock ===
Profiling:
make pgprofile
less pgprof.out
pgprof - opens a GUI profiler that interprets pgprof.out !

you may also do the following:
make dock_prof64
cd /dir/test
/dockdir/dock_prof64 INDOCK
less pgprof.out

make gmon.out
less gmon.out

make gprofile
less gprofile.txt

== DOCK 3.5.54 ==
This is for the Shoichet Lab local version of DOCK 3.5.54 trunk.

'''Checking out the source files'''

Commands:
csh
mkdir /where/to/put
cd /where/to/put
svn checkout file:///raid4/svn/dock
svn checkout file:///raid4/svn/libfgz

'''Compiling the program on our cluster'''

First, you need to set the path to the PGF compiler by adding this line to your .login file (at the end):

setenv DOCK_BASE ~xyz/dockenv
echo DOCK_BASE set to $DOCK_BASE.
source $DOCK_BASE/etc/login

When you login to sgehead now, you should see the "Enabling pgf compiler" message

Commands:
ssh sgehead
cd /where/to/put/libfgz/trunk
make

Since we still have some 32bit computers, you'll also want to do
make SIZE=32
before leaving the libfgz branch and going to DOCK:

cd ../../dock/trunk/i386
make

This makes the 64 bit version. Some options:

make SIZE=32

Makes the 32bit version, useful for running on the cluster since some machines are older.

make DEBUG=1

Makes a debug version that will report line numbers of errors and is usable with pgdbg (the Portland Group Debugger), which is useful when writing code but is 10x (or more) slower.

'''Compiling the program on the shared QB3 cluster'''

On one of the compilation nodes on the shared QB3 cluster (optint1 or optint2):

ssh optint2
cd /where/to/put/libfgz/trunk
cp Makefile Makefile.old
modify Makefile:
uncomment the following:
FC = ifort -O3
CC = icc -O3
make
cd ../../dock/trunk/i386
cp Makefile Makefile.old
modify Makefile
uncomment the following:
F77 = ifort
FFLAGS = -O3 -convert big_endian
make dock

[[Category:Tutorials]]
[[Category:DOCK]]

How to compile DOCK

2022-10-07T16:55:11Z

Ianscottknight: /* pgf instructions */

== compiling dock3.8 ==

Note- not every machine will have the prerequisite development libraries installed to compile DOCK fortran code. It is best to log into our "psi" machine, which is known to have the prerequisite libraries. Note: git will not work from psi, so you will need to have the code you would like to compile accessible via the NFS.

ssh $USER@psi

Wynton development nodes are also a good place to compile with gfortran. For PGF you will always need to log into our psi machine.

=== gfortran instructions ===

Note: in search.f and search_multi_cluster.f you need to (1) uncomment the lines that are commented with "for gfortran" and (2) comment out the lines that are commented with "for portland group".

gfortran is a widely available compiler that is preinstalled on all lab machines. In order to compile with gfortran, start from the base directory of DOCK and follow these instructions:

cd dock3/src/libfgz
COMPILER=gfortran make
cd ../i386
COMPILER=gfortran make

You should now have a bunch of .o object files as well as a dock64 executable in the i386 directory. If you want to compile a debug build add DEBUG=1 before make, and if you want to compile for a different architecture prefix make with SIZE=[32|64]

If you mistakenly compile something (wrong compiler or the like) you can clean up the files produced from compilation with "make clean". Don't worry about the error messages you may get from this, something is a little fishy with our makefile.

It may be necessary to run make twice due to an odd error with the version.f file.

=== pgf instructions ===

'''Note:''' in search.f and search_multi_cluster.f you need to (1) comment out the lines that are commented with "for gfortran" and (2) uncomment the lines that are commented with "for portland group".

PGF or the Portland Group compiler is the premium option for fortran compilation. In order to compile with pgf you must log onto the psi machine, where the license and installation is located.

ssh $USER@psi

Set up the compilation environment through the following script:

bash # if you are not already on bash
export PATH=/nfs/soft/pgi/current/linux86-64/12.10/bin:$PATH
source /nfs/home/tbalius/zzz.virtualenvs/virtualenv-1.9.1/myVEonGimel/bin/activate
source /nfs/soft/pgi/env.sh

The instructions to compile are identical to those for gfortran, the only difference being you need to set COMPILER=pgf, e.g

cd dock3/src/libfgz
COMPILER=pgf make
cd ../i386
COMPILER=pgf make

You can add DEBUG, SIZE etc. options just like gfortran.

Sometimes there is an odd error with the licensing server that causes compilation to fail. I don't remember exactly I fixed this in the past, but I believe it had to do with restarting the license service via systemctl.

It may be necessary to run make twice due to an odd error with the version.f file.

== compiling dock3.7 ==

1. log into psi (portland fortran compiler is on psi)
2. export PATH=/nfs/soft/pgi/current/linux86-64/12.10/bin:$PATH
3. source Trent's virual environment (source /nfs/home/tbalius/zzz.virtualenvs/virtualenv-1.9.1/myVEonGimel/bin/activate)
4. source /nfs/soft/pgi/env.csh

== DOCK 3.7 ==

Frist you need the source code:
* lab members and other developers may check out dock from [[Github]]
* others can request the distrabution here [http://dock.compbio.ucsf.edu/Online_Licensing/dock_license_application.html]
=== compiling dock ===

To compile DOCK go to path/DOCK/src/i386
make
make DEBUG=1
make SIZE=32 [64]
make clean

Note:
*To compile with portland group compilers
** go to a machine were pgf linsence is installed (sgehead1 or psi).

*To add a file for compilation, add the xxxx.f file to path/DOCK/src/ and add xxxx.o to i386/Makefile object list.
=== debuging dock ===
Debugging :

pgdbg path/DOCK/src/i386/dock_prof64

=== profiling dock ===
Profiling:
make pgprofile
less pgprof.out
pgprof - opens a GUI profiler that interprets pgprof.out !

you may also do the following:
make dock_prof64
cd /dir/test
/dockdir/dock_prof64 INDOCK
less pgprof.out

make gmon.out
less gmon.out

make gprofile
less gprofile.txt

== DOCK 3.5.54 ==
This is for the Shoichet Lab local version of DOCK 3.5.54 trunk.

'''Checking out the source files'''

Commands:
csh
mkdir /where/to/put
cd /where/to/put
svn checkout file:///raid4/svn/dock
svn checkout file:///raid4/svn/libfgz

'''Compiling the program on our cluster'''

First, you need to set the path to the PGF compiler by adding this line to your .login file (at the end):

setenv DOCK_BASE ~xyz/dockenv
echo DOCK_BASE set to $DOCK_BASE.
source $DOCK_BASE/etc/login

When you login to sgehead now, you should see the "Enabling pgf compiler" message

Commands:
ssh sgehead
cd /where/to/put/libfgz/trunk
make

Since we still have some 32bit computers, you'll also want to do
make SIZE=32
before leaving the libfgz branch and going to DOCK:

cd ../../dock/trunk/i386
make

This makes the 64 bit version. Some options:

make SIZE=32

Makes the 32bit version, useful for running on the cluster since some machines are older.

make DEBUG=1

Makes a debug version that will report line numbers of errors and is usable with pgdbg (the Portland Group Debugger), which is useful when writing code but is 10x (or more) slower.

'''Compiling the program on the shared QB3 cluster'''

On one of the compilation nodes on the shared QB3 cluster (optint1 or optint2):

ssh optint2
cd /where/to/put/libfgz/trunk
cp Makefile Makefile.old
modify Makefile:
uncomment the following:
FC = ifort -O3
CC = icc -O3
make
cd ../../dock/trunk/i386
cp Makefile Makefile.old
modify Makefile
uncomment the following:
F77 = ifort
FFLAGS = -O3 -convert big_endian
make dock

[[Category:Tutorials]]
[[Category:DOCK]]

How to compile DOCK

2022-10-07T16:55:01Z

Ianscottknight: /* pgf instructions */

== compiling dock3.8 ==

Note- not every machine will have the prerequisite development libraries installed to compile DOCK fortran code. It is best to log into our "psi" machine, which is known to have the prerequisite libraries. Note: git will not work from psi, so you will need to have the code you would like to compile accessible via the NFS.

ssh $USER@psi

Wynton development nodes are also a good place to compile with gfortran. For PGF you will always need to log into our psi machine.

=== gfortran instructions ===

Note: in search.f and search_multi_cluster.f you need to (1) uncomment the lines that are commented with "for gfortran" and (2) comment out the lines that are commented with "for portland group".

gfortran is a widely available compiler that is preinstalled on all lab machines. In order to compile with gfortran, start from the base directory of DOCK and follow these instructions:

cd dock3/src/libfgz
COMPILER=gfortran make
cd ../i386
COMPILER=gfortran make

You should now have a bunch of .o object files as well as a dock64 executable in the i386 directory. If you want to compile a debug build add DEBUG=1 before make, and if you want to compile for a different architecture prefix make with SIZE=[32|64]

If you mistakenly compile something (wrong compiler or the like) you can clean up the files produced from compilation with "make clean". Don't worry about the error messages you may get from this, something is a little fishy with our makefile.

It may be necessary to run make twice due to an odd error with the version.f file.

=== pgf instructions ===

'''Note''': in search.f and search_multi_cluster.f you need to (1) comment out the lines that are commented with "for gfortran" and (2) uncomment the lines that are commented with "for portland group".

PGF or the Portland Group compiler is the premium option for fortran compilation. In order to compile with pgf you must log onto the psi machine, where the license and installation is located.

ssh $USER@psi

Set up the compilation environment through the following script:

bash # if you are not already on bash
export PATH=/nfs/soft/pgi/current/linux86-64/12.10/bin:$PATH
source /nfs/home/tbalius/zzz.virtualenvs/virtualenv-1.9.1/myVEonGimel/bin/activate
source /nfs/soft/pgi/env.sh

The instructions to compile are identical to those for gfortran, the only difference being you need to set COMPILER=pgf, e.g

cd dock3/src/libfgz
COMPILER=pgf make
cd ../i386
COMPILER=pgf make

You can add DEBUG, SIZE etc. options just like gfortran.

Sometimes there is an odd error with the licensing server that causes compilation to fail. I don't remember exactly I fixed this in the past, but I believe it had to do with restarting the license service via systemctl.

It may be necessary to run make twice due to an odd error with the version.f file.

== compiling dock3.7 ==

1. log into psi (portland fortran compiler is on psi)
2. export PATH=/nfs/soft/pgi/current/linux86-64/12.10/bin:$PATH
3. source Trent's virual environment (source /nfs/home/tbalius/zzz.virtualenvs/virtualenv-1.9.1/myVEonGimel/bin/activate)
4. source /nfs/soft/pgi/env.csh

== DOCK 3.7 ==

Frist you need the source code:
* lab members and other developers may check out dock from [[Github]]
* others can request the distrabution here [http://dock.compbio.ucsf.edu/Online_Licensing/dock_license_application.html]
=== compiling dock ===

To compile DOCK go to path/DOCK/src/i386
make
make DEBUG=1
make SIZE=32 [64]
make clean

Note:
*To compile with portland group compilers
** go to a machine were pgf linsence is installed (sgehead1 or psi).

*To add a file for compilation, add the xxxx.f file to path/DOCK/src/ and add xxxx.o to i386/Makefile object list.
=== debuging dock ===
Debugging :

pgdbg path/DOCK/src/i386/dock_prof64

=== profiling dock ===
Profiling:
make pgprofile
less pgprof.out
pgprof - opens a GUI profiler that interprets pgprof.out !

you may also do the following:
make dock_prof64
cd /dir/test
/dockdir/dock_prof64 INDOCK
less pgprof.out

make gmon.out
less gmon.out

make gprofile
less gprofile.txt

== DOCK 3.5.54 ==
This is for the Shoichet Lab local version of DOCK 3.5.54 trunk.

'''Checking out the source files'''

Commands:
csh
mkdir /where/to/put
cd /where/to/put
svn checkout file:///raid4/svn/dock
svn checkout file:///raid4/svn/libfgz

'''Compiling the program on our cluster'''

First, you need to set the path to the PGF compiler by adding this line to your .login file (at the end):

setenv DOCK_BASE ~xyz/dockenv
echo DOCK_BASE set to $DOCK_BASE.
source $DOCK_BASE/etc/login

When you login to sgehead now, you should see the "Enabling pgf compiler" message

Commands:
ssh sgehead
cd /where/to/put/libfgz/trunk
make

Since we still have some 32bit computers, you'll also want to do
make SIZE=32
before leaving the libfgz branch and going to DOCK:

cd ../../dock/trunk/i386
make

This makes the 64 bit version. Some options:

make SIZE=32

Makes the 32bit version, useful for running on the cluster since some machines are older.

make DEBUG=1

Makes a debug version that will report line numbers of errors and is usable with pgdbg (the Portland Group Debugger), which is useful when writing code but is 10x (or more) slower.

'''Compiling the program on the shared QB3 cluster'''

On one of the compilation nodes on the shared QB3 cluster (optint1 or optint2):

ssh optint2
cd /where/to/put/libfgz/trunk
cp Makefile Makefile.old
modify Makefile:
uncomment the following:
FC = ifort -O3
CC = icc -O3
make
cd ../../dock/trunk/i386
cp Makefile Makefile.old
modify Makefile
uncomment the following:
F77 = ifort
FFLAGS = -O3 -convert big_endian
make dock

[[Category:Tutorials]]
[[Category:DOCK]]

How to compile DOCK

2022-10-07T16:54:32Z

Ianscottknight: /* pgf instructions */

== compiling dock3.8 ==

Note- not every machine will have the prerequisite development libraries installed to compile DOCK fortran code. It is best to log into our "psi" machine, which is known to have the prerequisite libraries. Note: git will not work from psi, so you will need to have the code you would like to compile accessible via the NFS.

ssh $USER@psi

Wynton development nodes are also a good place to compile with gfortran. For PGF you will always need to log into our psi machine.

=== gfortran instructions ===

Note: in search.f and search_multi_cluster.f you need to (1) uncomment the lines that are commented with "for gfortran" and (2) comment out the lines that are commented with "for portland group".

gfortran is a widely available compiler that is preinstalled on all lab machines. In order to compile with gfortran, start from the base directory of DOCK and follow these instructions:

cd dock3/src/libfgz
COMPILER=gfortran make
cd ../i386
COMPILER=gfortran make

You should now have a bunch of .o object files as well as a dock64 executable in the i386 directory. If you want to compile a debug build add DEBUG=1 before make, and if you want to compile for a different architecture prefix make with SIZE=[32|64]

If you mistakenly compile something (wrong compiler or the like) you can clean up the files produced from compilation with "make clean". Don't worry about the error messages you may get from this, something is a little fishy with our makefile.

It may be necessary to run make twice due to an odd error with the version.f file.

=== pgf instructions ===

**Note**: in search.f and search_multi_cluster.f you need to (1) comment out the lines that are commented with "for gfortran" and (2) uncomment the lines that are commented with "for portland group".

PGF or the Portland Group compiler is the premium option for fortran compilation. In order to compile with pgf you must log onto the psi machine, where the license and installation is located.

ssh $USER@psi

Set up the compilation environment through the following script:

bash # if you are not already on bash
export PATH=/nfs/soft/pgi/current/linux86-64/12.10/bin:$PATH
source /nfs/home/tbalius/zzz.virtualenvs/virtualenv-1.9.1/myVEonGimel/bin/activate
source /nfs/soft/pgi/env.sh

The instructions to compile are identical to those for gfortran, the only difference being you need to set COMPILER=pgf, e.g

cd dock3/src/libfgz
COMPILER=pgf make
cd ../i386
COMPILER=pgf make

You can add DEBUG, SIZE etc. options just like gfortran.

Sometimes there is an odd error with the licensing server that causes compilation to fail. I don't remember exactly I fixed this in the past, but I believe it had to do with restarting the license service via systemctl.

It may be necessary to run make twice due to an odd error with the version.f file.

== compiling dock3.7 ==

1. log into psi (portland fortran compiler is on psi)
2. export PATH=/nfs/soft/pgi/current/linux86-64/12.10/bin:$PATH
3. source Trent's virual environment (source /nfs/home/tbalius/zzz.virtualenvs/virtualenv-1.9.1/myVEonGimel/bin/activate)
4. source /nfs/soft/pgi/env.csh

== DOCK 3.7 ==

Frist you need the source code:
* lab members and other developers may check out dock from [[Github]]
* others can request the distrabution here [http://dock.compbio.ucsf.edu/Online_Licensing/dock_license_application.html]
=== compiling dock ===

To compile DOCK go to path/DOCK/src/i386
make
make DEBUG=1
make SIZE=32 [64]
make clean

Note:
*To compile with portland group compilers
** go to a machine were pgf linsence is installed (sgehead1 or psi).

*To add a file for compilation, add the xxxx.f file to path/DOCK/src/ and add xxxx.o to i386/Makefile object list.
=== debuging dock ===
Debugging :

pgdbg path/DOCK/src/i386/dock_prof64

=== profiling dock ===
Profiling:
make pgprofile
less pgprof.out
pgprof - opens a GUI profiler that interprets pgprof.out !

you may also do the following:
make dock_prof64
cd /dir/test
/dockdir/dock_prof64 INDOCK
less pgprof.out

make gmon.out
less gmon.out

make gprofile
less gprofile.txt

== DOCK 3.5.54 ==
This is for the Shoichet Lab local version of DOCK 3.5.54 trunk.

'''Checking out the source files'''

Commands:
csh
mkdir /where/to/put
cd /where/to/put
svn checkout file:///raid4/svn/dock
svn checkout file:///raid4/svn/libfgz

'''Compiling the program on our cluster'''

First, you need to set the path to the PGF compiler by adding this line to your .login file (at the end):

setenv DOCK_BASE ~xyz/dockenv
echo DOCK_BASE set to $DOCK_BASE.
source $DOCK_BASE/etc/login

When you login to sgehead now, you should see the "Enabling pgf compiler" message

Commands:
ssh sgehead
cd /where/to/put/libfgz/trunk
make

Since we still have some 32bit computers, you'll also want to do
make SIZE=32
before leaving the libfgz branch and going to DOCK:

cd ../../dock/trunk/i386
make

This makes the 64 bit version. Some options:

make SIZE=32

Makes the 32bit version, useful for running on the cluster since some machines are older.

make DEBUG=1

Makes a debug version that will report line numbers of errors and is usable with pgdbg (the Portland Group Debugger), which is useful when writing code but is 10x (or more) slower.

'''Compiling the program on the shared QB3 cluster'''

On one of the compilation nodes on the shared QB3 cluster (optint1 or optint2):

ssh optint2
cd /where/to/put/libfgz/trunk
cp Makefile Makefile.old
modify Makefile:
uncomment the following:
FC = ifort -O3
CC = icc -O3
make
cd ../../dock/trunk/i386
cp Makefile Makefile.old
modify Makefile
uncomment the following:
F77 = ifort
FFLAGS = -O3 -convert big_endian
make dock

[[Category:Tutorials]]
[[Category:DOCK]]

How to compile DOCK

2022-10-07T16:53:59Z

Ianscottknight: /* pgf instructions */

== compiling dock3.8 ==

Note- not every machine will have the prerequisite development libraries installed to compile DOCK fortran code. It is best to log into our "psi" machine, which is known to have the prerequisite libraries. Note: git will not work from psi, so you will need to have the code you would like to compile accessible via the NFS.

ssh $USER@psi

Wynton development nodes are also a good place to compile with gfortran. For PGF you will always need to log into our psi machine.

=== gfortran instructions ===

Note: in search.f and search_multi_cluster.f you need to (1) uncomment the lines that are commented with "for gfortran" and (2) comment out the lines that are commented with "for portland group".

gfortran is a widely available compiler that is preinstalled on all lab machines. In order to compile with gfortran, start from the base directory of DOCK and follow these instructions:

cd dock3/src/libfgz
COMPILER=gfortran make
cd ../i386
COMPILER=gfortran make

You should now have a bunch of .o object files as well as a dock64 executable in the i386 directory. If you want to compile a debug build add DEBUG=1 before make, and if you want to compile for a different architecture prefix make with SIZE=[32|64]

If you mistakenly compile something (wrong compiler or the like) you can clean up the files produced from compilation with "make clean". Don't worry about the error messages you may get from this, something is a little fishy with our makefile.

It may be necessary to run make twice due to an odd error with the version.f file.

=== pgf instructions ===

Note: in search.f and search_multi_cluster.f you need to (1) comment out the lines that are commented with "for gfortran" and (2) uncomment the lines that are commented with "for portland group".

PGF or the Portland Group compiler is the premium option for fortran compilation. In order to compile with pgf you must log onto the psi machine, where the license and installation is located.

ssh $USER@psi

Set up the compilation environment through the following script:

bash # if you are not already on bash
export PATH=/nfs/soft/pgi/current/linux86-64/12.10/bin:$PATH
source /nfs/home/tbalius/zzz.virtualenvs/virtualenv-1.9.1/myVEonGimel/bin/activate
source /nfs/soft/pgi/env.sh

The instructions to compile are identical to those for gfortran, the only difference being you need to set COMPILER=pgf, e.g

cd dock3/src/libfgz
COMPILER=pgf make
cd ../i386
COMPILER=pgf make

You can add DEBUG, SIZE etc. options just like gfortran.

Sometimes there is an odd error with the licensing server that causes compilation to fail. I don't remember exactly I fixed this in the past, but I believe it had to do with restarting the license service via systemctl.

It may be necessary to run make twice due to an odd error with the version.f file.

== compiling dock3.7 ==

1. log into psi (portland fortran compiler is on psi)
2. export PATH=/nfs/soft/pgi/current/linux86-64/12.10/bin:$PATH
3. source Trent's virual environment (source /nfs/home/tbalius/zzz.virtualenvs/virtualenv-1.9.1/myVEonGimel/bin/activate)
4. source /nfs/soft/pgi/env.csh

== DOCK 3.7 ==

Frist you need the source code:
* lab members and other developers may check out dock from [[Github]]
* others can request the distrabution here [http://dock.compbio.ucsf.edu/Online_Licensing/dock_license_application.html]
=== compiling dock ===

To compile DOCK go to path/DOCK/src/i386
make
make DEBUG=1
make SIZE=32 [64]
make clean

Note:
*To compile with portland group compilers
** go to a machine were pgf linsence is installed (sgehead1 or psi).

*To add a file for compilation, add the xxxx.f file to path/DOCK/src/ and add xxxx.o to i386/Makefile object list.
=== debuging dock ===
Debugging :

pgdbg path/DOCK/src/i386/dock_prof64

=== profiling dock ===
Profiling:
make pgprofile
less pgprof.out
pgprof - opens a GUI profiler that interprets pgprof.out !

you may also do the following:
make dock_prof64
cd /dir/test
/dockdir/dock_prof64 INDOCK
less pgprof.out

make gmon.out
less gmon.out

make gprofile
less gprofile.txt

== DOCK 3.5.54 ==
This is for the Shoichet Lab local version of DOCK 3.5.54 trunk.

'''Checking out the source files'''

Commands:
csh
mkdir /where/to/put
cd /where/to/put
svn checkout file:///raid4/svn/dock
svn checkout file:///raid4/svn/libfgz

'''Compiling the program on our cluster'''

First, you need to set the path to the PGF compiler by adding this line to your .login file (at the end):

setenv DOCK_BASE ~xyz/dockenv
echo DOCK_BASE set to $DOCK_BASE.
source $DOCK_BASE/etc/login

When you login to sgehead now, you should see the "Enabling pgf compiler" message

Commands:
ssh sgehead
cd /where/to/put/libfgz/trunk
make

Since we still have some 32bit computers, you'll also want to do
make SIZE=32
before leaving the libfgz branch and going to DOCK:

cd ../../dock/trunk/i386
make

This makes the 64 bit version. Some options:

make SIZE=32

Makes the 32bit version, useful for running on the cluster since some machines are older.

make DEBUG=1

Makes a debug version that will report line numbers of errors and is usable with pgdbg (the Portland Group Debugger), which is useful when writing code but is 10x (or more) slower.

'''Compiling the program on the shared QB3 cluster'''

On one of the compilation nodes on the shared QB3 cluster (optint1 or optint2):

ssh optint2
cd /where/to/put/libfgz/trunk
cp Makefile Makefile.old
modify Makefile:
uncomment the following:
FC = ifort -O3
CC = icc -O3
make
cd ../../dock/trunk/i386
cp Makefile Makefile.old
modify Makefile
uncomment the following:
F77 = ifort
FFLAGS = -O3 -convert big_endian
make dock

[[Category:Tutorials]]
[[Category:DOCK]]

How to compile DOCK

2022-10-07T16:53:37Z

Ianscottknight: /* gfortran instructions */

== compiling dock3.8 ==

Note- not every machine will have the prerequisite development libraries installed to compile DOCK fortran code. It is best to log into our "psi" machine, which is known to have the prerequisite libraries. Note: git will not work from psi, so you will need to have the code you would like to compile accessible via the NFS.

ssh $USER@psi

Wynton development nodes are also a good place to compile with gfortran. For PGF you will always need to log into our psi machine.

=== gfortran instructions ===

Note: in search.f and search_multi_cluster.f you need to (1) uncomment the lines that are commented with "for gfortran" and (2) comment out the lines that are commented with "for portland group".

gfortran is a widely available compiler that is preinstalled on all lab machines. In order to compile with gfortran, start from the base directory of DOCK and follow these instructions:

cd dock3/src/libfgz
COMPILER=gfortran make
cd ../i386
COMPILER=gfortran make

You should now have a bunch of .o object files as well as a dock64 executable in the i386 directory. If you want to compile a debug build add DEBUG=1 before make, and if you want to compile for a different architecture prefix make with SIZE=[32|64]

If you mistakenly compile something (wrong compiler or the like) you can clean up the files produced from compilation with "make clean". Don't worry about the error messages you may get from this, something is a little fishy with our makefile.

It may be necessary to run make twice due to an odd error with the version.f file.

=== pgf instructions ===

PGF or the Portland Group compiler is the premium option for fortran compilation. In order to compile with pgf you must log onto the psi machine, where the license and installation is located.

ssh $USER@psi

Set up the compilation environment through the following script:

bash # if you are not already on bash
export PATH=/nfs/soft/pgi/current/linux86-64/12.10/bin:$PATH
source /nfs/home/tbalius/zzz.virtualenvs/virtualenv-1.9.1/myVEonGimel/bin/activate
source /nfs/soft/pgi/env.sh

Note: in search.f and search_multi_cluster.f you need to (1) comment out the lines that are commented with "for gfortran" and (2) uncomment the lines that are commented with "for portland group".

The instructions to compile are identical to those for gfortran, the only difference being you need to set COMPILER=pgf, e.g

cd dock3/src/libfgz
COMPILER=pgf make
cd ../i386
COMPILER=pgf make

You can add DEBUG, SIZE etc. options just like gfortran.

Sometimes there is an odd error with the licensing server that causes compilation to fail. I don't remember exactly I fixed this in the past, but I believe it had to do with restarting the license service via systemctl.

It may be necessary to run make twice due to an odd error with the version.f file.

== compiling dock3.7 ==

1. log into psi (portland fortran compiler is on psi)
2. export PATH=/nfs/soft/pgi/current/linux86-64/12.10/bin:$PATH
3. source Trent's virual environment (source /nfs/home/tbalius/zzz.virtualenvs/virtualenv-1.9.1/myVEonGimel/bin/activate)
4. source /nfs/soft/pgi/env.csh

== DOCK 3.7 ==

Frist you need the source code:
* lab members and other developers may check out dock from [[Github]]
* others can request the distrabution here [http://dock.compbio.ucsf.edu/Online_Licensing/dock_license_application.html]
=== compiling dock ===

To compile DOCK go to path/DOCK/src/i386
make
make DEBUG=1
make SIZE=32 [64]
make clean

Note:
*To compile with portland group compilers
** go to a machine were pgf linsence is installed (sgehead1 or psi).

*To add a file for compilation, add the xxxx.f file to path/DOCK/src/ and add xxxx.o to i386/Makefile object list.
=== debuging dock ===
Debugging :

pgdbg path/DOCK/src/i386/dock_prof64

=== profiling dock ===
Profiling:
make pgprofile
less pgprof.out
pgprof - opens a GUI profiler that interprets pgprof.out !

you may also do the following:
make dock_prof64
cd /dir/test
/dockdir/dock_prof64 INDOCK
less pgprof.out

make gmon.out
less gmon.out

make gprofile
less gprofile.txt

== DOCK 3.5.54 ==
This is for the Shoichet Lab local version of DOCK 3.5.54 trunk.

'''Checking out the source files'''

Commands:
csh
mkdir /where/to/put
cd /where/to/put
svn checkout file:///raid4/svn/dock
svn checkout file:///raid4/svn/libfgz

'''Compiling the program on our cluster'''

First, you need to set the path to the PGF compiler by adding this line to your .login file (at the end):

setenv DOCK_BASE ~xyz/dockenv
echo DOCK_BASE set to $DOCK_BASE.
source $DOCK_BASE/etc/login

When you login to sgehead now, you should see the "Enabling pgf compiler" message

Commands:
ssh sgehead
cd /where/to/put/libfgz/trunk
make

Since we still have some 32bit computers, you'll also want to do
make SIZE=32
before leaving the libfgz branch and going to DOCK:

cd ../../dock/trunk/i386
make

This makes the 64 bit version. Some options:

make SIZE=32

Makes the 32bit version, useful for running on the cluster since some machines are older.

make DEBUG=1

Makes a debug version that will report line numbers of errors and is usable with pgdbg (the Portland Group Debugger), which is useful when writing code but is 10x (or more) slower.

'''Compiling the program on the shared QB3 cluster'''

On one of the compilation nodes on the shared QB3 cluster (optint1 or optint2):

ssh optint2
cd /where/to/put/libfgz/trunk
cp Makefile Makefile.old
modify Makefile:
uncomment the following:
FC = ifort -O3
CC = icc -O3
make
cd ../../dock/trunk/i386
cp Makefile Makefile.old
modify Makefile
uncomment the following:
F77 = ifort
FFLAGS = -O3 -convert big_endian
make dock

[[Category:Tutorials]]
[[Category:DOCK]]

How to compile DOCK

2022-10-07T16:53:07Z

Ianscottknight:

== compiling dock3.8 ==

Note- not every machine will have the prerequisite development libraries installed to compile DOCK fortran code. It is best to log into our "psi" machine, which is known to have the prerequisite libraries. Note: git will not work from psi, so you will need to have the code you would like to compile accessible via the NFS.

ssh $USER@psi

Wynton development nodes are also a good place to compile with gfortran. For PGF you will always need to log into our psi machine.

=== gfortran instructions ===

gfortran is a widely available compiler that is preinstalled on all lab machines. In order to compile with gfortran, start from the base directory of DOCK and follow these instructions:

cd dock3/src/libfgz
COMPILER=gfortran make
cd ../i386
COMPILER=gfortran make

You should now have a bunch of .o object files as well as a dock64 executable in the i386 directory. If you want to compile a debug build add DEBUG=1 before make, and if you want to compile for a different architecture prefix make with SIZE=[32|64]

If you mistakenly compile something (wrong compiler or the like) you can clean up the files produced from compilation with "make clean". Don't worry about the error messages you may get from this, something is a little fishy with our makefile.

It may be necessary to run make twice due to an odd error with the version.f file.

=== pgf instructions ===

PGF or the Portland Group compiler is the premium option for fortran compilation. In order to compile with pgf you must log onto the psi machine, where the license and installation is located.

ssh $USER@psi

Set up the compilation environment through the following script:

bash # if you are not already on bash
export PATH=/nfs/soft/pgi/current/linux86-64/12.10/bin:$PATH
source /nfs/home/tbalius/zzz.virtualenvs/virtualenv-1.9.1/myVEonGimel/bin/activate
source /nfs/soft/pgi/env.sh

Note: in search.f and search_multi_cluster.f you need to (1) comment out the lines that are commented with "for gfortran" and (2) uncomment the lines that are commented with "for portland group".

The instructions to compile are identical to those for gfortran, the only difference being you need to set COMPILER=pgf, e.g

cd dock3/src/libfgz
COMPILER=pgf make
cd ../i386
COMPILER=pgf make

You can add DEBUG, SIZE etc. options just like gfortran.

Sometimes there is an odd error with the licensing server that causes compilation to fail. I don't remember exactly I fixed this in the past, but I believe it had to do with restarting the license service via systemctl.

It may be necessary to run make twice due to an odd error with the version.f file.

== compiling dock3.7 ==

1. log into psi (portland fortran compiler is on psi)
2. export PATH=/nfs/soft/pgi/current/linux86-64/12.10/bin:$PATH
3. source Trent's virual environment (source /nfs/home/tbalius/zzz.virtualenvs/virtualenv-1.9.1/myVEonGimel/bin/activate)
4. source /nfs/soft/pgi/env.csh

== DOCK 3.7 ==

Frist you need the source code:
* lab members and other developers may check out dock from [[Github]]
* others can request the distrabution here [http://dock.compbio.ucsf.edu/Online_Licensing/dock_license_application.html]
=== compiling dock ===

To compile DOCK go to path/DOCK/src/i386
make
make DEBUG=1
make SIZE=32 [64]
make clean

Note:
*To compile with portland group compilers
** go to a machine were pgf linsence is installed (sgehead1 or psi).

*To add a file for compilation, add the xxxx.f file to path/DOCK/src/ and add xxxx.o to i386/Makefile object list.
=== debuging dock ===
Debugging :

pgdbg path/DOCK/src/i386/dock_prof64

=== profiling dock ===
Profiling:
make pgprofile
less pgprof.out
pgprof - opens a GUI profiler that interprets pgprof.out !

you may also do the following:
make dock_prof64
cd /dir/test
/dockdir/dock_prof64 INDOCK
less pgprof.out

make gmon.out
less gmon.out

make gprofile
less gprofile.txt

== DOCK 3.5.54 ==
This is for the Shoichet Lab local version of DOCK 3.5.54 trunk.

'''Checking out the source files'''

Commands:
csh
mkdir /where/to/put
cd /where/to/put
svn checkout file:///raid4/svn/dock
svn checkout file:///raid4/svn/libfgz

'''Compiling the program on our cluster'''

First, you need to set the path to the PGF compiler by adding this line to your .login file (at the end):

setenv DOCK_BASE ~xyz/dockenv
echo DOCK_BASE set to $DOCK_BASE.
source $DOCK_BASE/etc/login

When you login to sgehead now, you should see the "Enabling pgf compiler" message

Commands:
ssh sgehead
cd /where/to/put/libfgz/trunk
make

Since we still have some 32bit computers, you'll also want to do
make SIZE=32
before leaving the libfgz branch and going to DOCK:

cd ../../dock/trunk/i386
make

This makes the 64 bit version. Some options:

make SIZE=32

Makes the 32bit version, useful for running on the cluster since some machines are older.

make DEBUG=1

Makes a debug version that will report line numbers of errors and is usable with pgdbg (the Portland Group Debugger), which is useful when writing code but is 10x (or more) slower.

'''Compiling the program on the shared QB3 cluster'''

On one of the compilation nodes on the shared QB3 cluster (optint1 or optint2):

ssh optint2
cd /where/to/put/libfgz/trunk
cp Makefile Makefile.old
modify Makefile:
uncomment the following:
FC = ifort -O3
CC = icc -O3
make
cd ../../dock/trunk/i386
cp Makefile Makefile.old
modify Makefile
uncomment the following:
F77 = ifort
FFLAGS = -O3 -convert big_endian
make dock

[[Category:Tutorials]]
[[Category:DOCK]]

How to compile DOCK

2022-10-06T00:11:27Z

Ianscottknight: /* pgf instructions */

== compiling dock3.8 ==

Note- not every machine will have the prerequisite development libraries installed to compile DOCK fortran code. It is best to log into our "psi" machine, which is known to have the prerequisite libraries. Note: git will not work from psi, so you will need to have the code you would like to compile accessible via the NFS.

ssh $USER@psi

Wynton development nodes are also a good place to compile with gfortran. For PGF you will always need to log into our psi machine.

=== gfortran instructions ===

gfortran is a widely available compiler that is preinstalled on all lab machines. In order to compile with gfortran, start from the base directory of DOCK and follow these instructions:

cd dock3/src/libfgz
COMPILER=gfortran make
cd ../i386
COMPILER=gfortran make

You should now have a bunch of .o object files as well as a dock64 executable in the i386 directory. If you want to compile a debug build add DEBUG=1 before make, and if you want to compile for a different architecture prefix make with SIZE=[32|64]

If you mistakenly compile something (wrong compiler or the like) you can clean up the files produced from compilation with "make clean". Don't worry about the error messages you may get from this, something is a little fishy with our makefile.

It may be necessary to run make twice due to an odd error with the version.f file.

=== pgf instructions ===

PGF or the Portland Group compiler is the premium option for fortran compilation. In order to compile with pgf you must log onto the psi machine, where the license and installation is located.

ssh $USER@psi

Set up the compilation environment through the following script:

bash # if you are not already on bash
export PATH=/nfs/soft/pgi/current/linux86-64/12.10/bin:$PATH
source /nfs/home/tbalius/zzz.virtualenvs/virtualenv-1.9.1/myVEonGimel/bin/activate
source /nfs/soft/pgi/env.sh

The instructions to compile are identical to those for gfortran, the only difference being you need to set COMPILER=pgf, e.g

cd dock3/src/libfgz
COMPILER=pgf make
cd ../i386
COMPILER=pgf make

You can add DEBUG, SIZE etc. options just like gfortran.

Sometimes there is an odd error with the licensing server that causes compilation to fail. I don't remember exactly I fixed this in the past, but I believe it had to do with restarting the license service via systemctl.

It may be necessary to run make twice due to an odd error with the version.f file.

== compiling dock3.7 ==

1. log into psi (portland fortran compiler is on psi)
2. export PATH=/nfs/soft/pgi/current/linux86-64/12.10/bin:$PATH
3. source Trent's virual environment (source /nfs/home/tbalius/zzz.virtualenvs/virtualenv-1.9.1/myVEonGimel/bin/activate)
4. source /nfs/soft/pgi/env.csh

== DOCK 3.7 ==

Frist you need the source code:
* lab members and other developers may check out dock from [[Github]]
* others can request the distrabution here [http://dock.compbio.ucsf.edu/Online_Licensing/dock_license_application.html]
=== compiling dock ===

To compile DOCK go to path/DOCK/src/i386
make
make DEBUG=1
make SIZE=32 [64]
make clean

Note:
*To compile with portland group compilers
** go to a machine were pgf linsence is installed (sgehead1 or psi).

*To add a file for compilation, add the xxxx.f file to path/DOCK/src/ and add xxxx.o to i386/Makefile object list.
=== debuging dock ===
Debugging :

pgdbg path/DOCK/src/i386/dock_prof64

=== profiling dock ===
Profiling:
make pgprofile
less pgprof.out
pgprof - opens a GUI profiler that interprets pgprof.out !

you may also do the following:
make dock_prof64
cd /dir/test
/dockdir/dock_prof64 INDOCK
less pgprof.out

make gmon.out
less gmon.out

make gprofile
less gprofile.txt

== DOCK 3.5.54 ==
This is for the Shoichet Lab local version of DOCK 3.5.54 trunk.

'''Checking out the source files'''

Commands:
csh
mkdir /where/to/put
cd /where/to/put
svn checkout file:///raid4/svn/dock
svn checkout file:///raid4/svn/libfgz

'''Compiling the program on our cluster'''

First, you need to set the path to the PGF compiler by adding this line to your .login file (at the end):

setenv DOCK_BASE ~xyz/dockenv
echo DOCK_BASE set to $DOCK_BASE.
source $DOCK_BASE/etc/login

When you login to sgehead now, you should see the "Enabling pgf compiler" message

Commands:
ssh sgehead
cd /where/to/put/libfgz/trunk
make

Since we still have some 32bit computers, you'll also want to do
make SIZE=32
before leaving the libfgz branch and going to DOCK:

cd ../../dock/trunk/i386
make

This makes the 64 bit version. Some options:

make SIZE=32

Makes the 32bit version, useful for running on the cluster since some machines are older.

make DEBUG=1

Makes a debug version that will report line numbers of errors and is usable with pgdbg (the Portland Group Debugger), which is useful when writing code but is 10x (or more) slower.

'''Compiling the program on the shared QB3 cluster'''

On one of the compilation nodes on the shared QB3 cluster (optint1 or optint2):

ssh optint2
cd /where/to/put/libfgz/trunk
cp Makefile Makefile.old
modify Makefile:
uncomment the following:
FC = ifort -O3
CC = icc -O3
make
cd ../../dock/trunk/i386
cp Makefile Makefile.old
modify Makefile
uncomment the following:
F77 = ifort
FFLAGS = -O3 -convert big_endian
make dock

[[Category:Tutorials]]
[[Category:DOCK]]

How to compile DOCK

2022-10-06T00:11:03Z

Ianscottknight: /* gfortran instructions */

== compiling dock3.8 ==

Note- not every machine will have the prerequisite development libraries installed to compile DOCK fortran code. It is best to log into our "psi" machine, which is known to have the prerequisite libraries. Note: git will not work from psi, so you will need to have the code you would like to compile accessible via the NFS.

ssh $USER@psi

Wynton development nodes are also a good place to compile with gfortran. For PGF you will always need to log into our psi machine.

=== gfortran instructions ===

gfortran is a widely available compiler that is preinstalled on all lab machines. In order to compile with gfortran, start from the base directory of DOCK and follow these instructions:

cd dock3/src/libfgz
COMPILER=gfortran make
cd ../i386
COMPILER=gfortran make

You should now have a bunch of .o object files as well as a dock64 executable in the i386 directory. If you want to compile a debug build add DEBUG=1 before make, and if you want to compile for a different architecture prefix make with SIZE=[32|64]

If you mistakenly compile something (wrong compiler or the like) you can clean up the files produced from compilation with "make clean". Don't worry about the error messages you may get from this, something is a little fishy with our makefile.

It may be necessary to run make twice due to an odd error with the version.f file.

=== pgf instructions ===

PGF or the Portland Group compiler is the premium option for fortran compilation. In order to compile with pgf you must log onto the psi machine, where the license and installation is located.

ssh $USER@psi

Set up the compilation environment through the following script:

bash # if you are not already on bash
export PATH=/nfs/soft/pgi/current/linux86-64/12.10/bin:$PATH
source /nfs/home/tbalius/zzz.virtualenvs/virtualenv-1.9.1/myVEonGimel/bin/activate
source /nfs/soft/pgi/env.sh

The instructions to compile are identical to those for gfortran, the only difference being you need to set COMPILER=pgf, e.g

cd ucsfdock/docking/DOCK/src/libfgz
COMPILER=pgf make
cd ../i386
COMPILER=pgf make

You can add DEBUG, SIZE etc. options just like gfortran.

Sometimes there is an odd error with the licensing server that causes compilation to fail. I don't remember exactly I fixed this in the past, but I believe it had to do with restarting the license service via systemctl.

It may be necessary to run make twice due to an odd error with the version.f file.

== compiling dock3.7 ==

1. log into psi (portland fortran compiler is on psi)
2. export PATH=/nfs/soft/pgi/current/linux86-64/12.10/bin:$PATH
3. source Trent's virual environment (source /nfs/home/tbalius/zzz.virtualenvs/virtualenv-1.9.1/myVEonGimel/bin/activate)
4. source /nfs/soft/pgi/env.csh

== DOCK 3.7 ==

Frist you need the source code:
* lab members and other developers may check out dock from [[Github]]
* others can request the distrabution here [http://dock.compbio.ucsf.edu/Online_Licensing/dock_license_application.html]
=== compiling dock ===

To compile DOCK go to path/DOCK/src/i386
make
make DEBUG=1
make SIZE=32 [64]
make clean

Note:
*To compile with portland group compilers
** go to a machine were pgf linsence is installed (sgehead1 or psi).

*To add a file for compilation, add the xxxx.f file to path/DOCK/src/ and add xxxx.o to i386/Makefile object list.
=== debuging dock ===
Debugging :

pgdbg path/DOCK/src/i386/dock_prof64

=== profiling dock ===
Profiling:
make pgprofile
less pgprof.out
pgprof - opens a GUI profiler that interprets pgprof.out !

you may also do the following:
make dock_prof64
cd /dir/test
/dockdir/dock_prof64 INDOCK
less pgprof.out

make gmon.out
less gmon.out

make gprofile
less gprofile.txt

== DOCK 3.5.54 ==
This is for the Shoichet Lab local version of DOCK 3.5.54 trunk.

'''Checking out the source files'''

Commands:
csh
mkdir /where/to/put
cd /where/to/put
svn checkout file:///raid4/svn/dock
svn checkout file:///raid4/svn/libfgz

'''Compiling the program on our cluster'''

First, you need to set the path to the PGF compiler by adding this line to your .login file (at the end):

setenv DOCK_BASE ~xyz/dockenv
echo DOCK_BASE set to $DOCK_BASE.
source $DOCK_BASE/etc/login

When you login to sgehead now, you should see the "Enabling pgf compiler" message

Commands:
ssh sgehead
cd /where/to/put/libfgz/trunk
make

Since we still have some 32bit computers, you'll also want to do
make SIZE=32
before leaving the libfgz branch and going to DOCK:

cd ../../dock/trunk/i386
make

This makes the 64 bit version. Some options:

make SIZE=32

Makes the 32bit version, useful for running on the cluster since some machines are older.

make DEBUG=1

Makes a debug version that will report line numbers of errors and is usable with pgdbg (the Portland Group Debugger), which is useful when writing code but is 10x (or more) slower.

'''Compiling the program on the shared QB3 cluster'''

On one of the compilation nodes on the shared QB3 cluster (optint1 or optint2):

ssh optint2
cd /where/to/put/libfgz/trunk
cp Makefile Makefile.old
modify Makefile:
uncomment the following:
FC = ifort -O3
CC = icc -O3
make
cd ../../dock/trunk/i386
cp Makefile Makefile.old
modify Makefile
uncomment the following:
F77 = ifort
FFLAGS = -O3 -convert big_endian
make dock

[[Category:Tutorials]]
[[Category:DOCK]]

Dockopt (pydock3 script)

2022-09-15T19:51:30Z

Ianscottknight: /* SGE */

''dockopt'' allows the generation of many different docking configurations which are then evaluated & analyzed in parallel using a specified job scheduler (e.g. Slurm).

== ''init'' ==

First you need to create the file structure for your dockopt job. To do so, simply type

pydock3 dockopt - init

By default, the job directory is named ''dockopt_job''. To specify a different name, type

pydock3 dockopt - init <JOB_DIR_NAME>

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''retrodock_jobs'': individual retrodock jobs for each docking configuration

The key difference between the working directories of ''blastermaster'' and ''dockopt'' is that the working directory of ''dockopt'' may contain multiple variants of the blaster files (prefixed by a number, e.g. "1_box"). These variant files are used to create the different docking configurations specified by the multi-valued entries of ''dockopt_config.yaml''. They are created efficiently, such that the same variant used in multiple docking configurations is not created more than once.

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the dockopt job.

* ''rec.pdb''
* ''xtal-lig.pdb''
* ''rec.crg.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb''
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''dockopt_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of dockopt.

'''Note:''' The ''dockopt_config.yaml'' file differs from the ''blastermaster_config.yaml'' file in that every parameter of the former may accept either a single value or a ''list of comma-separated values'', which indicates a pool of values to attempt for that parameter. Multiple such multi-valued parameters may be provided, and all unique resultant docking configurations will be attempted.

Single-valued YAML line format:

distance_to_surface: 1.0

Multi-valued YAML line format:

distance_to_surface: [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]

== Environmental variables ==

Designate where temporary job files should be placed. E.g.:

export TEMP_STORAGE_PATH=/scratch

In order for ''dockopt'' to know which scheduler it should use, please configure the following environmental variables according to which one of the job schedulers you have.

=== Slurm ===

E.g., on the UCSF Shoichet Lab Gimel cluster (on any node other than 'gimel' itself, such as 'gimel5'):

export SBATCH_EXEC=/usr/bin/sbatch
export SQUEUE_EXEC=/usr/bin/squeue

=== SGE ===

E.g., on the UCSF Wynton cluster:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub

The following is necessary on the UCSF Wynton cluster:

export SGE_SETTINGS=/opt/sge/wynton/common/settings.sh

On most clusters using SGE, this will probably be:

export SGE_SETTINGS=/opt/sge/default/common/settings.sh

== ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run ''dockopt'':
cd <JOB_DIR_NAME>
pydock3 dockopt - run <JOB_SCHEDULER_NAME> [--retrodock_job_timeout_minutes=None] [--retrodock_job_max_reattempts=0]

where <JOB_SCHEDULER_NAME> is one of:
* ''sge''
* ''slurm''

This will execute the many dockopt subroutines in sequence, except for the retrodock jobs run on each docking configuration, which are run in parallel via the scheduler. The state of the program will be printed to standard output as it runs.

Once the dockopt job is complete, the following files will be generated in the job directory:
* ''dockopt_job_report.pdf'': contains (1) roc.png of best retrodock job, (2) box plots of enrichment for every multi-valued config parameter, and (3) heatmaps of enrichment for every pair of multi-valued config parameters
* ''dockopt_job_results.csv'': enrichment metrics for each docking configuration

In addition, the best retrodock job will be copied to its own sub-directory ''best_retrodock_job/''.

Within best_retrodock_job, there are the following files and sub-directories:
* ''dockfiles/'': parameters files and INDOCK for given docking configuration
* ''output/'': contains:
** joblist
** sub-directories ''1/'' for actives and ''2/'' for decoys (the former containing OUTDOCK and test.mol2 files, the latter containing just OUTDOCK)
** log files for the retrodock jobs
* ''roc.png'': the ROC enrichment curve (log-scaled x-axis) for given docking configuration

'''Note:''' by default, a mol2 file is exported only for actives (''output/1/''), not for decoys (''output/2/''), in order to prevent disk space issues.

Dockopt (pydock3 script)

2022-09-15T19:50:21Z

Ianscottknight: /* run */

''dockopt'' allows the generation of many different docking configurations which are then evaluated & analyzed in parallel using a specified job scheduler (e.g. Slurm).

== ''init'' ==

First you need to create the file structure for your dockopt job. To do so, simply type

pydock3 dockopt - init

By default, the job directory is named ''dockopt_job''. To specify a different name, type

pydock3 dockopt - init <JOB_DIR_NAME>

The job directory contains two sub-directories:
# ''working'': input files, intermediate blaster files, sub-directories for individual blastermaster subroutines
# ''retrodock_jobs'': individual retrodock jobs for each docking configuration

The key difference between the working directories of ''blastermaster'' and ''dockopt'' is that the working directory of ''dockopt'' may contain multiple variants of the blaster files (prefixed by a number, e.g. "1_box"). These variant files are used to create the different docking configurations specified by the multi-valued entries of ''dockopt_config.yaml''. They are created efficiently, such that the same variant used in multiple docking configurations is not created more than once.

If your current working directory contains any of the following files, then they will be automatically copied into the working directory within the created job directory. This feature is intended to simplify the process of configuring the dockopt job.

* ''rec.pdb''
* ''xtal-lig.pdb''
* ''rec.crg.pdb''
* ''reduce_wwPDB_het_dict.txt''
* ''filt.params''
* ''radii''
* ''amb.crg.oxt''
* ''vdw.siz''
* ''delphi.def''
* ''vdw.parms.amb.mindock''
* ''prot.table.ambcrg.ambH''

Only the following are required. Default versions / generated versions of the others will be used instead if they are not detected.
* ''rec.pdb''
* ''xtal-lig.pdb''

If you would like to use files not present in your current working directory, copy them into your job's working directory, e.g.:
cp <FILE_PATH> <JOB_DIR_NAME>/working/

Finally, configure the ''dockopt_config.yaml'' file in the job directory to your specifications. The parameters in this file govern the behavior of dockopt.

'''Note:''' The ''dockopt_config.yaml'' file differs from the ''blastermaster_config.yaml'' file in that every parameter of the former may accept either a single value or a ''list of comma-separated values'', which indicates a pool of values to attempt for that parameter. Multiple such multi-valued parameters may be provided, and all unique resultant docking configurations will be attempted.

Single-valued YAML line format:

distance_to_surface: 1.0

Multi-valued YAML line format:

distance_to_surface: [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]

== Environmental variables ==

Designate where temporary job files should be placed. E.g.:

export TEMP_STORAGE_PATH=/scratch

In order for ''dockopt'' to know which scheduler it should use, please configure the following environmental variables according to which one of the job schedulers you have.

=== Slurm ===

E.g., on the UCSF Shoichet Lab Gimel cluster (on any node other than 'gimel' itself, such as 'gimel5'):

export SBATCH_EXEC=/usr/bin/sbatch
export SQUEUE_EXEC=/usr/bin/squeue

=== SGE ===

E.g., on the UCSF Wynton cluster:

export QSTAT_EXEC=/opt/sge/bin/lx-amd64/qstat
export QSUB_EXEC=/opt/sge/bin/lx-amd64/qsub

The following is necessary on the UCSF Wynton cluster:

export SGE_SETTINGS=/opt/sge/wynton/common/settings.sh

On most clusters, this will probably be:

export SGE_SETTINGS=/opt/sge/default/common/settings.sh

== ''run'' ==

Once your job has been configured to your liking, navigate to the the job directory and run ''dockopt'':
cd <JOB_DIR_NAME>
pydock3 dockopt - run <JOB_SCHEDULER_NAME> [--retrodock_job_timeout_minutes=None] [--retrodock_job_max_reattempts=0]

where <JOB_SCHEDULER_NAME> is one of:
* ''sge''
* ''slurm''

This will execute the many dockopt subroutines in sequence, except for the retrodock jobs run on each docking configuration, which are run in parallel via the scheduler. The state of the program will be printed to standard output as it runs.

Once the dockopt job is complete, the following files will be generated in the job directory:
* ''dockopt_job_report.pdf'': contains (1) roc.png of best retrodock job, (2) box plots of enrichment for every multi-valued config parameter, and (3) heatmaps of enrichment for every pair of multi-valued config parameters
* ''dockopt_job_results.csv'': enrichment metrics for each docking configuration

In addition, the best retrodock job will be copied to its own sub-directory ''best_retrodock_job/''.

Within best_retrodock_job, there are the following files and sub-directories:
* ''dockfiles/'': parameters files and INDOCK for given docking configuration
* ''output/'': contains:
** joblist
** sub-directories ''1/'' for actives and ''2/'' for decoys (the former containing OUTDOCK and test.mol2 files, the latter containing just OUTDOCK)
** log files for the retrodock jobs
* ''roc.png'': the ROC enrichment curve (log-scaled x-axis) for given docking configuration

'''Note:''' by default, a mol2 file is exported only for actives (''output/1/''), not for decoys (''output/2/''), in order to prevent disk space issues.