Transport Results

class champollion.TransportResult(model, x_1, x_2, f, g, prior_cost=None, cost=None, plan=None, modality_1_obs_names=None, modality_2_obs_names=None, modality_1_adata=None, modality_2_adata=None, y_prior_1=None, y_prior_2=None, plan_diagnostics=None)

Bases: object

Result of transporting cells between the two modalities.

A result stores the Sinkhorn potentials and lazily exposes the pairwise cost and transport plan. In dense mode these are torch tensors. In KeOps mode they may be symbolic LazyTensor objects, so use the high-level methods such as transfer_obs(), project(), and top_matches() when possible.

property potentials

Tuple of Sinkhorn potentials (f, g).

property is_symbolic

Whether the transport plan is represented symbolically.

property cost_is_symbolic

Whether the cost object is represented symbolically.

property plan_is_symbolic

Whether the plan object is represented symbolically.

property cost

Pairwise transport cost, computed lazily when needed.

property plan

Transport plan, computed lazily when needed.

clear_cost()

Drop cached cost objects so they can be recomputed later.

clear_plan()

Drop cached plan objects so they can be recomputed later.

materialize_cost(max_entries=900000000)

Return a dense tensor for the pairwise cost.

This explicitly allocates an n_1 by n_2 tensor, even when the result was computed with KeOps. Large materializations are blocked by default.

Parameters:

max_entries – Maximum allowed number of dense matrix entries. Increase this value only when the dense allocation is intentional.

Returns:

Dense pairwise cost matrix.

Return type:

torch.Tensor

materialize_plan(max_entries=900000000)

Return a dense tensor for the transport plan.

Parameters:

max_entries – Maximum allowed number of dense matrix entries. Increase this value only when the dense allocation is intentional.

Returns:

Dense transport plan with total mass close to one.

Return type:

torch.Tensor

transfer_obs(key, source, kind='auto', target_key=None, inplace=False, return_probabilities=False)

Transfer an .obs annotation from one modality to the other.

Categorical annotations are transferred by transporting one-hot class probabilities and taking the argmax. Continuous annotations are transferred by barycentric averaging.

Parameters:

  • key – Observation column to transfer from the source AnnData.

  • source – Source modality name. The target is the other modality.

  • kind – "auto", "categorical", or "continuous".

  • target_key – Column name used when inplace=True. Defaults to f"{key}_champollion".

  • inplace – If True, write the transferred annotation to the target AnnData.

  • return_probabilities – For categorical transfer, return both predictions and class probabilities.

Returns:

Transferred values, or a dictionary with "prediction" and "probabilities" for categorical transfers when requested.

Return type:

pandas.Series or dict

project(rep='X', source=None, target_key=None, inplace=False)

Barycentrically project a source representation onto target cells.

Parameters:

  • rep – Representation in the source AnnData to project.

  • source – Source modality name. The target is the other modality.

  • target_key – Target .obsm key used when inplace=True.

  • inplace – If True, write the projected matrix to target .obsm.

Returns:

Projected representation with one row per target cell.

Return type:

numpy.ndarray

apply(values, source)

Apply the normalized transport plan to arbitrary source values.

Parameters:

  • values – Array-like matrix with one row per source cell.

  • source – Source modality name.

Returns:

Transport-weighted values with one row per target cell.

Return type:

numpy.ndarray

normalized_plan(source)

Return a row-normalized dense plan for source-to-target transfer.

This method requires a dense plan. In KeOps mode, use apply or the higher-level transfer/projection methods instead of calling this directly.

top_matches(source, k=5)

Return top transported source cells for each target cell.

Parameters:

  • source – Source modality name.

  • k – Number of matches per target cell.

Returns:

Target-indexed table with match observation names and normalized weights.

Return type:

pandas.DataFrame