API guide¶
Use AMDockVSRuntime as the public facade. A runtime owns the active MolSuite
project and its executors, so close it with shutdown() when the work is done.
Quick start¶
Create or open a project, then use the runtime's domain namespaces for your workflow:
from amdockvs import AMDockVSRuntime
runtime = AMDockVSRuntime()
try:
project = runtime.create_or_open_project(
name="screening",
folder="./screening-project",
)
print(project)
finally:
runtime.shutdown()
| Namespace | Responsibility |
|---|---|
runtime.loader |
Ligand and receptor import |
runtime.molecules |
Queries, scopes, filters, and saved sets |
runtime.chemistry |
Ligand and receptor preparation |
runtime.complexes |
Explicit receptor-ligand relationships |
runtime.qsar |
Activities, descriptors, models, and predictions |
runtime.binding_sites |
Manual sites and P2Rank predictions |
runtime.docking |
Preparation, grids, docking with Vina, QuickVina 2, gnina, AutoDock-GPU or Uni-Dock, and results |
runtime.diversity |
Clustering and representative selection |
runtime.tools |
External tools: status, install, repair |
Projects and jobs¶
runtime = AMDockVSRuntime()
runtime.create_or_open_project(name="demo", folder="./demo-project")
jobs = runtime.loader.load_ligands(["ligands.sdf"])
statuses = runtime.watch_jobs(jobs)
for status in statuses.values():
print(status.job_id, status.status)
Long operations submit MolSuite jobs. They return a job identifier, or a list
of identifiers for partitioned imports. watch_job() and watch_jobs() show
a tqdm progress bar in a terminal or notebook; wait_for_job() and
wait_for_jobs() wait without one. A job that reads what another one writes
waits for it, so a pipeline can be submitted at once and waited for at the end.
Where jobs run¶
Every job method takes executor_name:
- Left out, the job goes to the first active executor that can run it: the pool of processes of this machine unless another one was made the default.
"thread"runs it on threads of this process, which suits small jobs.- The name of an active executor sends it there.
print(runtime.run_destinations()) # [(name, label), ...] active now
job_id = runtime.docking.run(ligands=ligands, receptors=receptors, executor_name="lab-ray")
runtime.resume_job(job_id, "local") # stop it there and continue it here
Hosts and executors are kept by MolSuite and edited from the Hosts and
Executors pages of Settings, or through runtime.workspace (save_host, save_executor,
activate): see the ms_flow guide.
resume_job() also continues a job that was interrupted or canceled, without
running again what it had done.
Query molecules without loading everything¶
select() returns a lazy Selection[MoleculeRecord]; its .scope is the
serializable MoleculeScope used by jobs. A selection can be iterated,
counted, streamed, or saved as a stable set.
ligands = runtime.molecules.select(
role="ligand",
excluded=False,
)
print(ligands.count())
for molecule in ligands:
print(molecule.id, molecule.name)
training_set = runtime.molecules.create_set(ligands, name="training ligands")
Pass scopes to downstream APIs when the operation should follow a live query;
pass a MoleculeSetRef when reproducibility requires a saved snapshot.
Chemistry and QSAR¶
Chemistry operations are optional and composable:
job_id = runtime.chemistry.run_ligand_pipeline(
["standardize", "protonate", "generate_3d"],
ligands=ligands,
)
runtime.wait_for_job(job_id)
descriptor_job = runtime.qsar.compute_descriptors(molecule_set=ligands)
runtime.wait_for_job(descriptor_job)
Activities can be assigned directly or loaded from tabular data. Training and prediction consume molecule scopes or saved set references, and training needs at least two ligands with the activity:
runtime.qsar.set_activity(
ligand_id=42,
endpoint="IC50",
value=25.0,
unit="nM",
source="assay-1",
)
model = runtime.qsar.train(
molecule_set=training_set,
endpoint="IC50",
algorithm="random_forest",
)
predictions = runtime.qsar.predict(model=int(model.id), molecule_set=ligands)
Both run as jobs and wait for them. Training computes the features a molecule
lacks first, in a descriptor job. Training the same model on the same data
again returns the stored model. To queue the work without waiting, use
submit_train and submit_predict. submit_train takes several algorithms,
one task per model:
request = runtime.qsar.submit_train(
endpoint="IC50",
algorithm=["ridge", "random_forest"],
feature_source="ecfp4",
)
runtime.wait_for_jobs([j for j in (request["descriptor_job_id"], request["job_id"]) if j])
# request["existing"] lists the algorithms whose model was already stored
Consult the generated reference for the complete signatures because available model options and return values are defined by the current implementation.
Binding sites¶
A binding site is a box on a receptor, drawn by hand or predicted:
receptors = runtime.molecules.select(role="receptor")
receptor = receptors.one()
runtime.binding_sites.save_site(
molecule_id=int(receptor.id),
name="active site",
center=(12.0, 13.0, 10.0),
size=(20.0, 20.0, 20.0),
)
P2Rank predicts them once it is installed through the tools facade:
status = runtime.tools.install("p2rank")
job_id = runtime.binding_sites.predict(receptor_ids=[int(receptor.id)])
runtime.watch_job(job_id)
sites = runtime.binding_sites.select(molecule_id=int(receptor.id), source="p2rank")
runtime.tools.status() lists every managed tool and whether it is ready.
Docking¶
A docking run needs prepared molecules and a grid on each receptor:
runtime.watch_jobs([
runtime.docking.prepare_ligands(ligands=ligands),
runtime.docking.prepare_receptors(receptors=receptors),
])
runtime.docking.set_grid(
receptor_id=int(receptor.id),
center=(12.0, 13.0, 10.0),
size=(20.0, 20.0, 20.0),
)
job_id = runtime.docking.run(ligands=ligands, receptors=receptors, exhaustiveness=8)
runtime.watch_job(job_id)
print(runtime.docking.result_stats())
program chooses the engine: vina (the default), qvina (QuickVina 2),
gnina, adgpu (AutoDock-GPU) or unidock (Uni-Dock). The options of any engine go in
engine_config, which is validated against that engine's model; for engines
other than vina the keyword arguments exhaustiveness, num_modes and
vina_cpu are not read.
job_id = runtime.docking.run(
program="gnina",
ligands=ligands,
receptors=receptors,
engine_config={"exhaustiveness": 8, "num_modes": 9, "scoring_function": "rescore"},
)
| Program | engine_config keys |
|---|---|
vina |
exhaustiveness, num_modes, scoring_function (vina, vinardo, ad4), vina_cpu, ... |
qvina |
exhaustiveness, num_modes, vina_cpu, energy_range, seed |
gnina |
exhaustiveness, num_modes, vina_cpu, scoring_function (rescore, none, refinement, all), seed |
adgpu |
nrun, num_modes, parameter_file, derived_types, seed |
unidock |
scoring_function (vina, vinardo), search_mode (fast, balance, detail), num_modes, energy_range, seed |
runtime.docking.list_programs() describes them. A pair already docked with
the same protocol is skipped unless skip_existing=False.
Complexes¶
A complex names a receptor-ligand pair explicitly, for redocking or rescoring a known pose:
complex_record = runtime.complexes.create(
receptor_molecule_id=int(receptor.id),
ligand_molecule_id=42,
purpose="redocking",
)
print(runtime.complexes.count(purpose="redocking"))
Diversity¶
Clustering runs once as a job; choosing what represents each cluster is a separate step that can be repeated on the stored run:
job_id = runtime.diversity.cluster_job(method="bitbirch", threshold=0.65)
runtime.watch_job(job_id)
run = runtime.diversity.list_runs()[0]
runtime.diversity.pick_representatives(run["cluster_run_id"], mode="medoid")
representatives = runtime.diversity.save_centroids_as_set(run["cluster_run_id"], name="diverse")
runtime.diversity.supported_methods() and representative_modes() list the
choices.
Cleanup¶
Always release executors and project resources:
runtime.shutdown()
For scripts, a try/finally block is the safest pattern.