Distance Module¶

The distance module provides classes for computing distances between molecular datasets, metadata vectors, and combined task distances.

Core Classes¶

DatasetDistance¶

DatasetDistance ¶

DatasetDistance(method: DatasetDistanceMethod = 'euclidean')

Compute distances between molecule datasets (N×M matrix).

This class computes distances between sets of molecules, where each dataset contains multiple molecules with labels. Supports: - OTDD: Optimal Transport Dataset Distance (considers feature + label distributions) - Euclidean: L2 distance between positive/negative prototypes - Cosine: Cosine distance between positive/negative prototypes

For prototype-based methods (Euclidean/Cosine), the distance is computed as: 1. Compute prototype (mean feature) for each class in each dataset 2. Concatenate [pos_prototype, neg_prototype] into a single vector 3. Use scipy.cdist for efficient pairwise distance computation

Parameters:

Name	Type	Description	Default
`method`	`DatasetDistanceMethod`	Distance computation method ('otdd', 'euclidean', 'cosine')	`'euclidean'`

Examples:

>>> distance_calc = DatasetDistance(method="euclidean")
>>> matrix = distance_calc.compute_matrix(
...     source_features=[src_feat_1, src_feat_2],
...     source_labels=[src_labels_1, src_labels_2],
...     target_features=[tgt_feat_1, tgt_feat_2],
...     target_labels=[tgt_labels_1, tgt_labels_2],
...     source_ids=["CHEMBL001", "CHEMBL002"],
...     target_ids=["CHEMBL100", "CHEMBL101"],
...     n_jobs=8
... )

Initialize dataset distance calculator.

Parameters:

Name	Type	Description	Default
`method`	`DatasetDistanceMethod`	Distance method to use	`'euclidean'`

Raises:

Type	Description
`ValueError`	If method is not supported

compute_matrix ¶

compute_matrix(source_features: List[NDArray[float32]], source_labels: List[NDArray[int32]], target_features: List[NDArray[float32]], target_labels: List[NDArray[int32]], source_ids: List[str], target_ids: List[str], n_jobs: int = 1, device: str = 'auto', **kwargs: Any) -> DistanceMatrix

Compute N×M distance matrix between source and target datasets.

Parameters:

Name	Type	Description	Default
`source_features`	`List[NDArray[float32]]`	List of N feature matrices, each (n_i, d)	required
`source_labels`	`List[NDArray[int32]]`	List of N label arrays, each (n_i,)	required
`target_features`	`List[NDArray[float32]]`	List of M feature matrices, each (m_j, d)	required
`target_labels`	`List[NDArray[int32]]`	List of M label arrays, each (m_j,)	required
`source_ids`	`List[str]`	List of N source task identifiers	required
`target_ids`	`List[str]`	List of M target task identifiers	required
`n_jobs`	`int`	Number of parallel jobs (for OTDD)	`1`
`device`	`str`	Device for OTDD computation. `"auto"` (default) uses CUDA when available, else CPU. Accepts any torch device string. Ignored by Euclidean/Cosine (scipy.cdist, CPU-only).	`'auto'`
`**kwargs`	`Any`	Additional arguments for specific methods	`{}`

Returns:

Type	Description
`DistanceMatrix`	Nested dict mapping `target_id -> source_id -> distance`.

compute_single_distance ¶

compute_single_distance(source_features: NDArray[float32], source_labels: NDArray[int32], target_features: NDArray[float32], target_labels: NDArray[int32], **kwargs: Any) -> float

Compute distance between two datasets.

Parameters:

Name	Type	Description	Default
`source_features`	`NDArray[float32]`	Source feature matrix (n, d)	required
`source_labels`	`NDArray[int32]`	Source labels (n,)	required
`target_features`	`NDArray[float32]`	Target feature matrix (m, d)	required
`target_labels`	`NDArray[int32]`	Target labels (m,)	required

Returns:

Type	Description
`float`	Distance value

MetadataDistance¶

MetadataDistance ¶

MetadataDistance(method: MetadataDistanceMethod = 'euclidean')

Compute distances between task metadata vectors (N×M matrix).

This class computes distances between single feature vectors per task, such as protein embeddings or assay description embeddings.

Supports: - Euclidean: L2 distance - Cosine: Cosine distance (1 - cosine_similarity) - Manhattan: L1 distance

Since each task has exactly one vector, this reduces to simple pairwise distance computation using scipy.cdist - highly efficient.

Parameters:

Name	Type	Description	Default
`method`	`MetadataDistanceMethod`	Distance computation method ('euclidean', 'cosine', 'manhattan')	`'euclidean'`

Examples:

>>> distance_calc = MetadataDistance(method="cosine")
>>> matrix = distance_calc.compute_matrix(
...     source_vectors=protein_embeddings_train,
...     target_vectors=protein_embeddings_test,
...     source_ids=["CHEMBL001", "CHEMBL002"],
...     target_ids=["CHEMBL100", "CHEMBL101"]
... )

Initialize metadata distance calculator.

Parameters:

Name	Type	Description	Default
`method`	`MetadataDistanceMethod`	Distance method to use	`'euclidean'`

Raises:

Type	Description
`ValueError`	If method is not supported

compute_matrix ¶

compute_matrix(source_vectors: NDArray[float32], target_vectors: NDArray[float32], source_ids: List[str], target_ids: List[str]) -> DistanceMatrix

Compute N×M distance matrix between source and target metadata.

This uses scipy.cdist for efficient vectorized computation - all N×M distances are computed in a single optimized call.

Parameters:

Name	Type	Description	Default
`source_vectors`	`NDArray[float32]`	Source feature matrix of shape (N, d)	required
`target_vectors`	`NDArray[float32]`	Target feature matrix of shape (M, d)	required
`source_ids`	`List[str]`	List of N source task identifiers	required
`target_ids`	`List[str]`	List of M target task identifiers	required

Returns:

Type	Description
`DistanceMatrix`	Nested dict mapping `target_id -> source_id -> distance`.

compute_from_lists ¶

compute_from_lists(source_vectors: List[NDArray[float32]], target_vectors: List[NDArray[float32]], source_ids: List[str], target_ids: List[str]) -> DistanceMatrix

Compute distance matrix from lists of vectors.

Convenience method that stacks lists into arrays.

Parameters:

Name	Type	Description	Default
`source_vectors`	`List[NDArray[float32]]`	List of N source feature vectors	required
`target_vectors`	`List[NDArray[float32]]`	List of M target feature vectors	required
`source_ids`	`List[str]`	List of N source task identifiers	required
`target_ids`	`List[str]`	List of M target task identifiers	required

Returns:

Type	Description
`DistanceMatrix`	Nested dict mapping `target_id -> source_id -> distance`.

compute_single_distance ¶

compute_single_distance(source_vector: NDArray[float32], target_vector: NDArray[float32]) -> float

Compute distance between two vectors.

Parameters:

Name	Type	Description	Default
`source_vector`	`NDArray[float32]`	Source feature vector (d,)	required
`target_vector`	`NDArray[float32]`	Target feature vector (d,)	required

Returns:

Type	Description
`float`	Distance value

TaskDistanceCalculator¶

TaskDistanceCalculator ¶

TaskDistanceCalculator(tasks: Optional[Tasks] = None, dataset_method: str = 'euclidean', metadata_method: str = 'euclidean', molecule_method: Optional[str] = None, protein_method: Optional[str] = None, method: Optional[str] = None)

High-level orchestrator for computing task distance matrices.

This class coordinates the computation of distance matrices for different aspects of tasks (molecules, proteins, other metadata) and provides methods to combine them.

Parameters:

Name	Type	Description	Default
`tasks`	`Optional[Tasks]`	Optional Tasks collection (if provided, can auto-extract data)	`None`
`dataset_method`	`str`	Distance method for molecule datasets ('otdd', 'euclidean', 'cosine')	`'euclidean'`
`metadata_method`	`str`	Distance method for metadata ('euclidean', 'cosine', 'manhattan')	`'euclidean'`

Attributes:

Name	Type	Description
`molecule_distances`	`Optional[DistanceMatrix]`	Computed molecule distance matrix
`protein_distances`	`Optional[DistanceMatrix]`	Computed protein distance matrix
`combined_distances`	`Optional[DistanceMatrix]`	Combined distance matrix

Examples:

>>> calculator = TaskDistanceCalculator(
...     tasks=tasks,
...     dataset_method="euclidean",
...     metadata_method="cosine"
... )
>>> # Compute all distance types
>>> all_dist = calculator.compute_all_distances(
...     molecule_featurizer="ecfp",
...     n_jobs=8
... )
>>> # Access individual matrices
>>> mol_dist = all_dist["molecules"]
>>> prot_dist = all_dist["protein"]
>>> combined = all_dist["combined"]

Initialize the task distance calculator.

Parameters:

Name	Type	Description	Default
`tasks`	`Optional[Tasks]`	Tasks collection containing source and target tasks	`None`
`dataset_method`	`str`	Method for dataset distances (molecules)	`'euclidean'`
`metadata_method`	`str`	Method for metadata distances (protein, etc.)	`'euclidean'`
`molecule_method`	`Optional[str]`	Legacy alias for dataset_method	`None`
`protein_method`	`Optional[str]`	Legacy alias for metadata_method	`None`
`method`	`Optional[str]`	Legacy default method (applied to both)	`None`

compute_molecule_distance ¶

compute_molecule_distance(molecule_featurizer: str = 'ecfp', n_jobs: int = 1, source_fold: DataFold = TRAIN, target_folds: Optional[List[DataFold]] = None, **kwargs: Any) -> DistanceMatrix

Compute molecule dataset distance matrix.

Parameters:

Name	Type	Description	Default
`molecule_featurizer`	`str`	Name of molecular featurizer	`'ecfp'`
`n_jobs`	`int`	Number of parallel jobs	`1`
`source_fold`	`DataFold`	Fold to use as source	`TRAIN`
`target_folds`	`Optional[List[DataFold]]`	Folds to use as targets	`None`
`**kwargs`	`Any`	Additional arguments for distance computation	`{}`

Returns:

Type	Description
`DistanceMatrix`	Nested dict mapping `target_id -> source_id -> distance`.

compute_protein_distance ¶

compute_protein_distance(protein_featurizer: str = 'esm2_t33_650M_UR50D', source_fold: DataFold = TRAIN, target_folds: Optional[List[DataFold]] = None) -> DistanceMatrix

Compute protein metadata distance matrix.

Parameters:

Name	Type	Description	Default
`protein_featurizer`	`str`	Name of protein featurizer	`'esm2_t33_650M_UR50D'`
`source_fold`	`DataFold`	Fold to use as source	`TRAIN`
`target_folds`	`Optional[List[DataFold]]`	Folds to use as targets	`None`

Returns:

Type	Description
`DistanceMatrix`	Nested dict mapping `target_id -> source_id -> distance`.

compute_combined_distance ¶

compute_combined_distance(molecule_featurizer: str = 'ecfp', protein_featurizer: str = 'esm2_t33_650M_UR50D', weights: Optional[Dict[str, float]] = None, combination: CombinationStrategy = 'weighted_average', n_jobs: int = 1, **kwargs: Any) -> DistanceMatrix

Compute combined distance matrix from molecules and proteins.

Parameters:

Name	Type	Description	Default
`molecule_featurizer`	`str`	Name of molecular featurizer	`'ecfp'`
`protein_featurizer`	`str`	Name of protein featurizer	`'esm2_t33_650M_UR50D'`
`weights`	`Optional[Dict[str, float]]`	Optional weights for combination (default: equal)	`None`
`combination`	`CombinationStrategy`	Combination strategy	`'weighted_average'`
`n_jobs`	`int`	Number of parallel jobs	`1`
`**kwargs`	`Any`	Additional arguments	`{}`

Returns:

Type	Description
`DistanceMatrix`	Combined distance matrix

compute_all_distances ¶

compute_all_distances(molecule_featurizer: str = 'ecfp', protein_featurizer: str = 'esm2_t33_650M_UR50D', weights: Optional[Dict[str, float]] = None, combination: CombinationStrategy = 'weighted_average', n_jobs: int = 1, **kwargs: Any) -> Dict[str, DistanceMatrix]

Compute all distance types and return as dictionary.

This is the main entry point for computing complete task distances.

Parameters:

Name	Type	Description	Default
`molecule_featurizer`	`str`	Name of molecular featurizer	`'ecfp'`
`protein_featurizer`	`str`	Name of protein featurizer	`'esm2_t33_650M_UR50D'`
`weights`	`Optional[Dict[str, float]]`	Optional weights for combination	`None`
`combination`	`CombinationStrategy`	Combination strategy	`'weighted_average'`
`n_jobs`	`int`	Number of parallel jobs	`1`
`**kwargs`	`Any`	Additional arguments	`{}`

Returns:

Type	Description
`Dict[str, DistanceMatrix]`	Dictionary with keys: 'molecules', 'protein', 'combined'

get_distance ¶

get_distance() -> DistanceMatrix

Legacy method: get default distance matrix.

Convenience Functions¶

compute_dataset_distance_matrix¶

compute_dataset_distance_matrix ¶

compute_dataset_distance_matrix(source_features: List[NDArray[float32]], source_labels: List[NDArray[int32]], target_features: List[NDArray[float32]], target_labels: List[NDArray[int32]], source_ids: List[str], target_ids: List[str], method: DatasetDistanceMethod = 'euclidean', n_jobs: int = 1, device: str = 'auto', **kwargs: Any) -> DistanceMatrix

Convenience function to compute dataset distance matrix.

This is the main entry point for computing N×M distance matrices between molecule datasets.

Parameters:

Name	Type	Description	Default
`source_features`	`List[NDArray[float32]]`	List of N source feature matrices	required
`source_labels`	`List[NDArray[int32]]`	List of N source label arrays	required
`target_features`	`List[NDArray[float32]]`	List of M target feature matrices	required
`target_labels`	`List[NDArray[int32]]`	List of M target label arrays	required
`source_ids`	`List[str]`	List of N source task identifiers	required
`target_ids`	`List[str]`	List of M target task identifiers	required
`method`	`DatasetDistanceMethod`	Distance method ('otdd', 'euclidean', 'cosine')	`'euclidean'`
`n_jobs`	`int`	Number of parallel jobs	`1`
`device`	`str`	Device for OTDD (`"auto" \| "cpu" \| "cuda"`). `"auto"` picks CUDA when available. Ignored by Euclidean/Cosine.	`'auto'`
`**kwargs`	`Any`	Additional method-specific arguments	`{}`

Returns:

Type	Description
`DistanceMatrix`	Nested dict mapping `target_id -> source_id -> distance`.

Examples:

>>> distances = compute_dataset_distance_matrix(
...     source_features, source_labels,
...     target_features, target_labels,
...     source_ids, target_ids,
...     method="euclidean"
... )

compute_metadata_distance_matrix¶

compute_metadata_distance_matrix ¶

compute_metadata_distance_matrix(source_vectors: NDArray[float32], target_vectors: NDArray[float32], source_ids: List[str], target_ids: List[str], method: MetadataDistanceMethod = 'euclidean') -> DistanceMatrix

Convenience function to compute metadata distance matrix.

This is the main entry point for computing N×M distance matrices between task metadata (protein embeddings, descriptions, etc.).

Parameters:

Name	Type	Description	Default
`source_vectors`	`NDArray[float32]`	Source feature matrix of shape (N, d)	required
`target_vectors`	`NDArray[float32]`	Target feature matrix of shape (M, d)	required
`source_ids`	`List[str]`	List of N source task identifiers	required
`target_ids`	`List[str]`	List of M target task identifiers	required
`method`	`MetadataDistanceMethod`	Distance method ('euclidean', 'cosine', 'manhattan')	`'euclidean'`

Returns:

Type	Description
`DistanceMatrix`	Nested dict mapping `target_id -> source_id -> distance`.

Examples:

>>> # Compute protein distance matrix
>>> protein_distances = compute_metadata_distance_matrix(
...     train_protein_embeddings,  # (N, 1280) for ESM
...     test_protein_embeddings,   # (M, 1280)
...     train_task_ids,
...     test_task_ids,
...     method="cosine"
... )

combine_distance_matrices¶

combine_distance_matrices ¶

combine_distance_matrices(matrices: Dict[str, DistanceMatrix], weights: Optional[Dict[str, float]] = None, combination: str = 'weighted_average') -> DistanceMatrix

Combine multiple distance matrices into one.

Parameters:

Name	Type	Description	Default
`matrices`	`Dict[str, DistanceMatrix]`	Dict mapping aspect name to distance matrix	required
`weights`	`Optional[Dict[str, float]]`	Optional weights for each aspect (default: equal weights)	`None`
`combination`	`str`	Combination strategy ('weighted_average', 'min', 'max', 'sum')	`'weighted_average'`

Returns:

Type	Description
`DistanceMatrix`	Combined distance matrix

Examples:

>>> combined = combine_distance_matrices(
...     {"molecules": mol_distances, "protein": prot_distances},
...     weights={"molecules": 0.7, "protein": 0.3},
...     combination="weighted_average"
... )

Base Class¶

AbstractTasksDistance¶

AbstractTasksDistance ¶

AbstractTasksDistance(tasks: Optional[Tasks] = None, dataset_method: str = 'euclidean', metadata_method: str = 'euclidean', molecule_method: Optional[str] = None, protein_method: Optional[str] = None, method: Optional[str] = None)

Base class for computing distances between tasks.

This abstract class defines the interface for task distance computation. It distinguishes between: - Dataset distances: Between sets of molecules (OTDD, set-based Euclidean/Cosine) - Metadata distances: Between single vectors per task (vector-based Euclidean/Cosine)

Parameters:

Name	Type	Description	Default
`tasks`	`Optional[Tasks]`	Tasks collection for distance computation	`None`
`dataset_method`	`str`	Distance computation method for datasets (molecules) (default: "euclidean")	`'euclidean'`
`metadata_method`	`str`	Distance computation method for metadata including protein (default: "euclidean")	`'euclidean'`
`molecule_method`	`Optional[str]`	Deprecated alias for dataset_method	`None`
`protein_method`	`Optional[str]`	Deprecated - protein is metadata, use metadata_method	`None`
`method`	`Optional[str]`	Global method (for backward compatibility, overrides individual methods if provided)	`None`

get_num_tasks ¶

get_num_tasks() -> Tuple[int, int]

Get the number of source and target tasks.

get_distance ¶

get_distance() -> Dict[str, Dict[str, float]]

Compute the distance between datasets.

Each of the subclasses should implement this method.

Returns:

Type	Description
`Dict[str, Dict[str, float]]`	Dictionary containing distance matrix between source and target datasets.
`Dict[str, Dict[str, float]]`	The outer dictionary is keyed by target task IDs, and the inner dictionary
`Dict[str, Dict[str, float]]`	is keyed by source task IDs with distance values.

Raises:

Type	Description
`NotImplementedError`	If not implemented by subclass

get_hopts ¶

get_hopts(data_type: str = 'dataset') -> Optional[Dict[str, Any]]

Get hyperparameters for distance computation.

Each of the subclasses should implement this method.

Parameters:

Name	Type	Description	Default
`data_type`	`str`	Type of data ("dataset", "metadata") Legacy: "molecule" (alias for "dataset"), "protein" (alias for "metadata")	`'dataset'`

Returns:

Type	Description
`Optional[Dict[str, Any]]`	Dictionary containing hyperparameters for the distance computation method
`Optional[Dict[str, Any]]`	or None if no hyperparameters are needed.

Raises:

Type	Description
`NotImplementedError`	If not implemented by subclass

get_supported_methods ¶

get_supported_methods(data_type: str) -> List[str]

Get list of supported methods for a specific data type.

Parameters:

Name	Type	Description	Default
`data_type`	`str`	Type of data ("dataset", "metadata") Legacy: "molecule" (alias for "dataset"), "protein" (alias for "metadata")	required

Returns:

Type	Description
`List[str]`	List of supported method names for the data type

Raises:

Type	Description
`NotImplementedError`	If not implemented by subclass

Legacy Classes¶

These classes are kept for backward compatibility. Prefer DatasetDistance and MetadataDistance for new code.

MoleculeDatasetDistance¶

MoleculeDatasetDistance ¶

MoleculeDatasetDistance(tasks: Optional[Tasks] = None, molecule_method: str = 'euclidean', method: Optional[str] = None, **kwargs: Any)

Bases: AbstractTasksDistance

Calculate distances between molecule datasets using various methods.

This class implements distance computation between molecule datasets using: - Optimal Transport Dataset Distance (OTDD) - Euclidean distance - Cosine distance

The class supports both single dataset comparisons and batch comparisons across multiple datasets.

Parameters:

Name	Type	Description	Default
`tasks`	`Optional[Tasks]`	Tasks collection containing molecule datasets for distance computation	`None`
`method`	`Optional[str]`	Distance computation method ('otdd', 'euclidean', or 'cosine')	`None`
`**kwargs`	`Any`	Additional arguments passed to the distance computation method	`{}`

Raises:

Type	Description
`ValueError`	If the specified method is not supported for molecule datasets

get_hopts ¶

get_hopts(data_type: str = 'molecule') -> Optional[Dict[str, Any]]

Get hyperparameters for the distance computation method.

Parameters:

Name	Type	Description	Default
`data_type`	`str`	Type of data ("molecule", "protein", "metadata")	`'molecule'`

Returns:

Type	Description
`Optional[Dict[str, Any]]`	Dictionary of hyperparameters specific to the chosen distance method for the data type.

get_supported_methods ¶

get_supported_methods(data_type: str) -> List[str]

Get list of supported methods for a specific data type.

Parameters:

Name	Type	Description	Default
`data_type`	`str`	Type of data ("molecule", "protein", "metadata")	required

Returns:

Type	Description
`List[str]`	List of supported method names for the data type

otdd_distance ¶

otdd_distance() -> Dict[str, Dict[str, float]]

Compute Optimal Transport Dataset Distance between molecule datasets.

This method uses the OTDD implementation to compute distances between molecule datasets, which takes into account both the feature space and label space of the datasets.

Returns:

Type	Description
`Dict[str, Dict[str, float]]`	Dictionary containing OTDD distances between source and target datasets.
`Dict[str, Dict[str, float]]`	The outer dictionary is keyed by target task IDs, and the inner dictionary
`Dict[str, Dict[str, float]]`	is keyed by source task IDs with distance values.

euclidean_distance ¶

euclidean_distance(featurizer_name: str = 'ecfp') -> Dict[str, Dict[str, float]]

Compute Euclidean distance between molecule datasets.

This method computes the dataset-level Euclidean distance by comparing the prototypes of the datasets.

Parameters:

Name	Type	Description	Default
`featurizer_name`	`str`	Name of the molecular featurizer to use (e.g., "ecfp", "maccs", "desc2D")	`'ecfp'`

Returns:

Type	Description
`Dict[str, Dict[str, float]]`	Dictionary containing Euclidean distances between source and target datasets.
`Dict[str, Dict[str, float]]`	The outer dictionary is keyed by target task IDs, and the inner dictionary
`Dict[str, Dict[str, float]]`	is keyed by source task IDs with distance values.

Raises:

Type	Description
`DistanceComputationError`	If feature computation fails

cosine_distance ¶

cosine_distance(featurizer_name: str = 'ecfp') -> Dict[str, Dict[str, float]]

Compute cosine distance between molecule datasets.

This method computes the dataset-level cosine distance by comparing the prototypes of the datasets.

Parameters:

Name	Type	Description	Default
`featurizer_name`	`str`	Name of the molecular featurizer to use (e.g., "ecfp", "maccs", "desc2D")	`'ecfp'`

Returns:

Type	Description
`Dict[str, Dict[str, float]]`	Dictionary containing cosine distances between source and target datasets.
`Dict[str, Dict[str, float]]`	The outer dictionary is keyed by target task IDs, and the inner dictionary
`Dict[str, Dict[str, float]]`	is keyed by source task IDs with distance values.

get_distance ¶

get_distance(featurizer_name: str = 'ecfp') -> Dict[str, Dict[str, float]]

Compute the distance between molecule datasets using the specified method.

Parameters:

Name	Type	Description	Default
`featurizer_name`	`str`	Name of the molecular featurizer to use (e.g., "ecfp", "maccs", "desc2D")	`'ecfp'`

Returns:

Type	Description
`Dict[str, Dict[str, float]]`	Dictionary containing distance matrix between source and target datasets.
`Dict[str, Dict[str, float]]`	The outer dictionary is keyed by target task IDs, and the inner dictionary
`Dict[str, Dict[str, float]]`	is keyed by source task IDs with distance values.

load_distance ¶

load_distance(path: str) -> None

Load pre-computed distances from a file.

Parameters:

Name	Type	Description	Default
`path`	`str`	Path to the file containing pre-computed distances	required

Raises:

Type	Description
`FileNotFoundError`	If the file doesn't exist
`ValueError`	If the file format is invalid

to_pandas ¶

to_pandas() -> DataFrame

Convert the distance matrix to a pandas DataFrame.

Returns:

Type	Description
`DataFrame`	DataFrame with source task IDs as index and target task IDs as columns,
`DataFrame`	containing the distance values.

ProteinDatasetDistance¶

ProteinDatasetDistance ¶

ProteinDatasetDistance(tasks: Optional[Tasks] = None, protein_method: str = 'euclidean', method: Optional[str] = None)

Bases: AbstractTasksDistance

Calculate distances between protein datasets using various methods.

This class implements distance computation between protein datasets using: - Euclidean distance - Cosine distance

The class supports both single dataset comparisons and batch comparisons across multiple datasets.

Parameters:

Name	Type	Description	Default
`tasks`	`Optional[Tasks]`	Tasks collection containing protein datasets for distance computation	`None`
`method`	`Optional[str]`	Distance computation method ('euclidean' or 'cosine')	`None`

Raises:

Type	Description
`ValueError`	If the specified method is not supported for protein datasets

get_hopts ¶

get_hopts(data_type: str = 'protein') -> Optional[Dict[str, Any]]

Get hyperparameters for the distance computation method.

Parameters:

Name	Type	Description	Default
`data_type`	`str`	Type of data ("molecule", "protein", "metadata")	`'protein'`

Returns:

Type	Description
`Optional[Dict[str, Any]]`	Dictionary of hyperparameters specific to the chosen distance method for the data type.

get_supported_methods ¶

get_supported_methods(data_type: str) -> List[str]

Get list of supported methods for a specific data type.

Parameters:

Name	Type	Description	Default
`data_type`	`str`	Type of data ("molecule", "protein", "metadata")	required

Returns:

Type	Description
`List[str]`	List of supported method names for the data type

euclidean_distance ¶

euclidean_distance() -> Dict[str, Dict[str, float]]

Compute Euclidean distance between protein datasets.

This method calculates the pairwise Euclidean distances between protein feature vectors in the datasets.

Returns:

Type	Description
`Dict[str, Dict[str, float]]`	Dictionary containing Euclidean distances between source and target datasets.
`Dict[str, Dict[str, float]]`	The outer dictionary is keyed by target task IDs, and the inner dictionary
`Dict[str, Dict[str, float]]`	is keyed by source task IDs with distance values.

cosine_distance ¶

cosine_distance() -> Dict[str, Dict[str, float]]

Compute cosine distance between protein datasets.

This method calculates the pairwise cosine distances between protein feature vectors in the datasets.

Returns:

Type	Description
`Dict[str, Dict[str, float]]`	Dictionary containing cosine distances between source and target datasets.
`Dict[str, Dict[str, float]]`	The outer dictionary is keyed by target task IDs, and the inner dictionary
`Dict[str, Dict[str, float]]`	is keyed by source task IDs with distance values.

sequence_identity_distance ¶

sequence_identity_distance() -> Dict[str, Dict[str, float]]

Compute sequence identity-based distance between protein datasets.

This method calculates distances based on protein sequence identity.

Returns:

Type	Description
`Dict[str, Dict[str, float]]`	Dictionary containing sequence identity-based distances between datasets.

Raises:

Type	Description
`NotImplementedError`	This method is not yet implemented

get_distance ¶

get_distance() -> Dict[str, Dict[str, float]]

Compute the distance between protein datasets using the specified method.

Returns:

Type	Description
`Dict[str, Dict[str, float]]`	Dictionary containing distance matrix between source and target datasets.
`Dict[str, Dict[str, float]]`	The outer dictionary is keyed by target task IDs, and the inner dictionary
`Dict[str, Dict[str, float]]`	is keyed by source task IDs with distance values.

load_distance ¶

load_distance(path: str) -> None

Load pre-computed distances from a file.

Parameters:

Name	Type	Description	Default
`path`	`str`	Path to the file containing pre-computed distances	required

Raises:

Type	Description
`FileNotFoundError`	If the file doesn't exist
`ValueError`	If the file format is invalid

to_pandas ¶

to_pandas() -> DataFrame

Convert the distance matrix to a pandas DataFrame.

Returns:

Type	Description
`DataFrame`	DataFrame with source task IDs as index and target task IDs as columns,
`DataFrame`	containing the distance values.

Exceptions¶

DistanceComputationError¶

DistanceComputationError ¶

Bases: Exception

Custom exception for distance computation errors.

DataValidationError¶

DataValidationError ¶

Bases: Exception

Custom exception for data validation errors.

Constants¶

DATASET_DISTANCE_METHODS = ["otdd", "euclidean", "cosine"]
METADATA_DISTANCE_METHODS = ["euclidean", "cosine", "manhattan", "jaccard"]

See the Distance Computation Guide for usage examples and method comparisons.