Teemi

.. image:: https://raw.githubusercontent.com/hiyama341/teemi/main/pictures/teemi_logo.svg :width: 400 :alt: teemi logo

teemi: An open-source literate programming approach for iterative design-build-test-learn cycles in bioengineering

.. summary-start

.. image:: https://badge.fury.io/py/teemi.svg :target: https://badge.fury.io/py/teemi

.. image:: https://github.com/hiyama341/teemi/actions/workflows/main.yml/badge.svg :target: https://github.com/hiyama341/teemi/actions

.. image:: https://readthedocs.org/projects/teemi/badge/?version=latest :target: https://teemi.readthedocs.io/en/latest/?version=latest :alt: Documentation Status

.. image:: https://img.shields.io/github/license/hiyama341/teemi :target: https://github.com/hiyama341/teemi/blob/main/LICENSE

.. image:: https://img.shields.io/pypi/pyversions/teemi.svg :target: https://pypi.org/project/teemi/ :alt: Supported Python Versions

.. image:: https://codecov.io/gh/hiyama341/teemi/branch/main/graph/badge.svg?token=P4457QACUY :target: https://codecov.io/gh/hiyama341/teemi

.. image:: https://img.shields.io/badge/code%20style-black-black :target: https://black.readthedocs.io/en/stable/

.. image:: https://img.shields.io/github/last-commit/hiyama341/teemi

.. image:: https://img.shields.io/badge/DOI-10_1101_2023_06_18_545451 :target: https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1011929

What is teemi?

**teemi**, named after the Greek goddess of fairness, is a python package designed
to make microbial strain construction reproducible and FAIR (Findable, Accessible, 
Interoperable, and Reusable). With teemi, you can simulate all steps of 
a strain construction cycle, from generating genetic parts to designing 
a combinatorial library and keeping track of samples through a commercial
Benchling API and a low-level CSV file database. 
This tool can be used in literate programming to 
increase efficiency and speed in metabolic engineering tasks. 
To try teemi, visit our `Google Colab notebooks <https://github.com/hiyama341/teemi/tree/main/colab_notebooks>`__.


teemi not only simplifies the strain construction process but also offers the 
flexibility to adapt to different experimental workflows through its open-source
Python platform. This allows for efficient automation of repetitive tasks and
a faster pace in metabolic engineering.

Our demonstration of teemi in a complex machine learning-guided
metabolic engineering task showcases its efficiency 
and speed by debottlenecking a crucial step in the strictosidine pathway. 
This highlights the versatility and usefulness of this tool in various  
biological applications. 

Curious about how you can build strains easier and faster with teemi? 
Head over to our `Google Colab notebooks <https://github.com/hiyama341/teemi/tree/main/colab_notebooks>`__
and give it a try.

For a quick introduction, check our quick guides:

- `A Quick Guide to Creating a Combinatorial Library`_
- `A Quick Guide to making a CRISPR plasmid with USER cloning (for the beginner)`_

For more examples of literate programming in action, explore our
`teemi CAD workflows <https://github.com/hiyama341/teemi/tree/main/teemi_cad_workflows>`__ —
a collection of Jupyter notebooks demonstrating bioengineering workflows built with teemi.


teemi has been published in PLOS COMPUTATIONAL BIOLOGY: `"teemi: An open-source literate programming approach for iterative design-build-test-learn cycles in bioengineering" <https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1011929>`__.
Please cite it if you've used teemi in a scientific publication.


.. image:: https://raw.githubusercontent.com/hiyama341/teemi/refs/heads/main/pictures/PLOS_publication.png
  :width: 700
  :alt: PLOS publication


.. summary-end

Overview
--------
- `Roadmap <./ROADMAP.md>`_
- `Releasing <./RELEASING.md>`_
- `New Features`_
- `Features`_
- `Getting started`_
- `A Quick Guide to Creating a Combinatorial Library`_
- `A Quick Guide to making a CRISPR plasmid with USER cloning (for the beginner)`_
- `Colab notebooks`_
- `Strictosidine case : First DBTL cycle`_
- `Strictosidine case : Second DBTL cycle`_
- `Installation`_
- `Documentation and Examples`_
- `Contributions`_
- `License`_
- `Credits`_

Project docs
------------

- `Roadmap <./ROADMAP.md>`_
- `Releasing <./RELEASING.md>`_


New Features
------------
* CRISPR-Cas3
* CRISPR-Cas9
* CRISPR-Cas12a
* CRISPRi
* CRISPR-BEST (base-editing)


Features
--------

* Combinatorial library generation
* HT cloning and transformation workflows
* CSV-based LIMS system as well as integration to Benchling
* Genotyping of microbial strains
* Advanced Machine Learning of biological datasets with the AutoML `H2O <https://docs.h2o.ai/h2o/latest-stable/h2o-docs/automl.html>`__
* Workflows for selecting enzyme homologs
* Promoter selection workflows from RNA-seq datasets
* Data analysis of large LC-MS datasets along with workflows for analysis


Getting started

To get started with making microbial strains in an HT manner please follow the steps below:

1. Install teemi. You will find the necessary information below for installation.

2. Check out our notebooks <https://github.com/hiyama341/teemi/tree/main/colab_notebooks>__ for inspiration to make HT strain construction with teemi.

3. You can start making your own workflows by importing teemi into either Google colab or Jupyter lab/notebooks.

A Quick Guide to Creating a Combinatorial Library

This guide provides a simple example of the power and ease of use of the teemi tool. Let's take the example of creating a basic combinatorial library with the following design considerations:

• Four promoters
• Ten enzyme homologs
• A Kozak sequence integrated into the primers

Our goal is to assemble a library of promoters and enzymes into a genome via in vivo assembly. We already have a CRISPR plasmid; all we need to do is amplify the promoters and enzymes for the transformation. This requires generating primers and making PCRs. We'll use teemi for this process.

To begin, we load the genetic parts using Teemi's easy-to-use function read_genbank_files(), specifying the path to the genetic parts.

.. code-block:: python

from teemi.design.fetch_sequences import read_genbank_files
path = '../data/genetic_parts/G8H_CYP_CPR_PARTS/'
pCPR_sites = read_genbank_files(path+'CPR_promoters.gb')
CPR_sites = read_genbank_files(path+'CPR_tCYC1.gb')

We have four promoters and ten CPR homologs (all with integrated terminators). We want to convert them into pydna.Dseqrecord objects from their current form as Bio.Seqrecord. We can do it this way:

.. code-block:: python

from pydna.dseqrecord import Dseqrecord
pCPR_sites = [Dseqrecord(seq) for seq in pCPR_sites]
CPR_sites = [Dseqrecord(seq) for seq in CPR_sites]

Next, we add these genetic parts to a list in the configuration we desire, with the promoters upstream of the enzyme homologs.

.. code-block:: python

list_of_seqs = [pCPR_sites, CPR_sites]

If we want to integrate a sgRNA site into the primers, we can do that. In this case, we want to integrate a Kozak sequence. We can initialize it as shown below.

.. code-block:: python

kozak = [Dseqrecord('TCGGTC')]

Now we're ready to create a combinatorial library of our 4x10 combinations. We can import the Teemi class for this.

.. code-block:: python

from teemi.design.combinatorial_design import DesignAssembly

We initialize with the sequences, the pad (where we want the pad - in this case, between the promoters and CPRs), then select the overlap and the desired temperature for the primers. Note that you can use your own primer calculator. Teemi has a function that can calculate primer Tm using NEB, for example, but for simplicity, we'll use the default calculator here.

.. code-block:: python

CPR_combinatorial_library = DesignAssembly(list_of_seqs, pad = kozak , position_of_pads =[1], overlap=35, target_tm = 55 )

Now, we can retrieve the library.

.. code-block:: python

CPR_combinatorial_library.primer_list_to_dataframe()

.. list-table:: :widths: 5 10 15 10 5 10 15 15 10 :header-rows: 1

• • id
  • anneals to
  • sequence
  • annealing temperature
  • length
  • price(DKK)
  • description
  • footprint
  • len_footprint
• • P001
  • pMLS1
  • ...
  • 56.11
  • 20
  • 36.0
  • Anneals to pMLS1
  • ...
  • 20
• • P002
  • pMLS1
  • ...
  • 56.18
  • 49
  • 88.2
  • Anneals to pMLS1, overlaps to 2349bp_PCR_prod
  • ...
  • 28
• • ...
  • ...
  • ...
  • ...
  • ...
  • ...
  • ...
  • ...
  • ...

The result of this operation is a pandas DataFrame which will look similar to the given example (note that the actual DataFrame have more rows).

To obtain a DataFrame detailing the steps required for each PCR, we can use the following:

.. code-block:: python

CPR_combinatorial_library.pcr_list_to_dataframe()

.. list-table:: :widths: 10 20 15 15 10 10 :header-rows: 1

• • pcr_number
  • template
  • forward_primer
  • reverse_primer
  • f_tm
  • r_tm
• • PCR1
  • pMLS1
  • P001
  • P002
  • 56.11
  • 56.18
• • PCR2
  • AhuCPR_tCYC1
  • P003
  • P004
  • 53.04
  • 53.50
• • PCR3
  • pMLS1
  • P001
  • P005
  • 56.11
  • 56.18
• • ...
  • ...
  • ...
  • ...
  • ...
  • ...

The output is a pandas DataFrame. This is a simplified version and the actual DataFrame can have more rows.

Teemi has many more functionalities. For instance, we can easily view the different combinations in our library.

.. code-block:: python