Protein

Protein `pydantic-model`

Bases: BaseModel

A Rowan protein.

Data is not loaded by default to avoid unnecessary downloads that could impact performance. Call load_data() to fetch and attach the protein data to this Protein object.

Attributes:

Name	Type	Description
`uuid`	`str`	UUID of the protein
`created_at`	`datetime \| None`	creation date of the protein
`used_in_workflow`	`bool \| None`	whether the protein is used in a workflow
`ancestor_uuid`	`str \| None`	UUID of the ancestor protein
`name`	`str \| None`	name of the protein
`data`	`dict \| None`	data of the protein
`public`	`bool \| None`	whether the protein is public

Show JSON schema:

{
  "description": "A Rowan protein.\n\nData is not loaded by default to avoid unnecessary downloads that could impact performance.\nCall `load_data()` to fetch and attach the protein data to this `Protein` object.\n\nAttributes:\n    uuid: UUID of the protein\n    created_at: creation date of the protein\n    used_in_workflow: whether the protein is used in a workflow\n    ancestor_uuid: UUID of the ancestor protein\n    name: name of the protein\n    data: data of the protein\n    public: whether the protein is public",
  "properties": {
    "uuid": {
      "title": "Uuid",
      "type": "string"
    },
    "created_at": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Created At"
    },
    "used_in_workflow": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Used In Workflow"
    },
    "ancestor_uuid": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ancestor Uuid"
    },
    "name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Name"
    },
    "data": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Data"
    },
    "public": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Public"
    },
    "pocket": {
      "anyOf": [
        {
          "items": {
            "items": {
              "type": "number"
            },
            "type": "array"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Pocket"
    }
  },
  "required": [
    "uuid"
  ],
  "title": "Protein",
  "type": "object"
}

Fields:

uuid (str)
created_at (datetime | None)
used_in_workflow (bool | None)
ancestor_uuid (str | None)
name (str | None)
data (dict | None)
public (bool | None)
pocket (list[list[float]] | None)

chains `property`

chains: list[str]

Polymer chain IDs present in this protein.

get_atom_index

get_atom_index(chain: str, residue: int | str, atom: str, *, entity_type: Literal['polymer', 'non_polymer', 'water', 'branched'] | None = None, model_index: int = 0) -> int

Return an atom's zero-based position in PDB atom-record order.

Parameters:

Name	Type	Description	Default
`chain`	`str`	chain ID	required
`residue`	`int \| str`	residue number, optionally including an insertion code	required
`atom`	`str`	atom name, such as `SG` or `C1`	required
`entity_type`	`Literal['polymer', 'non_polymer', 'water', 'branched'] \| None`	entity collection to search	`None`
`model_index`	`int`	zero-based model index	`0`

Returns:

Type	Description
`int`	atom index in PDB record order

Raises:

Type	Description
`ValueError`	protein data is not loaded or the atom cannot be found

select_chains

select_chains(chains: list[str]) -> Protein

Create a new protein record containing only the specified chains.

Parameters:

Name	Type	Description	Default
`chains`	`list[str]`	chain IDs to keep (e.g. `["A"]`)	required

Returns:

Type	Description
`Protein`	new Protein object with only the selected chains

Raises:

Type	Description
`ValueError`	any requested chain is not present
`HTTPStatusError`	API request fails

refresh

refresh(in_place: bool = True, workflow_uuid: str | None = None) -> Self

Loads protein data.

Parameters:

Name	Type	Description	Default
`in_place`	`bool`	whether to update this protein or return a refreshed copy	`True`
`workflow_uuid`	`str \| None`	UUID of a workflow referencing this protein, for proteins reachable only through a workflow you can read. Not needed for proteins from a workflow result	`None`

Returns:

Type	Description
`Self`	protein with loaded data

update

update(name: str | None = None, data: dict | None = None, public: bool | None = None, pocket: list[list[float]] | None = None) -> Self

Updates protein data.

Parameters:

Name	Type	Description	Default
`name`	`str \| None`	new name of the protein	`None`
`data`	`dict \| None`	new data of the protein	`None`
`public`	`bool \| None`	whether the protein is public	`None`
`pocket`	`list[list[float]] \| None`	new pocket of the protein	`None`

Returns:

Type	Description
`Self`	updated protein object

delete

delete() -> None

Deletes a protein.

Raises:

Type	Description
`HTTPStatusError`	request to the API fails

validate_protein_forcefield

validate_protein_forcefield(exclude_residues: list[str | int] | None = None) -> None

Validate that this protein can be parameterized with the MD forcefield.

Calls the server-side validation which checks that all residues are recognized by OpenMM and that there are no clashing atoms. Call this before submitting any MD workflow to catch preparation issues early.

Ligand residues (LIG) are always excluded – they are parameterized separately by the MD workflow from the provided SMILES. Pass a binder's small_molecule_residues to exclude those as well.

A name is matched case-insensitively and excludes every residue with that name, including multiple copies. Integer entries are 0-based indices into the protein's sorted non-polymer records, and reference a record without naming it.

Run validation on the structure returned by submit_protein_preparation_workflow. The preparation workflow strips and reassigns hydrogens before returning the structure.

Parameters:

Name	Type	Description	Default
`exclude_residues`	`list[str \| int] \| None`	additional residue names and/or 0-based non-polymer indices to skip	`None`

Raises:

Type	Description
`HTTPStatusError`	validation fails or the API request fails

download_structure

download_structure(path: Path | str | None = None, name: str | None = None, workflow_uuid: str | None = None, *, file_format: Literal['mmcif', 'pdb'] = 'mmcif') -> Path

Download a protein structure, defaulting to mmCIF.

Parameters:

Name	Type	Description	Default
`path`	`Path \| str \| None`	output directory; defaults to the current directory	`None`
`name`	`str \| None`	filename without an extension; defaults to protein name or UUID	`None`
`workflow_uuid`	`str \| None`	UUID of a readable workflow referencing this protein	`None`
`file_format`	`Literal['mmcif', 'pdb']`	output format; mmCIF avoids PDB's fixed-width identifier limits	`'mmcif'`

Returns:

Type	Description
`Path`	saved `.cif` or `.pdb` path

Raises:

Type	Description
`ValueError`	file format is unsupported
`HTTPStatusError`	API request fails

download_pdb_file

download_pdb_file(path: Path | str | None = None, name: str | None = None, workflow_uuid: str | None = None) -> None

Downloads the PDB file for a protein.

Builds the file locally from this protein's data, calling refresh() if needed, so it works anywhere refresh() does – including proteins reachable only through a workflow.

Parameters:

Name	Type	Description	Default
`path`	`Path \| str \| None`	directory to save the file to (defaults to current directory)	`None`
`name`	`str \| None`	optional custom name for the file (defaults to protein name)	`None`
`workflow_uuid`	`str \| None`	UUID of a workflow referencing this protein, for proteins reachable only through a workflow you can read. Not needed for proteins from a workflow result	`None`

Raises:

Type	Description
`HTTPStatusError`	request to the API fails

retrieve_protein

retrieve_protein(uuid: str, workflow_uuid: str | None = None) -> Protein

Retrieves a protein from the API using its UUID.

Parameters:

Name	Type	Description	Default
`uuid`	`str`	UUID of the protein to retrieve	required
`workflow_uuid`	`str \| None`	UUID of a workflow referencing this protein, for proteins reachable only through a workflow you can read. Not needed for proteins from a workflow result	`None`

Returns:

Type	Description
`Protein`	protein object representing the retrieved protein

Raises:

Type	Description
`HTTPStatusError`	request to the API fails

list_proteins

list_proteins(ancestor_uuid: str | None = None, name_contains: str | None = None, page: int = 0, size: int = 20) -> list[Protein]

List proteins.

Parameters:

Name	Type	Description	Default
`ancestor_uuid`	`str \| None`	UUID of the ancestor protein to filter by	`None`
`name_contains`	`str \| None`	substring to search for in protein names	`None`
`page`	`int`	page number to retrieve	`0`
`size`	`int`	number of items per page	`20`

Returns:

Type	Description
`list[Protein]`	proteins that match the search criteria

Raises:

Type	Description
`HTTPStatusError`	request to the API fails

upload_protein

upload_protein(name: str, file_path: str | Path, project_uuid: str | Project | None = None) -> Protein

Upload a protein from an mmCIF or PDB file to the API.

Parameters:

Name	Type	Description	Default
`name`	`str`	name of the protein to create	required
`file_path`	`str \| Path`	path to an mmCIF (`.cif` or `.mmcif`) or PDB file	required
`project_uuid`	`str \| Project \| None`	UUID of the project to create the protein in	`None`

Returns:

Type	Description
`Protein`	protein object representing the uploaded protein

Raises:

Type	Description
`HTTPStatusError`	request to the API fails

create_protein_from_pdb_id

create_protein_from_pdb_id(code: str, name: str | None = None, project_uuid: str | Project | None = None) -> Protein

Creates a protein from a PDB ID.

Parameters:

Name	Type	Description	Default
`code`	`str`	PDB ID of the protein to create	required
`name`	`str \| None`	name of the protein. Defaults to the PDB ID	`None`
`project_uuid`	`str \| Project \| None`	UUID of the project to create the protein in	`None`

Returns:

Type	Description
`Protein`	protein object representing the created protein

Raises:

Type	Description
`HTTPStatusError`	request to the API fails

Protein-related data models.

ProteinSequence `pydantic-model`

Bases: Base

Protein sequence data.

:param sequence: amino-acid sequence string :param cyclic: whether this sequence forms a cyclic peptide :param modifications: non-standard residues overriding positions in the sequence

Show JSON schema:

{
  "$defs": {
    "ResidueModification": {
      "description": "A non-standard (modified) residue at a position in a protein sequence.\n\nThe canonical residue at `position` is replaced by the residue named by\nthe Chemical Component Dictionary (CCD) code, e.g. `SEP` for phosphoserine.\n\n:param position: 0-based index of the modified residue in the sequence\n:param ccd: CCD code of the modified residue (e.g. `SEP`)",
      "properties": {
        "position": {
          "title": "Position",
          "type": "integer"
        },
        "ccd": {
          "title": "Ccd",
          "type": "string"
        }
      },
      "required": [
        "position",
        "ccd"
      ],
      "title": "ResidueModification",
      "type": "object"
    }
  },
  "description": "Protein sequence data.\n\n:param sequence: amino-acid sequence string\n:param cyclic: whether this sequence forms a cyclic peptide\n:param modifications: non-standard residues overriding positions in the sequence",
  "properties": {
    "sequence": {
      "title": "Sequence",
      "type": "string"
    },
    "cyclic": {
      "default": false,
      "title": "Cyclic",
      "type": "boolean"
    },
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Id"
    },
    "modifications": {
      "default": [],
      "items": {
        "$ref": "#/$defs/ResidueModification"
      },
      "title": "Modifications",
      "type": "array"
    }
  },
  "required": [
    "sequence"
  ],
  "title": "ProteinSequence",
  "type": "object"
}

Fields:

sequence (str)
cyclic (bool)
id (str | None)
modifications (list[ResidueModification])

Validators:

validate_modifications

Protein

Protein pydantic-model

chains property

get_atom_index

select_chains

refresh

update

delete

validate_protein_forcefield

download_structure

download_pdb_file

retrieve_protein

list_proteins

upload_protein

create_protein_from_pdb_id

ProteinSequence pydantic-model

Protein `pydantic-model`

chains `property`

ProteinSequence `pydantic-model`