check_ape_cluster_member_distances

soda_analyzer.check_ape_cluster_member_distances(h5_lib, mode=1, bandwidth=None, temporary=False, cycle_field='cluster_assignment_cycle', print_report=True, max_rows=20)

Compare clustering members against independent current/earlier-cycle members.

Parameters:

  • h5_lib (h5py.File) – Open SODA HDF5 file containing the saved APE environment data. The caller keeps ownership of the file.

  • mode ({1, 2}, optional) – Use all model members as subjects (1, default), or only each cluster’s earliest known assignment-cycle members (2).

  • bandwidth (float, optional) – Finite, nonnegative cutoff in embedded-descriptor distance units. None uses a positive saved metadata value or the last saved bandwidth.

  • temporary (bool, optional) – Select temp_cluster_id instead of cluster_id. Default: False.

  • cycle_field (str, optional) – Persisted field used to order members. Default: "cluster_assignment_cycle"; falls back to descriptor_update_cycle when the requested field is absent.

  • print_report (bool, optional) – Print the formatted report as well as returning it. Default: True.

  • max_rows (int, optional) – Maximum examples shown per printed list; the returned report is not truncated. Default: 20.

Returns:

dict – Report containing settings, member and exclusion counts, smallest_distances (one closest cross-cluster pair per subject cluster with an eligible reference), and under_bandwidth (the subset strictly below the cutoff). Each pair includes row IDs, cycles, and the same subject’s nearest independent own-cluster reference, when available.

Raises:

ValueError – If the mode or bandwidth is invalid, no saved bandwidth is available without an override, or product-state alias records conflict.

Notes

Mode 1 uses all model members as subjects. Mode 2 uses only each cluster’s earliest known assignment-cycle members as subjects. In both modes, reference members come from the entire saved clustering-member list and must have a known cycle less than or equal to the subject’s cycle, regardless of cluster ID.

The report retains one closest cross-cluster pair per subject cluster. For that SAME subject row, same_cluster_distance gives its nearest independent member of its own cluster from the current or an earlier cycle. None means no such independent reference exists; it is not a zero distance or a failed assignment. Mode 2 can compare peers from the cluster’s first cycle.

Identical registry rows, shared nonnegative full-descriptor IDs, and aliases of the same resolved state/atom are excluded from both neighbor searches. Alias-blocked rows deliberately remain model members and possible subjects; blocking sampling does not remove their geometric reference from the model. Equal descriptor vectors at different sampling locations remain comparable. bandwidth=None uses the persisted bandwidth; temporary=True selects temp_cluster_id instead of cluster_id. Missing assignment-cycle metadata falls back to persisted descriptor_update_cycle, otherwise rows are skipped.

This is a snapshot diagnostic, not a replay of the historical classifier: vectors, labels, aliases and bandwidth are the saved values, and one cycle can span many registration events. max_rows only limits printed examples. The caller owns h5_lib; this function neither closes it nor retains HDF5 views.