Labelled Candidates¶

The LabelledCandidates dataclass represents a collection of candidates with their corresponding labels (fitness values). This is used for training data, validation data, and storing oracle evaluations.

class alf_core.dataclasses.labelled_candidates.LabelledCandidates(candidates, labels)[source]¶

Bases: object

A collection of candidates paired with their labels.

candidates¶: A list of Candidate objects.

labels¶: A numpy array of labels corresponding to each candidate.

append(candidates, labels=None)[source]¶

Append candidates and labels to this collection.

Parameters:

candidates (Union[list[Candidate], LabelledCandidates]) – Either a list of Candidate objects or another LabelledCandidates object. If a list is provided, labels must also be provided.
labels (ndarray | None) – Optional numpy array of labels. Required if candidates is a list, ignored if candidates is a LabelledCandidates object.

Raises:

AssertionError – If candidates is a list and labels is None, or if the length of candidates and labels don’t match.

Return type:

None

candidates: list[Candidate]¶

property data: list[Any]¶

Return the raw data of each candidate.

Returns:: A list containing the raw data (e.g. a sequence string, a SMILES string, a feature vector) of each candidate in the collection.

get_top_k(k)[source]¶

Return the top k candidates based on their label values.

Parameters:: k (int) – Number of top candidates to select.
Return type:: LabelledCandidates
Returns:: New LabelledCandidates object containing the top k candidates sorted by label values (highest first).

labels: ndarray¶

remove(candidates)[source]¶

Remove specified candidates and their corresponding labels from this collection.

Uses identity-based comparison (same object instance) for removal. Candidates not present in the collection are silently ignored.

Parameters:: candidates (Union[list[Candidate], LabelledCandidates]) – Either a list of Candidate objects or a LabelledCandidates object containing the candidates to remove.
Return type:: None

shuffle(seed)[source]¶

Create a new LabelledCandidates object with shuffled candidates and labels.

Parameters:: seed (int) – Random seed for reproducibility of the shuffle.
Return type:: LabelledCandidates
Returns:: A new LabelledCandidates object with the same candidates and labels, but in a randomly shuffled order.

sort(ascending=True)[source]¶

Sort the candidates and labels by label values.

Parameters:: ascending (bool) – If True, sort in ascending order (lowest to highest). If False, sort in descending order (highest to lowest). Defaults to True.
Return type:: LabelledCandidates
Returns:: A new LabelledCandidates object with candidates and labels sorted by label values.

to_dataframe()[source]¶

Convert the labelled candidates to a pandas DataFrame.

Returns:

“data”: The formatted data of each candidate
”label”: The label value for each candidate
Additional columns for any features present in the candidates

Return type:

DataFrame