Helper Functions

Window Merging

src.helpers.merge_window_matches_unique_ref(matches_list, cell_id_col='Cell_Num_Old')

Merge per-window matches and enforce one-to-one matching maximizing aligned count.

This function concatenates a list of per-window match DataFrames and returns a single DataFrame with no duplicates on either endpoint: each Aligned_{cell_id_col} and each Ref_{cell_id_col} appears at most once.

It maximizes the number of unique Aligned_{cell_id_col} kept by computing a maximum-cardinality bipartite matching between Aligned_{cell_id_col} and Ref_{cell_id_col}. For duplicate occurrences of the same (aligned, ref) pair across windows, it prefers rows with filtered_violation == False and then smaller window_id.

Required columns in each DataFrame: - 'window_id' - f'Aligned_{cell_id_col}' - f'Ref_{cell_id_col}' - 'X' - 'Y' - 'filtered_violation' (if missing, treated as True)

Parameters:

Name	Type	Description	Default
matches_list	list[DataFrame]	List of per-window matches DataFrames.	required
cell_id_col	str	Name of the cell ID column to use for matching.	'Cell_Num_Old'

Returns:

Type	Description
DataFrame	Maximum-cardinality one-to-one merged matches.

Triangle Utilities

src.triangle_utils.compute_filtered_delaunay(old_coords, alpha=0.05)

Computes the filtered Delaunay triangulation based on an alpha shape.

Parameters: - old_coords: array-like, shape (n_points, 2) The coordinates of the points to triangulate. - alpha: float, optional (default=0.05) The alpha value for the alpha shape. This value might need tuning.

Returns: - filtered_triangles: list of simplices The list of filtered triangles that are within the alpha shape.

Violation Analysis

src.violationhelper.verify_spatial_preservation(aligned_df, ref_df, matches_df, triangle_info, tolerance=1e-06)

Verify if spatial relationships are preserved in the matched points.

Parameters:

aligned_df : pd.DataFrame Original aligned points with 'X', 'Y' coordinates ref_df : pd.DataFrame Reference points with 'X', 'Y' coordinates matches_df : pd.DataFrame Dataframe containing the matches with columns: ['aligned_idx', 'ref_idx', 'X', 'Y', 'ref_X', 'ref_Y'] triangle_info : dict Dictionary containing triangle information from Delaunay triangulation tolerance : float Tolerance for floating point comparisons

Returns:

dict Detailed report of spatial preservation violations

src.violationhelper.print_violation_report(violations)

Print a human-readable report of the violations.