genevector.aggregation

genevector/_aggregation.py — graph aggregation registry and implementations.

aggr_mean(X_dense, graph, include_self=False, **kwargs)

Mean aggregation over graph neighbors.

Parameters:

• X_dense (np.ndarray) – Expression matrix (cells x genes).

• graph (scipy.sparse matrix) – Adjacency matrix (any graph topology).

• include_self (bool) – If True, blend 50/50 between self and neighbor mean.

Returns:

Aggregated expression, same shape as X_dense.

Return type:

np.ndarray

get_aggregation(name)

Look up a registered aggregation function by name, or return a callable directly.

Parameters:

name (str or callable) – Name of registered aggregation, or a callable with signature f(X_dense, graph, **params) -> np.ndarray.

Returns:

The aggregation function.

Return type:

callable

Raises:

ValueError – If name is a string and not registered.

register_aggregation(name)

Decorator to register an aggregation function.

genevector/_graph_targets.py — graph-aware co-expression targets.

target_graph_cross_mi(X, gene_names, graph=None, aggr='mean', aggr_params=None, n_bins=10, signed=True, backend='auto', device='cpu', **kwargs)

Asymmetric cross-neighbor MI: MI(gene_a in cell, gene_b in neighbors).

Directional spatial signal (e.g. ligand in a cell predicting receptor in its neighbours). Not symmetrized — the model’s separate input/output weights can encode the asymmetry. Encodes niche/communication directionality in the gene embedding. The cross-MI kernel is auto-selected (GPU torch on device="cuda", else the rayon Rust extension if built, else torch CPU, else numpy); force one with backend in {“rust”,”gpu”,”numpy”}.

target_graph_mi(X, gene_names, graph=None, aggr='mean', aggr_params=None, n_bins=10, signed=True, backend='auto', device='cpu', **kwargs)

Symmetric graph mutual information between self and neighbor-aggregated expression.

The MI analogue of graph_xcorr: captures non-linear spatial co-expression while the neighbor aggregation denoises sparse counts. Symmetrized over (i, j). The cross-MI kernel is auto-selected (GPU torch on device="cuda", else the rayon Rust extension if built, else torch CPU, else numpy); force one with backend in {“rust”,”gpu”,”numpy”}.

Returns:

scores[gene_a][gene_b] = signed MI in (roughly) [-log2(n_bins), log2(n_bins)].

Return type:

dict of dict

target_graph_xcorr(X, gene_names, graph=None, aggr='mean', aggr_params=None, **kwargs)

Cross-correlation between self-expression and graph-neighbor-aggregated expression.

Computes bivariate cross-correlation for all gene pairs: for each gene A and gene B, measures the correlation between A’s expression in each cell and B’s aggregated expression in that cell’s graph neighbors. The result is symmetrized.

Parameters:

• X (sparse or dense matrix) – Expression matrix (cells x genes).

• gene_names (list of str) – Gene symbols.

• graph (scipy.sparse matrix) – Adjacency matrix (spatial, TCR, or any graph topology).

• aggr (str or callable) – Aggregation method name or function. Default “mean”.

• aggr_params (dict, optional) – Extra keyword arguments passed to the aggregation function.

Returns:

scores[gene_a][gene_b] = float, cross-correlation in [-1, 1].

Return type:

dict of dict