txtl module design document

This page serves as the design document for the txtl module that is part of the txtlsim package. The txtl module provides a set of helper functions that can be used to create an SBML model that is compatible with other components of the txtlsim-python toolbox.

Key features:

• Provides functions that match TX-TL experimental workflows to quickly create a simulation of a TX-TL experiment
  • DNA assembly (txtl.assemble_dna)
  • Extract and buffer customization (txtl.add_extract, txt.add_buffer)
  • Addition of inducers and other molecules (txtl.add_species)
  • Circuit construction by combining components (txtl.combine_tubes)
  • Simulation and plotting (txtl.simulate, txtl.plot)
• Automatically adds reactions required to model TX-TL mechanisms such as resource utilization (NTPs, amino acids, energy) and linear DNA degradation
• When combined with the BioSIMI module, can be used to create subsystem models and artificial cells
• Supports simulation of in vivo experiments through the use of the cell object

Example

The following example illustrates the usage of the toolbox:

# Set up the standard TXTL tubes
tube1 = txtl.extract('E30VNPRL')
tube2 = txtl.buffer('E30VNPRL')

# Now set up a tube that will contain our DNA
tube3 = txtl.newtube('gene_expression')

# Define a DNA strand using strings
gene1 = txtl.assemble_dna('ptet(50)', 'utr1(20)', 'tetR(1200)')
txtl.add_dna(tube3, gene1, 1, 'plasmid')

# Assemble a DNA strand using objects
from txtl.models import ptet bcd1 degfp lva
gene2 = txtl.assemble_dna(ptet, bcd1, degfp, tag=lva)
txtl.add_dna(tube3, gene2, 1, 'plasmid')

# Mix the contents of the individual tubes
well1 = txtl.combine_tubes([tube1, tube2, tube3])

# Run a simulation
## (AP, 8/16) The function simulate is defined above (not runsim)
simData = txtl.runsim(well1, 8 * txtl.hours) 

# plot the result
txtl.plot(simData, well1)

# Create an SBML file containing the model
## (AP, 8/16) Changing .sbml to .xml, which is the correct extension for an SBML file. 
txtl.writeSBML(well1, 'autoreg.xml')

Class structure

The txtl module uses libsbml classes to represent the core objects in a model. This enables the use of any libsbml compatible library for further operations. There are two primary classes that are defined within the txtl module:

• Tube - the Tube class is used to hold the contents of a tube. It corresponds to an SBML container, but with functions that allow you to manipulate tubes (eg, adding a species to a tube, combining tubes with other tubes)

• DNAassembly - the DNAassembly class is used to represent a DNA construct that is able to express a protein. The DNAassembly class creates a set of species and reactions that correspond to transcription, translation, folding, and degradation of mRNA and proteins.

Tube class

The tube class is used to represent a container that holds a set of species (including DNA).

Data attributes

• name - string representing the name of this species
• model - SBML model for the contents of the tube
• contents - list of DNA/species that are contained in this tube
• concentrations - list of concentrations of DNA/species contained in the tube
• mechanisms - (optional) list of mechanisms that should be included in the tube
• _SBMLdoc - SBML document object (hidden)

Methods

• update_species() - update (or generate) all of the species created within this tube
• update_reactions() - update (or generate) all of the reactions created within this tube

DNAassembly class

The DNAassembly class is used to represent a DNA sequence that will be transcribed and (optionally) translated. It is a special object because it generates a collection of species and reactions that correspond to transcription, translation, and degradation of mRNA and proteins.

Data attributes

• name - string representing the name of this piece of DNA
• promoter - promoter sequence (used to start transcription)
• utr5 - 5' untranslated region (including ribosome binding site)
• cds - coding sequence (start codon to stop codon); can also be a list
• ctag - optional C-terminus tag (for controlling degradation)
• utr3 - optional 3' untranslated region (including terminator)
• type - 'linear' or 'plasmid' (controls degradation)
• <rates> - component specific reaction rates

If only one of the elements of the DNA components is given and the other elements are all None, then this corresponds to a DNA component that can be assembled into a fully functional DNA segment.

Methods

• update_species() - update (or generate) all of the species create by this DNA sequence
• update_reactions() - update (or generate) all of the reactions create by this DNA sequence

Developer note: when two species interact, there is some ambiguity about which species is responsible for setting up the reactions between those species. Generally, the more specialized species should set up the reaction (e.g., LacR is responsible for setting up binding of LacR to IPTG).

Library structure

The following files and subdirectories are used to organize the code:

txtl/ - TX-TL modeling module
  extracts/ - configuration files for extract, buffers
  core/ - core functions used in creating models, species, reactions, etc
    dimerization.py - set up dimerization species and reactions
    dna_degradation.py - set up DNA degradation reactions
    phosophorylation.py - set up phosphorylation reactions
    protein_degradation.py - set up protein degradation reactions
    transcription.py - set up transcription species and reactions
    translation.py - set up translation species and reactions
    stars.py - set up STARs (small transcription activating RNAs) species and reactions
  dna.py - DNA class
  tube.py - tube class
  models/ - models of DNA components and chemical species
    prom_<name>.py - promoter model
    5utr_<name>.py - 5\' untranslated region model
    cds_<name>.py - coding sequence model
    tag_<name>.py - protein (degradation) tag
    3utr_<name>.py - 5\' untranslated region model
    term_<name>.py - terminator sequence model
    prot_<name>.py - protein models
biosimi/ - BioSIMI module
sbmlutil/ - helper functions for interacting with libsbml