mkg                  package:ccems                  R Documentation

_M_a_k_e _G_e_n_e_r_i_c _M_o_d_e_l

_D_e_s_c_r_i_p_t_i_o_n:

     This function maps network topology information into a generic
     full spur graph model.    If 'TCC' is 'TRUE' (default) it also
     automatically generates  and compiles total concentration
     constraint C code and stores it in the 'models' subdirectory.

_U_s_a_g_e:

      mkg(strct,TCC=TRUE,activity=FALSE,free=FALSE) 

_A_r_g_u_m_e_n_t_s:

   strct: The thread topology of the equilibrium network  (see
          'ccems'). The slots of this list structure are: 'heads' which
          is a character vector of the head nodes of threads  of the
          first site in 'sites'; and 'sites' which is a list of sites
          where each site is a list of  character vectors of non-head
          thread nodes.  Naming conventions are given below under 'Z'.  

     TCC: This is 'TRUE' if total concentration constraints (TCCs) are
          to be used. If so, model C code is automatically generated
          and compiled. If 'TCC' is 'FALSE' a rational polynomial model
          is automatically generated as an R function component of the
          output.   Use of rational polynomial models assumes that the
          approximations [Xfree] = [XT] are reasonable for all non-hub
          species X (i.e. ligands).

activity: If 'TRUE' data fitted is enzyme activity data. In this case
          the substrate variable should be named S. 

    free: Set 'TRUE' if non-hub reactants are to be treated as free
          concentrations.  

_D_e_t_a_i_l_s:

     This function is typically the first 'ccems' function called in a
     script.  It creates a list of objects generic to the entire model
     space, i.e. a model space kernel.

_V_a_l_u_e:

     A list comprised of the inputs and the following:  

     id : The biochemical equilibrium system ID. This is the set of
          single character reactant representations collapsed into one
          string. 

hubChar : The first character of the first name in 'strct'. As of ver
          1.02 this is no longer a passed option. 

      Z : The names of the hub protein complexes expressed as single
          character reactant symbols followed by the number of copies
          of it in the complex. For example, R2t1 is a dimer of R with
          one bound ligand t, R2t2 is saturated dimer, and R2t0 is
          ligand free dimer.  The choice of the symbol Z for hub
          complexes derives from its common use as a complex number. 

      nZ: The length of 'Z'. An 'n' in front of a name often implies a
          length. 

  atomS : A character vector of atom/reactant names where the term atom
          refers to reactant molecules being indivisible  in the system
          of interest. A capital 'S' at the end of a name implies a
          string.

 nAtomS : The length of 'atomS'.

specieS : A character vector equal to 'c(atomS,Z)', i.e. the names of
          all of the chemical species. 

nSpecieS : The length of 'specieS'.

reactantS : A list with component names equal to complex names and
          values equal  to vectors of the 'atomS' that comprise them.

      W : A dataframe of copy numbers/weights of atoms (column names)
          in each species (row names). 

    KdS : Subscript names of the dissociation constants, one for each
          element of 'Z'.  Binary K sit in positions of their products
          and use '"_"' to separate their reactants; spur edges (e.g.
          head nodes) take their names from 'Z'.  

    hdS : The names of the head nodes.

    hds : The positions of the head nodes within the Z vector of
          complex nodes.

 sstime : The amount of ODE integration time used to reach steady state
          when solving TCCs (preset to 1e6). Since integration uses
          variable step sizes which rapidly become large near steady
          state, overkill is OK.

   rtol : An 'lsoda' integration relative error tolerance parameter:
          'rtol'=1e-5.  

   atol : An 'lsoda' integration absolute error tolerance parameter:
          'atol'=1e-7.  

parmsTCC: The parameters of the total concentration constraints passed
          to the .dll (or .so)  when using 'lsoda'. These include the
          total concentrations (i.e. system inputs). 

initialStateTCC: The initial conditions (default zero) used to solve
          the TCC ODEs.

dfThread: A dataframe of the thread within site and oligo structure.

 threads: A nested list of the thread structure with threads at the top
          of the list and their contents and memberships below.

threadsWithinSites: A list  of threads within sites, i.e. the list
          indices are sites.

nodesWithinSites: A list of non-head nodes within sites.

usedLets: A vector of the single characters used to label Kd equivalent
          threads. Currently, if there is  more than one thread, entire
          threads are either completely equal or all free to be
          different. If the curtain contains a single thread, then that
          thread can have patches of contiguous blocks that are equal. 
          Thus, a curtain with n threads has n used letters, but a
          curtain with one thread has as many used  letters as there
          are nodes in that one thread. 

   fback: A function that maps a vector of free concentrations into  a
          vector of complex concentrations given the current set of
          complete  dissociation constant estimates of the optimization
          algorithm.

   code : If 'TCC = TRUE' this is the C code of the TCC ODE right hand
          side.   This code is automatically compiled for use by
          'lsoda'.

     The 'TCC' flag, which passes unchanged from input to output, is
     used by 'simulateData' to determine how the expected response
     surface is to be generated.

_N_o_t_e:

     Kd and Kj are generic grid and spur edge names, respectively.  The
     name 'KdS' above is thus a grid-like name. That it is used to
     describe hybrid models that include head node spur edges is
     consistent with their  allowance in a generalized definition of
     grid graphs.

     In the description of 'KdS' above "reactants" is used generically
     to mean a complex or a ligand, but by far, it refers most often to
      purified substances of known controlled amounts (i.e. the
     experimentally  manipulated variables or the reactants that are
     initially present). This common usage is  synonymous with the use
     of "atoms" above, which emphasizes their indivisible building
     block nature in the non-covalent binding equilibriums of interest. 

     This work was supported by the National Cancer Institute
     (K25CA104791).

_A_u_t_h_o_r(_s):

     Tom Radivoyevitch

_R_e_f_e_r_e_n_c_e_s:

     Radivoyevitch, T. (2008) Equilibrium model selection: dTTP induced
     R1 dimerization.  _BMC Systems Biology_ *2*, 15.

_S_e_e _A_l_s_o:

     'ccems','ems'

_E_x_a_m_p_l_e_s:

     library(ccems)
     topology <- list(  
             heads=c("R1t0","R2t0"),  
             sites=list(       
                     s=list(                     # s-site    thread #
                             m=c("R1t1"),        # monomer      1
                             d=c("R2t1","R2t2")  # dimer        2
                     )
             )
     ) 
     mkg(topology) 

