README.md

---
datasets:
- multimolecule/ena
library_name: multimolecule
license: agpl-3.0
mask_token: <mask>
pipeline_tag: fill-mask
tags:
- Biology
- DNA
- cDNA
- dna
widget:
- example_title: tumor protein p53
  mask_index: 15
  mask_index_1based: 16
  masked_char: A
  output:
  - label: GCC
    score: 0.032617
  - label: CCC
    score: 0.029804
  - label: TCC
    score: 0.027406
  - label: AGC
    score: 0.02203
  - label: GGC
    score: 0.021305
  pipeline_tag: fill-mask
  sequence_type: DNA
  task: fill-mask
  text: ACTCCCCTGCCCTCA<mask>AGATGTTTTGCCAACTGGCCAAGACCTGCCCTGTGCAGCTGTGGGTTGATTCCACACCCCCGCCCGGCACCCGCGTCCGCGCCATGGCCATCTACAAGCAGTCACAGCACATGACGGAGGTTGTGAGGCGCTGCCCCCACCATGAGCGCTGCTCAGATAGCGATG
- example_title: BRCA1 DNA repair associated
  mask_index: 12
  mask_index_1based: 13
  masked_char: A
  output:
  - label: ATT
    score: 0.040768
  - label: TTT
    score: 0.035795
  - label: TTA
    score: 0.035687
  - label: AAA
    score: 0.031899
  - label: GAA
    score: 0.025676
  pipeline_tag: fill-mask
  sequence_type: DNA
  task: fill-mask
  text: TCATTGGAACAG<mask>GAAATGGATTTATCTGCTCTTCGCGTTGAAGAAGTACAAAATGTCATTAATGCTATGCAGAAAATCTTAGAGTGTCCCATCTGG
- example_title: hemoglobin subunit beta
  mask_index: 12
  mask_index_1based: 13
  masked_char: A
  output:
  - label: CTG
    score: 0.034383
  - label: CAG
    score: 0.027415
  - label: CTT
    score: 0.020351
  - label: AAG
    score: 0.015547
  - label: GAG
    score: 0.015124
  pipeline_tag: fill-mask
  sequence_type: DNA
  task: fill-mask
  text: CATTTGCTTCTG<mask>CAACTGTGTTCACTAGCAACCTCAAACAGACACCATGGTGCATCTGACTCCTGAGGAGAAGTCTGCCGTTACTGCCCTGTGGGGCAAGGTGAACGTGGATGAAGTTGGTGGTGAGGCCCTGGGCAG
- example_title: CF transmembrane conductance regulator
  mask_index: 12
  mask_index_1based: 13
  masked_char: A
  output:
  - label: GAA
    score: 0.030003
  - label: AAA
    score: 0.029599
  - label: GAT
    score: 0.026906
  - label: AAT
    score: 0.025006
  - label: AAG
    score: 0.023527
  pipeline_tag: fill-mask
  sequence_type: DNA
  task: fill-mask
  text: ACTTCACTTCTA<mask>GTGATTATGGGAGAACTGGAGCCTTCAGAGGGTAAAATTAAGCACAGTGGAAGAATTTCATTCTGTTCTCAGTTTTCCTGGATTATGCCTGGCACCATTAAAGAAAATATCATCTTTGGTGTTTCCTATGATGAATATAGATACAGAAGCGTCATCAAAGCATGCCAACTAGAAGAG
- example_title: telomerase reverse transcriptase
  mask_index: 60
  mask_index_1based: 61
  masked_char: A
  output:
  - label: GGG
    score: 0.098828
  - label: GGC
    score: 0.091279
  - label: GCG
    score: 0.049364
  - label: GCC
    score: 0.039628
  - label: GAG
    score: 0.036577
  pipeline_tag: fill-mask
  sequence_type: DNA
  task: fill-mask
  text: CGCGGGGGTGGCCGGGGCCAGGGCTTCCCACGTGCGCAGCAGGACGCAGCGCTGCCTGAA<mask>CGCGCCGCGAGGAGAGGGCGGGGCCGCGGAAAGGAAGGGGAGGGGCTGGGAGGGCCCGGAGGGGGCTGGGCCGGGGACCCGGGAGGGGTCGGGACGGGGCGGGGTCCGCGCGGAGGAGGCGGAGCTGGAAGGTGAAGGGGCAGGACGGGTGCCCGGGTCCCCAGTCCCTCCGCCACGTGGGAAGCGCGGTCCTGGGCGTCTGTGCCCGCGAATCCACTGGGAGCCCGGCCTGGCCCCGACAGCGCAGCTGCTCCGGGCGGACCCGGG
- example_title: KRAS proto-oncogene
  mask_index: 18
  mask_index_1based: 19
  masked_char: A
  output:
  - label: GAA
    score: 0.019936
  - label: GAG
    score: 0.01979
  - label: AAG
    score: 0.0175
  - label: AAA
    score: 0.016498
  - label: TGG
    score: 0.015715
  pipeline_tag: fill-mask
  sequence_type: DNA
  task: fill-mask
  text: GCCTGCTGAAAATGACTG<mask>ATAAACTTGTGGTAGTTGGAGCTGGTGGCGTAGGCAAGAGTGCCTTGACGATACAGCTAATTCAGAATCATTTTGTGGACGAATATGATCCAACAATAG
- example_title: prion protein (Kanno blood group)
  mask_index: 21
  mask_index_1based: 22
  masked_char: A
  output:
  - label: CTG
    score: 0.032616
  - label: CTT
    score: 0.017547
  - label: GTG
    score: 0.017529
  - label: CTC
    score: 0.017386
  - label: GCT
    score: 0.017019
  pipeline_tag: fill-mask
  sequence_type: cDNA
  task: fill-mask
  text: ATGGCGAACCTTGGCTGCTGG<mask>CTGGTTCTCTTTGTGGCCACATGGAGTGACCTGGGCCTCTGC
- example_title: interleukin 10
  mask_index: 39
  mask_index_1based: 40
  masked_char: A
  output:
  - label: CTG
    score: 0.04454
  - label: GCT
    score: 0.030566
  - label: CAG
    score: 0.02417
  - label: GAG
    score: 0.023355
  - label: GTG
    score: 0.023244
  pipeline_tag: fill-mask
  sequence_type: cDNA
  task: fill-mask
  text: ATGCACAGCTCAGCACTGCTCTGTTGCCTGGTCCTCCTG<mask>GGGGTGAGGGCC
- example_title: Zaire ebolavirus
  mask_index: 45
  mask_index_1based: 46
  masked_char: A
  output:
  - label: GAA
    score: 0.039255
  - label: GAT
    score: 0.038116
  - label: AAA
    score: 0.035714
  - label: GTT
    score: 0.032169
  - label: ATT
    score: 0.031362
  pipeline_tag: fill-mask
  sequence_type: cDNA
  task: fill-mask
  text: AATGTTCAAACACTTTGTGAAGCTCTGTTAGCTGATGGTCTTGCT<mask>GCATTTCCTAGCAATATGATGGTAGTCACAGAGCGTGAGCAAAAAGAAAGCTTATTGCATCAAGCATCATGGCACCACACAAGTGATGATTTTGGTGAGCATGCCACAGTTAGAGGGAGTAGCTTTGTAACTGATTTAGAGAAATACAATCTTGCATTTAGATATGAGTTTACAGCACCTTTTATAGAATATTGTAACCGTTGCTATGGTGTTAAGAATGTTTTTAATTGGATGCATTATACAATCCCACAGTGTTAT
- example_title: SARS coronavirus
  mask_index: 24
  mask_index_1based: 25
  masked_char: A
  output:
  - label: TCT
    score: 0.041331
  - label: TTT
    score: 0.035835
  - label: TCA
    score: 0.033734
  - label: TTA
    score: 0.033474
  - label: ATT
    score: 0.031609
  pipeline_tag: fill-mask
  sequence_type: cDNA
  task: fill-mask
  text: ATGTTTATTTTCTTATTATTTCTT<mask>CTCACTAGTGGTAGTGACCTTGACCGGTGCACCACTTTTGATGATGTTCAAGCTCCTAATTACACTCAACATACTTCATCTATGAGGGGGGTTTACTATCCTGATGAAATTTTTAGATCAGACACTCTTTATTTAACTCAGGATTTATTTCTTCCATTTTATTCTAATGTTACAGGGTTTCATACTATTAATCATACGTTTGACAACCCTGTCATACCTTTTAAGGATGGTATTTATTTTGCTGCCACAGAGAAATCAAATGTTGTCCGTGGTTGGGTTTTTGGTTCTACCATGAACAACAAGTCACAGTCGGTGATTATTATTAACAATTCTACTAATGTTGTTATACGAGCATGTAACTTTGAATTGTGTGACAACCCTTTCTTTGCTGTTTCTAAACCCATGGGTACACAGACACATACTATGATATTCGATAATGCATTTAAATGCACTTTCGAGTACATATCT
- example_title: insulin
  mask_index: 12
  mask_index_1based: 13
  masked_char: A
  output:
  - label: CCC
    score: 0.167264
  - label: CTG
    score: 0.064332
  - label: GCC
    score: 0.043857
  - label: GGC
    score: 0.042804
  - label: CTC
    score: 0.04177
  pipeline_tag: fill-mask
  sequence_type: cDNA
  task: fill-mask
  text: ATGGCCCTGTGG<mask>CGCCTCCTGCCCCTGCTGGCGCTGCTGGCCCTCTGGGGACCTGACCCAGCCGCAGCCTTTGTGAACCAACACCTGTGCGGCTCACACCTGGTGGAAGCTCTCTACCTAGTGTGCGGGGAACGAGGCTTCTTCTACACACCCAAGACCCGCCGGGAGGCAGAGGACCTGCAGGTGGGGCAGGTGGAGCTGGGCGGGGGCCCTGGTGCAGGCAGCCTGCAGCCCTTGGCCCTGGAGGGGTCCCTGCAGAAGCGTGGCATTGTGGAACAATGCTGTACCAGCATCTGCTCCCTCTACCAGCTGGAGAACTACTGCAACTAG
- example_title: cyclin dependent kinase inhibitor 2A
  mask_index: 18
  mask_index_1based: 19
  masked_char: A
  output:
  - label: CCC
    score: 0.084286
  - label: CCG
    score: 0.065236
  - label: GGC
    score: 0.044583
  - label: GCC
    score: 0.037446
  - label: CTG
    score: 0.03396
  pipeline_tag: fill-mask
  sequence_type: cDNA
  task: fill-mask
  text: ATGGAGCCGGCGGCGGGG<mask>AGCATGGAGCCTTCGGCTGACTGGCTGGCCACGGCCGCGGCCCGGGGTCGGGTAGAGGAGGTGCGGGCGCTGCTGGAGGCGGGGGCGCTGCCCAACGCACCGAATAGTTACGGTCGGAGGCCGATCCAGGTCATGATGATGGGCAGCGCCCGAGTGGCGGAGCTGCTGCTGCTCCACGGCGCGGAGCCCAACTGCGCCGACCCCGCCACTCTCACCCGACCCGTGCACGACGCTGCCCGGGAGGGCTTCCTGGACACGCTGGTGGTGCTGCACCGGGCCGGGGCGCGGCTGGACGTGCGCGATGCCTGGGGCCGTCTGCCCGTGGACCTGGCTGAGGAGCTGGGCCATCGCGATGTCGCACGGTACCTGCGCGCGGCTGCGGGGGGCACCAGAGGCAGTAACCATGCCCGCATAGATGCCGCGGAAGGTCCCTCAGACATCCCCGATTGA
- example_title: human papillomavirus type 16 E6
  mask_index: 12
  mask_index_1based: 13
  masked_char: A
  output:
  - label: ATA
    score: 0.030003
  - label: AAA
    score: 0.028509
  - label: TGT
    score: 0.025889
  - label: TTA
    score: 0.024819
  - label: ATT
    score: 0.021249
  pipeline_tag: fill-mask
  sequence_type: cDNA
  task: fill-mask
  text: ATGCACCAAAAG<mask>ACTGCAATGTTTCAGGACCCACAGGAGCGACCCAGAAAGTTACCACAGTTATGCACAGAGCTGCAAACAACTATACATGATATAATATTAGAATGTGTGTACTGCAAGCAACAGTTACTGCGACGTGAGGTATATGACTTTGCTTTTCGGGATTTATGCATAGTATATAGAGATGGGAATCCATATGCTGTATGTGATAAATGTTTAAAGTTTTATTCTAAAATTAGTGAGTATAGACATTATTGTTATAGTTTGTATGGAACAACATTAGAACAGCAATACAACAAACCGTTGTGTGATTTGTTAATTAGGTGTATTAACTGTCAAAAGCCACTGTGTCCTGAAGAAAAGCAAAGACATCTGGACAAAAAGCAAAGATTCCATAATATAAGGGGTCGGTGGACCGGTCGATGTATGTCTTGTTGCAGATCATCAAGAACACGTAGAGAAACCCAGCTGTAA
---

# CaLM

Pre-trained model on protein-coding DNA (cDNA) using a masked language modeling (MLM) objective.

## Statement

_Codon language embeddings provide strong signals for use in protein engineering_ is published in [Nature Machine Intelligence](https://doi.org/10.1038/s42256-024-00791-0), which is a Closed Access / Author-Fee journal.

> Machine learning has been at the forefront of the movement for free and open access to research.
>
> We see no role for closed access or author-fee publication in the future of machine learning research and believe the adoption of these journals as an outlet of record for the machine learning community would be a retrograde step.

The MultiMolecule team is committed to the principles of open access and open science.

We do NOT endorse the publication of manuscripts in Closed Access / Author-Fee journals and encourage the community to support Open Access journals and conferences.

Please consider signing the [Statement on Nature Machine Intelligence](https://openaccess.engineering.oregonstate.edu).

## Disclaimer

This is an UNOFFICIAL implementation of the [Codon language embeddings provide strong signals for use in protein engineering](https://doi.org/10.1101/2022.12.15.519894) by Carlos Outeiral, et al.

The OFFICIAL repository of CaLM is at [oxpig/CaLM](https://github.com/oxpig/CaLM).

> [!WARNING]
> The MultiMolecule team is unable to confirm that the provided model and checkpoints are producing the same intermediate representations as the original implementation.
> This is because
>
> The proposed method is published in a Closed Access / Author-Fee journal.

**The team releasing CaLM did not write this model card for this model so this model card has been written by the MultiMolecule team.**

## Model Details

CaLM is a [bert](https://huggingface.co/google-bert/bert-base-uncased)-style model pre-trained on a large corpus of protein-coding DNA sequences in a self-supervised fashion. This means that the model was trained on the raw nucleotides of DNA sequences only, with an automatic process to generate inputs and labels from those texts. Please refer to the [Training Details](#training-details) section for more information on the training process.

### Model Specification

| Num Layers | Hidden Size | Num Heads | Intermediate Size | Num Parameters (M) | FLOPs (G) | MACs (G) | Max Num Tokens |
| ---------- | ----------- | --------- | ----------------- | ------------------ | --------- | -------- | -------------- |
| 12         | 768         | 12        | 3072              | 85.75              | 96.86     | 48.32    | 1024           |

### Links

- **Code**: [multimolecule.calm](https://github.com/DLS5-Omics/multimolecule/tree/master/multimolecule/models/calm)
- **Weights**: [multimolecule/calm](https://huggingface.co/multimolecule/calm)
- **Data**: [European Nucleotide Archive](https://ebi.ac.uk/ena)
- **Paper**: [Codon language embeddings provide strong signals for use in protein engineering](https://doi.org/10.1101/2022.12.15.519894)
- **Developed by**: Carlos Outeiral, Charlotte M. Deane
- **Model type**: [BERT](https://huggingface.co/google-bert/bert-base-uncased) - [ESM](https://huggingface.co/facebook/esm2_t48_15B_UR50D)
- **Original Repository**: [oxpig/CaLM](https://github.com/oxpig/CaLM)

## Usage

The model file depends on the [`multimolecule`](https://multimolecule.danling.org) library. You can install it using pip:

```bash
pip install multimolecule
```

### Direct Use

#### Masked Language Modeling

You can use this model directly with a pipeline for masked language modeling:

```python
import multimolecule  # you must import multimolecule to register models
from transformers import pipeline

predictor = pipeline("fill-mask", model="multimolecule/calm")
output = predictor("agc<mask>cattatggcgaaccttggctgctg")
```

### Downstream Use

#### Extract Features

Here is how to use this model to get the features of a given sequence in PyTorch:

```python
from multimolecule import DnaTokenizer, CaLmModel


tokenizer = DnaTokenizer.from_pretrained("multimolecule/calm")
model = CaLmModel.from_pretrained("multimolecule/calm")

text = "GCCAGTCGCTGACAGCCGCGG"
input = tokenizer(text, return_tensors="pt")

output = model(**input)
```

#### Sequence Classification / Regression

> [!NOTE]
> This model is not fine-tuned for any specific task. You will need to fine-tune the model on a downstream task to use it for sequence classification or regression.

Here is how to use this model as backbone to fine-tune for a sequence-level task in PyTorch:

```python
import torch
from multimolecule import DnaTokenizer, CaLmForSequencePrediction


tokenizer = DnaTokenizer.from_pretrained("multimolecule/calm")
model = CaLmForSequencePrediction.from_pretrained("multimolecule/calm")

text = "GCCAGTCGCTGACAGCCGCGG"
input = tokenizer(text, return_tensors="pt")
label = torch.tensor([1])

output = model(**input, labels=label)
```

#### Token Classification / Regression

> [!NOTE]
> This model is not fine-tuned for any specific task. You will need to fine-tune the model on a downstream task to use it for token classification or regression.

Here is how to use this model as backbone to fine-tune for a nucleotide-level task in PyTorch:

```python
import torch
from multimolecule import DnaTokenizer, CaLmForTokenPrediction


tokenizer = DnaTokenizer.from_pretrained("multimolecule/calm")
model = CaLmForTokenPrediction.from_pretrained("multimolecule/calm")

text = "GCCAGTCGCTGACAGCCGCGG"
input = tokenizer(text, return_tensors="pt")
label = torch.randint(2, (len(text), ))

output = model(**input, labels=label)
```

#### Contact Classification / Regression

> [!NOTE]
> This model is not fine-tuned for any specific task. You will need to fine-tune the model on a downstream task to use it for contact classification or regression.

Here is how to use this model as backbone to fine-tune for a contact-level task in PyTorch:

```python
import torch
from multimolecule import DnaTokenizer, CaLmForContactPrediction


tokenizer = DnaTokenizer.from_pretrained("multimolecule/calm")
model = CaLmForContactPrediction.from_pretrained("multimolecule/calm")

text = "GCCAGTCGCTGACAGCCGCGG"
input = tokenizer(text, return_tensors="pt")
label = torch.randint(2, (len(text), len(text)))

output = model(**input, labels=label)
```

## Training Details

CaLM used Masked Language Modeling (MLM) as the pre-training objective: taking a sequence, the model randomly masks 25% of the tokens in the input then runs the entire masked sentence through the model and has to predict the masked tokens. This is comparable to the Cloze task in language modeling.

### Training Data

The CaLM model was pre-trained coding sequences of all organisms available on the [European Nucleotide Archive (ENA)](https://ebi.ac.uk/ena). European Nucleotide Archive provides a comprehensive record of the world’s nucleotide sequencing information, covering raw sequencing data, sequence assembly information and functional annotation.

CaLM collected coding sequences of all organisms from ENA on April 2022, including 114,214,475 sequences. Only high level assembly information (dataclass CON) were used. Sequences matching the following criteria were filtered out:

- Unknown nucleotides: remove sequences with `N`, `Y`, or `R`
- Start codon: require `ATG`
- Stop codons: remove sequences with interstitial stop codons
- Sequence length: require a multiple of three nucleotides

To reduce redundancy, CaLM grouped the entries by organism, and apply CD-HIT (CD-HIT-EST) with a cut-off at 40% sequence identity to the translated protein sequences.

The final dataset contains 9,858,385 cDNA sequences.

The original checkpoint uses RNA codon spelling internally, but MultiMolecule converts the checkpoint to DNA codon order and exposes CaLM with [`DnaTokenizer`][multimolecule.DnaTokenizer]. `DnaTokenizer` will convert "U"s to "T"s by default; you may disable this behaviour by passing `replace_U_with_T=False`.

### Training Procedure

#### Preprocessing

CaLM used masked language modeling (MLM) as the pre-training objective. The masking procedure is similar to the one used in BERT:

- Mask rate: 25%
- Replacement: `<mask>` for 80% of masked tokens
- Replacement: random token for 10% of masked tokens
- Replacement: unchanged token for 10% of masked tokens

#### Pre-training

The model was trained on 4 NVIDIA Quadro RTX4000 GPUs with 8GiB memories.

- Batch Size: 1,000
- Epochs: 14
- Optimizer: AdamW
- Learning rate: 1e-4
- Learning rate scheduler: Cosine
- Learning rate warm-up: 1,000 steps

## Citation

```bibtex
@article {outeiral2022coodn,
	author = {Outeiral, Carlos and Deane, Charlotte M.},
	title = {Codon language embeddings provide strong signals for protein engineering},
	elocation-id = {2022.12.15.519894},
	year = {2022},
	doi = {10.1101/2022.12.15.519894},
	publisher = {Cold Spring Harbor Laboratory},
	abstract = {Protein representations from deep language models have yielded state-of-the-art performance across many tasks in computational protein engineering. In recent years, progress has primarily focused on parameter count, with recent models{\textquoteright} capacities surpassing the size of the very datasets they were trained on. Here, we propose an alternative direction. We show that large language models trained on codons, instead of amino acid sequences, provide high-quality representations that outperform comparable state-of-the-art models across a variety of tasks. In some tasks, like species recognition, prediction of protein and transcript abundance, or melting point estimation, we show that a language model trained on codons outperforms every other published protein language model, including some that contain over 50 times more parameters. These results suggest that, in addition to commonly studied scale and model complexity, the information content of biological data provides an orthogonal direction to improve the power of machine learning in biology.Competing Interest StatementThe authors have declared no competing interest.},
	URL = {https://www.biorxiv.org/content/early/2022/12/19/2022.12.15.519894},
	eprint = {https://www.biorxiv.org/content/early/2022/12/19/2022.12.15.519894.full.pdf},
	journal = {bioRxiv}
}
```

> [!NOTE]
> The artifacts distributed in this repository are part of the MultiMolecule project.
> If MultiMolecule supports your research, please cite the MultiMolecule project as follows:

```bibtex
@software{chen_2024_12638419,
  author    = {Chen, Zhiyuan and Zhu, Sophia Y.},
  title     = {MultiMolecule},
  doi       = {10.5281/zenodo.12638419},
  publisher = {Zenodo},
  url       = {https://doi.org/10.5281/zenodo.12638419},
  year      = 2024,
  month     = may,
  day       = 4
}
```

## Contact

Please use GitHub issues of [MultiMolecule](https://github.com/DLS5-Omics/multimolecule/issues) for any questions or comments on the model card.

Please contact the authors of the [CaLM paper](https://doi.org/10.1101/2022.12.15.519894) for questions or comments on the paper/model.

## License

This model implementation is licensed under the [GNU Affero General Public License](license.md).

For additional terms and clarifications, please refer to our [License FAQ](license-faq.md).

```spdx
SPDX-License-Identifier: AGPL-3.0-or-later
```