COBRAmodels:fire:code headers:art: add tutorials

src/design/TrimGdel/GRPRchecker.m

@@ -1,38 +1,40 @@
-function [GR ,PR] = GRPRchecker(model, targetMet, givenGvalue)
+function [GR ,PR] = GRPRchecker(model, targetMet, gvalue)
 % GRPRchecker calculates the maximum GR and the minimu PR 
 % under the GR maximization when a constraint-based model, a target
 % metabolite, and a gene deletion stratety are given.
 %
-% function [GR, PR]  
-%      = GRPRchecker(model, targetMet, givenGvalue)
+% USAGE:
 %
-% INPUTS
-%  model     COBRA model structure containing the following required fields to perform gDel_minRN.
-%    rxns                    Rxns in the model
-%    mets                    Metabolites in the model
-%    genes               Genes in the model
-%    grRules            Gene-protein-reaction relations in the model
-%    S                       Stoichiometric matrix (sparse)
-%    b                       RHS of Sv = b (usually zeros)
-%    c                       Objective coefficients
-%    lb                      Lower bounds for fluxes
-%    ub                      Upper bounds for fluxes
-%    rev                     Reversibility of fluxes
+%    function [GR, PR]  
+%        = GRPRchecker(model, targetMet, givenGvalue)
 %
-%  targetMet   target metabolites
-%              (e.g.,  'btn_c')
-%  givenGvalue    The first column is the list of genes in the original model.
-%                 The second column contains a 0/1 vector indicating which genes should be deleted.
-%                 0 indicates genes to be deleted.
-%                 1 indecates genes to be remained.
+% INPUTS:
+%    model:     COBRA model structure containing the following required fields to perform gDel_minRN.
 %
-% OUTPUTS
-%  GR        the growth rate obained when the gene deletion strategy is
-%            applied and the growth rate is maximized.
-%  PR        the minimum target metabolite production rate obained 
-%            when the gene deletion strategy is applied and the growth rate is maximized.
+%        *.rxns:       Rxns in the model
+%        *.mets:       Metabolites in the model
+%        *.genes:      Genes in the model
+%        *.grRules:    Gene-protein-reaction relations in the model
+%        *.S:          Stoichiometric matrix (sparse)
+%        *.b:          RHS of Sv = b (usually zeros)
+%        *.c:          Objective coefficients
+%        *.lb:         Lower bounds for fluxes
+%        *.ub:         Upper bounds for fluxes
+%        *.rev:        Reversibility of fluxes
 %
-%   Feb. 10, 2025  Takeyuki TAMURA
+%    targetMet:    target metabolites    (e.g.,  'btn_c')
+%    gvalue:       The first column is the list of genes in the original model.
+%                  The second column contains a 0/1 vector indicating which genes should be deleted.
+%                      0: indicates genes to be deleted.
+%                      1: indecates genes to be remained.
+%
+% OUTPUTS:
+%    GR:    the growth rate obained when the gene deletion strategy is
+%           applied and the growth rate is maximized.
+%    PR:    the minimum target metabolite production rate obained 
+%           when the gene deletion strategy is applied and the growth rate is maximized.
+% 
+% .. Author:    - Takeyuki Tamura, Mar 06, 2025
 %
 
 
@@ -46,7 +48,7 @@
 
 
 model2 = model;
-[grRules0] = calculateGR(model, givenGvalue);
+[grRules0] = calculateGR(model, gvalue);
 lb2 = model.lb;
 ub2 = model.ub;
 

src/design/TrimGdel/TrimGdel.m

@@ -1,5 +1,4 @@
 function [gvalue, GR, PR, size1, size2, size3, success] = TrimGdel(model, targetMet, maxLoop, PRLB, GRLB)
-%
 % TrimGdel appropriately considers GPR rules and determines 
 % a minimal gene deletion strategies to achieve growth-coupled production 
 % for a given target metabolite and a genome-scale model.
@@ -8,66 +7,70 @@
 % Gurobi is required for this version. 
 % The CPLEX version is available on https://github.com/MetNetComp/TrimGdel
 %
-% function [gvalue, GR, PR, size1, size2, size3, success] 
-%                  = TrimGdel(model, targetMet, maxLoop, PRLB, GRLB)
+% USAGE:
+%
+%    function [gvalue, GR, PR, size1, size2, size3, success] 
+%                      = TrimGdel(model, targetMet, maxLoop, PRLB, GRLB)
+%
+% INPUTS:
+%    model:    COBRA model structure containing the following required fields to perform gDel_minRN.
 %
-% INPUTS
-%  model     COBRA model structure containing the following required fields to perform gDel_minRN.
-%    rxns                    Rxns in the model
-%    mets                    Metabolites in the model
-%    genes               Genes in the model
-%    grRules            Gene-protein-reaction relations in the model
-%    S                       Stoichiometric matrix (sparse)
-%    b                       RHS of Sv = b (usually zeros)
-%    c                       Objective coefficients
-%    lb                      Lower bounds for fluxes
-%    ub                      Upper bounds for fluxes
-%    rev                     Reversibility of fluxes
+%        *.rxns:       Rxns in the model
+%        *.mets:       Metabolites in the model
+%        *.genes:      Genes in the model
+%        *.grRules:    Gene-protein-reaction relations in the model
+%        *.S:          Stoichiometric matrix (sparse)
+%        *.b:          RHS of Sv = b (usually zeros)
+%        *.c:          Objective coefficients
+%        *.lb:         Lower bounds for fluxes
+%        *.ub:         Upper bounds for fluxes
+%        *.rev:        Reversibility of fluxes
 %
-%  targetMet   target metabolites
-%             (e.g.,  'btn_c')
-%  maxLoop   the maximum number of iterations in gDel_minRN
-%  PRLB           the minimum required production rates of the target metabolites
-%                     when gDel-minRN searches the gene deletion
-%                     strategy candidates. 
-%                     (But it is not ensured to achieve this minimum required value
-%                      when GR is maximized withoug PRLB.)
-%  GRLB         the minimum required growth rate 
-%                     when gDel-minRN searches the gene deletion
-%                     strategy candidates. 
+%    targetMet:    target metabolites    (e.g.,  'btn_c')
+%    maxLoop:      the maximum number of iterations in gDel_minRN
+%    PRLB:         the minimum required production rates of the target metabolites
+%                  when gDel-minRN searches the gene deletion
+%                  strategy candidates. 
+%                  (But it is not ensured to achieve this minimum required value
+%                  when GR is maximized withoug PRLB.)
+%    GRLB:         the minimum required growth rate 
+%                  when gDel-minRN searches the gene deletion
+%                  strategy candidates. 
 %
-% OUTPUTS
-%  gvalue       a small gene deletion strategy (obtained by TrimGdel).
-%              The first column is the list of genes.
-%              The second column is a 0/1 vector indicating which genes should be deleted.
-%              0 indicates genes to be deleted.
-%              1 indecates genes to be remained.
-%  GR           the maximum growth rate when the obtained gene deletion
-%              strategy represented by gvalue is applied.
-%  PR           the minimum production rate of the target metabolite under 
-%              the maximization of the growth rate when the obtained gene deletion
-%              strategy represented by gvalue is applied.
-%  size1        the number of gene deletions after Step1.
-%  size2        the number of gene deletions after Step2.
-%  size3        the number of gene deletions after Step3.
-%  success      indicates whether TrimGdel obained an appropriate gene
-%               deletion strategy. (1:success, 0:failure)
+% OUTPUTS:
+%    gvalue:     a small gene deletion strategy (obtained by TrimGdel).
+%                The first column is the list of genes.
+%                The second column is a 0/1 vector indicating which genes should be deleted.
+%                    0: indicates genes to be deleted.
+%                    1: indecates genes to be remained.
+%    GR:         the maximum growth rate when the obtained gene deletion
+%                strategy represented by gvalue is applied.
+%    PR:         the minimum production rate of the target metabolite under 
+%                the maximization of the growth rate when the obtained gene deletion
+%                strategy represented by gvalue is applied.
+%    size1:      the number of gene deletions after Step1.
+%    size2:      the number of gene deletions after Step2.
+%    size3:      the number of gene deletions after Step3.
+%    success:    indicates whether TrimGdel obained an appropriate gene
+%                deletion strategy. (1:success, 0:failure)
 %
-%   T. Tamura, "Trimming Gene Deletion Strategies for Growth-Coupled 
-%   Production in Constraint-Based Metabolic Networks: TrimGdel," 
-%   in IEEE/ACM Transactions on Computational Biology and Bioinformatics,
-%   vol. 20, no. 2, pp. 1540-1549, 2023.
+% NOTE:
 %
-%   Comprehensive computational results are accumulated in MetNetComp
-%   database.
-%   https://metnetcomp.github.io/database1/indexFiles/index.html
+%    T. Tamura, "Trimming Gene Deletion Strategies for Growth-Coupled 
+%    Production in Constraint-Based Metabolic Networks: TrimGdel," 
+%    in IEEE/ACM Transactions on Computational Biology and Bioinformatics,
+%    vol. 20, no. 2, pp. 1540-1549, 2023.
 %
-%   T. Tamura, "MetNetComp: Database for Minimal and Maximal Gene-Deletion Strategies 
-%   for Growth-Coupled Production of Genome-Scale Metabolic Networks," 
-%   in IEEE/ACM Transactions on Computational Biology and Bioinformatics, 
-%   vol. 20, no. 6, pp. 3748-3758, 2023, 
+%    Comprehensive computational results are accumulated in MetNetComp
+%    database.
+%    https://metnetcomp.github.io/database1/indexFiles/index.html
 %
-%   Feb. 10, 2025  Takeyuki TAMURA
+%    T. Tamura, "MetNetComp: Database for Minimal and Maximal Gene-Deletion Strategies 
+%    for Growth-Coupled Production of Genome-Scale Metabolic Networks," 
+%    in IEEE/ACM Transactions on Computational Biology and Bioinformatics, 
+%    vol. 20, no. 6, pp. 3748-3758, 2023, 
+% 
+% .. Author:    - Takeyuki Tamura, Mar 06, 2025
 %
 
 [gvalue gr pr it success] = gDel_minRN(model, targetMet, maxLoop, PRLB, GRLB) % Step 1

src/design/TrimGdel/calculateGR.m

@@ -1,4 +1,45 @@
-function [grRules] = calculateGR(model, xname)
+function [grRules] = calculateGR(model, gvalue)
+% calculateGR is a function of gDel_minRN that reads
+% a COBRA model and a 0-1 assignment for genes and outputs whether
+% each reaction is repressed or not.
+%
+% USAGE:
+%
+%    function [grRules] = calculateGR(model, gvalue)
+%
+% INPUTS:
+%    model:    COBRA model structure containing the following required fields to perform gDel_minRN.
+%
+%        *.rxns:       Rxns in the model
+%        *.mets:       Metabolites in the model
+%        *.genes:      Genes in the model
+%        *.grRules:    Gene-protein-reaction relations in the model
+%        *.S:          Stoichiometric matrix (sparse)
+%        *.b:          RHS of Sv = b (usually zeros)
+%        *.c:          Objective coefficients
+%        *.lb:         Lower bounds for fluxes
+%        *.ub:         Upper bounds for fluxes
+%        *.rev:        Reversibility of fluxes
+%
+%    gvalue:    The first column is the list of genes in the original model.
+%               The second column contains a 0/1 vector indicating which genes should be deleted.
+%                   0: indicates genes to be deleted.
+%                   1: indecates genes to be remained.
+%
+% OUTPUT:
+%    grRules:    The first column is the list of GPR-rules. If a reaction does
+%                not have a GPR-rule, it is represented as 1.
+%                In the second columun, each gene is converted to 0 or 1 based
+%                on the given 0-1 assignment, with AND converted to * and OR
+%                converted to +.
+%                The third comumn contains the calculation results from the
+%                second column.
+%                The fourth column is 0 if the third column is 0 and 1 if it is
+%                greater. If it is 0, the reaction is repressed; if it is 1, it
+%                is not repressed.
+% 
+% .. Author:    - Takeyuki Tamura, Mar 06, 2025
+%
 
 grRules = cell(size(model.rxns));
 for i=1:size(model.grRules, 1)
@@ -12,9 +53,9 @@
 grRules(:, 2) = strrep(grRules, 'or', '+');
 grRules(:,2) = strrep(grRules(:,2), 'and', '*');
 
-[xname2, index] = sortrows(xname(:,1), 'descend');
+[xname2, index] = sortrows(gvalue(:,1), 'descend');
 for i=1:size(index, 1)
-   sorted_gvalue(i, 1) = xname{index(i, 1), 2}; 
+   sorted_gvalue(i, 1) = gvalue{index(i, 1), 2}; 
 end
 for i = 1:size(model.genes, 1)
     grRules(:, 2) = strrep(grRules(:, 2), xname2{i, 1},num2str(sorted_gvalue(i, 1)));

src/design/TrimGdel/example1.m

@@ -1,9 +1,14 @@
-function [outputArg1, outputArg2] = example1()
+function [] = example1()
 % example1 calculates the gene deletion strategy for growth coupling
 % for succinate in e_coli_core.
 %
-% Feb. 6, 2025  Takeyuki TAMURA
+% USAGE:
 %
+%     function [] = example1()
+%
+% .. Author:    - Takeyuki Tamura, Mar 05, 2025
+%
+
 
 load('e_coli_core.mat');
 model = e_coli_core;

src/design/TrimGdel/example2.m

@@ -1,8 +1,12 @@
 function [outputArg1, outputArg2] = example2()
 % example2 calculates the gene deletion strategy for growth coupling
 % for biotin in iML1515.
+% 
+% USAGE:
 %
-% Feb. 6, 2025  Takeyuki TAMURA
+%     function [] = example2()
+%
+% .. Author:    - Takeyuki Tamura, Mar 06, 2025
 %
 
 load('iML1515.mat');

src/design/TrimGdel/example3.m

@@ -1,8 +1,12 @@
 function [outputArg1, outputArg2] = example3()
 % example3 calculates the gene deletion strategy for growth coupling
 % for riboflavin in iML1515.
+% 
+% USAGE:
 %
-% Feb. 6, 2025  Takeyuki TAMURA
+%     function [] = example3()
+% 
+% .. Author:    - Takeyuki Tamura, Mar 06, 2025
 %
 
 load('iML1515.mat');

src/design/TrimGdel/example4.m

@@ -1,8 +1,12 @@
 function [outputArg1, outputArg2] = exampl4()
 % example4 calculates the gene deletion strategy for growth coupling
 % for pantothenate in iML1515.
+% 
+% USAGE:
 %
-% Feb. 6, 2025  Takeyuki TAMURA
+%     function [] = example4()
+%
+% .. Author:    - Takeyuki Tamura, Mar 06, 2025
 %
 
 load('iML1515.mat');

src/design/TrimGdel/example5.m

@@ -1,8 +1,12 @@
 function [outputArg1, outputArg2] = example5()
 % example5 calculates the gene deletion strategy for growth coupling
 % for succinate in iMM904.
+% 
+% USAGE:
 %
-% Feb. 6, 2025  Takeyuki TAMURA
+%     function [] = example5()
+%
+% .. Author:    - Takeyuki Tamura, Mar 06, 2025
 %
 
 load('iMM904.mat');