Create a task

Overview

Tasks translate sampler indices into model inputs X and targets y. They are the bridge between on-disk shards and your model’s train_step.

When to create one

Add a task when your prediction problem is not covered by Tasks (property prediction, inverse folding, virtual screening, structure prediction, etc.).

Walkthrough

Step 1 — Subclass Task

import awkward as ak

from bioverse.task import Task


class MyTask(Task):
    """Describe what X contains and what y supervises."""

    def __init__(self, target_field="label"):
        self.target_field = target_field

    def __call__(self, vbatch, assets, index):
        X = vbatch[index["scene"], index["frame"], index["molecule"]]
        X.resolution = "atom"
        targets = X.molecules.__getattr__(f"molecule_{self.target_field}")
        y = ak.Array({"target": ak.flatten(targets, axis=None)})
        return X, y

Step 2 — Pair with sampler and metric

dataset: D_AFCATH
sampler: MoleculeSampler
task:
  MyTask:
    target_field: label
metric: BinaryAccuracyMetric

Step 3 — Inspect loader output

benchmark = BenchmarkFactory("B_MYBENCH")
loader = benchmark.loader(partition="train", batch_size=2, progress=False)
(X, y), data = next(iter(loader))
print(X.resolution, y.fields)

Required interface

Implement __call__(vbatch, assets, index)() returning (X, y):

  • X — Batch view with resolution set to "atom" or "residue"

  • y — Awkward array; metrics typically expect a target field

Reference tasks

Configuration

Tasks are stateless; pass hyperparameters via YAML kwargs. The collater and model receive collated data objects produced from X and y.

Testing

benchmark = BenchmarkFactory("B_MYBENCH")
loader = benchmark.loader(partition="train", batch_size=1, progress=False)
(X, y), collated = next(iter(loader))
assert "target" in y.fields
loss, out, tgt = benchmark.model.eval_step((X, y), collated)  # if model wired

Common pitfalls

  • Wrong resolution — atom-level models need X.resolution = "atom"; residue-level models use "residue"

  • Variable-length targets — pack sizes in y (see PropertyPredictionTask) so collaters can pad correctly

  • Assets not loaded — token featurization may require keys in Assets; ensure the adapter populates them

Submitting upstream

Document target semantics, compatible samplers/metrics, and expected collater in the class docstring. See Contributor Guide.