Matching Module¶

src/fed_maxfuse/matching/ and src/fed_maxfuse/models/federated/server_functions.py

Implements cell-to-cell matching. Conceptual background: Federated Matching.

Server-side functions¶

models/federated/server_functions.py, the only component that sees both modalities, and then only as normalised, smoothed representations.

Function	Role
`cell_matching(...)`	Linear sum assignment over the cross-modal distance matrix
`calculate_cdistance(correlation_one, correlation_two)`	Builds \(D = 1 - \rho\)
`sum_corr(correlation_one, correlation_two)`	Combines correlations for propagation weighting
`sort_indices_with_corr(...)`	Orders matches by score; supports redundancy removal
`flatten_indices_values_meta_indices(...)`	Expands meta-cell indices to constituent cells
`get_matching_federated(...)`	Top-level orchestration of a matching round

The kernel is small by design:

\[ D \leftarrow 1.0 - X_1' \cdot (X_2')^\top, \qquad \{(i_k, j_k)\} \leftarrow \texttt{LinearSumAssignment}(D) \]

Because each node ships mean-centred, L2-normalised data, this dot product is the Pearson correlation, with no approximation.

Node-side helpers¶

matching/

Module	Role
`checkpoint.py`	Persist and restore matching state
`conversion.py`	Convert between matching representations
`utils.py`	Index manipulation, redundancy handling

The Split-Π convention¶

A matching is stored per node as index/weight pairs:

Node 1: \(\Pi_{(0,2)} = \{(i_k, w_k)\}\)
Node 2: \(\Pi_{(1,2)} = \{(j_k, w_k)\}\)

Indices are private; weights are shared. Shared weights let both nodes apply the pivot filter α independently and agree without an extra round trip.

Sign convention¶

During matching, values are distances (\(1 - \rho\), lower is better). After pivot filtering and scoring, stored values are correlations (higher is better). Check which stage you are reading before interpreting a score.

Matching output¶

matching.csv contains one row per matched pair:

Column	Meaning
`mod1_indx`	Cell index in modality 1
`mod2_indx`	Cell index in modality 2
`score`	Match score (higher is better)

cli analysis matching ./out/<run-dir> --summary