Candidate

The Candidate dataclass represents a single candidate sequence or design to be evaluated. It contains the sequence representation and associated metadata.

class alf_core.dataclasses.candidate.Candidate(data, modality, features=None)

Bases: object

A candidate is a data point with a modality and features.

data

The raw data of the candidate (e.g., a sequence string, a SMILES string, a feature vector).

modality

The data’s domain (see Modality) — what it represents, e.g. "sequence" or "molecule". Not its storage type.

features

Optional dictionary of precomputed features for the candidate.

data: Any

features: dict | None = None

modality: Modality | str

to_serializable()

Convert candidate data to a format suitable for pandas DataFrame storage.

Dispatch is based on the type of data, not on modality. Modality describes the data’s domain (see Modality); how it is stored — and therefore how it is serialised — is determined by its Python type:

• str (sequences, SMILES, JSON-encoded payloads): returned unchanged.

• torch.Tensor: converted to a numpy array for compact storage.

• numpy array, scalar (Python int/float/bool or a numpy scalar such as np.int64), dict, list, tuple, pandas Series: returned unchanged.

• None: returned as None.

Returns:

The candidate data in a DataFrame-compatible format.

Common types include str, dict, np.ndarray, pd.Series, or torch.Tensor.

Return type:

Union[str, int, float, bool, dict, list, tuple, ndarray, Any, None]

Raises:

TypeError – If the data type is not DataFrame-compatible.

Examples

>>> # A sequence or SMILES string is stored as-is
>>> Candidate(data="ACDEFG", modality=Modality.SEQUENCE).to_serializable()
'ACDEFG'

>>> Candidate(data="CC(=O)O", modality=Modality.MOLECULE).to_serializable()
'CC(=O)O'

>>> # A feature dict is stored as-is
>>> c = Candidate(data={"age": 32, "height": 178}, modality=Modality.TABULAR)
>>> c.to_serializable()
{'age': 32, 'height': 178}

class alf_core.dataclasses.candidate.Modality(*values)

Bases: Enum

The kind of candidate — used to match datasets with compatible models and metrics.

It is the data’s domain where one exists, not how the data is stored. This is why a protein sequence and a SMILES string are distinct modalities (SEQUENCE vs MOLECULE) even though both are stored as str: they pair with different models and metrics. Storage type is never encoded here — it is inferred from type(data) (see Candidate.to_serializable).

Members:

SEQUENCE: Biological sequences (protein / nucleotide), as strings. MOLECULE: Small molecules, as SMILES strings. TABULAR: Domain-agnostic numeric feature vectors (arrays, tensors, scalars, dicts).

MOLECULE = 'molecule'

SEQUENCE = 'sequence'

TABULAR = 'tabular'