> ## 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.

# Dinucleotide Composition

> Match a sequence's dinucleotide-frequency distribution to a reference composition profile.

<div class="page-hero">
  <img class="page-hero-banner" src="https://proto-bio.github.io/proto-assets/images/constraint/dinucleotide-composition/hero.png" alt="Dinucleotide Composition" />
</div>

<p class="entity-disclaimer">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.</p>

<hr class="entity-rule" />

<div class="tool-tab-bar entity-source-bar"><span class="tool-tab-wrap"><span class="tool-tab badge-source entity-source-tab"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="16 18 22 12 16 6" /><polyline points="8 6 2 12 8 18" /></svg> Source</span></span></div>

<a href="https://github.com/evo-design/proto-language/blob/d3b7822f74ea64747cc751a3b2ab1aa6b799ac47/proto_language/constraint/sequence_composition/dinucleotide_composition_constraint.py#L137" target="_blank" class="tab-panel source-panel entity-source-panel">
  <div class="source-info">
    <img noZoom src="https://github.com/evo-design.png?size=40" class="source-avatar" width="36" height="36" />

    <span class="source-path">evo-design/proto-language<span class="source-subpath">/proto\_language/constraint/sequence\_composition/dinucleotide\_composition\_constraint.py</span></span>
  </div>

  <span class="panel-goto-btn source-goto-btn"><span><svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0C5.37 0 0 5.37 0 12c0 5.31 3.435 9.795 8.205 11.385.6.105.825-.255.825-.57 0-.285-.015-1.23-.015-2.235-3.015.555-3.795-.735-4.035-1.41-.135-.345-.72-1.41-1.23-1.695-.42-.225-1.02-.78-.015-.795.945-.015 1.62.87 1.845 1.23 1.08 1.815 2.805 1.305 3.495.99.105-.78.42-1.305.765-1.605-2.67-.3-5.46-1.335-5.46-5.925 0-1.305.465-2.385 1.23-3.225-.12-.3-.54-1.53.12-3.18 0 0 1.005-.315 3.3 1.23.96-.27 1.98-.405 3-.405s2.04.135 3 .405c2.295-1.56 3.3-1.23 3.3-1.23.66 1.65.24 2.88.12 3.18.765.84 1.23 1.905 1.23 3.225 0 4.605-2.805 5.625-5.475 5.925.435.375.81 1.095.81 2.22 0 1.605-.015 2.895-.015 3.3 0 .315.225.69.825.57A12.02 12.02 0 0024 12c0-6.63-5.37-12-12-12z" /></svg> View source</span></span>
</a>

<div class="entity-contributors"><span class="entity-contributors-label">Constraint contributors</span><span class="entity-contributors-people"><a class="entity-contributor" href="https://github.com/adititm" target="_blank" rel="noopener" title="adititm: 3 commits"><img noZoom class="entity-contributor-avatar" src="https://avatars.githubusercontent.com/u/61667248?v=4&s=64" alt="" loading="lazy" /><span class="entity-contributor-login">adititm</span></a></span></div>
Score the distance between observed and reference dinucleotide composition.

The observed overlapping-dinucleotide frequency distribution of each sequence
is compared to `config.reference_frequencies` using the configured distance
metric. Lower scores mean the sequence's nucleotide-pair usage is closer to the
reference (natural) composition.

## API Reference

<div class="api-model-section api-model-static api-config-section">
  <div class="api-model-header"><span class="api-model-badge api-config-badge">Config</span><span class="api-model-name">DinucleotideCompositionConfig</span><a href="https://github.com/evo-design/proto-language/blob/d3b7822f74ea64747cc751a3b2ab1aa6b799ac47/proto_language/constraint/sequence_composition/dinucleotide_composition_constraint.py#L37" target="_blank" class="func-table-btn func-source-btn api-model-source"><svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="16 18 22 12 16 6" /><polyline points="8 6 2 12 8 18" /></svg> Source</a></div>

  Configuration for the dinucleotide-composition match constraint.

  Scores the distance between a sequence's observed dinucleotide-frequency
  distribution and a reference distribution. The reference is supplied as a
  mapping of dinucleotide -> frequency (e.g. derived from natural sequences);
  RNA (`U`) keys are folded onto the DNA alphabet (`T`) and the reference is
  renormalized to sum to 1.

  <ParamField path="reference_frequencies" type="object" required>
    Target dinucleotide -> frequency mapping (natural composition profile).
  </ParamField>

  <ParamField path="distance_metric" type="enum" default="total_variation">
    Distribution distance: 'total\_variation' (0.5\*sum|p-q|) or normalized 'l2'.

    Options: `total_variation`, `l2`
  </ParamField>

  <ParamField path="scale" type="number" default="1.0">
    Multiplier applied to the raw distance before clamping to \[0, 1].
  </ParamField>
</div>

<div class="api-model-section api-model-static api-output-section">
  <div class="api-model-header"><span class="api-model-badge api-output-badge">Returns</span><span class="api-model-name">ConstraintOutput</span></div>

  One result per sequence. `score` is in `[0, 1]`
  (0.0 = observed composition matches the reference). `metadata` carries
  `dinucleotide_distance` (the raw, pre-scale distance) and
  `dinucleotide_frequencies` (the observed distribution, or `None` when
  the sequence is too short).
</div>

## Usage

```python python icon="python" theme={null}
>>> from proto_language.core import Sequence
>>> ref = {"AT": 0.6, "TA": 0.4}  # matches "ATATAT" exactly -> perfect score
>>> cfg = DinucleotideCompositionConfig(reference_frequencies=ref)
>>> out = dinucleotide_composition_constraint([(Sequence("ATATAT", "dna"),)], cfg)
>>> round(out[0].score, 3)
0.0
```

## Metadata

| Property        | Value                                 |
| --------------- | ------------------------------------- |
| Key             | `dinucleotide-composition`            |
| Function        | `dinucleotide_composition_constraint` |
| Category        | `sequence_composition`                |
| Mode            | `discrete`                            |
| Uses GPU        | `False`                               |
| Supported Types | `dna`, `rna`                          |