mkModel                package:ccems                R Documentation

_M_a_k_e _S_p_e_c_i_f_i_c _M_o_d_e_l

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

     This function takes a generic model input list 'g' and augments it
     to include data and a specific hypothesis. The hypotheses come in
     the form of claims that certain Kj are so large that the data
     cannot discriminate them from being infinity, that certain Kd are
     so close in value that the data cannot distinguish them from being
     equal, and that the protein proportion that is active is so  close
     to 1 that the data cannot discriminate it from being 1. 
     Hypotheses regarding enzyme activity parameters k being
     essentially  equal to others on an average per occupied catalytic
     site basis can also be made.

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

      mkModel(g,mid,d=NULL,Kjparams=NULL,Kdparams=NULL,Keq=NULL,
             Kd2KjLst=NULL, pparams=c(p=1i), kparams=NULL,
             keq=NULL, tightLogic=TRUE, indx=NULL, nParams=NULL) 

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

       g: The output of 'mkg'.  

     mid: The name of the specific hypothesis/model. The convention is
          that I stands for infinity,  J for a freely estimated spur
          graph edge, H for a freely estimated grid head node,  and D,
          E, F, etc. (i.e. other characters) for grid Kd that are equal
          to each other. In the latter case the same letter in two
          different positions  indicates equality between them;
          positions in model name strings are the binary reaction
          product node positions in 'g$Z', see 'mkg'). When k
          constraints exist they preceded by the  K name (a period
          separates them) and they follow   single thread curtain
          conventions (k constraints  for larger curtains remain to be
          worked out). The model name, which becomes 'g$mid', should
          not be confused with the name of the biochemical system
          'g$id'.    

       d: The data as a dataframe.  

Kjparams: If the hypothesis is a spur model, this is a numeric  vector
          of its initial complete dissociation constant parameter
          values.     

Kdparams: If the hypothesis is a generalized grid model these  are the
          initial dissociation constant parameter values:  head node
          spur edges are distinguished from thread  edges by not having
          '"_"' in their names.   

     Keq: This character vector specifies which Kd parameters are equal
          to each other. Names are followers  and values leaders in the
          sense of parameters constrained to track each other.  

Kd2KjLst: This is a list of functions (see 'mkKd2Kj') that maps
          generalized  grid Kd parameters into full spur model Kj
          parameters.  An appropriate component of this list is
          assigned to 'g$Kd2Kj'. Such functions are needed so that one
          generic full spur graph model, typically compiled in C, can
          be used by all of the specific hypotheses/models of the model
          space. 

 pparams: This is the fraction of hub protein that is active. The pure
          imaginary default of '1i' keeps it fixed at 1 (minus 1 also
          achieves this).  An initial value of +1 indicates that it is
          to be optimized.     

 kparams: These are the enzyme activity parameter initial values,  if
          the data is reaction rate data, else it should be 'NULL'.   

     keq: These are the equality constraints (if any) that are being
          placed on the enzyme activity parameters.  

tightLogic: If 'tightLogic' is true, instead of taking Kj to .001 as an
          approximation of infinitely tight binding,  logic is used to
          model Kj = 0 exactly. 

    indx: This is an integer index of the model.  The current
          hypothesis is the 'indx'th model of the model space.  

 nParams: The number of model parameters, i.e. the first column of a
          'chunk' data frame. 

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

     Infinite initial Kj parameters remain fixed at 'Inf' and are
     passed from R to C properly to eliminate corresponding polynomial
     terms in the  total concentration constraints.

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

     The input object 'g' augmented to include the arguments 'd', 'mid'
     and 'indx' and the following:   

  params: A dataframe specification of the parameter's initial values
          and whether they are optimized or fixed or  constrained to
          track others. Final value placeholders are initialized to
          initial values. 

 Kparams: This is either 'Kjparams' or 'Kdparams'.  It is the one of
          the two which is not 'NULL'. In cases of hybrids 'Kdparams'
          is used.

   codeS: This is the name of the component of 'Kd2KjLst' that is
          relevant to the current hypothesis. It  is a string of digits
          whose binary representation indicates which threads are
          infinite.  

   Kd2Kj: This is the component of 'Kd2KjLst' that is  relevant to the
          current hypothesis, i.e. 'Kd2Kj = Kd2KjLst[[codeS]]'. 

    fitS: A string indicator of the status of the model fitting. It is
          initialized here to '"not fitted yet"'. 

   typeY: The type of output. This is 'm' for average mass and 'v' for
          reaction velocity. 

    posY: This is the column number of the output measurement in the
          data dataframe 'd'. 

posReactantsD: These are the column numbers of the total reactant 
          concentrations (system inputs) in the data dataframe 'd'.

     The value returned by this function is a model object that is
     ready to be fitted by 'fitModel'.

_N_o_t_e:

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

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

     Tom Radivoyevitch (txr24@case.edu)

_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:

     'mkg', 'mkKd2Kj' and 'fitModel'.

_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
                     )
             )
     ) 
     g <- mkg(topology,TCC=TRUE) 

     data(RNR)
     dRt <- subset(RNR,(year==2001)&(fg==1)&(G==0)&(t>0),select=c(R,t,m,year))
     names(dRt)[1:2] <- c("RT","tT") 

     ## first a simple spur model
     mkModel(g,"IIIJ",dRt,Kjparams=c(R2t0=Inf, R1t1=Inf, R2t1=Inf, R2t2=1))
     Kmapping=mkKd2Kj(g)
     mdl=mkModel(g,"HDFF",dRt,Kdparams=c(R2t0=1, R0t0_t=1, R2t0_t=1, R2t1_t=1), 
                       Keq=c(R2t1_t="R2t0_t"),Kd2KjLst=Kmapping) 
     fmdl <- fitModel(mdl)

     ## or mkGrids can be used to achieve the same thing as follows
     gridL <- mkGrids(g,maxTotalPs=3)
     chunk <- gridL$chunk
     Keqs <- gridL$Keqs
     mdl <- mkModel(g,"HDFF",dRt,Kdparams=chunk["HDFF",2:(g$nZ+1)], Keq=Keqs[["HDFF"]], Kd2KjLst=Kmapping,
            pparams=chunk["HDFF","p",drop=FALSE],indx=chunk["HDFF","indx"])
     print(mdl)
     print(chunk)
     print(Keqs)

