Data

Bioverse stores biomolecular data as Awkward Array records organized in a fixed hierarchy: scenes → frames → molecules → residues → atoms. The three core containers below travel through adapters, transforms, tasks, and metrics.

  • Batch — one shard of structured data with nested fields (coordinates, sequences, labels, graphs, …) and a table-of-contents (toc) that describes how many elements exist at each level.

  • Split — partition assignments (train, validation, test, or custom splits) keyed by scene, frame, molecule, or other levels.

  • Assets — a dictionary of shared resources referenced across batches (token vocabularies, precomputed embeddings, ID maps, etc.).

Tasks read data through VirtualBatch, a lazy, cache-backed view over on-disk shards that applies live transforms at load time.

class bioverse.data.Assets[source]

Bases: dict

Shared lookup tables referenced across dataset batches.

Assets hold vocabularies, embedding matrices, ID maps, and other resources that are too large or too static to duplicate in every batch. Tasks and live transforms read from assets at load time.

Examples

assets = Assets({"residue_tokens": ["ALA", "GLY", ...], "residue_features": emb})
class bioverse.data.Batch(data: dict[str, Array], prefixes: List[str] = ['scene', 'frame', 'molecule', 'chain', 'residue', 'atom'], resolution: str = 'atom')[source]

Bases: object

One shard of structured biomolecular data.

A batch stores nested Awkward arrays keyed by {level}_{property} (e.g. residue_pos, molecule_label) together with a table-of-contents (toc) that records how many elements exist at each hierarchy level: scene → frame → molecule → chain → residue → atom.

Batches support attribute-style access via BatchProxy and fancy indexing to select subsets across the hierarchy.

Examples

batch = Batch({"residue_pos": pos, "residue_token": tokens})
coords = batch.residues.residue_pos
subset = batch[0]  # first scene
class bioverse.data.BatchProxy(batch: Batch, nesting: List[int] = [])[source]

Bases: object

Attribute-access wrapper for nested Batch hierarchy levels.

BatchProxy tracks nesting depth so that attribute access like batch.molecules.residue_pos returns appropriately flattened Awkward arrays without manual indexing.

class bioverse.data.Split(data: dict[str, Array | ndarray | list | tuple] = {}, default: str = 'default')[source]

Bases: object

Train/validation/test partition assignments for dataset elements.

Splits map named partitions ("train", "val", "test", …) to integer labels per hierarchy level. Keys must end with _split and reference a valid level (scene_split, molecule_split, etc.).

Examples

split = Split({"scene_split": ["train", "train", "val", "test"]})
train_mask = split["train"]       # default split name
val_mask = split["default", "val"]