`deeporigin.drug_discovery.Pocket`¶

Bases: Entity

Class representing a binding pocket in a protein structure.

This class provides essential methods for pocket analysis, visualization, and coordinate manipulation.

Attributes¶

apolar_sasa `class-attribute` `instance-attribute` ¶

apolar_sasa: Optional[float] = None

box_size_x `class-attribute` `instance-attribute` ¶

box_size_x: Optional[float] = None

box_size_y `class-attribute` `instance-attribute` ¶

box_size_y: Optional[float] = None

box_size_z `class-attribute` `instance-attribute` ¶

box_size_z: Optional[float] = None

center `class-attribute` `instance-attribute` ¶

center: Optional[list[float]] = None

color `class-attribute` `instance-attribute` ¶

color: str = 'red'

coordinates `class-attribute` `instance-attribute` ¶

coordinates: Optional[ndarray] = None

drugability_score `class-attribute` `instance-attribute` ¶

drugability_score: Optional[float] = None

hydrophobicity `class-attribute` `instance-attribute` ¶

hydrophobicity: Optional[float] = None

index `class-attribute` `instance-attribute` ¶

index: Optional[int] = 0

name `class-attribute` `instance-attribute` ¶

name: Optional[str] = None

pdb_id `class-attribute` `instance-attribute` ¶

pdb_id: Optional[str] = None

polar_apolar_sasa_ratio `class-attribute` `instance-attribute` ¶

polar_apolar_sasa_ratio: Optional[float] = None

polar_sasa `class-attribute` `instance-attribute` ¶

polar_sasa: Optional[float] = None

polarity `class-attribute` `instance-attribute` ¶

polarity: Optional[float] = None

props `class-attribute` `instance-attribute` ¶

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

protein_id `class-attribute` `instance-attribute` ¶

protein_id: Optional[str] = None

total_sasa `class-attribute` `instance-attribute` ¶

total_sasa: Optional[float] = None

volume `class-attribute` `instance-attribute` ¶

volume: Optional[float] = None

Functions¶

from_function_result `classmethod` ¶

from_function_result(
    *, result: "FunctionResult", client: "DeepOriginClient"
) -> list[Self]

Build Pocket objects from a pocket-finder FunctionResult.

Extracts the pocket list and stores the remote paths without downloading. Files are fetched lazily when coordinates are first accessed.

Parameters:

Name	Type	Description	Default
`result`	`'FunctionResult'`	FunctionResult wrapping a pocket-finder response.	required
`client`	`'DeepOriginClient'`	DeepOrigin client (retained for API compatibility).	required

Returns:

Type	Description
`list[Self]`	A list of Pocket objects.

from_id `classmethod` ¶

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

Create a Pocket from a result-explorer record ID.

Fetches the single record and stores the remote path without downloading. The PDB file is fetched lazily when coordinates are first accessed.

Parameters:

Name	Type	Description	Default
`id`	`str`	Result-explorer record ID of the pocket.	required
`client`	`Optional['DeepOriginClient']`	Optional DeepOriginClient instance. If not provided, uses the default client.	`None`

Returns:

Type	Description
`Self`	A Pocket with properties populated from the record.

Raises:

Type	Description
`ValueError`	If no record is found for the given ID.

from_json `classmethod` ¶

from_json(
    data: list[dict[str, Any]],
    *,
    client: Optional["DeepOriginClient"] = None
) -> list[Self]

Create a list of Pocket objects from a JSON pocket list.

Each entry should contain at least one of file_path / local_path (a local filesystem path) or remote_path (a UFA remote path). When only remote_path is provided the pocket is created without downloading; coordinates will be fetched lazily on first access via :meth:_ensure_coordinates.

Known property keys (volume, total_SASA, etc.) are mapped to dedicated attributes. The protein_id key is mapped to its own attribute. Any remaining unknown keys go into props.

Parameters:

Name	Type	Description	Default
`data`	`list[dict[str, Any]]`	List of pocket dicts, e.g. the value of the `"pockets"` key returned by the pocket-finder tool.	required
`client`	`Optional['DeepOriginClient']`	Optional client to use for lazy downloads. When provided, stored on each Pocket and used by :meth:`download` when coordinates are first accessed.	`None`

Returns:

Type	Description
`list[Self]`	List of Pocket objects with properties populated from the dicts.

from_ligand `classmethod` ¶

from_ligand(
    ligand: "Ligand", name: Optional[str] = None
) -> Self

Create a Pocket instance from a Ligand instance.

from_pdb_file `classmethod` ¶

from_pdb_file(
    pdb_file_path: str | Path,
    name: Optional[str] = None,
    **kwargs: Any
) -> Self

Create a Pocket instance from a PDB file.

Parameters:

Name	Type	Description	Default
`pdb_file_path`	`str \| Path`	Path to the PDB file.	required
`name`	`Optional[str]`	Name for the pocket.	`None`
`**kwargs`	`Any`	Additional arguments to pass to the Pocket constructor.	`{}`

Returns:

Name	Type	Description
`Pocket`	`Self`	A new Pocket instance.

from_remote_file `classmethod` ¶

from_remote_file(
    remote_path: str,
    *,
    client: DeepOriginClient | None = None,
    lazy: bool = True,
    name: Optional[str] = None,
    **kwargs: Any
) -> Self

Create a Pocket from a PDB file stored on the platform.

Downloads the file via :meth:deeporigin.platform.files.FilesClient.download, then loads it with :meth:from_pdb_file.

Parameters:

Name	Type	Description	Default
`remote_path`	`str`	Platform file path (e.g. org storage path) to the PDB file.	required
`client`	`DeepOriginClient \| None`	DeepOrigin client used for download. If `None`, uses `DeepOriginClient()`.	`None`
`lazy`	`bool`	Passed to `files.download`; if `True`, skip download when the file already exists locally at the default cache location.	`True`
`name`	`Optional[str]`	Optional pocket name; defaults to the downloaded file stem (see :meth:`from_pdb_file`).	`None`
`**kwargs`	`Any`	Additional arguments passed to :meth:`from_pdb_file`.	`{}`

Returns:

Name	Type	Description
`Pocket`	`Self`	A pocket with :attr:`~deeporigin.drug_discovery.structures.entity.Entity.remote_path`
	`Self`	set to `remote_path` and :attr:`~deeporigin.drug_discovery.structures.entity.Entity.local_path`
	`Self`	set to the downloaded file path.

from_residue_number `classmethod` ¶

from_residue_number(
    protein,
    residue_number: int,
    chain_id: str | None = None,
    cutoff: float = 5.0,
) -> Self

Creates a pocket centered on a given residue (by number)

Parameters:

Name	Type	Description	Default
`protein`	`Protein`	A DeepOrigin Protein Object	required
`residue_number`	`int`	Residue number of the target residue	required
`chain_id`	`str`	Chain ID that the residue is in	`None`
`cutoff`	`float`	Minimum distance cutoff (Angstroms) from target residue to be included in pocket	`5.0`

Returns:

Type	Description
`Self`	A Pocket object matching the above design.

from_result `classmethod` ¶

from_result(
    *,
    protein_id: str | None = None,
    execution_id: str | None = None,
    pocket_count: int | None = None,
    pocket_min_size: int | None = None,
    client: Optional["DeepOriginClient"] = None
) -> list[Self]

Create Pocket objects from pocketfinder results in the data platform.

Fetches pocketfinder results for the given protein and stores the remote paths without downloading. PDB files are fetched lazily when coordinates are first accessed.

Parameters:

Name	Type	Description	Default
`protein_id`	`str \| None`	Protein ID to fetch pocket results for.	`None`
`execution_id`	`str \| None`	Optional compute job ID to filter by.	`None`
`pocket_count`	`int \| None`	Optional maximum number of pockets to filter by.	`None`
`pocket_min_size`	`int \| None`	Optional minimum pocket volume in cubic Angstroms to filter by.	`None`
`client`	`Optional['DeepOriginClient']`	Optional DeepOriginClient instance. If not provided, uses the default client.	`None`

Returns:

Type	Description
`list[Self]`	List of Pocket objects with properties populated from the results.

Raises:

Type	Description
`ValueError`	If no pocket results are found for the protein.

get_center ¶

get_center() -> ndarray

Get the center of the pocket.

Returns the pre-computed center when available, otherwise falls back to computing the mean of the loaded coordinates.

Returns:

Type	Description
`ndarray`	np.ndarray: A numpy array of shape (3,) with the pocket center.

sync ¶

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

Upload pocket coordinates to remote storage.

Unlike :class:Protein and :class:Ligand, pockets are not looked up in the entities API; this only uploads the generated PDB so :attr:remote_path is set for tools that need a file reference.

Parameters:

Name	Type	Description	Default
`lazy`	`bool`	If True, skip when the pocket already has a platform `id`.	`False`
`client`	`Optional[DeepOriginClient]`	DeepOrigin client. If None, uses `DeepOriginClient()`.	`None`
`remote_path`	`Optional[str]`	Optional explicit destination path on the file server.	`None`

to_file ¶

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

Write pocket coordinates to a PDB file.

Parameters:

Name	Type	Description	Default
`file_path`	`str \| Path \| None`	Destination path. When `None` a temporary file is created; the caller is responsible for deleting it when done.	`None`

Returns:

Type	Description
`str`	The path the file was written to.

to_hash ¶

to_hash() -> str

Compute a hash of the pocket PDB content.

Returns:

Type	Description
`str`	SHA-256 hex digest of the generated PDB string.

to_pdb_file ¶

to_pdb_file(output_path: str)

Write coordinates to a PDB file.

Parameters:

Name	Type	Description	Default
`output_path`	`str`	Destination file path.	required

update_coordinates ¶

update_coordinates(coords: ndarray)

update coordinates of the pocket

deeporigin.drug_discovery.Pocket¶

Attributes¶

apolar_sasa class-attribute instance-attribute ¶

box_size_x class-attribute instance-attribute ¶

box_size_y class-attribute instance-attribute ¶

box_size_z class-attribute instance-attribute ¶

center class-attribute instance-attribute ¶

color class-attribute instance-attribute ¶

coordinates class-attribute instance-attribute ¶

drugability_score class-attribute instance-attribute ¶

hydrophobicity class-attribute instance-attribute ¶

index class-attribute instance-attribute ¶

name class-attribute instance-attribute ¶

pdb_id class-attribute instance-attribute ¶

polar_apolar_sasa_ratio class-attribute instance-attribute ¶

polar_sasa class-attribute instance-attribute ¶

polarity class-attribute instance-attribute ¶

props class-attribute instance-attribute ¶

protein_id class-attribute instance-attribute ¶

total_sasa class-attribute instance-attribute ¶

volume class-attribute instance-attribute ¶

Functions¶

from_function_result classmethod ¶

from_id classmethod ¶

from_json classmethod ¶

from_ligand classmethod ¶

from_pdb_file classmethod ¶

from_remote_file classmethod ¶

from_residue_number classmethod ¶

from_result classmethod ¶

get_center ¶

sync ¶

to_file ¶

to_hash ¶

to_pdb_file ¶

update_coordinates ¶

`deeporigin.drug_discovery.Pocket`¶

apolar_sasa `class-attribute` `instance-attribute` ¶

box_size_x `class-attribute` `instance-attribute` ¶

box_size_y `class-attribute` `instance-attribute` ¶

box_size_z `class-attribute` `instance-attribute` ¶

center `class-attribute` `instance-attribute` ¶

color `class-attribute` `instance-attribute` ¶

coordinates `class-attribute` `instance-attribute` ¶

drugability_score `class-attribute` `instance-attribute` ¶

hydrophobicity `class-attribute` `instance-attribute` ¶

index `class-attribute` `instance-attribute` ¶

name `class-attribute` `instance-attribute` ¶

pdb_id `class-attribute` `instance-attribute` ¶

polar_apolar_sasa_ratio `class-attribute` `instance-attribute` ¶

polar_sasa `class-attribute` `instance-attribute` ¶

polarity `class-attribute` `instance-attribute` ¶

props `class-attribute` `instance-attribute` ¶

protein_id `class-attribute` `instance-attribute` ¶

total_sasa `class-attribute` `instance-attribute` ¶

volume `class-attribute` `instance-attribute` ¶

from_function_result `classmethod` ¶

from_id `classmethod` ¶

from_json `classmethod` ¶

from_ligand `classmethod` ¶

from_pdb_file `classmethod` ¶

from_remote_file `classmethod` ¶

from_residue_number `classmethod` ¶

from_result `classmethod` ¶