update readme

README.md

@@ -4,52 +4,94 @@ tags:
 - human_genome
 ---
 
-# WARNING
+# GENA-LM (gena-lm-bigbird-base-sparse-t2t)
 
-This readme should be changed according to current model. Num steps: 800000
+GENA-LM is a Family of Open-Source Foundational Models for Long DNA Sequences.
 
-# GENA-LM
+GENA-LM models are transformer masked language models trained on human DNA sequence. 
 
-GENA-LM is a transformer masked language model trained on human DNA sequence.
+`gena-lm-bigbird-base-sparse-t2t` follows the BigBird architecture and uses sparse attention from DeepSpeed.
 
-Differences between GENA-LM and DNABERT:
+Differences between GENA-LM (`gena-lm-bigbird-base-sparse-t2t`) and DNABERT:
 - BPE tokenization instead of k-mers;
-- input sequence size is about 3000 nucleotides (512 BPE tokens) compared to 510 nucleotides of DNABERT
+- input sequence size is about 36000 nucleotides (4096 BPE tokens) compared to 512 nucleotides of DNABERT;
 - pre-training on T2T vs. GRCh38.p13 human genome assembly.
 
 Source code and data: https://github.com/AIRI-Institute/GENA_LM
 
-## Examples
-### How to load the model to fine-tune it on classification task
-```python
-from src.gena_lm.modeling_bert import BertForSequenceClassification
-from transformers import AutoTokenizer
+Paper: https://www.biorxiv.org/content/10.1101/2023.06.12.544594v1
 
-tokenizer = AutoTokenizer.from_pretrained('AIRI-Institute/gena-lm-bert-base')
-model = BertForSequenceClassification.from_pretrained('AIRI-Institute/gena-lm-bert-base')
+## Installation
+`gena-lm-bigbird-base-sparse-t2t` sparse ops require DeepSpeed.
+
+### DeepSpeed
+DeepSpeed installation is needed to work with SparseAttention versions of language models. DeepSpeed Sparse attention supports only GPUs with compute compatibility >= 7 (V100, T4, A100).
+```bash
+pip install triton==1.0.0
+DS_BUILD_SPARSE_ATTN=1 pip install deepspeed==0.6.0 --global-option="build_ext" --global-option="-j8" --no-cache
+```
+and check installation with
+```bash
+ds_report
 ```
 
-## Model description
-GENA-LM model is trained in a masked language model (MLM) fashion, following the methods proposed in the BigBird paper by masking 85% of tokens. Model config for `gena-lm-bert-base` is similar to the bert-base:
+### APEX for FP16
+Install APEX https://github.com/NVIDIA/apex#quick-start
+```
+git clone https://github.com/NVIDIA/apex
+cd apex
+pip install -v --disable-pip-version-check --no-cache-dir --global-option="--cpp_ext" --global-option="--cuda_ext" ./
+```
 
-- 512 Maximum sequence length
-- 12 Layers, 12 Attention heads
-- 768 Hidden size
-- 32k Vocabulary size
+## Examples
 
-We pre-trained `gena-lm-bert-base` using the latest T2T human genome assembly (https://www.ncbi.nlm.nih.gov/assembly/GCA_009914755.3/). Pre-training was performed for 500,000 iterations with the same parameters as in BigBird, except sequence length was equal to 512 tokens and we used pre-layer normalization in Transformer.
+### Load pre-trained model
+```python
+from transformers import AutoTokenizer, BigBirdForMaskedLM
 
-## Downstream tasks
-Currently, gena-lm-bert-base model has been finetuned  and tested on promoter prediction task.  Its' performance is comparable to previous SOTA results. We plan to fine-tune and make available models for other downstream tasks in the near future.
+tokenizer = AutoTokenizer.from_pretrained('AIRI-Institute/gena-lm-bigbird-base-sparse-t2t')
+model = BigBirdForMaskedLM.from_pretrained('AIRI-Institute/gena-lm-bigbird-base-sparse-t2t')
+```
 
-### Fine-tuning GENA-LM on our data and scoring
-After fine-tuning gena-lm-bert-base on promoter prediction dataset, following results were achieved: 
 
-| model                    | seq_len (bp) | F1    |
-|--------------------------|--------------|-------|
-| DeePromoter              | 300          | 95.60 |
-| GENA-LM bert-base (ours) | 2000         | 95.72 |
-| BigBird                  | 16000        | 99.90 |
+### How to load the model to fine-tune it on classification task
+```python
+from transformers import AutoTokenizer, BigBirdForSequenceClassification
+
+tokenizer = AutoTokenizer.from_pretrained('AIRI-Institute/gena-lm-bigbird-base-sparse-t2t')
+model = BigBirdForSequenceClassification.from_pretrained('AIRI-Institute/gena-lm-bigbird-base-sparse-t2t')
+```
 
-We can conclude that our model achieves comparable performance to the previously published results for promoter prediction task.
+## Model description
+GENA-LM (`gena-lm-bigbird-base-sparse-t2t`) model is trained in a masked language model (MLM) fashion, following the methods proposed in the BigBird paper by masking 15% of tokens. Model config for `gena-lm-bigbird-base-sparse-t2t` is similar to the `google/bigbird-roberta-base`:
 
+- 4096 Maximum sequence length
+- 12 Layers, 12 Attention heads
+- 768 Hidden size
+- sparse config:
+    - block size: 64
+    - random blocks: 3
+    - global blocks: 2
+    - sliding window blocks: 3
+- Rotary positional embeddings
+- 32k Vocabulary size, tokenizer trained on DNA data.
+
+We pre-trained `gena-lm-bigbird-base-sparse-t2t` using the latest T2T human genome assembly (https://www.ncbi.nlm.nih.gov/assembly/GCA_009914755.3/). The data was augmented by sampling mutations from 1000-genome SNPs (gnomAD dataset). Pre-training was performed for 800,000 iterations with batch size 256. We modified Transformer with [Pre-Layer normalization](https://arxiv.org/abs/2002.04745).
+
+## Evaluation
+For evaluation results, see our paper: https://www.biorxiv.org/content/10.1101/2023.06.12.544594v1
+
+## Citation
+```bibtex
+@article{GENA_LM,
+	author = {Veniamin Fishman and Yuri Kuratov and Maxim Petrov and Aleksei Shmelev and Denis Shepelin and Nikolay Chekanov and Olga Kardymon and Mikhail Burtsev},
+	title = {GENA-LM: A Family of Open-Source Foundational Models for Long DNA Sequences},
+	elocation-id = {2023.06.12.544594},
+	year = {2023},
+	doi = {10.1101/2023.06.12.544594},
+	publisher = {Cold Spring Harbor Laboratory},
+	URL = {https://www.biorxiv.org/content/early/2023/06/13/2023.06.12.544594},
+	eprint = {https://www.biorxiv.org/content/early/2023/06/13/2023.06.12.544594.full.pdf},
+	journal = {bioRxiv}
+}
+```