src.geometry.matrix package

Submodules

src.geometry.matrix.adjacency module

class src.geometry.matrix.adjacency.AdjacencyMatrix(*args, **kwargs)

Bases: AdjacencyMatrixMixin, ABC

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

AdjacencyMatrix

class src.geometry.matrix.adjacency.AdjacencyMatrixMixin(*args, **kwargs)

Bases: GeometryMatrixMixin, ABC

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

AdjacencyMatrix

classmethod create(*args, **kwargs)
Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

AdjacencyMatrix

fixed_dtype

alias of bool

class src.geometry.matrix.adjacency.CsrAdjacencyMatrix(*args, **kwargs)

Bases: AdjacencyMatrix, CsrArray

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

AdjacencyMatrix

class src.geometry.matrix.adjacency.DenseAdjacencyMatrix(*args, **kwargs)

Bases: AdjacencyMatrix, DenseArray

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

AdjacencyMatrix

src.geometry.matrix.affinity module

class src.geometry.matrix.affinity.AffinityMatrix(*args, **kwargs)

Bases: AffinityMatrixMixin, ABC

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

AffinityMatrix

laplacian(lap_type='geometric', diag_add=1.0, aff_minus_id=True, in_place=False)

Construct a graph Laplacian from an affinity matrix using the specified type. Uses aff’s eps metadata for scaling. Papers:

Parameters:

  • affs – Affinity matrix.

  • eps – Optional scaling parameter. If provided, the resulting Laplacian is multiplied by 4 / eps^2. (default: None).

  • lap_type (Literal['geometric', 'random_walk', 'symmetric']) – Type of Laplacian to compute. (default: “geometric”). - “geometric”: normalized symmetric followed by random-walk-like normalization. - “random_walk”: standard random walk Laplacian. - “symmetric”: symmetric normalized Laplacian.

  • diag_add (float) – Value to add to the diagonal after constructing the Laplacian. If aff_minus_id is True, this value is negated before being added.

  • aff_minus_id (bool) – Whether to subtract the identity matrix from the affinity matrix. (default: True) If True, computes I - normalized_affs. If False, negates the Laplacian directly.

  • in_place (bool) – Whether to modify the input affinity matrix in place during normalization. (default: False).

  • aff (AffinityMatrix)

Returns:

The constructed Laplacian matrix.

Return type:

LaplacianMatrix

class src.geometry.matrix.affinity.AffinityMatrixMixin(*args, **kwargs)

Bases: GeometryMatrixMixin, ABC

Mixin class that adds factory functionality to the AffinityMatrix hierarchy.

This allows users to work with AffinityMatrix as an abstract entry point without needing to explicitly choose between dense or sparse representations.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

AffinityMatrix

classmethod create(*args, **kwargs)
Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

AffinityMatrix

class src.geometry.matrix.affinity.CsrAffinityMatrix(*args, **kwargs)

Bases: AffinityMatrix, CsrArray

Implementation of a sparse (Csr-backed) affinity matrix.

This class represents an affinity matrix stored in sparse format, providing fast element-wise operations at the cost of memory usage.

Typically not instantiated directly: instead, construct an AffinityMatrix in CsrArray format which will return an instance.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

AffinityMatrix

class src.geometry.matrix.affinity.DenseAffinityMatrix(*args, **kwargs)

Bases: AffinityMatrix, DenseArray

Implementation of a dense (NumPy-backed) affinity matrix.

This class represents an affinity matrix stored in dense format, providing fast element-wise operations at the cost of memory usage.

Typically not instantiated directly: instead, construct an AffinityMatrix in DenseArray format which will return an instance.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

AffinityMatrix

src.geometry.matrix.distance module

class src.geometry.matrix.distance.CsrDistanceMatrix(*args, **kwargs)

Bases: DistanceMatrix, CsrArray

Implementation of a sparse (CSR-backed) distance matrix. Provides thresholding and adjacency operations for sparse arrays.

Typically not instantiated directly: instead, construct an DistanceMatrix in CsrArray format which will return an instance.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

DistanceMatrix

class src.geometry.matrix.distance.DenseDistanceMatrix(*args, **kwargs)

Bases: DistanceMatrix, DenseArray

Implementation of a dense (NumPy-backed) distance matrix. Provides thresholding and adjacency operations for dense arrays.

Typically not instantiated directly: instead, construct an DistanceMatrix in DenseArray format which will return an instance.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

DistanceMatrix

class src.geometry.matrix.distance.DistanceMatrix(*args, **kwargs)

Bases: DistanceMatrixMixin, ABC

Abstract base class representing a distance matrix, with functionality to derive adjacency and affinity matrices, and to threshold distances.

This class serves as a template for distance matrix operations and enforces the implementation of adjacency and threshold execution methods in subclasses. It also provides registration and dispatching mechanisms for affinity functions.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

DistanceMatrix

adjacency(copy=False)

Convert the distance matrix into an adjacency matrix.

Parameters:

copy (bool) – Whether to return a copy of the adjacency matrix or reuse existing data. (default: False

Returns:

The adjacency matrix corresponding to this distance matrix.

Return type:

AdjacencyMatrix

affinity(aff_type='gaussian', eps=None, in_place=False)

Compute an affinity matrix from the distance matrix.

The operation can be computed either in place or out of place depending on the in_place flag. The distance matrix is assumed to contain squared distances if the DistanceMatrix`s dist_type metadata is sqeuclidean.

Parameters:

  • aff_type (AffinityType) – The type of affinity to compute (e.g., gaussian).

  • eps (Optional[float]) – Optional scaling parameter for the affinity function. If None, a default is used. (default: None)

  • in_place (bool) – If True, modify the existing matrix; otherwise, return a new one. (default: False)

Returns:

The computed affinity matrix.

Return type:

AffinityMatrix

threshold(radius, in_place=False)

Threshold the distance matrix by eliminating entries above a given radius.

Parameters:

  • radius (float) – The maximum radius to retain distances. When dense, entries larger than this will be set to np.inf.

  • in_place (bool) – If True, modify the existing distance matrix; otherwise, return a new one. (default: False)

Raises:

ValueError – If the given radius is greater than the maximum radius defined in the matrix metadata.

Returns:

The thresholded distance matrix.

Return type:

DistanceMatrix

threshold_distance_iter(radii, in_place=False)

Generate an iterator over thresholded distance matrices with a single radius or sequence of radii.

Parameters:

  • radii (float or Iterable[float]) – A single radius or an iterable of radii with which to threshold the distance matrix.

  • in_place (bool) – If True, modify the existing distance matrix with each radius (This will ultimately threshold with the largest radius); otherwise, return new matrices. (default: False)

Returns:

An iterator over thresholded distance matrices.

Return type:

Iterator[DistanceMatrix]

class src.geometry.matrix.distance.DistanceMatrixMixin(*args, **kwargs)

Bases: GeometryMatrixMixin, ABC

Mixin class that adds factory functionality to the DistanceMatrix hierarchy.

This allows users to work with DistanceMatrix as an abstract entry point without worrying about the underlying dense/sparse representation.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

DistanceMatrix

classmethod create(*args, **kwargs)
Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

DistanceMatrix

src.geometry.matrix.distance.gaussian(dists, eps=None, dist_is_sq=False, in_place=False)

Compute a Gaussian affinity matrix from a distance matrix.

Parameters:

  • dists (DistanceMatrix) – The distance matrix to convert into an affinity matrix.

  • eps (Optional[float]) – Scaling parameter for the Gaussian kernel. If None, chosen to be 1. (default: None)

  • dist_is_sq (bool) – Whether the distance matrix already contains squared distances. (default: False)

  • in_place (bool) – If True, compute the affinity in place by modifying the given distance matrix; otherwise, compute out of place. (default: False)

Returns:

The Gaussian affinity matrix.

Return type:

AffinityMatrix

src.geometry.matrix.laplacian module

class src.geometry.matrix.laplacian.CsrLaplacianMatrix(*args, **kwargs)

Bases: LaplacianMatrix, CsrArray

Concrete implementation of a sparse (CSR-backed) Laplacian matrix.

This class provides a memory-efficient sparse representation, especially useful for large, sparse graphs.

Typically not instantiated directly; instead, construct a LaplacianMatrix and let the LaplacianMatrixMixin factory return a CsrLaplacianMatrix if constructed in a CsrArray format.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

LaplacianMatrix

class src.geometry.matrix.laplacian.DenseLaplacianMatrix(*args, **kwargs)

Bases: LaplacianMatrix, DenseArray

Implementation of a dense (NumPy-backed) Laplacian matrix.

This class provides a dense representation, offering fast element-wise operations at the cost of memory usage.

Typically not instantiated directly; instead, construct a LaplacianMatrix and let the LaplacianMatrixMixin factory return a DenseLaplacianMatrix if constructed in a DenseArray format.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

LaplacianMatrix

class src.geometry.matrix.laplacian.LaplacianMatrix(*args, **kwargs)

Bases: LaplacianMatrixMixin, BaseArray

Abstract base class representing a Laplacian matrix.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

LaplacianMatrix

class src.geometry.matrix.laplacian.LaplacianMatrixMixin(*args, **kwargs)

Bases: GeometryMatrixMixin, ABC

Mixin class that adds factory functionality to the LaplacianMatrix hierarchy.

When instantiating LaplacianMatrix directly, this mixin intercepts construction and returns either a DenseLaplacianMatrix or a CsrLaplacianMatrix depending on the provided arguments.

This allows users to work with LaplacianMatrix as an abstract entry point without explicitly choosing the dense or sparse representation.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

LaplacianMatrix

classmethod create(*args, **kwargs)
Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

LaplacianMatrix

src.geometry.matrix.laplacian.eps_adjustment(eps)
Parameters:

eps (float)

Return type:

float

Module contents

class src.geometry.matrix.AdjacencyMatrix(*args, **kwargs)

Bases: AdjacencyMatrixMixin, ABC

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

AdjacencyMatrix

class src.geometry.matrix.AffinityMatrix(*args, **kwargs)

Bases: AffinityMatrixMixin, ABC

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

AffinityMatrix

laplacian(lap_type='geometric', diag_add=1.0, aff_minus_id=True, in_place=False)

Construct a graph Laplacian from an affinity matrix using the specified type. Uses aff’s eps metadata for scaling. Papers:

Parameters:

  • affs – Affinity matrix.

  • eps – Optional scaling parameter. If provided, the resulting Laplacian is multiplied by 4 / eps^2. (default: None).

  • lap_type (Literal['geometric', 'random_walk', 'symmetric']) – Type of Laplacian to compute. (default: “geometric”). - “geometric”: normalized symmetric followed by random-walk-like normalization. - “random_walk”: standard random walk Laplacian. - “symmetric”: symmetric normalized Laplacian.

  • diag_add (float) – Value to add to the diagonal after constructing the Laplacian. If aff_minus_id is True, this value is negated before being added.

  • aff_minus_id (bool) – Whether to subtract the identity matrix from the affinity matrix. (default: True) If True, computes I - normalized_affs. If False, negates the Laplacian directly.

  • in_place (bool) – Whether to modify the input affinity matrix in place during normalization. (default: False).

  • aff (AffinityMatrix)

Returns:

The constructed Laplacian matrix.

Return type:

LaplacianMatrix

class src.geometry.matrix.DistanceMatrix(*args, **kwargs)

Bases: DistanceMatrixMixin, ABC

Abstract base class representing a distance matrix, with functionality to derive adjacency and affinity matrices, and to threshold distances.

This class serves as a template for distance matrix operations and enforces the implementation of adjacency and threshold execution methods in subclasses. It also provides registration and dispatching mechanisms for affinity functions.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

DistanceMatrix

adjacency(copy=False)

Convert the distance matrix into an adjacency matrix.

Parameters:

copy (bool) – Whether to return a copy of the adjacency matrix or reuse existing data. (default: False

Returns:

The adjacency matrix corresponding to this distance matrix.

Return type:

AdjacencyMatrix

affinity(aff_type='gaussian', eps=None, in_place=False)

Compute an affinity matrix from the distance matrix.

The operation can be computed either in place or out of place depending on the in_place flag. The distance matrix is assumed to contain squared distances if the DistanceMatrix`s dist_type metadata is sqeuclidean.

Parameters:

  • aff_type (AffinityType) – The type of affinity to compute (e.g., gaussian).

  • eps (Optional[float]) – Optional scaling parameter for the affinity function. If None, a default is used. (default: None)

  • in_place (bool) – If True, modify the existing matrix; otherwise, return a new one. (default: False)

Returns:

The computed affinity matrix.

Return type:

AffinityMatrix

threshold(radius, in_place=False)

Threshold the distance matrix by eliminating entries above a given radius.

Parameters:

  • radius (float) – The maximum radius to retain distances. When dense, entries larger than this will be set to np.inf.

  • in_place (bool) – If True, modify the existing distance matrix; otherwise, return a new one. (default: False)

Raises:

ValueError – If the given radius is greater than the maximum radius defined in the matrix metadata.

Returns:

The thresholded distance matrix.

Return type:

DistanceMatrix

threshold_distance_iter(radii, in_place=False)

Generate an iterator over thresholded distance matrices with a single radius or sequence of radii.

Parameters:

  • radii (float or Iterable[float]) – A single radius or an iterable of radii with which to threshold the distance matrix.

  • in_place (bool) – If True, modify the existing distance matrix with each radius (This will ultimately threshold with the largest radius); otherwise, return new matrices. (default: False)

Returns:

An iterator over thresholded distance matrices.

Return type:

Iterator[DistanceMatrix]

class src.geometry.matrix.LaplacianMatrix(*args, **kwargs)

Bases: LaplacianMatrixMixin, BaseArray

Abstract base class representing a Laplacian matrix.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

LaplacianMatrix