scope                 package:scope                 R Documentation

_S_p_e_c_i_f_y _A_r_b_i_t_r_a_r_y _R_o_w _N_a_m_e _S_u_b_s_e_t_s

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

     Create or refine a list of vectors of row names.  Each vector
     corresponds to  a row in a data frame, and its elements identify
     rows relevant to that row. Relevance is determined by the passed
     arguments.  Refinement consists of  passing the output back to the
     function with further criteria, effectively  nesting serial
     restrictions (scope can shrink but not grow).

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

     scope(x, this, FUN = NULL, that = NULL, scope = NULL, ...)
     "[<-.scope"(x,...,value)
     "[.scope"(x, ..., drop = TRUE)
     "[[.scope"(x, ..., drop = TRUE)
     c.scope(..., recursive = FALSE)

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

       x: A data frame.

    this: A column name in 'x', representing the first argument to
          'FUN'.

     FUN: A function taking two arguments, typically a comparison
          operator.

    that: A column name in 'x', representing the second argument to
          'FUN'; or a vector of same length as columns in 'x'; or an
          atomic value to be recycled.

   scope: A scope object, e.g. created by previous use of 'scope()'.
          Specifically, a list (same length as columns in 'x') of
          vectors of row  names in 'x'. An atomic character string will
          be understood as an element of x.

     ...: Extra arguments passed to FUN.

   value: Used internally by the subset assignment method for scope.

    drop: Used internally by the subset and element-selection methods
          for scope; defaults to TRUE.

recursive: Used internally by the c() method for scope; defaults to
          FALSE.

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

     A data frame and one of its column names must be specified ('x',
     'this').  Defaults  are chosen so that if nothing else is
     specified, per-row scope will be all  rows with the same value of
     'this' as the row in question.  'FUN' will operate on 'this' and
     'that', within 'scope', which is all rows, by default.  All 
     row-specific values  of 'this' within 'scope' will be compared to
     the row-specific value of 'that'. If comparison  evaluates to
     'TRUE', the corresponding row name is retained in the return
     value.

     'this' is usually atomic.  If it contains more than one (valid)
     column name,  and if no other arguments are supplied, the scope
     object will be constructed by  using the columns as factors in a
     multi-way classification of rows (using 'tapply'). Such usage is a
     shortcut for serial scoping (each iteration passing the scope
     object  from the previous iteration) where 'FUN' is always "=="
     and 'that' is  always the same as 'this' (the defaults).

     'FUN' is typically a binary operator, but must accept extra
     arguments.  'scope()'  will pass any extra arguments supplied. 
     Also, 'scope()' will pass the extra argument "row", which is a
     character vector of row names (taken from 'x') for the current
     comparison.

     For each element, 'format.scope()' prints the name, the first and
     last member, and the length. 'print.scope()' gives all the details
     (vector values, i.e. corresponding row names).

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

     A list of vectors, one per row in 'x', of relevant row names in
     'x'.  'print.scope()' has been defined.

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

     'score', 'skim', 'scoop', 'probe'

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

     data(Theoph)
     #For each row, consider only those rows with the same Subject
     S <- scope(x=Theoph, this='Subject', FUN='==', that='Subject')
     #Same effect as...
     S <- scope(Theoph,'Subject')
     #For each row within Subject, consider only those rows having non-zero times.
     S2 <- scope(Theoph,'Time','>',0,scope=S)

