Metadata-Version: 2.4
Name: dgrec-tools
Version: 0.2.0
Summary: Analyse and design DGRec targeted-hypermutagenesis experiments
Home-page: https://github.com/dbikard/dgrec
Author: David Bikard
Author-email: David Bikard <david.bikard@pasteur.fr>
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/dbikard/dgrec
Project-URL: Documentation, https://dbikard.github.io/dgrec
Project-URL: Issues, https://github.com/dbikard/dgrec/issues
Keywords: bioinformatics,DGR,diversity-generating retroelement,mutagenesis,directed evolution,amplicon sequencing,UMI
Classifier: Natural Language :: English
Classifier: Intended Audience :: Science/Research
Classifier: Development Status :: 4 - Beta
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10, <3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastcore
Requires-Dist: pandas
Requires-Dist: biopython>=1.86
Requires-Dist: click
Requires-Dist: matplotlib
Requires-Dist: seaborn
Requires-Dist: tqdm
Requires-Dist: scikit-learn==1.7.1
Requires-Dist: logomaker
Requires-Dist: svgwrite
Requires-Dist: ViennaRNA
Provides-Extra: lstm
Requires-Dist: tensorflow[and-cuda]>=2.17; extra == "lstm"
Provides-Extra: dev
Requires-Dist: cython; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# dgrec


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## Overview

DGRec is an in vivo hypermutation technique that combines two biological systems:

- **DGR** (Diversity Generating Retroelement): the DGR reverse transcriptase (bRT) and its accessory protein Avd reverse-transcribe the **template region (TR)**, a segment of a small non-coding RNA called the dgrRNA, making errors predominantly at **adenine positions**.
- **Recombineering** (CspRecT + mutL\*): the single-strand annealing protein CspRecT integrates the mutagenic cDNA into the **variable region (VR)** of a target gene, while mutL\* prevents mismatch repair from correcting the mutations.

This creates a powerful tool for targeted in vivo diversification in *E. coli*, where adenine positions within the TR are selectively mutagenized while other bases remain largely unchanged.

The `dgrec` package provides tools to:

- **Design TR sequences**: score a candidate TR from the predicted folding of its dgrRNA, and recode a poorly mutagenic one using codon substitutions that leave the protein encoded by the target gene unchanged
- **Predict the diversity a TR will generate**: an LSTM model of the position- and context-dependent error profile of the reverse transcriptase, used to simulate the VR sequences reachable from a given TR
- **Call genotypes** from amplicon sequencing data (single-end or paired-end), with UMI-based deduplication to correct PCR and sequencing errors
- **Visualize mutation profiles** at nucleotide and amino acid resolution

**Source code:** [github.com/dbikard/dgrec](https://github.com/dbikard/dgrec)

**Documentation:** [dbikard.github.io/dgrec](https://dbikard.github.io/dgrec/)

**Publication:** Rochette *et al.*, [Diversity-generating retroelements for programmable targeted hypermutagenesis](https://doi.org/10.1038/s41587-026-03078-4), *Nature Biotechnology* (2026)

## Install

`dgrec` requires **Python 3.10 to 3.13** and installs with pip. The distribution is
named `dgrec-tools` because `dgrec` was already taken on PyPI; the import name is
still `dgrec`:

``` sh
pip install dgrec-tools
```

All dependencies, including ViennaRNA, are installed automatically — no conda environment is needed.

The LSTM model needs TensorFlow, which is an optional extra because it is large:

``` sh
pip install "dgrec-tools[lstm]"
```

## Quick start

`dgrec` is used at two points in a DGRec experiment: beforehand, to choose a template region
that will actually be mutagenized, and afterwards, to measure what the experiment produced.
The package ships with a small example dataset, so the code below runs as written.

**Before the experiment** — score a candidate TR, from 0 (poor) to 1 (good):

``` python
import dgrec

dgrec.tr_score('AAATGATCGCCAAATCTGAACAGGAAATTGGCAAAGCAACCGCTAAATACTTTTTCTACTCAAACATTAT')
```

    0.84

A sequence that scores poorly can usually be rescued by recoding. The TR is itself non-coding,
but it is read in the frame of the gene that carries the variable region (VR) it diversifies, so
the substitutions are chosen to leave that protein unchanged. Making the same changes in the VR
keeps the two homologous, which is what the recombination step relies on. See
[How to use](https://dbikard.github.io/dgrec/how_to.html#before-the-experiment-designing-a-tr).

**After the experiment** — call genotypes from the amplicon reads, deduplicated by UMI:

``` sh
dgrec genotypes reads.fastq.gz reference.fasta -o genotypes.csv
```

or, in Python, with the mutation profile plotted:

``` python
import os
from Bio import SeqIO

data_path = dgrec.get_example_data_dir()   #the example dataset that ships with the package
ref_seq = str(next(SeqIO.parse(os.path.join(data_path, 'sacB_ref.fasta'), 'fasta')).seq)

gen_list = dgrec.get_genotypes(os.path.join(data_path, 'sacB_example.fastq.gz'), ref_seq,
                               ignore_pos=[0, 1, 2, 138, 139, 140, 141])

fig = dgrec.plot_mutations(gen_list, ref_seq, sample_name='sacB', TR_range=[50, 119])
```

    n reads:    1000
    n_reads pass filter:    847
    n_reads aligned:    824
    Number of UMIs: 814
    Median number of reads per UMI: 1.0
    Number of genotypes: 123

![](index_files/figure-commonmark/cell-3-output-2.png)

The shaded region is the TR range, where DGRec mutagenesis is active. Note the enrichment of
mutations at adenine positions within it — the hallmark DGRec signature.

**[Read the full walkthrough →](https://dbikard.github.io/dgrec/how_to.html)** for paired-end reads, the command-line options,
TR recoding, and the LSTM model of the mutational profile. Every function is documented in the
[API reference](https://dbikard.github.io/dgrec/API/genotypes.html).

## Citation

If you use `dgrec`, please cite:

> Rochette P, Lopez-Rodriguez E, Wen DJ, Régnier L, *et al.* Diversity-generating retroelements for programmable targeted hypermutagenesis. *Nature Biotechnology* (2026). doi:[10.1038/s41587-026-03078-4](https://doi.org/10.1038/s41587-026-03078-4)

A separate paper describing the bioinformatics and sequence-design tools provided by this package is in preparation; once it is published, please cite both. A `CITATION.cff` file is included in the repository.
