pycaverdock.caverdock module

class pycaverdock.caverdock.CaverDock(binary: str | None = None)

Bases: object

Wraps CaverDock and exposes a method to calculate lower/upper bounds.

run(directory: str, name: str, ligand: str, receptor: str, tunnel: DiscretizedTunnel, direction: Direction = Direction.OUT, trajectory_type: TrajectoryType = TrajectoryType.LOWERBOUND, mpi_processes: int | None = None, seed: int | None = None, catomnum: int | None = None, exhaustiveness: int | None = None, stdout=-3, stderr=-3, args: List[str] | None = None) → CaverDockTrajectory

Runs CaverDock with the given ligand, receptor and tunnel.

Parameters:

  • directory – The results and CaverDock configuration will be stored into this directory.

  • name – Name of the computation (will be used for naming the result files).

  • ligand – Path to the input ligand.

  • receptor – Path to the input receptor.

  • tunnel – Discretized tunnel to be used for the computation.

  • direction – Direction of the simulation IN or OUT.

  • trajectory_type – Type of calculated simulation LOWERBOUND - only lowerbound, UPPERBOUND - both lowerbound and upperbound calculation.

  • mpi_processes – Set the number of used MPI processes. If set to None, MPI will not be used.

  • seed – Seed for random number generator.

  • catomnum – Atom number from ligand pdbqt file which will be used as drag atom.

  • exhaustiveness – Exhaustiveness setting for the docking algorithm.

  • stdout – Defines what happens with the STDOUT strings, see subprocess documentation.

  • stderr – Defines what happens with the STDERR strings, see subprocess documentation.

  • args – Additional arguments for CaverDock.

run_with_config(directory: str, name: str, config_path: str, trajectory_type: TrajectoryType | None = None, mpi_processes: int | None = None, stdout=-3, stderr=-3, args: List[str] | None = None) → Tuple[str, str]

Runs CaverDock with the custom configuration file.

Parameters:

  • directory – The results and CaverDock configuration will be stored into this directory.

  • name – Name of the computation (will be used for naming the result files).

  • config_path – Path to the custom configuration file.

  • trajectory_type – Type of calculated simulation LOWERBOUND - only lowerbound, UPPERBOUND - both lowerbound and upperbound calculation.

  • mpi_processes – Set the number of used MPI processes. If set to None, MPI will not be used.

  • stdout – Defines what happens with the STDOUT strings, see subprocess documentation.

  • stderr – Defines what happens with the STDERR strings, see subprocess documentation.

  • args – Additional arguments for CaverDock.

exception pycaverdock.caverdock.CaverDockNotFoundError

Bases: Exception

class pycaverdock.caverdock.CaverDockTrajectory(tunnel: DiscretizedTunnel, direction: Direction, lb: str, ub: str | None = None)

Bases: object

Creates energy profile from CaverDock calculation.

direction: Direction
property energy_profile: EnergyProfile
property energy_profile_lowerbound: EnergyProfile
property energy_profile_upperbound: EnergyProfile
lb: str
tunnel: DiscretizedTunnel
ub: str | None = None
pycaverdock.caverdock.calculate_dist_max(atoms: List[Vec3D]) → float
pycaverdock.caverdock.calculate_tunnel_gridbox(ligand_path: str, tunnel: DiscretizedTunnel) → Tuple[Tuple[int, int, int], Tuple[int, int, int]]
pycaverdock.caverdock.generate_caverdock_config(ligand_path: str, receptor_path: str, tunnel_path: str, seed: int | None = None, catomnum: int | None = None, exhaustiveness: int | None = None, additional_params: List[Tuple[str, str]] | None = None) → str

Creates custom configuration file.

Parameters:

  • directory – The results and CaverDock configuration will be stored into this directory.

  • name – Name of the computation (will be used for naming the result files).

  • ligand_path – Path to the input ligand.

  • receptor_path – Path to the input receptor.

  • tunnel_path – Path to the discretized tunnel file.

  • seed – Seed for random number generator.

  • catomnum – Atom number from ligand pdbqt file which will be used as drag atom.

  • exhaustiveness – Exhaustiveness setting for the docking algorithm.

  • args – Additional parameters to write into the configuration file.

pycaverdock.caverdock.get_ligand_atoms(ligand_path: str) → List[Vec3D]
pycaverdock.caverdock.get_result_path(name: str, trajectory_type: TrajectoryType) → str

pycaverdock.energy_profile module

class pycaverdock.energy_profile.BoundaryType(*values)

Bases: Enum

DISC_NUMBER = 1
FRACTION = 2
class pycaverdock.energy_profile.DiscRanges(bound_start: int | float, bound_end: int | float, max_start: int | float, max_end: int | float, surface_start: int | float, surface_end: int | float, type: BoundaryType = BoundaryType.DISC_NUMBER)

Bases: object

Definition of Disc ranges for energy profile analysis. Selected parts of profile are used for calculation of important energy values.

Parameters:

  • bound_start – Disc range start for the selection of bound energy in active site.

  • bound_end – Disc range end for the selection of bound energy in active site.

  • max_start – Disc range start for the selection of energy maximum in the profile.

  • max_end – Disc range end for the selection of energy maximum in the profile.

  • surface_start – Disc range start for the selection of surface energy at the protein surface.

  • surface_end – Disc range end for the selection of surface energy at the protein surface.

  • type – Type of range value, DISC_NUMBER for exact disc number, FRACTION for selecting fraction of the profile.

bound_end: int | float
bound_start: int | float
convert(direction: Direction, number_of_discs: int)
max_end: int | float
max_start: int | float
surface_end: int | float
surface_start: int | float
type: BoundaryType = 1
class pycaverdock.energy_profile.EnergyProfile(frame: DataFrame, direction: Direction)

Bases: object

Stores calculated energy profile results in a pandas DataFrame.

analyse(trajectory_type: TrajectoryType = TrajectoryType.LOWERBOUND, disc_ranges: DiscRanges | None = None) → EnergyProfileAnalysis

Calculates E_bound, E_max, E_surface, k_barier, dE_bs and returns the results as a pandas Dataframe.

Parameters:

  • trajectory_type – Type of calculated simulation for energy analysis LOWERBOUND - lowerbound, UPPERBOUND - upperbound profile.

  • disc_ranges – must be six int or float in precise correct order to set parameters for analysis, see DiscRanges documentation.

direction: Direction
frame: DataFrame
static load_from_file(path: str, direction: Direction) → EnergyProfile

Loads an energy profile from disk.

reverse()
write(stream)
write_to_dat(path: str)

Writes the results to a .dat file.

class pycaverdock.energy_profile.EnergyProfileAnalysis(direction: pycaverdock.direction.Direction, trajectory_type: pycaverdock.trajectory_type.TrajectoryType, E_bound: float, E_max: float, E_surface: float, k_on: float, k_off: float, dE_bs: float)

Bases: object

E_bound: float
E_max: float
E_surface: float
dE_bs: float
direction: Direction
k_off: float
k_on: float
trajectory_type: TrajectoryType
pycaverdock.energy_profile.create_energy_profile(tunnel: DiscretizedTunnel, caverdock_trajectory: str, direction: Direction, start_disc: int = 0) → EnergyProfile

Creates an energy profile from a discretized tunnel and a path to caverdock trajectory results.

Parameters:

  • tunnel – Object with discretized tunnel.

  • caverdock_trajectory – Path CaverDock result trajectory pdbqt file.

  • direction – Direction of the previously calcualted simulation.

  • start_disc – Disc number where the energy profile generation will start.

pycaverdock.experiment module

class pycaverdock.experiment.Experiment(workdir: Workdir, name: str, mgltools: MGLToolsWrapper, caverdock: CaverDock)

Bases: object

Utility class for running experiments.

It takes care of storing input/output data of experiments and caching them so that they are not recomputed needlessly. The caching is based on hashes of experiment input files.

Parameters:

  • workdir – Working directory

  • name – Name of the experiment

  • mgltools – MGLTools package wrapper

  • caverdock – CaverDock executable wrapper

discretize_tunnel(tunnel_path: str, delta: float, threads: int | None = None) → DiscretizedTunnel

Discretize a tunnel. The result is cached if the workdir and the input tunnel file stays the same.

intermediate_path(file: str)

Get the path of an intermediate result with the given filename.

prepare_ligand(ligand_path: str, args: List[str] = None) → Ligand

Prepare a ligand using MGLTools. The result is cached if the workdir and the input ligand file stays the same.

Parameters:

  • ligand_path – Path to a ligand file

  • args – Additional arguments passed to MGLToolsWrapper::prepare_ligand

prepare_receptor(receptor_path: str, args: List[str] = None) → Receptor

Prepare a receptor using MGLTools. The result is cached if the workdir and the input receptor file stays the same.

Parameters:

  • receptor_path – Path to a receptor file

  • args – Additional arguments passed to MGLToolsWrapper::prepare_receptor

result_path(file: str)

Get the path of a result with the given filename.

run_caverdock(ligand: Ligand, receptor: Receptor, tunnel: DiscretizedTunnel, direction: Direction = Direction.OUT, trajectory_type: TrajectoryType = TrajectoryType.LOWERBOUND, mpi_processes: int | None = None, seed: int | None = None, catomnum: int | None = None, exhaustiveness: int | None = None, args: List[str] = None) → CaverDockTrajectory

Runs CaverDock trajectory computation. The result is cached if the workdir and the inputs (ligand, receptor, tunnel) stay the same.

Returns a dictionary with “lb” (and “ub”, if upperbound is True) keys that map to filenames containing the computed results.

Parameters:

  • directory – The results and CaverDock configuration will be stored into this directory.

  • ligand – Path to the input ligand.

  • receptor – Path to the input receptor.

  • tunnel – Discretized tunnel to be used for the computation.

  • direction – Direction of the simulation IN or OUT.

  • trajectory_type – Type of calculated simulation LOWERBOUND - only lowerbound, UPPERBOUND - both lowerbound and upperbound calculation.

  • mpi_processes – Set the number of used MPI processes. If set to None, MPI will not be used.

  • seed – Seed for random number generator.

  • catomnum – Atom number from ligand pdbqt file which will be used as drag atom.

  • exhaustiveness – Exhaustiveness setting for the docking algorithm.

  • args – Additional arguments for CaverDock.

store_input_file(file: str, overwrite=True)

Copies the passed input file to the experiment directory.

class pycaverdock.experiment.InputFile(path: str)

Bases: object

path: str
class pycaverdock.experiment.Stream(*values)

Bases: Enum

STDERR = 2
STDOUT = 1
class pycaverdock.experiment.Workdir(directory: str, memory_cache_size=1000)

Bases: object

create_key(args: dict) → str
entry_path(key: str) → str
has_entry(key: str) → bool
log_file(step: str, path: str, stream: Stream | None, include_path_hash: bool = True, extract_basename: bool = True)
resolve_entry(load_fn, compute_fn, args)
pycaverdock.experiment.check_args(args: List[str] | None)
pycaverdock.experiment.compress_files(file_map, output_path: str)
pycaverdock.experiment.convert_eprofile_analysis(experiment_name: str, eprofile_analysis: EnergyProfileAnalysis, receptor_path: str, tunnel_path: str, ligand_path: str) → DataFrame

Saves information from calculation into pandas Dataframe.

Parameters:

  • experiment_name – Name of the simulation.

  • eprofile_analysis – Object with calculated energy values from eprofile analysis.

  • receptor_path – Path to the input receptro file.

  • tunnel_path – Path to the input tunnel file.

  • ligand_path – Path to the input ligand file.

pycaverdock.experiment.create_args_cache_value(args: List[str] | None) → str
pycaverdock.experiment.decompress_files(input_path: str, unpack_dir: str) → dict
pycaverdock.experiment.hash_discretized_tunnel(tunnel: DiscretizedTunnel) → str
pycaverdock.experiment.hash_file(path: str) → str

pycaverdock.mgltoolswrapper module

class pycaverdock.mgltoolswrapper.Ligand(path: str)

Bases: object

Represents a ligand stored on disk.

path: str
exception pycaverdock.mgltoolswrapper.MGLToolsNotFoundError

Bases: Exception

class pycaverdock.mgltoolswrapper.MGLToolsWrapper(mgltools_root: str | None = None)

Bases: object

This class wraps the MGLTools package and exposes useful methods for working with it.

exec(args, stdout, stderr)
mgltools_path(path: str) → str
prepare_ligand(ligand: str, output_path: str, stdout=-3, stderr=-3, args: List[str] = None) → Ligand

Prepares an input ligand using MGLTools and stores it in output_path.

Parameters:

  • ligand – Path to the input ligand file.

  • output_path – Output path for the created ligand pdbqt file.

  • stdout – Standard output stream destination. Valid values are subprocess.PIPE, subprocess.DEVNULL, an existing file descriptor (a positive integer), an existing file object with a valid file descriptor, and None.

  • stderr – Standard error stream destination. Valid values are subprocess.PIPE, subprocess.DEVNULL, an existing file descriptor (a positive integer), an existing file object with a valid file descriptor, and None.

  • args – Additional arguments for prepare_ligand.

prepare_receptor(receptor: str, output_path: str, stdout=-3, stderr=-3, args: List[str] = None) → Receptor

Prepares an input receptor using MGLTools and stores it in output_path.

Parameters:

  • receptor – Path to the input receptor file.

  • output_path – Output path for the created receptor pdbqt file.

  • stdout – Standard output stream destination. Valid values are subprocess.PIPE, subprocess.DEVNULL, an existing file descriptor (a positive integer), an existing file object with a valid file descriptor, and None.

  • stderr – Standard error stream destination. Valid values are subprocess.PIPE, subprocess.DEVNULL, an existing file descriptor (a positive integer), an existing file object with a valid file descriptor, and None.

  • args – Additional arguments for prepare_receptor.

class pycaverdock.mgltoolswrapper.Receptor(path: str)

Bases: object

Represents a receptor stored on disk.

path: str

pycaverdock.tunnel module

class pycaverdock.tunnel.DiscretizedTunnel(disks: List[Disk])

Bases: object

Memory representation of the discretized tunnel.

Parameters:

disks – List of discs.

disks: List[Disk]
extend(distance: float = 2, step=0.2) → DiscretizedTunnel

Extends the length of the tunnel in the direction of the vector between the last two tunnel dummy atoms.

Parameters:

  • distance – Length of the extension.

  • step – Width of the extended discs.

static load_from_file(path: str) → DiscretizedTunnel

Loads a discretized tunnel from a file on the disk. Each disk of the tunnel should be stored on a single line, with its values separated by space.

reverse() → DiscretizedTunnel

Reverse the direction of the tunnel, i.e. the last disk will become the first disk, etc.

write(stream)
write_to_file(path: str)

Writes the discretized tunnel to a file on the disk.

class pycaverdock.tunnel.Disk(center: Vec3D, normal: Vec3D, radius: float)

Bases: object

One disc in the tunnel.

center: Vec3D
copy() → Disk
normal: Vec3D
radius: float
class pycaverdock.tunnel.Vec3D(x: float, y: float, z: float)

Bases: object

copy()
to_tuple() → Tuple[float, float, float]
x: float
y: float
z: float
pycaverdock.tunnel.discretize_tunnel(tunnel: Tunnel, delta: float = 0.3, threads: int | None = None, log: str | None = None) → DiscretizedTunnel

Discretizes a tunnel using multiple threads.

Parameters:

  • tunnel – Name of the object with loaded tunnel.

  • delta – Width of the discretized discs.

  • threads – Number of maximum threads for running the discretization.

  • log – Path for optional log file.

pycaverdock.tunnel.load_tunnel(path: str) → Tunnel

Loads a (non-discretized) tunnel from a PDB file.