> ## Documentation Index
> Fetch the complete documentation index at: https://proto.evodesign.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# K-mer Frequency
> Evaluate k-mer frequencies or usage deviations with configurable mer length and scoring mode
This constraint is open source. Any third-party models, product names, or trademarks referenced are the property of their respective owners, and Proto is not affiliated with them.
Evaluate k-mer frequencies or usage deviations with configurable mer length and scoring modes.
This constraint function analyzes k-mer (subsequences of length k) composition
in DNA, RNA, or protein sequences using two possible scoring modes:
1. **Frequency mode**: Evaluates raw k-mer frequencies (observed\_count / total\_kmers).
2. **Usage deviation mode**: Evaluates observed/expected ratios using a zero-order
Markov model where expected = product of individual nucleotide/amino acid
frequencies. A ratio of 1.0 indicates observed matches expected composition,
> 1.0 indicates overrepresentation, \<1.0 indicates underrepresentation.
The penalty is the maximum deviation from the \[min\_value, max\_value] band across
observed k-mers; absent k-mers are not penalized. To target a single specific
k-mer (including penalizing its absence), use specific\_kmer\_constraint instead.
## API Reference
Configuration for k-mer frequency constraint.
This class defines configuration parameters for evaluating k-mer composition
in DNA, RNA, or protein sequences. K-mers are subsequences of length k, and
their frequencies can indicate codon bias, tandem repeats, sequence composition
biases, CpG islands, etc. The constraint supports two scoring modes:
frequency-based (direct k-mer counts) and usage deviation (observed vs expected
based on nucleotide/amino acid composition).
**Frequency mode** evaluates raw k-mer proportions (10/100 CG dinucleotides
\= 0.1). Only k-mers that occur in the sequence are scored; absent k-mers
are not penalized.
**Usage deviation mode** compares observed to expected frequencies under
a zero-order Markov model. Expected frequency = product of individual
nucleotide frequencies. For example, if a sequence is 40% G and 60% C,
the expected CG dinucleotide frequency is 0.4 x 0.6 = 0.24. If observed
is 0.12, usage\_deviation = 0.12/0.24 = 0.5 (underrepresented).
The penalty is the maximum deviation across observed k-mers. To evaluate a
single specific k-mer (including penalizing its absence), use
specific\_kmer\_constraint instead.
Length of k-mer to analyze (e.g., 2 for dinucleotide, 3 for trinucleotide).
Scoring metric: 'frequency' uses raw k-mer counts; 'usage\_deviation' uses observed/expected ratios.
Options: `frequency`, `usage_deviation`
Minimum acceptable frequency/deviation based on scoring\_mode
Maximum acceptable frequency/deviation based on scoring\_mode
ReturnsConstraintOutput
One result per sequence. A score of 0.0 indicates
every observed k-mer is within the acceptable range \[min\_value, max\_value].
Higher scores indicate the maximum deviation across observed k-mers. The
penalty scales linearly with deviation distance from the acceptable
range, capped at 1.0. `metadata` carries (over *observed* k-mers only):
**For frequency mode:**
* `{k}mer_frequencies`: Dictionary mapping each observed k-mer to its
frequency (0.0-1.0). For example, `2mer_frequencies` for dinucleotides.
**For usage\_deviation mode:**
* `{k}mer_usage_deviations`: Dictionary mapping each observed k-mer to
its observed/expected ratio
**For sequences too short (\
## Usage
Analyzing codon usage (all trinucleotides):
```python python icon="python" theme={null}
>>> coding_seq = Sequence("ATGAAACGTATTGCGTCG", "dna")
>>> config = KmerFrequencyConfig(
... k=3,
... scoring_mode="usage_deviation",
... min_value=0.5, # Allow some underrepresentation
... max_value=2.0, # Allow some overrepresentation
... )
>>> results = kmer_frequency_constraint([(coding_seq,)], config)
>>> deviations = results[0].metadata["3mer_usage_deviations"]
>>> for codon, ratio in sorted(deviations.items(), key=lambda x: x[1], reverse=True):
... print(f"{codon}: {ratio:.2f}x expected")
```
## Metadata
| Property | Value |
| --------------- | --------------------------- |
| Key | `kmer-frequency` |
| Function | `kmer_frequency_constraint` |
| Category | `sequence_composition` |
| Mode | `discrete` |
| Uses GPU | `False` |
| Supported Types | `dna`, `rna`, `protein` |
evo-design/proto-language/proto\_language/constraint/sequence\_composition/kmer\_frequency\_constraint.py
dguo8412