Simulation of an array of constructs with a capacity monitor
========================================================

This file explains how to use the simulate_landscape.py file to simulate a variety of circuits with an array of RBS strengths and mRNA numbers.

REQUIREMENTS
------------

In order to run this script, python must be installed with the following packages:
- numpy
- scipy


SIMULATION PARAMETERS
=====================

The parameters for the simulation are defined in an XML file, e.g. fast_codons_parameters.xml or slow_codons_parameters.xml. An example is shown below:

<?xml version="1.0"?>
<simulation>
	<simulation_name>fast_codons</simulation_name>
	<cell>
	    <total_ribosomes>10000</total_ribosomes>
	</cell>
	<monitor>
		<mrna_number>20</mrna_number>
		<rbs_strength>1</rbs_strength>
		<betas>1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1</betas>
		<alpha_plus_scale>0.0001</alpha_plus_scale>
		<alpha_minus_scale>200</alpha_minus_scale>
	</monitor>
	<circuit>
		<mrna_number_steps>50</mrna_number_steps>
		<mrna_number_step>100</mrna_number_step>
		<rbs_strength_steps>100</rbs_strength_steps>
		<rbs_strength_step>0.1</rbs_strength_step>
		<betas>1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1</betas>
		<alpha_plus_scale>0.0001</alpha_plus_scale>
		<alpha_minus_scale>200</alpha_minus_scale>
	</circuit>
</simulation>

All parameters for the simulation are found within the <simulation> element.

<simulation_name>
	This is the name given to a simulation. This is also the name of the directory within which the data directory that will contain the output csv files will be placed. E.g. if simulation_name is "fast_codons" the data will be placed into "data/fast_codons/".

cell attributes
---------------

These are found within the <cell> element inside <simulation>:

<total_ribosomes>
	This is the total number of ribosomes available within the cell. This should be an integer number.

monitor attributes
------------------

These are found within the <monitor> element inside <simulation>:

<mrna_number>
	This is the number of mRNA per cell for the monitor circuit. This should be an integer number.

<rbs_strength>
	This is the relative strength of the RBS for the monitor circuit. This should be an integer number.

<betas>
	This declares the elongation rates for the monitor. This is defined as a series of numbers separated by commas. The length of the circuit is defined by the number of values within the <betas> element.

<alpha_plus_scale>
	This is the scaling factor for ribosome-RBS affinity. This should not be changed from 0.0001 without an understanding of how this value is used. See models.py for details.

<alpha_minus_scale>
	This is the scaling factor for ribosome-RBS affinity. This should not be changed from 200 without an understanding of how this value is used. See models.py for details.

circuit attributes
------------------

<mrna_number_steps>
	This is the number of different values considered for the number of mRNA per cell used in the simulation landscape.

<mrna_number_step>
	This is the difference between the successive values of number of mRNAs per cell that are to be simulated. It is also the smallest mRNA per cell that will be tested. E.g. if this is 50 and mrna_number_steps is 100, the number of mRNA per cell that will be used to simulate is 50, 100, 150, ..., 5000

<rbs_strength_steps>
	This is the number of different values for the RBS strength used in the simulation landscape.

<rbs_strength_step>
	This is the difference between the successive values of RBS strengths that are to be simulated. It is also the smallest RBS strength that will be tested. E.g. if this is 0.5 and rbs_strength_steps is 20, the nRBS strengths that will be used to simulate is 0.5, 1.0, 1.5, ..., 10.0

<betas>
	This declares the elongation rates for the circuit. This is defined as a series of numbers separated by commas. The length of the circuit is defined by the number of values within the <betas> element.

<alpha_plus_scale>
	This is the scaling factor for ribosome-RBS affinity. This should not be changed from 0.0001 without an understanding of how this value is used. See models.py for details.

<alpha_minus_scale>
	This is the scaling factor for ribosome-RBS affinity. This should not be changed from 200 without an understanding of how this value is used. See models.py for details.

RUNNING THE SIMULATION
======================

This package should be unzipped and using the command line, the user should navigate into the unzipped directory. Once in the directory, the user can run the simulation using the following command:

python simulate_landscape.py [xml_location]

where [xml_location] is to be replaced by the name of the xml file (if in the same directory), or the location and name of the xml file (e.g. /Users/username/synbio_simulations/parameter_files/fast_codon_paramters.xml). This will then output the data into csv files. Each row represents a single RBS strength and each column represents a single number of mRNA. The top left cell represents the lowest RBS strength and lowest number of mRNA with the number of RBS increasing by rbs_strength_step in each subsequent row and the number of mRNA increasing by mrna_number_step in each subsequent column.

PLOTTING THE SIMULATION RESULTS
===============================

The data contained in the .csv files once the Python simulations are complete can be visualised using the Matlab script Plot_Matlab_Heatmap_Efficiency_from_CSV.m and Plot_Matlab_Heatmap_Circuit_Output_from_CSV.m. Each of these Matlab script will create a PDF file whose name is specified within the content of these files (in the last line of both these files) and representing the Simulated Expression Efficiency, calculated as the product of circuit output and number of free ribosomes, and the Circuit Output, defined as the circuit protein production rate per cell.

The Matlab script Extract_Values_from_CSV.m can be used to easily extract the values contained in the python generated .csv files (for example, the values of the circuit output for RBS strength = 6 and mRNA number = 3000). Extract_Values_from_CSV.m writes the extracted values in another .csv file whose name is specified in the last line of the file. To write this CSV file containing the extracted values with the appropriate headers the Matlab script Extract_Values_from_CSV.m uses the Matlab function csvwrite_with_headers.m created by Keith Brady and available from http://uk.mathworks.com/matlabcentral/fileexchange/29933-csv-with-column-headers/content/csvwrite_with_headers.m

These scripts have been tested on Matlab 2014B.

CONSTITUENT FILES
=================

models.py
---------

This python file includes two classes Cell and Circuit that can be used to simulate the behaviour of gene circuits within a cell. In order to simulate a cell containing a synthetic gene and a burden monitor, two separate instances of Circuit must be created (one for the synthetic gene and one for the monitor). These instances can be passed as an argument into the initiation of a cell instance, along with the number of ribosomes. The Cell class has a simulate function which returns the number of free ribosomes and the distribution of ribosomes along the transcripts of each circuit. These distributions, along with the betas for the circuit can be used to calculate the protein production rate for each circuit, the total ribosomes sequestered on each circuit's transcripts and the efficiency of the circuit.

simulations.py
--------------

This file contains a SimulationResult class which parses the raw simulation data from the Cell class from models.py. It parses the raw data into key metrics such as circuit output, circuit ribosomal usage etc. This file also contains a function simulate_landscape that takes key parameters to simulate an array of cells containing a single synthetic circuit and a single monitor circuit. These landscapes are created across various mRNA numbers and RBS strengths.

simulate_landscape.py
---------------------

This is a command line executable file that takes the location of an XML file as an argument. This then takes parameters from the XML file, runs the simulations across the defined landscape and outputs the files into a defined directory in a series of csv files:

circuit_out.csv
	This file contains the protein production rates per cell for the synthetic circuit.

circuit_ribs.csv
	This file contains the total numbers of ribosomes sequestered on all of the transcripts for the synthetic circuit.

free_ribs.csv
	This file contains the numbers of free ribosomes per cell.

monitor_out.csv
	This file contains the protein production rates per cell for the burden monitor.

monitor_ribs.csv
	This file contains the total numbers of ribosomes sequestered on all of the transcripts for the burden monitor.

mRNA_amount.csv
	This file contains a vector of all the mRNA amounts used in the simulations across the landscape.

RBS_str.csv
	This file contains a vector of all the RBS strengths used in the simulations across the landscape.