matchms.Scores module

class matchms.Scores.Scores(data: dict[str, ndarray | coo_array])

Bases: object

Container for computed matchms scores.

The Scores class stores the output of one similarity computation and provides a small, intuitive API that works for both dense and sparse score matrices.

A Scores instance can represent either:

• a scalar score matrix with one field, usually "score"

• a multi-field score result, for example "score" and "matches"

• dense data stored as NumPy arrays

• sparse data stored as SciPy COO arrays

Parameters:

data – Dictionary mapping score field names to score data. Each value must be either a 2D NumPy array or a SciPy coo_array. All fields must have the same shape and must all be either dense or sparse.

Notes

The class is designed to offer a consistent API independent of the underlying storage format.

Field access

Score fields can be accessed by name, for example scores["score"] or scores["matches"]. Field selection returns another Scores object containing only the selected field.

Scalar scores

If only one field is present, direct comparisons are supported, for example scores > 0.5. This is equivalent to scores["score"] > 0.5.

Masking

Boolean masking returns a filtered Scores object with the same shape. For example, scores[scores["score"] > 0.5] keeps only entries where the condition is true.

Slicing

Basic slicing is supported, for example scores[3, 4], scores[3, :], or scores[:, 2].

Conversion

Use to_array() to obtain a dense NumPy representation and to_coo() to obtain a sparse COO representation.

Examples

Scalar dense scores:

>>> scores = Scores({"score": np.array([[1.0, 0.0], [0.3, 0.8]])})
>>> scores["score"].to_array()
array([[1. , 0. ],
       [0.3, 0.8]])
>>> filtered = scores[scores > 0.5]
>>> filtered.to_array()
array([[1. , 0. ],
       [0. , 0.8]])

Multi-field scores:

>>> scores = Scores({
...     "score": np.array([[1.0, 0.0], [0.3, 0.8]]),
...     "matches": np.array([[5, 0], [1, 4]])
... })
>>> scores["score"].to_array()
array([[1. , 0. ],
       [0.3, 0.8]])
>>> scores["matches"].to_array()
array([[5, 0],
       [1, 4]])
>>> good = scores[(scores["score"] > 0.2) & (scores["matches"] >= 2)]
>>> good.to_array("score")
array([[1. , 0. ],
       [0. , 0.8]])

__init__(data: dict[str, ndarray | coo_array])

copy() → Scores

Return a copy of the Scores object.

Dense score fields are copied as independent NumPy arrays. Sparse score fields are copied as independent SciPy COO arrays. The returned Scores object preserves the score fields, shape, and storage mode of the original object.

classmethod load(path: str | Path) → Scores

Load a Scores object from a .npz file.

Parameters:

path – Input file path.

Returns:

Reconstructed Scores object.

Return type:

Scores

save(path: str | Path, compressed: bool = True) → None

Save the Scores object to a single .npz file.

Parameters:

• path – Output file path.

• compressed – If True, use numpy.savez_compressed. Default is True.

class matchms.Scores.ScoresMask(shape: tuple[int, int], dense_mask: ndarray | None = None, row: ndarray | None = None, col: ndarray | None = None)

Bases: object

Boolean mask for Scores, stored either densely or as sparse coordinates.

Parameters:

• shape (tuple[int, int]) – Shape of the score matrix this mask applies to.

• dense_mask (numpy.ndarray | None) – Optional dense boolean array of shape shape. If provided, row and col must be None.

• row (numpy.ndarray | None) – Optional array of row indices for sparse representation.

• col (numpy.ndarray | None) – Optional array of column indices for sparse representation. If provided, dense_mask must be None.

__init__(shape: tuple[int, int], dense_mask: ndarray | None = None, row: ndarray | None = None, col: ndarray | None = None) → None