kmers

tangermeme.kmers.gapped_kmers(X: Tensor, scores: Tensor | None = None, min_k: int = 4, max_k: int = 8, max_gap: int = 2, max_len: int = 10, max_gkmers: int = 10, max_pos: int | None = None) → csr_matrix

Extract gapped k-mers from sequences and optionally scores.

This function will extract the gapped k-mers from a set of sequences that are one-hot encoded and optionally scores for each position. Without scores, this function will return a sparse matrix where each row is an example, each column is a gapped k-mer, and the value is the count of that gapped k-mer in the data. With scores, the shape will be the same but the value will be the sum of the scores across positions in the gapped k-mers.

Parameters

X: torch.Tensor, shape=(-1, len(alphabet), sequence_length)

A one-hot encoded set of sequences.

scores: torch.Tensor with shape=(-1, sequence_length) or None, optional

A corresponding set of attribution values to use. If None, return counts instead of sum of attribution values. Default is None.

min_k: int, optional

The minimum number of non-gaps in the k-mer. Default is 4.

max_k: int, optional

The maximum number of non-gaps in the k-mer. Default is 8.

max_gap: int, optional

The maximum number of gaps in the k-mer. Default is 2.

max_len: int, optional

The maximum length of the k-mer, as in, the total number of gaps and non-gap characters. Default is 10.

max_gkmers: int, optional

The maximum number of gapped k-mers to return per example, ranked by absolute score. Any gapped k-mers beyond this cap are silently dropped from the output sparse matrix; raise this if your example may contain more than 10 meaningful gapped k-mers. Default is 10.

max_pos: int or None, optional

If provided, only consider the top max_pos positions per example ranked by score before extracting gapped k-mers. If None, consider all positions. Default is None.

Returns

gkmers: scipy.sparse.csr_matrix

A sparse matrix containing either counts or score sums for each kmer found.

tangermeme.kmers.kmers(X: Tensor, k: int, scores: Tensor | None = None) → csr_matrix

Extract all k-mers found in a sequence, optionally weighted by a score.

This function will count the number of k-mers found in each sequence and return a feature matrix. If score is provided, the counts will be weighted by the sum of the score across the k positions where the k-mer resides. If score is not provided, the count will just be 1 for each instance of the k-mer in the sequence.

Parameters

X: torch.Tensor, shape=(-1, len(alphabet), sequence_length)

A one-hot encoded set of sequences.

k: int

The size of the k-mers to consider.

scores: torch.Tensor, shape=(-1, sequence_length) or None, optional

Per-position scores (e.g., attribution values) to weight each k-mer by. When provided, the value stored for each k-mer is the sum of the scores at the k positions it spans. If None, each k-mer instance contributes a count of 1. Default is None.

Returns

X_kmers: torch.Tensor, shape=(-1, n_kmers)

A featurization where each row is an example from the original set of sequences and each column is a k-mer that could be in the sequence.