moscot.base.output.BaseDiscreteSolverOutput.sparsify

BaseDiscreteSolverOutput.sparsify(mode, value=None, batch_size=1024, n_samples=None, seed=None, max_k=None)[source]

Sparsify the transport_matrix.

This function sets entries of the transport matrix to \(0\) according to mode and returns a MatrixSolverOutput with sparsified transport matrix stored as a csr_matrix. The transport matrix is materialized in row blocks of batch_size rows; outputs that can build rows directly - ott Sinkhorn, Gromov-Wasserstein/fused Gromov-Wasserstein, their low-rank counterparts, and already materialized matrices - never hold more than [batch_size, m] at a time. Other outputs fall back to pushing indicator columns, whose cost depends on the output’s push().

Rows carrying no mass keep no entries and take no part in choosing a threshold, whichever mode is used - no threshold can make them non-empty, and letting them take part would drag the threshold down to \(0\). A warning is emitted when any are present, since the result then cannot be normalized into a Markov transition matrix.

Warning

This function only serves for interfacing software which has to instantiate the transport matrix, moscot never uses the sparsified transport matrix.

Parameters:

  • mode (Literal['threshold', 'percentile', 'min_row', 'mass']) –

    How to determine the entries that are set to \(0\). Valid options are:

    • ’threshold’ - value is the threshold below which entries are set to \(0\).

    • ’percentile’ - value is the percentile in \([0, 100]\) of the transport_matrix. below which entries are set to \(0\), estimated from n_samples randomly sampled rows.

    • ’min_row’ - value is not used, it is set to min_i max_j T_ij, the largest threshold for which every row keeps at least 1 non-zero entry. It does not depend on batch_size; the rows are materialized twice, once for the threshold and once for the values.

    • ’mass’ - per row, keep the largest entries capturing a fraction value of the row’s mass (at most max_k entries per row); value must be in \((0, 1]\).

  • value (Optional[float]) – Value to use for sparsification. Its meaning depends on mode (see above).

  • batch_size (int) – How many rows to materialize at a time when sparsifying the transport_matrix.

  • n_samples (Optional[int]) – If mode = 'percentile', the number of rows sampled to estimate the percentile stochastically. Note this means that a matrix of shape [n_samples, m] has to be instantiated. If None, n_samples is set to batch_size.

  • seed (Optional[int]) – Random seed needed for sampling if mode = 'percentile'.

  • max_k (Optional[int]) – Maximum number of entries to keep per row. Only valid when mode = 'mass'.

Return type:

MatrixSolverOutput

Returns:

: Output with sparsified transport matrix.