Editing OptFlux3:RT

__TOC__

=Installation=

After install the OptFlux, the Reg4OptFlux plugin can be installed through the repository manager present in OptFlux.
*You can access the '''Repository''' option under the '''Help -> Repository Manager''' menu.<br>

[[Image:installregplugin.png|600px]]

*After accessing to the '''Repository Manager''' click over the Regulatory Tool (version x) and perform the installation by clicking on '''Install - Version x.x.x)'''.
* Click on '''Restart''' button.

=Example file=

You can download it here -> [http://darwin.di.uminho.pt/optfluxwiki/images/1/17/IntegratedModelToy_example.zip IntegratedModelToy]

[[Image:IntegratedModel.png‎]]

This tutorial uses an example based on work presented by '''J. Kim and J. Reed'''.''OptORF: Optimal metabolic and regulatory perturbations for metabolic engineering of microbial strains''. BMC, 2010


*The regulatory model is composed by a transcription factor (TF1) that is activated when metabolite S is present, activates the expression of two genes (G3, G5) and represses the expression of gene G1A.

*The Gene Reactions rules are characterized in the following way: R1 is catalyzed when the gene G1A and G1B are activated; R2 is catalyzed by the gene G2; R3 and R4 are catalyzed by the genes G3 and G4, respectively; finally, R5 can be catalyzed by either genes G5 or G6.

*At the metabolic level, the substrate (S) is utilized to produce biomass (B) and by-products P1 and P2. The cellular objective is to maximize biomass production (B) and the engineering objective is the production of P1. Reaction R2 converts the internal metabolite I1 into product P1 and 0.08 biomass (B), whereas reaction R5 converts the internal metabolite I2 into product P2 and 0.12 Biomass. The stoichiometric coefficients of all other reactions reflect a one-to-one relationship between molecule quantities.


=Define a regulatory model file to be used in the Reg4OptFlux plugin=

Reg4OptFlux plugin supports the loading of a regulatory model in excel file format (.xls and .xlsx) or the comma-separated values file format (.csv).

* Is possible to define a regulatory model by describing only the genes that have an associated regulatory rule, or a regulatory model containing all the genes that are present in the metabolic model and the regulatory model.

<b>In the implementation of the regulatory model is mandatory the description of the following elements for each gene rule:</b>

<b>1. <i>A column containing the  identifiers for each gene</i></b><br>
* The gene identifier must be the same that is used in the metabolic GPRs rules, to link a metabolic gene to a regulatory rule. 
<b>Example</b>: if you have a reaction R1 that have two associated genes b0536 and b2567 and they are affected by a regulatory rule, you must define a column containing the identifiers (b0536 and b2567) of these two genes. 
<br>
<br>
<b>2. <i>A column with the identifiers that will map a rule to the other rules</i></b><br>
If you have three regulatory genes and do you want to associate them by the respective regulatory rule identifiers, you have to define these associations as shown in the following example:
     rule identifiers   regulatory rules
         tf1             R_Substrate>0
         tf2             NOT tf1
         tf3             tf4 OR NOT tf2

As shown in the previous example the rule identifier must be the same that is used in the regulatory rule, thus, the tf2 regulatory rule  is linked  to the tf1 regulatory rule by the tf1 identifier, and the tf3 regulatory rule is linked to tf2 regulatory rule by the tf2 identifier. Is advisable to use the names of the transcriptional factors to perform these associations.   
<br>
<br>
<b>3. <i>A column describing the regulatory rules for each gene</i></b><br>
* The regulatory rules must be defined in the last column of your regulatory file.


= Build a new project containing an integrated model =

User can build a project with an integrated model in two distinctive ways:

===1. Through the "New Project Wizard Operation"===

[[Image:MakeIntegratedProject.png]]

At the moment it is only possible to build an integrated model using the wizard operation from Flat Files, (new Formats will be available in a near future version).  

* '''Step 1'''
[[Image:Loadprojectfrommodel.png]]

* '''Step 2'''
[[Image:SelectionModelFiles.png]]


The user have to choose the the ''toy.fluxes'' file as the '''Reactions File'''; the ''toy.matrix'' file as the '''Matrix File'''; the ''toy.metab'' file as the '''Metabolites File'''; the ''toy.gr'' file as the '''GPR Information''' and the ''toy.regNet'' file as the '''Regulatory Model File'''.

* '''Reader Configuration'''

[[Image:ReaderConfiguration.png]]

In this step some definitions can be selected (depending from the type of the delimiters that are used on user Flat Files)

Continue to next panel '''Step 3''' by pressing ''next''. The user can select any of the options presented in the panel '''Step 3''' or continue to next panel '''Step 4'''.

* '''Step 4'''
[[Image:SelectBiomassGrowth.png]]

After selecting the biomass reaction, press the ''Finish'' button and a new project will be created. The model components will be displayed on '''Clipboard''' panel at left.

[[Image:Clipboard.png]]

===2. From an existing project ===

To create an integrated model project by this way it's required to have a metabolic model project already loaded (for more information click [[OptFlux3:CORE:NewProject|here]]).
It's mandatory that the previous loaded metabolic model, have the GPR Rules information.  

[[Image:MenuCreateRegulatoryModelWay2.png]]

* The following dialog panel will be displayed

[[Image:NewIntegratedModelProject.png]]

<b>1. <i>Project</i></b><br>
You can select the model/project to integrate the regulatory model.<br>
<br>
<b>2. <i>Choose Regulatory model reader type</i></b><br>
You can select the type of reader for the regulatory network.<br>
<br>
<b>3. <i>Choose Regulatory model file</i></b><br>
You can select the regulatory model file. In our example the regulatory model file name is toy.regNet.<br>
<br>

After pressing the ''Ok'' button the new project will be created, and the model components will be displayed on '''Clipboard'''.

=How to perform a mutant simulation=

* You can access the Simulation option under the '''Simulation->Regulatory''' menu or right clicking on the Integrated Model icon on the clipboard. 


[[Image:MenuRegulatorySimulation.png]]

* In both simulation types you can select the project to work, and set up your configuration.

=== Regulatory Model Simulation ===

[[Image:RegulatoryNetworkSimulation2.png|800px]]
<br>
<b>1. <i>Select genes to knockout</i></b><br>
Selecting in the Gene list you can add/remove (using the arrows buttons) genes to the knockout list (the list of genes to be knocked out, in the right).<br>
Genes can be displayed by '''Name''' or '''ID'''. 
<br>
<br>
<b>2. <i>Variables</i></b><br>
Here you can define which variables (present in metabolic model or regulatory model) are to be considered in the simulation of the regulatory network.<br>
<br>
<b>3. <i>Simulation Method</i></b><br>
Methods to perform the regulatory network simulation. In future new methods will be added.<br> 
<br>
<b>4. <i>First Step Boolean Simulation</i></b><br>
This parameter is related to '''BRNV''' simulation method (define how genes are knockout at beginning of regulatory simulation) , for example the user can assign a initial set of knockout genes instead of using the predefined ''OptFlux Strategy''. 
<br>
*And that's all!! You can press OK and the results will be loaded into the clipboard.<br>


=== Integrated Model Simulation ===

[[Image:IntegratedmodelSimulation2.png|800px]]

<br>
<b>1. <i>Select genes to knockout</i></b><br>
Selecting in the Gene list you can add/remove (using the arrows buttons) genes to the knockout list (the list of genes to be knocked out, in the right).
<br>
<br>
<b>2. <i>Select Environmental Conditions</i></b><br>
If you have created [[Environmental conditions|environmental conditions]] you can select them to be used as constraints in the simulation. These can be used to define the values of drain fluxes, i.e. the rates at which metabolites are consumed or produced.<br>
<br>
<b>3. <i>Objective Function Definition </i></b><br>
Here you can select the reaction to optimize (biomass, by default), and you can also define if you will be maximizing or minimizing that flux.<br>
<br>
<b>4. <i>Set Regulatory Variables</i></b><br>
Here you can define the value of all regulatory user variables, and see the values of the model variables.<br>
<br>
<b>5. <i>Select Simulation Method</i></b><br>
OptFlux can use several simulation methods for knockout simulations, namely:<br>
'''SR-FBA''' and '''Integrated_BRN''' plus: ''FBA'' or ''pFBA'' or ''MOMA''<br>
<br>
*And that's all!! You can press OK and the results will be loaded into the clipboard.<br>
[[Image:SimulationResult.png]]


==Critical Genes==

The regulatory plug-in allows the users to define which are the genes present on the integrated model that are essential for the strain to survive, i.e. to keep a value of growth (biomass reaction flux) different from zero. The essential genes can be calculated using the simulation algorithms presented in the regulatory plugin. Also, the software allows the user to load these genes or reactions from a file (if they are available). The list of essential genes can be manually edited, allowing users to add or remove elements, given their knowledge or the purpose of their experiments.

===How to do load critical genes from a file===

*To load the information from a file just access the '''Load Critical Regulatory Genes''' option under the '''Import->Load Critical Regulatory Genes''' menu in the Project Menu or right click on the Integrated Model icon in the clipboard.


[[Image:MenuLoadCriticalGenesRegulatory.png]]
<br>
<br>
*The following dialog will be displayed.
<br>
[[Image:LoadCriticalRegulatoryGenes.png‎]]
<br>
<br>
<b>1. <i>Select Project</i></b><br>
You can select a project to assign the set of critical regulatory genes.<br>
<br>
<b>2. <i>Select File</i></b><br>
You can select the file that have the critical genes information.<br>
<br>
*Now press OK and you can see a new element on the clipboard with the loaded critical genes.
<br>
[[Image:CriticalGenesClipboard.png‎]]

===How to determining essential genes===
*You can access the '''Compute Critical Regulatory Genes''' option under the '''Analysis->Regulatory->Compute Critical Regulatory Genes''' menu or by right clicking on the Integrated Model icon on the clipboard.

[[Image:MenuCriticalGenesRegulatory.png]]<br>
<br>

[[Image:ComputeCriticalRegulatoryGenes.png‎|400px]]
<br>
<b>1. <i>Select Project</i></b><br>
You can select a project to assign the set of critical regulatory genes.<br>
<br>
<b>2. <i>Set Regulatory User Variables</i></b><br>
Here you can define the value of all regulatory user variables, and see the values of the model variables.<br>
<br>
<b>3. <i>Select Environmental Conditions</i></b><br>
If you have created environmental conditions you can select them to be used as constraints in the critical genes/reactions calculation. This means that in this case you will calculate essential genes in a given environment.<br>
<br>
<b>4. <i>Select Simulation Method</i></b><br>
The critical genes operation can be performed using the same simulation methods, described in the ''Integrated Model Simulation'' section.<br>
<br>

*And that's all !! Now you can press OK and check the results in the clipboard.
[[Image:CriticalGenesClipboard.png‎‎]]

==How to optimize the gene knockouts set==
*You can access the '''Optimization''' option under the '''Optimization->Regulatory Optimization''' menu.<br>
[[Image:MenuRegulatoryOptimization.png]]<br>
<br>
*The following dialog will be displayed.<br>
[[Image:OptimizationRegulatoryoperation.png|800px]]
<br>
<br>
<b>1. <i>Select Project </i></b><br>
In the Project combo box select the project where you want to perform the
optimization.<br>
<br>
<b>2. <i>Select Simulation Method</i></b><br>
OptFlux can use several simulation methods for knockout simulations, namely:<br>
'''SR-FBA''' and '''Integrated_BRN''' plus: ''FBA'' or ''pFBA'' or ''MOMA''<br>
<br>
<b>3. <i>Select Environmental Conditions</i></b><br>
If you have created [[Environmental conditions|environmental conditions]] you can select them to be used as constraints in the simulation.<br>
<br>
<b>4. <i>Select Critical Genes</i></b><br>
If you have created or calculated a critical genes set, you can select them to be used in the simulation.<br>
<br>
<b>5. <i>Select Objective Functions</i></b><br>
OptFlux can use two types of objective function:<br>
''BPCY - Biomass-Product Coupled Yield'';
<br>
''YIELD - Product Yield with Minimum Biomass''.
<br>
<br>
The first calculates the product of the biomass flux and the compound production flux; the second, returns the value of the target compound production flux divided by the substrate consumption flux, if the biomass is larger than a minimum value, defined by the user<br>
<br>
<b>6. <i>Select Optimization Algorithm</i></b><br>
Three optimization algorithms can be used:<br>
''Strengh Pareto Evolutionary Algorithm (MultiObjective algorithm)'';
<br>
''Evolutionary Algorithm'';
<br>
''Simulated Annealing''.
<br>
<br>
<b>7. <i>Maximum Number of knockouts</i></b><br>
Is used to define the maximum of allowed gene knockouts, if '''Variable solution size''' is selected the solution will vary between 0 and maximum knockouts.
<br>
<br>
<b>8. <i>Variables</i></b><br>
Here you can define the value of all regulatory user variables, and see the values of the model variables.<br>
<br>
<b>8. <i>First Step Boolean Simulation</i></b><br>
This parameter is related to '''BRNV''' simulation method (define how genes are knockout at beginning of regulatory simulation) , for example the user can assign a initial set of knockout genes instead of using the predefined ''OptFlux Strategy''. 
<br>
===Analysing optimization solutions===
<br>
When the optimization procedure completes, the solutions will be sent to the OptFlux clipboard: 
<br>
<br>
[[Image:ClipboardOptimizationRegulatory.png]]
<br>
<br>
Clicking it will launch the following view: 
<br>
[[Image:RegulatoryOptimizationResults.png|800px]]
<br>
<br>
*The optimization view contains three distinct sections: 
**(TOP) The List of solutions and respective fitnesses.
**(BOTTOM-LEFT) The decoded solution (you must select a solution either in the list or in the chart). This list will display the suggested gene deletions for the selected solution.
**(BOTOM-RIGHT) The chart displaying the trade-of solutions (This chart is displayed as a pareto front when multiple objective functions were used, otherwise, the solutions will be ploted with the single objective function as the Y axis only) 
<br>
*Pressing the '''<< Add to simulation''' results button, will send the selected solutions to the list of simulations in the clipboard.
@@ Line 33: / Line 33: @@
 * Is possible to define a regulatory model by describing only the genes that have an associated regulatory rule, or a regulatory model containing all the genes that are present in the metabolic model and the regulatory model.
-<b>In the implementation of the regulatory model is mandatory the description of the following elements:</b>
+<b>In the implementation of the regulatory model is mandatory the description of the following elements for each gene rule:</b>
 <b>1. <i>A column containing the  identifiers for each gene</i></b><br>
@@ Line 50: / Line 50: @@
 <br>
 <br>
 <b>3. <i>A column describing the regulatory rules for each gene</i></b><br>
 * The regulatory rules must be defined in the last column of your regulatory file.
-<br>
-<b>A column describing the name for each one of the genes that are present in the regulatory model can be also defined (this is an optional feature)</b>
-<br>
-===Examples===
-The following figure shows a regulatory model in an excel file format containing only the genes with an associated regulatory rule. The first column contains the gene identifiers, the second column contains the gene names (optional), the third column contains the rule identifiers and the last column contains the regulatory rules.<br>
-[[Image:excel_example.png]]
-<br>
-<br>
-The next figure, shows a regulatory model in a comma-separated values file format containing all genes (includes also all metabolic genes). However, the name of the genes are not described in the regulatory file.<br>
-[[Image:csvfile_example.png]]
-<br>
-<br>
-<b>Note</b>: <i>If the regulatory model contains any rule with external stimuli, such as lys-L(e)>0, leu-L(e)>0, etc..., these elements must have the same identifier of the drain reactions (the drain reaction ID) of the metabolic model</i>.
 = Build a new project containing an integrated model =
@@ Line 76: / Line 62: @@
 [[Image:MakeIntegratedProject.png]]
+At the moment it is only possible to build an integrated model using the wizard operation from Flat Files, (new Formats will be available in a near future version).
 * '''Step 1'''
-<gallery mode="packed" widths=600px heights=600px >
+[[Image:Loadprojectfrommodel.png]]
-File:createintegratedproject_flatfiles.png|Create an integrated model project using a metabolic model in flat files format and a regulatory model in excel or csv format.
-File:createintegratedproject_sbml.png|Create an integrated model project using a metabolic model in SBML file format and a regulatory model in excel or csv format.
-</gallery>
 * '''Step 2'''
-<gallery mode="packed" widths=600px heights=600px >
+[[Image:SelectionModelFiles.png]]
-File:selectflatfiles_reg_model.png|Select the metabolic model flat files and the regulatory model in excel or csv format.
-File:selectsbml_reg_model.png|Select the metabolic model SBML file and the regulatory model in excel or csv format.
-</gallery>
+The user have to choose the the ''toy.fluxes'' file as the '''Reactions File'''; the ''toy.matrix'' file as the '''Matrix File'''; the ''toy.metab'' file as the '''Metabolites File'''; the ''toy.gr'' file as the '''GPR Information''' and the ''toy.regNet'' file as the '''Regulatory Model File'''.
 * '''Reader Configuration'''
-<gallery mode="packed" widths=600px heights=600px >
+[[Image:ReaderConfiguration.png]]
-File:readerconfiguration_flatfiles.png|Select the respective columns according your regulatory model configuration, and select the delimiters that you are using on your Flat Files.
-File:readerconfiguration_sbml.png|Select the respective columns according your regulatory model configuration.
-</gallery>
 In this step some definitions can be selected (depending from the type of the delimiters that are used on user Flat Files)
@@ Line 118: / Line 97: @@
 * The following dialog panel will be displayed
-[[Image:New_Integrated Model Project_from_another.png]]
+[[Image:NewIntegratedModelProject.png]]
 <b>1. <i>Project</i></b><br>
 You can select the model/project to integrate the regulatory model.<br>
 <br>
-<b>2. <i>Select Regulatory Model File</i></b><br>
+<b>2. <i>Choose Regulatory model reader type</i></b><br>
-You can select the regulatory model file in excel or csv file format<br>
+You can select the type of reader for the regulatory network.<br>
 <br>
-<b>3. <i>Select Auxiliar Model File</i></b><br>
+<b>3. <i>Choose Regulatory model file</i></b><br>
-You can select an auxiliary file to the regulatory model, where are described the type (condition or transcritional factor) of identifiers that the plugin is not be able to perform the automatic detection of its type. These are shown in a specific panel, when the regulatory model is loaded and they can be saved as an <b>"auxiliar model file"</b> for future use.<br>
+You can select the regulatory model file. In our example the regulatory model file name is toy.regNet.<br>
 <br>
-<b>4. <i>Select the respective columns according your regulatory model configuration</i></b><br>
 After pressing the ''Ok'' button the new project will be created, and the model components will be displayed on '''Clipboard'''.