Projects¶

Use the high-level deeporigin.projects module to list and select data platform projects, inspect ligands, proteins, and executions for the current project, and sync structures with project scope.

Requires the core optional dependency (includes pandas) for DataFrame helpers.

Configuration¶

The active project is whatever DeepOriginClient().project_id holds in memory.

When DO_AUTH_TOKEN, DO_ORG_KEY, and DO_BASE_URL are all set, the no-arg DeepOriginClient() resolves via environment variables and optional DO_PROJECT_ID. Otherwise the client is built from disk (from_disk) with project_id unset until you call projects.load(...) or projects.create(...), which assign client.project_id for that process (again, no disk write).

API reference¶

deeporigin.projects ¶

User-facing project helpers for the Deep Origin data platform.

Requires the core optional dependency (pandas) for DataFrame helpers.

Attributes¶

Classes¶

Functions:¶

create ¶

create(
    name: str,
    *,
    description: str | None = None,
    load: bool = True,
    client: DeepOriginClient | None = None
) -> str

Create a project on the data platform, or select an existing one by name.

If a non-deleted project already exists with the same display name (exact match), that row is used and no new project is created. Otherwise a new project is created. When multiple rows share the same name, the first search hit is used.

Parameters:

Name	Type	Description	Default
`name`	`str`	Project display name.	required
`description`	`str \| None`	Optional description. Used only when a new project is created; an existing match is not updated.	`None`
`load`	`bool`	When True (default), set the resolved project as active on the client instance.	`True`
`client`	`DeepOriginClient \| None`	Platform client to use. Defaults to `DeepOriginClient()`.	`None`

Returns:

Type	Description
`str`	The project id (canonical id string from the data platform).

current ¶

current() -> tuple[str, str | None] | None

Return the current project id and display name.

The id comes from :attr:deeporigin.platform.client.DeepOriginClient.project_id (set via DO_PROJECT_ID env var, :func:create, or :func:load). The name is loaded from the data platform via :meth:deeporigin.platform.projects.Projects.get.

Returns:

Type	Description
`tuple[str, str \| None] \| None`	`(project_id, name)` when a project is selected. `name` is `None`
`tuple[str, str \| None] \| None`	if the project row could not be resolved.
`tuple[str, str \| None] \| None`	`None` when no project is selected.

executions ¶

executions() -> Any

Executions associated with the current project.

Returns:

Type	Description
`Any`	DataFrame with execution id, tool key, version, and timestamps.

Raises:

Type	Description
`DeepOriginException`	If no current project is set.
`ImportError`	If pandas is not installed.

get_ligands ¶

get_ligands(
    *, limit: int | None = None, **filter_kwargs: Any
) -> LigandSet

Load ligands for the current project as a :class:LigandSet.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Max ligands to fetch (passed through to search).	`None`
`**filter_kwargs`	`Any`	Extra equality filters merged into the search filter.	`{}`

Raises:

Type	Description
`DeepOriginException`	If no current project is set.

get_proteins ¶

get_proteins(
    *, limit: int | None = 100, **filter_kwargs: Any
) -> Sequence[Protein]

Load proteins for the current project as metadata-only Protein objects.

Structures are not downloaded; call :meth:~deeporigin.drug_discovery.structures.protein.Protein.download to hydrate a protein. This keeps listing resilient when a remote PDB is missing or unparseable.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Max proteins to fetch.	`100`
`**filter_kwargs`	`Any`	Extra equality filters merged into the search filter.	`{}`

Raises:

Type	Description
`DeepOriginException`	If no current project is set.

ligands ¶

ligands(*, client: DeepOriginClient | None = None) -> Any

Ligands in the current project as a DataFrame.

Returns:

Type	Description
`Any`	DataFrame with at least `id`, `name`, `smiles`, `canonical_smiles`.

Raises:

Type	Description
`DeepOriginException`	If no current project is set.
`ImportError`	If pandas is not installed.

list ¶

list(*, limit: int | None = 100) -> Any

List projects as a DataFrame.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum rows to return. Defaults to 100 (matches the data platform default for project search). Pass `None` to omit `limit` from the API request (server default applies).	`100`

Returns:

Type	Description
`Any`	DataFrame with columns `id`, `name`, `description` only.

Raises:

Type	Description
`ImportError`	If pandas is not installed.

load ¶

load(
    identifier: str,
    *,
    client: DeepOriginClient | None = None
) -> None

Select a project by id, name, or slug.

Sets client.project_id to the resolved id. No disk writes are performed.

Parameters:

Name	Type	Description	Default
`identifier`	`str`	Project id, name, or slug string.	required
`client`	`DeepOriginClient \| None`	Platform client to use. Defaults to `DeepOriginClient()`.	`None`

Raises:

Type	Description
`DeepOriginException`	If no matching project exists.

proteins ¶

proteins() -> Any

Proteins in the current project as a DataFrame.

Returns:

Type	Description
`Any`	DataFrame with `id`, `name`, `file_path`, `pdb_id`.

Raises:

Type	Description
`DeepOriginException`	If no current project is set.
`ImportError`	If pandas is not installed.

set_ligands ¶

set_ligands(ligands: LigandSet) -> None

Sync a ligand set to the current project (upload + register).

Parameters:

Name	Type	Description	Default
`ligands`	`LigandSet`	Ligands to persist under the current project.	required

Raises:

Type	Description
`DeepOriginException`	If no current project is set.

set_proteins ¶

set_proteins(proteins: Sequence[Protein]) -> None

Sync proteins to the current project.

Parameters:

Name	Type	Description	Default
`proteins`	`Sequence[Protein]`	Proteins to persist under the current project.	required

Raises:

Type	Description
`DeepOriginException`	If no current project is set.

sync_proteins ¶

sync_proteins(
    path: str | Path | Sequence[str | Path],
    *,
    recursive: bool = False,
    timeout: (
        int | float
    ) = DATA_PLATFORM_INGESTION_TIMEOUT_SECONDS
) -> Sequence[Protein]

Import a folder of protein structure files into the current project.

Each .pdb, .cif, .mmcif or .ent file becomes one protein named after its file name without extension, as with Protein.from_file(path).sync(). Files that share a name become separate proteins. A structure already in the project is reused and keeps its name.

Every file is checked first, and if any can't be imported nothing is uploaded and one error lists them all. The import then runs on Deep Origin; this waits on the platform's live update stream rather than holding a request open, and returns once the proteins are saved.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path \| Sequence[str \| Path]`	A folder, a single file, or a list of files.	required
`recursive`	`bool`	Also import files in subfolders.	`False`
`timeout`	`int \| float`	Seconds to wait for the import before giving up.	`DATA_PLATFORM_INGESTION_TIMEOUT_SECONDS`

Returns:

Type	Description
`Sequence[Protein]`	Sequence[Protein]: Every protein in the current project, not only the
`Sequence[Protein]`	imported files, metadata only (no structure downloaded).

Raises:

Type	Description
`DeepOriginException`	If no current project is set, the entities API is unavailable, any file can't be imported, or the import does not start or does not succeed.
`TimeoutError`	If the import has not finished within `timeout`. The message includes the import's execution id.

Platform client¶

Lower-level access uses deeporigin.platform.projects.Projects on ~deeporigin.platform.client.DeepOriginClient — see docs/platform/ref/projects.md.