gnina package

Submodules

gnina.gnina_run module

Module containing the GninaRun class and the command line interface.

class gnina.gnina_run.GninaRun(input_ligand_path, input_receptor_path, output_sdf_path, input_box_path=None, input_autobox_path=None, output_summary_path=None, output_log_path=None, properties=None, **kwargs)[source]

Bases: BiobbObject

biobb_vs GninaRun
Wrapper of the gnina software.
This class performs docking of a ligand to a receptor, optionally rescoring the poses with a convolutional neural network, via the gnina software.
Parameters:

  • input_ligand_path (str) – Path to the input ligand. It may hold several ligands and it must hold genuine 3D coordinates, as gnina samples torsions but never bond lengths, bond angles or ring conformations. File type: input. Sample file. Accepted formats: sdf (edam:format_3814), mol2 (edam:format_3816), pdb (edam:format_1476), pdbqt (edam:format_1476).

  • input_receptor_path (str) –

    Path to the input receptor. Every atom of this file is treated as rigid receptor, so any crystal ligand must be removed beforehand. Provide a PDBQT file for full control over protonation, as PDBQT input is passed to gnina unmodified. Charges are not taken into account, just hydrogen donor/acceptor character which depends on the protonation state. File type: input. Sample file. Accepted formats: pdb (edam:format_1476), pdbqt (edam:format_1476).

  • input_box_path (str) (Optional) –

    Path to the PDB file with the box center and size annotated as a REMARK, as written by the box and box_residues building blocks. Mutually exclusive with input_autobox_path. File type: input. Sample file. Accepted formats: pdb (edam:format_1476).

  • input_autobox_path (str) (Optional) –

    Path to a reference structure whose bounding coordinates define the docking box, for example a crystal ligand, an fpocket pocket or the whole receptor. It only needs atoms with Cartesian coordinates, it does not need to be a real molecule. Mutually exclusive with input_box_path. File type: input. Sample file. Accepted formats: sdf (edam:format_3814), mol2 (edam:format_3816), pdb (edam:format_1476), pdbqt (edam:format_1476), pqr (edam:format_1476).

  • output_sdf_path (str) –

    Path to the output file with the docked poses and their scores as SD data fields. Use a .sdf.gz extension to obtain gzip compressed output. File type: output. Sample file. Accepted formats: sdf (edam:format_3814), gz (edam:format_3989).

  • output_summary_path (str) (Optional) –

    Path to the JSON summary file, holding one entry per output pose with the ligand it belongs to and every score gnina assigned to it. File type: output. Sample file. Accepted formats: json (edam:format_3464).

  • output_log_path (str) (Optional) –

    Path to the log file written by gnina. File type: output. Sample file. Accepted formats: log (edam:format_2330).

  • properties (dic - Python dictionary object containing the tool parameters, not input/output files) –

    • cpu (int) - (1) [1~1000|1] Number of CPU cores to use. Keep it lower than or equal to exhaustiveness, and always set it explicitly on a shared machine.

    • exhaustiveness (int) - (8) [1~10000|1] Number of independent Monte Carlo search chains. This is the main sampling knob, but it gives diminishing returns past the default for a targeted pocket.

    • num_modes (int) - (9) [1~1000|1] Maximum number of binding modes written out.

    • min_rmsd_filter (float) - (1.0) [0~100|0.1] RMSD in Angstroms below which a pose is dropped as redundant with a better ranked one.

    • num_mc_saved (int) - (None) [1~10000|1] Number of top poses retained in each Monte Carlo chain, gnina defaults to 50 when unset.

    • seed (int) - (None) Explicit random seed. Docking is stochastic, so set it for reproducible runs.

    • scoring (str) - (None) Built-in empirical scoring function, gnina uses its own default when unset. Values: default (the gnina default empirical scoring function), vina (the AutoDock Vina scoring function), vinardo (a reparameterization of the Vina terms that often does better for virtual screening), ad4_scoring (the AutoDock4 scoring function), dkoes_fast (a fast variant of the dkoes scoring function), dkoes_scoring (the dkoes scoring function), dkoes_scoring_old (the legacy dkoes scoring function).

    • cnn_scoring (str) - (None) Where the convolutional neural network is used in the pipeline, gnina defaults to rescore when unset. Values: none (empirical scoring only throughout, by far the fastest), rescore (the network only re-ranks the final pool of poses), refinement (the network also locally minimizes poses after the Monte Carlo search, around ten times slower), metrorescore (network rescoring combined with Metropolis sampling), metrorefine (network refinement combined with Metropolis sampling), all (the network scores the whole search, very slow).

    • cnn (str) - (None) Name of a built-in convolutional neural network model, or a name ending in _ensemble to evaluate every built-in model sharing that prefix. gnina defaults to an ensemble of three models when unset.

    • pose_sort_order (str) - (None) How the internal pose pool is sorted before the redundancy filter and the num_modes cutoff are applied, so it can surface a different set of poses and not merely reorder them. gnina defaults to CNNscore when unset. Values: CNNscore (sort by network pose score, which answers whether a pose is right), CNNaffinity (sort by predicted affinity, which is what ranks compounds in a screen), Energy (sort by empirical energy).

    • autobox_add (float) - (None) [0~100|0.1] Buffer in Angstroms added on every side of the box derived from input_autobox_path, gnina defaults to 4 when unset. A larger box does not slow gnina down, but it does loosen the constraint on sampling.

    • autobox_extend (bool) - (None) Enlarge the box derived from input_autobox_path when needed so the input ligand can rotate freely inside it, gnina enables this when unset.

    • minimize (bool) - (False) Energy minimize the poses given in input_ligand_path instead of searching for new ones.

    • score_only (bool) - (False) Score the poses given in input_ligand_path without searching or minimizing.

    • local_only (bool) - (False) Restrict the search to a local one inside the box.

    • no_gpu (bool) - (False) Disable GPU acceleration even when a GPU is available.

    • device (int) - (None) [0~16|1] Index of the GPU device to use.

    • quiet (bool) - (False) Suppress the gnina output messages.

    • binary_path (str) - (‘gnina’) Path to the gnina executable in your local computer. gnina is not distributed with this package, install it from its binary release or run it through a container.

    • remove_tmp (bool) - (True) [WF property] Remove temporal files.

    • restart (bool) - (False) [WF property] Do not execute if output files exist.

    • sandbox_path (str) - (“./”) [WF property] Parent path to the sandbox directory.

    • container_path (str) - (None) Container path definition.

    • container_image (str) - (‘gnina/gnina:latest’) Container image definition.

    • container_volume_path (str) - (‘/data’) Container volume path definition.

    • container_working_dir (str) - (None) Container working directory definition.

    • container_user_id (str) - (None) Container user_id definition.

    • container_shell_path (str) - (‘/bin/bash -c’) Path to default shell inside the container.

Examples

This is a use example of how to use the building block from Python:

from biobb_vs.gnina.gnina_run import gnina_run
prop = {
    'cnn_scoring': 'rescore',
    'scoring': 'vinardo',
    'exhaustiveness': 8,
    'cpu': 4,
    'seed': 42
}
gnina_run(input_ligand_path='/path/to/myLigand.sdf',
          input_receptor_path='/path/to/myReceptor.pdbqt',
          input_box_path='/path/to/myBox.pdb',
          output_sdf_path='/path/to/newPoses.sdf',
          output_summary_path='/path/to/newSummary.json',
          output_log_path='/path/to/newLog.log',
          properties=prop)

Instead of a box file, the docking box may be drawn around a reference structure, which is gnina’s own idiom and needs no box file at all. An fpocket pocket works as a reference, and so does the receptor itself for whole protein docking:

gnina_run(input_ligand_path='/path/to/myLigand.sdf',
          input_receptor_path='/path/to/myReceptor.pdbqt',
          input_autobox_path='/path/to/myPocket.pqr',
          output_sdf_path='/path/to/newPoses.sdf',
          properties={'autobox_add': 4})

To reach a GPU from inside a container, ask the container runtime for it through the container_generic_command property, as in {‘container_path’: ‘docker’, ‘container_generic_command’: ‘run –gpus all’} for Docker or ‘run –nv’ for Singularity.

Info:
SWITCH_FLAGS = (('--minimize', 'minimize'), ('--score_only', 'score_only'), ('--local_only', 'local_only'), ('--no_gpu', 'no_gpu'), ('--quiet', 'quiet'))
VALUE_FLAGS = (('--cpu', 'cpu'), ('--exhaustiveness', 'exhaustiveness'), ('--num_modes', 'num_modes'), ('--min_rmsd_filter', 'min_rmsd_filter'), ('--num_mc_saved', 'num_mc_saved'), ('--seed', 'seed'), ('--scoring', 'scoring'), ('--cnn_scoring', 'cnn_scoring'), ('--cnn', 'cnn'), ('--pose_sort_order', 'pose_sort_order'), ('--device', 'device'))
build_cmd() → list[source]

Builds the gnina command line out of the staged files and the properties

Kept apart from launch() so the command can be inspected without running gnina. Must be called after stage_files.

calculate_box(box_file_path)[source]

Reads the docking box out of the REMARK line written by the box building blocks

Returns the box center and its edge lengths, as strings. SIZE is the full edge length of the box, which is what gnina expects in –size_x/y/z, so it is passed through unchanged.

Does not log, as it is called both to validate the box file up front and to build the command line.

check_data_params(out_log, err_log)[source]

Checks all the input/output paths and parameters

cmd_path(path)[source]

Renders a staged path the way gnina will see it

Inside a container every staged file sits in the mounted volume, so a bare name is enough once the command has moved there. Locally the staged paths are already usable as they stand, which also keeps them correct when the sandbox is disabled or already the working directory.

launch() → int[source]

Execute the GninaRun gnina.gnina_run.GninaRun object.

gnina.gnina_run.gnina_run(input_ligand_path: str, input_receptor_path: str, output_sdf_path: str, input_box_path: str | None = None, input_autobox_path: str | None = None, output_summary_path: str | None = None, output_log_path: str | None = None, properties: dict | None = None, **kwargs) → int[source]
biobb_vs GninaRun
Wrapper of the gnina software.
This class performs docking of a ligand to a receptor, optionally rescoring the poses with a convolutional neural network, via the gnina software.
Parameters:

  • input_ligand_path (str) –

    Path to the input ligand. It may hold several ligands and it must hold genuine 3D coordinates, as gnina samples torsions but never bond lengths, bond angles or ring conformations. File type: input. Sample file. Accepted formats: sdf (edam:format_3814), mol2 (edam:format_3816), pdb (edam:format_1476), pdbqt (edam:format_1476).

  • input_receptor_path (str) –

    Path to the input receptor. Every atom of this file is treated as rigid receptor, so any crystal ligand must be removed beforehand. Provide a PDBQT file for full control over protonation, as PDBQT input is passed to gnina unmodified. Charges are not taken into account, just hydrogen donor/acceptor character which depends on the protonation state. File type: input. Sample file. Accepted formats: pdb (edam:format_1476), pdbqt (edam:format_1476).

  • input_box_path (str) (Optional) –

    Path to the PDB file with the box center and size annotated as a REMARK, as written by the box and box_residues building blocks. Mutually exclusive with input_autobox_path. File type: input. Sample file. Accepted formats: pdb (edam:format_1476).

  • input_autobox_path (str) (Optional) –

    Path to a reference structure whose bounding coordinates define the docking box, for example a crystal ligand, an fpocket pocket or the whole receptor. It only needs atoms with Cartesian coordinates, it does not need to be a real molecule. Mutually exclusive with input_box_path. File type: input. Sample file. Accepted formats: sdf (edam:format_3814), mol2 (edam:format_3816), pdb (edam:format_1476), pdbqt (edam:format_1476), pqr (edam:format_1476).

  • output_sdf_path (str) –

    Path to the output file with the docked poses and their scores as SD data fields. Use a .sdf.gz extension to obtain gzip compressed output. File type: output. Sample file. Accepted formats: sdf (edam:format_3814), gz (edam:format_3989).

  • output_summary_path (str) (Optional) –

    Path to the JSON summary file, holding one entry per output pose with the ligand it belongs to and every score gnina assigned to it. File type: output. Sample file. Accepted formats: json (edam:format_3464).

  • output_log_path (str) (Optional) –

    Path to the log file written by gnina. File type: output. Sample file. Accepted formats: log (edam:format_2330).

  • properties (dic - Python dictionary object containing the tool parameters, not input/output files) –

    • cpu (int) - (1) [1~1000|1] Number of CPU cores to use. Keep it lower than or equal to exhaustiveness, and always set it explicitly on a shared machine.

    • exhaustiveness (int) - (8) [1~10000|1] Number of independent Monte Carlo search chains. This is the main sampling knob, but it gives diminishing returns past the default for a targeted pocket.

    • num_modes (int) - (9) [1~1000|1] Maximum number of binding modes written out.

    • min_rmsd_filter (float) - (1.0) [0~100|0.1] RMSD in Angstroms below which a pose is dropped as redundant with a better ranked one.

    • num_mc_saved (int) - (None) [1~10000|1] Number of top poses retained in each Monte Carlo chain, gnina defaults to 50 when unset.

    • seed (int) - (None) Explicit random seed. Docking is stochastic, so set it for reproducible runs.

    • scoring (str) - (None) Built-in empirical scoring function, gnina uses its own default when unset. Values: default (the gnina default empirical scoring function), vina (the AutoDock Vina scoring function), vinardo (a reparameterization of the Vina terms that often does better for virtual screening), ad4_scoring (the AutoDock4 scoring function), dkoes_fast (a fast variant of the dkoes scoring function), dkoes_scoring (the dkoes scoring function), dkoes_scoring_old (the legacy dkoes scoring function).

    • cnn_scoring (str) - (None) Where the convolutional neural network is used in the pipeline, gnina defaults to rescore when unset. Values: none (empirical scoring only throughout, by far the fastest), rescore (the network only re-ranks the final pool of poses), refinement (the network also locally minimizes poses after the Monte Carlo search, around ten times slower), metrorescore (network rescoring combined with Metropolis sampling), metrorefine (network refinement combined with Metropolis sampling), all (the network scores the whole search, very slow).

    • cnn (str) - (None) Name of a built-in convolutional neural network model, or a name ending in _ensemble to evaluate every built-in model sharing that prefix. gnina defaults to an ensemble of three models when unset.

    • pose_sort_order (str) - (None) How the internal pose pool is sorted before the redundancy filter and the num_modes cutoff are applied, so it can surface a different set of poses and not merely reorder them. gnina defaults to CNNscore when unset. Values: CNNscore (sort by network pose score, which answers whether a pose is right), CNNaffinity (sort by predicted affinity, which is what ranks compounds in a screen), Energy (sort by empirical energy).

    • autobox_add (float) - (None) [0~100|0.1] Buffer in Angstroms added on every side of the box derived from input_autobox_path, gnina defaults to 4 when unset. A larger box does not slow gnina down, but it does loosen the constraint on sampling.

    • autobox_extend (bool) - (None) Enlarge the box derived from input_autobox_path when needed so the input ligand can rotate freely inside it, gnina enables this when unset.

    • minimize (bool) - (False) Energy minimize the poses given in input_ligand_path instead of searching for new ones.

    • score_only (bool) - (False) Score the poses given in input_ligand_path without searching or minimizing.

    • local_only (bool) - (False) Restrict the search to a local one inside the box.

    • no_gpu (bool) - (False) Disable GPU acceleration even when a GPU is available.

    • device (int) - (None) [0~16|1] Index of the GPU device to use.

    • quiet (bool) - (False) Suppress the gnina output messages.

    • binary_path (str) - (‘gnina’) Path to the gnina executable in your local computer. gnina is not distributed with this package, install it from its binary release or run it through a container.

    • remove_tmp (bool) - (True) [WF property] Remove temporal files.

    • restart (bool) - (False) [WF property] Do not execute if output files exist.

    • sandbox_path (str) - (“./”) [WF property] Parent path to the sandbox directory.

    • container_path (str) - (None) Container path definition.

    • container_image (str) - (‘gnina/gnina:latest’) Container image definition.

    • container_volume_path (str) - (‘/data’) Container volume path definition.

    • container_working_dir (str) - (None) Container working directory definition.

    • container_user_id (str) - (None) Container user_id definition.

    • container_shell_path (str) - (‘/bin/bash -c’) Path to default shell inside the container.

Examples

This is a use example of how to use the building block from Python:

from biobb_vs.gnina.gnina_run import gnina_run
prop = {
    'cnn_scoring': 'rescore',
    'scoring': 'vinardo',
    'exhaustiveness': 8,
    'cpu': 4,
    'seed': 42
}
gnina_run(input_ligand_path='/path/to/myLigand.sdf',
          input_receptor_path='/path/to/myReceptor.pdbqt',
          input_box_path='/path/to/myBox.pdb',
          output_sdf_path='/path/to/newPoses.sdf',
          output_summary_path='/path/to/newSummary.json',
          output_log_path='/path/to/newLog.log',
          properties=prop)

Instead of a box file, the docking box may be drawn around a reference structure, which is gnina’s own idiom and needs no box file at all. An fpocket pocket works as a reference, and so does the receptor itself for whole protein docking:

gnina_run(input_ligand_path='/path/to/myLigand.sdf',
          input_receptor_path='/path/to/myReceptor.pdbqt',
          input_autobox_path='/path/to/myPocket.pqr',
          output_sdf_path='/path/to/newPoses.sdf',
          properties={'autobox_add': 4})

To reach a GPU from inside a container, ask the container runtime for it through the container_generic_command property, as in {‘container_path’: ‘docker’, ‘container_generic_command’: ‘run –gpus all’} for Docker or ‘run –nv’ for Singularity.

Info:

gnina.gnina_select_pose module

Module containing the GninaSelectPose class and the command line interface.

class gnina.gnina_select_pose.GninaSelectPose(input_sdf_path, output_sdf_path, properties=None, **kwargs)[source]

Bases: BiobbObject

biobb_vs GninaSelectPose
Selects a single pose in the output of the gnina_run building block.
Extracts one pose out of the multi record SDF file written by the gnina_run building block, copying the record verbatim.
Parameters:

  • input_sdf_path (str) –

    Path to the SDF file with the docked poses written by the gnina_run building block. File type: input. Sample file. Accepted formats: sdf (edam:format_3814), gz (edam:format_3989).

  • output_sdf_path (str) –

    Path to the output SDF file with the selected pose. File type: output. Sample file. Accepted formats: sdf (edam:format_3814), gz (edam:format_3989).

  • properties (dic - Python dictionary object containing the tool parameters, not input/output files) –

    • pose (int) - (1) [1~10000|1] Rank of the pose to extract, counted over the poses left after ligand has been applied and sort_by has been honoured.

    • ligand (int) - (None) [1~1000000|1] Index of the ligand whose poses are considered, following the order of the ligands in the file gnina docked. All poses in the file are considered when unset.

    • sort_by (str) - (None) Score to reorder the poses by before one is picked. The poses are taken in the order gnina wrote them when unset, which is already gnina’s own ranking. Note that this reorders only the poses present in the file, so it is not equivalent to the pose_sort_order property of gnina_run, which reorders the whole internal pool before the redundancy filter and the num_modes cutoff discard poses. Values: CNNscore (network pose score, highest first), CNNaffinity (network predicted affinity, highest first), minimizedAffinity (empirical affinity in kcal/mol, lowest first).

    • remove_tmp (bool) - (True) [WF property] Remove temporal files.

    • restart (bool) - (False) [WF property] Do not execute if output files exist.

    • sandbox_path (str) - (“./”) [WF property] Parent path to the sandbox directory.

Examples

This is a use example of how to use the building block from Python:

from biobb_vs.gnina.gnina_select_pose import gnina_select_pose
prop = {
    'pose': 1,
    'sort_by': 'CNNaffinity'
}
gnina_select_pose(input_sdf_path='/path/to/myPoses.sdf',
                  output_sdf_path='/path/to/myBestPose.sdf',
                  properties=prop)
Info:
SORT_ORDERS = {'CNNaffinity': True, 'CNNscore': True, 'minimizedAffinity': False}
check_data_params(out_log, err_log)[source]

Checks all the input/output paths and parameters

launch() → int[source]

Execute the GninaSelectPose gnina.gnina_select_pose.GninaSelectPose object.

select_record(records)[source]

Narrows the records down to the requested ligand, reorders them and picks one

gnina.gnina_select_pose.gnina_select_pose(input_sdf_path: str, output_sdf_path: str, properties: dict | None = None, **kwargs) → int[source]
biobb_vs GninaSelectPose
Selects a single pose in the output of the gnina_run building block.
Extracts one pose out of the multi record SDF file written by the gnina_run building block, copying the record verbatim.
Parameters:

  • input_sdf_path (str) –

    Path to the SDF file with the docked poses written by the gnina_run building block. File type: input. Sample file. Accepted formats: sdf (edam:format_3814), gz (edam:format_3989).

  • output_sdf_path (str) –

    Path to the output SDF file with the selected pose. File type: output. Sample file. Accepted formats: sdf (edam:format_3814), gz (edam:format_3989).

  • properties (dic - Python dictionary object containing the tool parameters, not input/output files) –

    • pose (int) - (1) [1~10000|1] Rank of the pose to extract, counted over the poses left after ligand has been applied and sort_by has been honoured.

    • ligand (int) - (None) [1~1000000|1] Index of the ligand whose poses are considered, following the order of the ligands in the file gnina docked. All poses in the file are considered when unset.

    • sort_by (str) - (None) Score to reorder the poses by before one is picked. The poses are taken in the order gnina wrote them when unset, which is already gnina’s own ranking. Note that this reorders only the poses present in the file, so it is not equivalent to the pose_sort_order property of gnina_run, which reorders the whole internal pool before the redundancy filter and the num_modes cutoff discard poses. Values: CNNscore (network pose score, highest first), CNNaffinity (network predicted affinity, highest first), minimizedAffinity (empirical affinity in kcal/mol, lowest first).

    • remove_tmp (bool) - (True) [WF property] Remove temporal files.

    • restart (bool) - (False) [WF property] Do not execute if output files exist.

    • sandbox_path (str) - (“./”) [WF property] Parent path to the sandbox directory.

Examples

This is a use example of how to use the building block from Python:

from biobb_vs.gnina.gnina_select_pose import gnina_select_pose
prop = {
    'pose': 1,
    'sort_by': 'CNNaffinity'
}
gnina_select_pose(input_sdf_path='/path/to/myPoses.sdf',
                  output_sdf_path='/path/to/myBestPose.sdf',
                  properties=prop)
Info: