mkSpurs                package:ccems                R Documentation

_M_a_k_e _S_p_u_r _M_o_d_e_l _S_p_a_c_e

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

     This function takes 'g' from 'mkg' and maps it into a dataframe of
     spur graph model definitions.

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

      mkSpurs(g,state=list(globMdlIndex=0,globCmbIndex=0,relCmbIndex=0,config=NULL), maxnPs=NULL, 
               batchSize=500, pRows=FALSE, doTights=FALSE,atLeastOne=TRUE,IC=1) 

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

       g: The generic model output list of 'mkg'. 

   state: The current state of model space generation. Its components
          are:  'globMdlIndex' which is the global model space index 
          (when 'mkSpurs' is called within 'ems' spurs begin where
          grids end);  'globCmbIndex' which is the global spur model
          index  (this index is used to trim the last 'batchSize', if
          needed, to avoid attempts to extend the spur space size
          beyond its upper limit of '2^g$nZ'); and  'relCmbIndex' which
          is the most critical component (this is the column number of
          the current matrix output of 'combn', i.e. it is a relative
          index.   The spur space 'chunk' returned by this function
          begins just after this column.);  'config' is a vector of the
          integer positions in 'g$Z' of the  last model's finite K
          (i.e. the last model of the previous chunk). 'config'  is 
          the 'relCmbIndex' column of the current 'combn' matrix.  Its
          length is the current number of K parameters in the model
          unless 'relCmbIndex=0',  in which case the number of 
          parameters is one more than this  (in this case the end of
          the last batch coincides with the end of a 'combn' matrix). 

  maxnPs: The maximum number of parameters of models in the model
          space. Full chunks  are created and then trimmed, so this
          cannot solve  "out of memory" problems. 

batchSize: This is the number of K infinity models fitted per batch.
          Chunk sizes  are bigger than this if 'doTights' is 'TRUE'
          and/or   if 'pRows' is 'TRUE'. Values less than ~1000 are
          recommended. 

   pRows: Set to 'TRUE' if additional rows are to be added to the
          output dataframe  to include models with 'p' freely
          estimated. 

doTights: This should be 'TRUE' if infinitely tight binding models  of
          single edge spur graphs are to be created.

atLeastOne: Leave 'TRUE' if only models with at least one complex of
          maximal size are to be considered. Set 'FALSE' if there is no
          prior knowledge supportive of the assertion that the largest
          oligomer must be in the model.

      IC: The initial condition of all K parameters optimized. The
          default is 'IC=1'. 

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

     This function is complicated by the fact that one readily runs out
     of memory  with 29 complexes and thus roughly 500,000,000 spur
     models (in this case 8 GB RAM allows at most 16 bytes per model!).
       Thus, chunks of the spur model space must be created, fitted and
     summarized in sizes small enough to fit into memory.  As both an
     input and an output, 'state' links successive calls to this
     function.  It keeps track of where we are in the spur graph model
     space and it allows searches through  the low parameter number
     models without first defining all of the higher parameter number
     models (and thus consuming all of the RAM in the process).

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

     A list with components  

   chunk: A dataframe where each row is a spur model. 

   state: The state, defined in the same way as the input argument
          'state' since the output 'state' of one call is the input
          'state' of the next call.

maxReached: This is 'TRUE' if the maximum number of parameter has been
          reached.

lastCompleted: When all of the models with  j K parameters have been
          specified, 'lastCompleted' equals j.   This is useful in
          'ems' when 'smart = TRUE' as it defines how far into the
          model space AICs should be tested  for increases due to
          overparameterization.    

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

     'mkGrids', 'ccems', 'combn'

_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) 
     mkSpurs(g,pRows=TRUE,doTights=TRUE)

