smftools.tools.tensor_factorization

smftools.tools.tensor_factorization#

Functions

build_sequence_one_hot_and_mask(...[, ...])

Build one-hot encoded reads and a seen/unseen mask.

calculate_sequence_cp_decomposition(adata, ...)

Compute CP decomposition on one-hot encoded sequence data with masking.
smftools.tools.tensor_factorization.build_sequence_one_hot_and_mask(encoded_sequences, *, bases=('A', 'C', 'G', 'T'), dtype=<class 'numpy.float32'>)#

Build one-hot encoded reads and a seen/unseen mask.

Parameters:

  • encoded_sequences (ndarray) -- Integer-encoded sequences shaped (n_reads, seq_len).

  • bases (Sequence[str] (default: ('A', 'C', 'G', 'T'))) -- Bases to one-hot encode.

  • dtype (dtype | type[floating] (default: <class 'numpy.float32'>)) -- Output dtype for the one-hot tensor.

Returns:

  • one_hot_tensor: (n_reads, seq_len, n_bases)

  • mask: (n_reads, seq_len) boolean array indicating seen bases.

Return type:

Tuple of (one_hot_tensor, mask) where

smftools.tools.tensor_factorization.calculate_sequence_cp_decomposition(adata, *, layer, var_mask=None, var_mask_name=None, rank=5, n_iter_max=100, random_state=0, overwrite=True, embedding_key='X_cp_sequence', components_key='H_cp_sequence', uns_key='cp_sequence', bases=('A', 'C', 'G', 'T'), backend='pytorch', show_progress=False, init='random', non_negative=False)#

Compute CP decomposition on one-hot encoded sequence data with masking.

Parameters:

  • adata (AnnData) -- AnnData object to update.

  • layer (str) -- Layer name containing integer-encoded sequences.

  • var_mask (ndarray | None (default: None)) -- Optional boolean mask over variables to include in the CP fit.

  • var_mask_name (str | None (default: None)) -- Optional label describing the provided var_mask.

  • rank (int (default: 5)) -- CP rank.

  • n_iter_max (int (default: 100)) -- Maximum number of iterations for the solver.

  • random_state (int (default: 0)) -- Random seed for initialization.

  • overwrite (bool (default: True)) -- Whether to recompute if the embedding already exists.

  • embedding_key (str (default: 'X_cp_sequence')) -- Key for embedding in adata.obsm.

  • components_key (str (default: 'H_cp_sequence')) -- Key for position factors in adata.varm.

  • uns_key (str (default: 'cp_sequence')) -- Key for metadata stored in adata.uns.

  • bases (Iterable[str] (default: ('A', 'C', 'G', 'T'))) -- Bases to one-hot encode (in order).

  • backend (str (default: 'pytorch')) -- Tensorly backend to use (numpy or pytorch).

  • show_progress (bool (default: False)) -- Whether to display progress during factorization if supported.

  • non_negative (bool (default: False)) -- Whether to request a non-negative CP decomposition.

Return type:

AnnData

Returns:

Updated AnnData object containing the CP decomposition outputs.