l2gv2.align package

Contents

l2gv2.align package#

Subpackages#

Submodules#

l2gv2.align.alignment module#

Base functions and classes for alignment problems.

class l2gv2.align.alignment.AlignmentProblem(patches: list[Patch], patch_edges=None, min_overlap=None, copy_data=True, self_loops=False, verbose=False)#

Bases: object

Base class for alignment problems.

align_patches(_scale=False)#

Align the patches. This is where the magic happens.

dim = None#
get_aligned_embedding(scale=False, realign=False, out=None)#

Return the aligned embedding

Parameters:

  • scale (bool) – if True, rescale patches (default: False)

  • realign (bool) – if True, recompute aligned embedding even if it already exists (default: False)

Returns:

n_nodes x dim numpy array of embedding coordinates

classmethod load(filename)#

restore AlignmentProblem from patch file

Parameters:

filename – path to patch file

mean_embedding(out=None)#

Compute node embeddings as the centroid over patch embeddings

Parameters:

out – numpy array to write results to (supply a memmap for large-scale problems that do not fit in ram)

median_embedding(out=None)#
n_nodes = None#
n_patches = None#
rotate_patches(rotations: ndarray)#

align the rotation/reflection of all patches

Parameters:

rotations – If provided, apply the given transformations instead of synchronizing patch rotations

rotations = None#
save_embedding(filename)#

save aligned embedding to json file

Parameters:

filename – output filename

save_patches(filename)#

save patch embeddings to json file :param filename: path to output file

scale_patches(scale_factors: ndarray)#

Synchronise scales of the embeddings for each patch

Parameters:

scale_factors – if provided apply the given scales instead of synchronising

scales = None#
shifts = None#
translate_patches(translations: ndarray)#

align the patches by translation

Parameters:

translations – If provided, apply the given translations instead of synchronizing

verbose = False#
weight(_i, _j)#

Compute the weight for a pair of patches

class l2gv2.align.alignment.WeightedAlignmentProblem(patches: list[Patch], patch_edges=None, min_overlap=None, copy_data=True, self_loops=False, verbose=False)#

Bases: AlignmentProblem

Variant of the local2global algorithm where patch edges are weighted according to the number of nodes in the overlap.

weight(i, j)#

compute weight for pair of patches

Parameters:

  • i – first patch index

  • j – second patch index

Returns:

number of shared nodes between patches i and j

l2gv2.align.alignment.local_error(patch: Patch, reference_coordinates)#

compute the euclidean distance between patch coordinate and reference coordinate for each node in patch

Parameters:

  • patch

  • reference_coordinates

Returns:

vector of error values

l2gv2.align.alignment.orthogonal_MSE_error(rots1, rots2)#

Compute the MSE between two sets of orthogonal transformations up to a global transformation

Parameters:

  • rots1 – First list of orthogonal matrices

  • rots2 – Second list of orthogonal matrices

l2gv2.align.alignment.procrustes_error(coordinates1, coordinates2)#

compute the procrustes alignment error between two sets of coordinates

Parameters:

  • coordinates1 – First set of coordinates (array-like)

  • coordinates2 – Second set of coordinates (array-like)

Note that the two sets of coordinates need to have the same shape.

l2gv2.align.alignment.transform_error(transforms)#

Compute the recovery error based on tracked transformations.

After recovery, all transformations should be constant across patches as we can recover the embedding only up to a global scaling/rotation/translation. The error is computed as the mean over transformation elements of the standard deviation over patches.

Parameters:

transforms – list of transforms

l2gv2.align.registry module#

Registry for aligners.

l2gv2.align.registry.get_aligner(name, **kwargs)#

Factory function to instantiate an aligner based on its registered name.

Parameters:

  • name (str) – The registered name of the aligner (e.g., “local2global”).

  • **kwargs – Additional keyword arguments that will be passed to the aligner’s constructor.

Returns:

An instance of the aligner class corresponding to the given name.

Raises:

ValueError – If the aligner name is not found in the registry.

l2gv2.align.registry.register_aligner(name)#

Decorator to register an aligner class under a specified name.

Parameters:

name (str) – The key under which the aligner class will be registered.

Returns:

A decorator that registers the class.

l2gv2.align.utils module#

Utils for alignment

l2gv2.align.utils.get_intersections(patches, min_overlap=0)#

Calculate the intersection of nodes between patches.

l2gv2.align.utils.to_device(obj, device, dtype=torch.float32)#

Recursively moves tensors in a nested structure to the specified device and converts them to the specified dtype.

Parameters:

  • obj – The object to process (tensor, dict, list, tuple, etc.)

  • device – The target device (‘cuda’, ‘cpu’, etc.)

  • dtype – The target data type (default: torch.float32)

Returns:

The same structure with all tensors moved to device and converted to dtype

Module contents#

class l2gv2.align.AlignmentProblem(patches: list[Patch], patch_edges=None, min_overlap=None, copy_data=True, self_loops=False, verbose=False)#

Bases: object

Base class for alignment problems.

align_patches(_scale=False)#

Align the patches. This is where the magic happens.

dim = None#
get_aligned_embedding(scale=False, realign=False, out=None)#

Return the aligned embedding

Parameters:

  • scale (bool) – if True, rescale patches (default: False)

  • realign (bool) – if True, recompute aligned embedding even if it already exists (default: False)

Returns:

n_nodes x dim numpy array of embedding coordinates

classmethod load(filename)#

restore AlignmentProblem from patch file

Parameters:

filename – path to patch file

mean_embedding(out=None)#

Compute node embeddings as the centroid over patch embeddings

Parameters:

out – numpy array to write results to (supply a memmap for large-scale problems that do not fit in ram)

median_embedding(out=None)#
n_nodes = None#
n_patches = None#
rotate_patches(rotations: ndarray)#

align the rotation/reflection of all patches

Parameters:

rotations – If provided, apply the given transformations instead of synchronizing patch rotations

rotations = None#
save_embedding(filename)#

save aligned embedding to json file

Parameters:

filename – output filename

save_patches(filename)#

save patch embeddings to json file :param filename: path to output file

scale_patches(scale_factors: ndarray)#

Synchronise scales of the embeddings for each patch

Parameters:

scale_factors – if provided apply the given scales instead of synchronising

scales = None#
shifts = None#
translate_patches(translations: ndarray)#

align the patches by translation

Parameters:

translations – If provided, apply the given translations instead of synchronizing

verbose = False#
weight(_i, _j)#

Compute the weight for a pair of patches

class l2gv2.align.GeoAlignmentProblem(patches: list[Patch], patch_edges=None, min_overlap=None, copy_data=True, self_loops=False, verbose=False, num_epochs: int = 1000, learning_rate: float = 0.001, model_type: str = 'affine', device: str = 'cpu')#

Bases: AlignmentProblem

Alignment problem using pytorch geometric.

align_patches(scale=False)#

Align the patches.

l2gv2.align.get_aligner(name, **kwargs)#

Factory function to instantiate an aligner based on its registered name.

Parameters:

  • name (str) – The registered name of the aligner (e.g., “local2global”).

  • **kwargs – Additional keyword arguments that will be passed to the aligner’s constructor.

Returns:

An instance of the aligner class corresponding to the given name.

Raises:

ValueError – If the aligner name is not found in the registry.

l2gv2.align.local_error(patch: Patch, reference_coordinates)#

compute the euclidean distance between patch coordinate and reference coordinate for each node in patch

Parameters:

  • patch

  • reference_coordinates

Returns:

vector of error values

l2gv2.align.orthogonal_MSE_error(rots1, rots2)#

Compute the MSE between two sets of orthogonal transformations up to a global transformation

Parameters:

  • rots1 – First list of orthogonal matrices

  • rots2 – Second list of orthogonal matrices

l2gv2.align.procrustes_error(coordinates1, coordinates2)#

compute the procrustes alignment error between two sets of coordinates

Parameters:

  • coordinates1 – First set of coordinates (array-like)

  • coordinates2 – Second set of coordinates (array-like)

Note that the two sets of coordinates need to have the same shape.

l2gv2.align.register_aligner(name)#

Decorator to register an aligner class under a specified name.

Parameters:

name (str) – The key under which the aligner class will be registered.

Returns:

A decorator that registers the class.

l2gv2.align.transform_error(transforms)#

Compute the recovery error based on tracked transformations.

After recovery, all transformations should be constant across patches as we can recover the embedding only up to a global scaling/rotation/translation. The error is computed as the mean over transformation elements of the standard deviation over patches.

Parameters:

transforms – list of transforms

Contents