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  zero
     and/or equal to each other 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' in the case of a spur model and the
          output list 'mkGrids()$g' in the case of a grid model.  

     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 this case the same letter in two different
          positions indicates equality between them, where positions
          are the binary reaction product node positions in 'g$Z', see
          'mkg'). This ID, 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/grid 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 output is a reaction rate, 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 constraint model.

_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'. 

   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 position of the system output measurement
          in the data dataframe 'd'. 

posReactantsD: These are the column positions of the total reactant
          concentrations (system inputs) in the data dataframe 'd'. 
          This is needed because the order of the reactant

     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),indx=1)

     ## next three grid graphs
     gridL <- mkGrids(g,3)
     g <- gridL$g
     chunk <- gridL$chunk
     Keqs <- gridL$Keqs
     Kmapping <- mkKd2Kj(g)
     models <- NULL
     mdlNames <- rownames(chunk)
     for (j in mdlNames) models[[j]] <- mkModel(g=gridL$g,j,dRt,Kdparams=chunk[j,2:(g$nZ+1),drop=FALSE],
                             Keq=Keqs[[j]],Kd2KjLst=Kmapping,pparams=chunk[j,"p",drop=FALSE],indx=chunk[j,"indx"])
     print(models[[3]])
     print(chunk)

