Skip to content

deeporigin.drug_discovery.Pose / PoseSet

Bases: Entity

A 3D ligand conformation backed by an SDF in the platform pose result table.

A :class:Pose holds the platform pose result id (:attr:id) and the parent ligand id (:attr:ligand_id). These are distinct from :class:~deeporigin.drug_discovery.structures.ligand.Ligand identity.

Attributes:

Name Type Description
ligand_id str

Parent ligand id in the ligands table.
smiles str | None

Canonical or input SMILES when known without loading the SDF.
name str | None

Optional pose or ligand name.
protein_id str | None

Optional protein the pose is associated with.
compute_job_id str | None

Optional compute job that produced this pose.
pose_score float | None

Docking pose score when present.
binding_energy float | None

Docking binding energy when present.
best_pose bool | None

Whether this row is the best pose for its ligand in a run.
origin str | None

Provenance string (for example registered or docking).
props dict[str, Any]

Additional metadata from the platform row.

Attributes

best_pose class-attribute instance-attribute 

best_pose: bool | None = None

binding_energy class-attribute instance-attribute 

binding_energy: float | None = None

compute_job_id class-attribute instance-attribute 

compute_job_id: str | None = None

ligand_id instance-attribute 

ligand_id: str

mol property 

mol: Mol | None

Return the RDKit molecule, loading from disk when needed.

name class-attribute instance-attribute 

name: str | None = None

origin class-attribute instance-attribute 

origin: str | None = None

pose_score class-attribute instance-attribute 

pose_score: float | None = None

props class-attribute instance-attribute 

props: dict[str, Any] = field(default_factory=dict)

protein_id class-attribute instance-attribute 

protein_id: str | None = None

smiles class-attribute instance-attribute 

smiles: str | None = None

Methods:

from_id classmethod 

from_id(
    id: str, *, client: Optional[DeepOriginClient] = None
) -> Self

Load a single pose from a result-explorer record id.

Parameters:

Name Type Description Default
id str

Platform pose result id.

 required
client Optional[DeepOriginClient]

Optional platform client.

 None

Returns:

Type Description
Self

The matching :class:Pose.

Raises:

Type Description
ValueError

If no pose record exists for id.

from_json classmethod 

from_json(
    data: list[dict[str, Any]],
    *,
    client: Optional[DeepOriginClient] = None,
    sanitize: bool = True,
    remove_hydrogens: bool = False
) -> list[Self]

Build :class:Pose objects from pose metadata dicts.

Parameters:

Name Type Description Default
data list[dict[str, Any]]

Pose rows (for example result-explorer data payloads).

 required
client Optional[DeepOriginClient]

Optional client for project_id fallback.

 None
sanitize bool

Passed to :meth:Ligand.from_sdf for local SDF paths.

 True
remove_hydrogens bool

Passed to :meth:Ligand.from_sdf for local paths.

 False

Returns:

Type Description
list[Self]

One pose per dict, in input order.

Raises:

Type Description
ValueError

If a row is invalid or lacks required fields.

from_sdf classmethod 

from_sdf(
    path: str | Path,
    *,
    ligand: Ligand | None = None,
    protein_id: str | None = None,
    origin: str = "registered",
    client: Optional[DeepOriginClient] = None,
    sanitize: bool = True,
    remove_hydrogens: bool = False
) -> Self

Register an external SDF as a platform pose and return a :class:Pose.

Syncs the parent :class:Ligand (unless ligand is supplied), uploads the SDF, and invokes the ImportTool pose-registration path.

Parameters:

Name Type Description Default
path str | Path

Local SDF file path.

 required
ligand Ligand | None

Optional explicit parent ligand (skips auto-sync by SMILES).

 None
protein_id str | None

Optional associated protein id.

 None
origin str

Provenance string stored on the pose row.

 'registered'
client Optional[DeepOriginClient]

Optional platform client.

 None
sanitize bool

Passed to :meth:Ligand.from_sdf.

 True
remove_hydrogens bool

Passed to :meth:Ligand.from_sdf.

 False

Returns:

Name Type Description
Registered Self

class:Pose with platform id populated.

Raises:

Type Description
DeepOriginException

If registration fails or returns no pose row.

sync 

sync(
    *,
    lazy: bool = False,
    client: Optional[DeepOriginClient] = None,
    remote_path: Optional[str] = None
) -> None

Upload the pose SDF when a local file exists.

Pose registration (platform pose id) is handled by :meth:from_sdf. This method only uploads bytes when local_path is set.

Parameters:

Name Type Description Default
lazy bool

Skip upload when :attr:remote_path is already set.

 False
client Optional[DeepOriginClient]

Optional platform client.

 None
remote_path Optional[str]

Optional explicit remote key.

 None

to_file 

to_file(file_path: str | Path | None = None) -> str

Write this pose to an SDF file.

Parameters:

Name Type Description Default
file_path str | Path | None

Destination path. When omitted, writes a temp file.

 None

Returns:

Type Description
str

Path to the written SDF file.

Raises:

Type Description
DeepOriginException

If no local structure is available.

to_hash 

to_hash() -> str

Return a stable hash string for remote path generation.

to_ligand 

to_ligand() -> Ligand

Convert this pose to a legacy pose-hydrated :class:Ligand.

Prefer using :class:Pose directly; this exists for backward compatibility with code paths that still expect :class:Ligand pose rows.

Collection of :class:Pose objects.

Attributes

poses class-attribute instance-attribute 

poses: list[Pose] = field(default_factory=list)

Methods:

from_json classmethod 

from_json(
    data: list[dict[str, Any]],
    *,
    client: Optional[DeepOriginClient] = None,
    sanitize: bool = True,
    remove_hydrogens: bool = False
) -> Self

Build a :class:PoseSet from pose metadata dicts.

from_result classmethod 

from_result(
    *,
    protein_id: str | None = None,
    execution_id: str | None = None,
    ligand_id: str | list[str] | None = None,
    best_pose: bool | None = None,
    scored_only: bool = False,
    client: Optional[DeepOriginClient] = None
) -> Self

Load poses from the data platform result explorer.

Parameters:

Name Type Description Default
protein_id str | None

Optional protein filter.

 None
execution_id str | None

Optional compute job / execution id filter.

 None
ligand_id str | list[str] | None

Optional ligand id filter (single id or list).

 None
best_pose bool | None

When set, restrict to rows whose best_pose matches.

 None
scored_only bool

When True, skip reference/metadata rows that lack docking scores (same filter as legacy docking loaders).

 False
client Optional[DeepOriginClient]

Optional platform client.

 None

Returns:

Name Type Description
Matching Self

class:PoseSet.

Raises:

Type Description
ValueError

If no pose rows match the filters.

to_ligand_set 

to_ligand_set() -> LigandSet

Convert to a legacy :class:LigandSet of pose-hydrated ligands.

Overview

A Pose is a 3D ligand conformation stored in the platform pose result table (result_type=pose). It has its own platform pose id (Pose.id) and a parent ligand id (Pose.ligand_id) in the ligands table.

Use :class:Pose / :class:PoseSet when you need pose-scoped identity. Docking outputs still return :class:~deeporigin.drug_discovery.LigandSet from :meth:~deeporigin.drug_discovery.Docking.get_poses until a later release; prefer :meth:PoseSet.from_result or :meth:~deeporigin.drug_discovery.Ligand.get_poses for new code.

Register an external SDF

from deeporigin.drug_discovery import Pose

pose = Pose.from_sdf("cocrystal.sdf", protein_id=protein.id)
print(pose.id, pose.ligand_id)

List poses for a ligand

ligand.sync()
poses = ligand.get_poses()
for pose in poses:
    print(pose.id, pose.pose_score)

Load poses from a docking run

from deeporigin.drug_discovery import PoseSet

pose_set = PoseSet.from_result(execution_id=docking.id)