2.1 Internal CRN representation

Underlying BioCRNpyler is a comprehensive chemical reaction network class. The species classes in BioCRNpyler consist of object-oriented data structures with increasing complexity which generate their own unique string representations. Table A in S1 Text describes the different species classes in BioCRNpyler. Similarly, BioCRNpyler comes equipped with many diverse propensity function types including mass-action, Hill functions, and general user specified propensities described in Table B in S1 Text. The CRN classes inside BioCRNpyler provide useful functionality so that users can easily modify CRNs produced via compilation, produce entire CRNs by hand, or interface hand-produced CRNs with compiled CRNs. Additionally, user-friendly printing functionality allows for the easy visualization of CRNs in multiple text formats or as interactive reaction graphs formatted and drawn using Bokeh and ForceAtlas2 [42, 43].

2.2 Mechanisms are reaction schemas

When modeling biological systems, modelers frequently make use of mass-action CRN kinetics which ensure that parameters and states have clear underlying mechanistic meanings. However, for the design of synthetic biological circuits and analysis using experimental data, phenomenological or reduced-order models are commonly utilized as well [2]. Empirical phenomenological models have been successful in predicting and analyzing complex circuit behavior using simple models with only a few lumped parameters [44–46]. Bridging the connections between the different modeling abstractions is a challenging research problem. This has been explored in the literature using various approaches such as by direct mathematical comparison of mechanistic and phenomenological models [47–49] or by studying particular examples of reduced models [2]. BioCRNpyler provides a computational approach using reaction schemas to easily change the mechanisms used in compilation from detailed mass-action to coarse-grained at various level of complexity.

Reaction schemas refer to BioCRNpyler’s generalization of switching between different mechanistic models: a single process can be modeled using multiple underlying motifs to generate a class of models which may have qualitatively different behavior. Mechanisms are the BioCRNpyler objects responsible for defining reaction schemas. In other words, various levels of abstractions and model reductions can all be represented easily by using built-in and custom Mechanisms in BioCRNpyler. Biologically, reaction schemas can represent different underlying biochemical mechanisms or modeling assumptions and simplifications. For example, to model the process of transcription (as shown in Fig 1), BioCRNpyler allows the use of various phenomenological and mass-action kinetic models by simply changing the choice of reaction schema. The simplest of these schemas “Simple Transcription” includes no details about how a gene produces a transcription. “Michaelis Menten Transcription” elaborates on this simplification by including the RNA polymerase enzyme in the model. “Michaelis Menten Transcription with a Hill Function” simplifies the previous mass action model assuming a quasi-equilibrium approximation of RNA polymerase binding. Finally, the “Multi-Occupancy Michaelis Menten Transcription Model” aims to be more realistic by examining the possibility of multiple RNA polymerase enzymes bound to a single transcript. Of course, these are not the only possible transcription Mechanisms: more detailed models may include transcript elongation or organism-specific co-factors, such as σ-factors in E. coli, which could also easily be included in a BioCRNpyler Mechanism.

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 1. Mechanisms (reaction schemas) representing transcription.

https://doi.org/10.1371/journal.pcbi.1009987.g001

Formally, reaction schemas are functions that produce CRN species and reactions from a set of input species and parameters: f : (S′, θ)→(S, R). Here the inputs S′ are chemical species and θ are rate constants. The outputs S ⊇ S′ is an increased set of species and R is a set of reactions. The functions f used to define the transcription reaction schemas in Fig 1 are examples of relatively simple Mechanisms which do not have any internal logic. However, BioCRNpyler allows for reaction schemas to be defined directly in Python. This allows for incredible flexibility in defining Mechanisms capable of complex logic, combinatoric enumeration, or other advanced functionality. The object oriented design of Mechanisms also allows modelers to generate CRNs at different levels of complexity and reuse CRN motifs for some Components while customizing Mechanisms for others. Internally, each Mechanism class has a type (e.g. transcription) which defines the input and output species it requires. BioCRNpyler contains an extensive library of Mechanisms (Table C in S1 Text) which are easy to repurpose without extensive coding. Custom Mechanisms are also easy to define by subclassing Mechanism as described in Section I in S1 Text. Ultimately, Mechanisms provides a unique capability to quickly compare system models across various levels of abstraction enabling a more nuanced approach to circuit design and exploring system parameter regimes.

2.3 Components represent functionality

In BioCRNpyler, Components are biochemical parts or motifs, such as promoters, enzymes and chemical complexes. Components represent biomolecular functionality; a promoter enables transcription, enzymes perform catalysis, and chemical complexes must bind together. Components express their functionality by calling particular Mechanism types during compilation. Importantly, Components are not the same as CRN species; one species might be represented by multiple Components and a Component might produce multiple species. For example, a promoter Component will call transcription Mechanisms like those shown in Fig 1. If the “Simple Transcription” Mechanism is used, the promoter will be represented by a single species G. On the other hand, if the “Michaelis Menten Transcription” schema is used, the promoter will actually have two forms: G and G:RNAP representing the free promoter and the promoter bound to RNA polymerase. Components are flexible and can behave differently in different contexts or behave context-independently. To define dynamic-context behavior, Components will automatically use Mechanisms and parameters provided by the Mixture. To define context-independent behavior, Components can have their own internal Mechanisms and parameters. The BioCRNpyler library includes many kinds of Component some of which are listed in S1 Text Table D. Custom Components can also be easily created by subclassing another Component as described in Section II in S1 Text.

2.4 Mixtures represent context

Mixtures are collections of Components, Mechanisms, and parameters. Mixtures can represent chemical context (e.g. cell extract vs. in vivo), as well as modeling resolution (e.g. what level of detail to model transcription or translation at) by containing different internal Components, Mechanisms, and parameters. BioCRNpyler comes with a variety of Mixtures (see Table E in S1 Text) to represent cell-extracts and cell-like systems with multiple levels of modeling complexity. Custom Mixtures can also be easily created either by subclassing an existing mixture or via a few simple scripting operations as described in Section III in S1 Text.

2.5 Flexible parameter databases

Developing models is a process that involves defining then parameterizing interactions. Often, at the early stage of model construction, exact parameter values will be unavailable. BioCRNpyler has a sophisticated parameter framework which allows for the software to search user-populated parameter databases for the parameter that closest matches a specific Mechanism, Component, and parameter name as illustrated in Fig 2. This allows for models to be rapidly constructed and simulated with “ball-park” parameters and then later refined with specific parameters derived from literature or experiments later. This framework also makes it easy to incorporate diverse parameter files together and share parameters between many chemical reactions. BioCRNpyler also allows each Component to have its own parameter database allowing for multiple parameter sources to be combined easily. Components without their own parameters default to the parameters stored in the Mixture.

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 2. BioCRNpyler parameter defaulting hierarchy.

If a specific ParameterKey (orange boxes) cannot be found, the ParameterDatabase automatically defaults to other ParameterKeys. This allows for parameter sharing and rapid construction of complex models from relatively few non-specific (e.g. lower in the hierarchy) parameters.

https://doi.org/10.1371/journal.pcbi.1009987.g002

2.6 Component enumeration allows for arbitrary complexity

Component enumeration is a powerful and specialized compilation step which allows new Components to be generated dynamically. Internally, this is achieved in BioCRNpyler by subclassing the ComponentEnumerator class to implement an arbitrary function in Python g: C → C′ where C ⊂ C′ are sets of Components. In local component enumeration the set C consist of just a single component c which contains its own ComponentEnumerator. In global component enumeration, C consists of all components in the Mixture. As more Components are generated, C′ will be fed back into g recursively until no new Components are created or a user defined recursion depth is reached. Like Mechanisms, we emphasize that component enumeration is highly flexible because the enumerators can be written as Python code, allowing for diverse logic, combinatoric enumeration, and more. Section 3.3 describes BioCRNpyler models that makes use of both local and global component enumeration.

2.7 Specification example

Before describing the compilation algorithm in detail, we illustrate the central idea of a BioCRNpyler specification via an example involving a DNAassembly Component which represents a simple piece of DNA, called X, with a promoter, ribosome binding site, and coding sequence for a protein. The DNAassembly uses transcription and translation Mechanisms which will be placed into a Mixture.

# Create Mechanisms

tx = SimpleTranscription() #Transcription

tl = SimpleTranslation() #Translation

# Create a Component

G = DNAassembly(“X”, promoter = “prom”, rbs = “rbs”, protein = “X”)

# Define Parameters

params = {“kb”:100, “ku”:10, “ktx”:0.1, “ktl”:0.5,}

# Place the Component and Mechanisms in a Mixture

M = Mixture(“mixture”, components = [G], mechanisms = [tx, tl], parameters = params)

# Compile the CRN

CRN = M.compile_crn()

This simple code compiles the CRN: (1)

The modularity of BioCRNpyler can be illustrated by considering what would happen if we instead used “Michaelis Menten” transcription and translation Mechanisms which model RNA-polymerase (P) and ribosomes (R):

tx = Transcription_MM(rnap = Species(“P”)) #Transcription Mechanism

tl = Translation_MM(ribosome = Species(“R”)) #Translation Mechanism

This compiles a considerably more complex CRN:

Here, “:” indicates that two species are bound together to form a new species.

2.8 Chemical reaction network compilation

Having provided an overview of the core classes in BioCRNpyler, we will now describe the compilation algorithm in detail. First, we assume a user has specified a Mixture and populated it with Components, Mechanisms, and parameters. We note that some Components may have their own internal Mechanisms and Parameters while others will be reliant on the Mixture. Compilation proceeds in 7 steps, shown in Fig 3 and elaborated on below.

1. Global Component Enumeration: this step is optional and will only occur if a Mixture contains a one or more global ComponentEnumerators. All Components in the Mixture will be fed into the ComponentEnumerator recursively until either no new Components are created or a user-specified recursion depth is reached.
2. Local Component Enumeration: this step is optional and will be applied to every Component in the Mixture that contains a one or more local ComponentEnumerators. Each of these Components will generate new Components from itself. If these new Components contain local ComponentEnumerators they will also generate new Components. Like global component enumeration, local component enumeration is stopped when no new Components are created or a user-specified maximum recursion depth is reached.
3. The Mixture iterates through all its internal Components (including those generated via enumeration) and calls the Component’s update_species() and update_reactions() methods.
4. In each Component’s update_species() and update_reactions() method, the Component first searches for Mechanisms of the types it requires. Mechanisms stored inside the Component will be used preferentially. If the Component does not have a particular internal Mechanism, that Mechanism is instead retrieved from the Mixture. The Component then calls the update_species(…) and update_reactions(…) methods of each Mechanism supplying the proper parameters for that Mechanism.
5. Mechanisms generate species and reactions based upon the arguments supplied by the Component that called them. Mechanisms search for rate parameters in the parameter database of the Component that called them. If no parameters are found, the Mechanism will then search for parameters in the Mixture’s parameter database. Note that the same Mechanism may be called multiple times with different parameters, effectively reusing the reaction schema to compile a large CRN. The species and reactions generated this way are returned to the Mixture.
6. Global Mechanisms are a special kind of Mechanism which are stored in the Mixture and produce new species and reactions from a single species parameter. All species generated in previous steps are passed into the Mixture’s global Mechanisms to generate additional species and reactions. Note that global Mechanisms are not called recursively.
7. The resulting species and reactions generated in the previous steps form a chemical reaction network which can be modified programatically or exported as SBML.

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 3.

A. the organization of classes in BioCRNpyler. Gray arrows indicate the hierarchical organization of objects (e.g. Components are contained in a Mixture). Dark gray arrows take precedence over light gray arrows (e.g. a Component will search for Mechanisms in itself before looking at its Mixture). Colored arrows denote the generate of objects: Components are orange, parameters are blue, and CRN species and reactions are yellow. B. The compilation sequence in BioCRNpyler. The numbers on the arrows in (A) indicate which part of compilation these connections are involved in.

https://doi.org/10.1371/journal.pcbi.1009987.g003

2.9 Integrated testing

BioCRNpyler uses GitHub Actions and Codecov [50] to automate testing on GitHub. Whenever the software is updated, a suite of tests is run including extensive unit tests and functional testing of tutorial and documentation notebooks. Automated testing ensures that changes to the core BioCRNpyler code preserve functionality of the package. The integration of Jupyter notebooks into testing allows users to easily define new functionality for the software and document that functionality with detailed explanations which are simultaneously tests cases.

2.10 Documentation and tutorials

The BioCRNpyler GitHub page contains over a dozen tutorial Jupyter notebooks [40] and video presentations explaining everything from the fundamental features of the code to specialized functionality for advanced models to how to add to the BioCRNpyler code-base [51]. This documentation has been used successfully in multiple academic courses and is guaranteed to be up-to-date and functional due to automatic testing.

3.1 Synthetic biological circuit examples

Fig 4A, 4B and 4C show three models of synthetic biological circuits which demonstrate the modularity and expressivity of BioCRNpyler. Underlying all these models is a single Component class called a DNAassembly which was described in Section 2.7. These first three examples use idealized models of their underlying biological processes via a very simple Mixture. In Fig 4A two DNAassemblies are wired together with a repressor (red) repressing a report (yellow). The repressor is expressed at a constant rate using the “Simple Transcription” Mechanism shown in Fig 1 which is supplied by the Mixture. The reporter, on the other hand, uses a different transcription Mechanism, “Negative Hill Repression” stored in its DNAassembly. This illustrates the ability for the same process, transcription, to be modeled in different ways within a single model. In Fig 4B, two DNAassembly Components are wired to repress each other, both using Hill functions, to produce a model of the famous bistable toggle switch [54]. Similarly, Fig 4C wires three repressors together so A represses B, B represses C, and C represses A, giving rise to a transcriptional oscillator called the repressilator [55].

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 4. Motivating examples.

The idealized models (A, B, and C) do not model the cellular environment; genes and transcripts transcribe and translate catalytically. A. Schematic and simulation of a constituitively active repressor gene repressing a reporter. B. Schematic and simulations of of a toggle switch created by having two genes, A and B, mutually repress each other. C. Schematic and dynamics of a 3-repressor oscillator. The detailed models (D, E, & F) model the cellular environment by including ribosomes, RNAases and background resource competition for cellular resources. D. A dCas9-guideRNA complex binds to the promoter of a reporter and inhibiting transcription. Heatmap shows retroactivity caused by varying the amount of dCas9 and guide-RNA expressed. The sharing of transcription and translational resources gives rise to increases and decreases of reporter even when there is very little repressor. E. A proposed model for a non-transcriptional toggle switch formed by homodimer-RNAase; the homodimer-RNAase made from subunit A selectively degrades the mRNA producing subunit B and visa-versa. F. A model of the Repressillator exploring the effects of multiple ribosomes binding to the same mRNA. G. Histogram comparing the sizes of models A-F and the amount of BioCRNpyler code needed to generate them.

https://doi.org/10.1371/journal.pcbi.1009987.g004

Fig 4D, 4E and 4F examine similar circuits to Fig 4A, 4B and 4C but with more complex implementations modeled in a more detailed context. In these three following examples, a less idealized Mixture is used which models transcription, translation, and RNA degradation with biological machinery including RNA polymerase, ribosomes, and RNAses. Fig 4D examines a detailed implementation of a repression circuit consisting DNAassembly Components which express a guide-RNA (gRNA) and deactived Cas9 (dCas9) protein [56]. The dCas9-gRNA complex is capable of binding to the promoter of the reporter assembly, repressing transcription. This more complex circuit in a complex context reveals some unexpected behavior; if the amount of dCas9 and gRNA are not carefully balanced, resource loading can give rise to unexpected increases and decreases of the reporter, a phenomena known as retroactivity [57]. Fig 4E shows a hypothetical variation of a bistable toggle switch implemented via translational regulation using targeted RNAses (RNAse A degrades the transcript for RNAse B and visa-versa). Such a system could potentially be engineered via RNA-targeting Cas9 [58] or more complex fusion proteins [59]. Finally, Fig 4F compiles a model of the repressilator which allows for multiple ribosomes to bind to each transcript. The added complexity creates much more complicated dynamics, but oscillatory behavior still clearly occurs. This example illustrates how BioCRNpyler can be used to test different modeling assumptions (e.g. does multiple occupancy of ribosomes matter?).

Finally, we comment that all the examples from Fig 4 make use of the same underlying set of 10–20 default parameters (estimated from Cell Biology by the Numbers [60]) demonstrating how BioCRNpyler’s parameter database and defaulting behavior make model construction and simulation possible even before detailed experiments or literature review. The efficiency of using BioCRNpyler to explore diverse modeling assumptions and circuit architectures is quantified in Fig 4G which compares the number of species, reactions, and ordinary differential equation terms in the compiled models to the lines of BioCRNpyler code needed to create these models. In short, BioCRNpyler allows for the rapid generation of large and diverse models. Code for these six examples can be in Sections I-IV in S1 Text.

3.2 Systems biology circuit example

Fig 5 illustrates how a set of BioCRNpyler Components and Mechanisms can be joined together to produce a systems level model of the lac operon—a highly studied gene regulatory network in E. coli which regulates whether glucose or lactose is metabolized [61]. This specification is shown in Fig 5A and consists of around a dozen Components and Mechanisms which jointly enumerate hundreds of species and reactions representing the combinatorial set of conformations of the lac operon (depicted by the cartoons in panel B) and its associated transcription factors, transcription, translation, transport, mRNA degradation and dilution. Besides showing how BioCRNpyler can be applied to model the kinds of combinatoric interactions common in systems biology, this example also graphically illustrates the BioCRNpyler abstraction where Components interact via Mechanisms in order to generate a large, complex CRN (panel C). Furthermore, this example highlights that the Component species mapping is not one-to-one. For example, the Lac Operon is modeled as two Components one representing the promoter architecture and another coupling that promoter to translation. Jointly, these two Components produce a combinatoric number of formal CRN species (shown in panel C by the many different blue dots). Similarly, β-galactosidase is modeled as two Components: as an enzyme (which metabolizes lactose) and a chemical complex (because it is a homeotetramer). Finally, we note that the simulated output of our model (Fig 5D) produces a ~1-2 hour delay between the depletion of glucose and steady state lactose metabolism, consistent with previous models and experiments [61]. Interestingly, this is observed even though we made no efforts to fine-tune our parameters, suggesting that the combinatorial nature of this system may give rise to this behavior in a manner that is robust to detailed kinetic rates. The code used to generate this model can be found in Section VII in S1 Text.

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 5. A model of the lac operon compiled using BioCRNpyler specifications with 141 species and 271 reactions using ∼50 lines of code.

A. A Mixture contains a set of Components and Mechanisms. The Component classes used for each element of the model are shown in brackets. The colored circles show how Components correspond to compiled CRN species in panel C. B. A schematic of the lac operon and the three looped and one open conformation it can take. Each conformation contains a combinatoric number of states based upon the accessible binding sites: R are lac repressor binding sites; C is the activator c-CRP binding site; P is the promoter; and Z, Y, A are the three lac genes. The conformations are placed over clusters of identically colored species corresponding to that conformation in the compiled CRN. C. A graph representation of the compiled CRN. Each circle is a unique chemical species. Square boxes show how chemical species interact via reactions generated by specific Mechanisms. D. Simulated output of the model.

https://doi.org/10.1371/journal.pcbi.1009987.g005

3.3 Component enumeration example

Fig 6 shows three example circuits which make use of component enumeration in order to produce sophisticated CRNs. Local component enumeration is illustrated in Fig 6A. Here, a single DNA Component (top) uses local component enumeration to read through the parts included in its plasmid and determine all possible correctly oriented terminator-promoter pairs. This information is then used to produce multiple RNA Components which model transcription and translation for complex genetic circuit architectures. The CRN and simulation output for this circuit are shown in Fig 6B and 6C, respectively. Fig 6D provides an example of global component enumeration involving the enzymatic recombination of DNA. Specifically, serine integrases (such as Bxb1) are enzymes capable of recombining strands of DNA at specific integration sites [62]. Integration events can happen within a single piece of DNA (top two reactions in panel D) or between multiple DNA species (bottom 4 reactions of panel D). In these reactions, the integrase binds to attP and attB sites and reorganizes them into attL and attR sites which can result in DNA insertions, excisions, or re-orientations. Importantly, each new DNA strand produced by an integrase reaction could potentially recombine with itself or the other strands already produced. Such systems can give rise to theoretically infinite CRNs [63]. BioCRNpyler can approximate integrase systems by recursively using a global component enumerator. In this example, only a single round of recursion is shown for clarity. The clusters of dots in Fig 6E are due to the combinatoric number bound and unbound states due to the potential for integrases to bind and unbind to attP, attB, attL, and attR sites. Finally, the BioCRNpyler framework is designed so that local and global component enumeration are mutually compatible. In Fig 6F, a model of a self-flipping promoter is shown. Initially, the promoter faces right and expresses the integrase Bxb1 which in turn flips the promoter causing Bxb1 expression to cease in favor of RFP expression. In BioCRNpyler, this model is compiled by first using global component enumeration to produce all the possible DNA Components generated by integrase recombinations. Each of these DNA Components then uses local component enumeration to produce RNA Components. All these Components can then be used to compile a CRN by calling their respective Mechanisms. More details about local and global component enumeration, including code for the example models, can be found in Sections VIII-X in S1 Text.

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 6. Examples involving component enumeration.

A. Schematic of local component enumeration for a gene expression circuit where a single DNA Component generates multiple RNA Components. B. The CRN for (A) represented graphically. Colored dots are species corresponding to the components adjacent to the dots in (A). C. Simulated output from the CRN in (B). D. Schematic of global component enumeration in an integrase circuit where one or more DNA Components recombine to produce new DNA Components. Note that the larger DNA outputs could also recombined analogously but this is not shown. E. The CRN for (D) represented graphically. Colored dots are species which correspond to the components adjacent to the dots in (D). F. A genetic circuit which combines global and local component enumeration to flip a promoter which drives gene expression. G. The CRN for the circuit in (F). Colored dots are species representing the components adjacent to the dots in (F). H. Simulated output of the CRN.

https://doi.org/10.1371/journal.pcbi.1009987.g006