varPed              package:MasterBayes              R Documentation

_T_r_a_n_s_f_o_r_m_s _V_a_r_i_a_b_l_e_s _f_o_r _a _M_u_l_t_i_n_o_m_i_a_l _L_o_g-_L_i_n_e_a_r _M_o_d_e_l

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

     Creates offspring specific design matrices the columns of which
     refer to the explanatory variables of the liner model.

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

     varPed(x, gender=NULL, lag=c(0,0), relational=FALSE, 
       lag_relational=c(0,0), restrict=NULL, keep=FALSE, 
       USvar=NULL, merge=FALSE, ...)

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

       x: predictor variable; numeric or factor

  gender: the gender of the parent to which 'x' applies

     lag: numeric vector of length 2. The time interval over which 'x'
          is evaluated relative to a record of the offspring.

relational: a character string. If "Offspring", calculates the distance
          between 'x' in the parents and 'x' in the offspring. If
          "Mate", calculates the distance between 'x' in the two
          parental sexes. If 'NULL', 'x' is untransformed.

lag_relational: numeric vector of length 2. If 'relational' is not
          empty then the time interval over which 'x' is evaluated in
          the relational category relative to the offspring record can
          be changed

restrict: Designates parents with a zero prior probability of
          parentage. logical or character string. If
          'relational="Offspring"' then 'restrict' may be 'TRUE' or
          'FALSE', and parents that and 'x' is a 'factor' then only
          parents with zero distance are retained as plausible
          candidates. If a character string only parents for which 'x'
          matches are retained.

    keep: logical; if 'TRUE' then the design matrices for parents
          excluded using the argument 'restrict' are retained in the
          estimation of beta

   USvar: if 'NULL', unsampled parents take the population mean value
          of the parameter.  If 'x' is a factor then 'USvar' can be a
          level of that factor to which unsampled parents belong.  If
          'x' is numeric then 'USvar' can be the value for unsampled
          parents. Is not implemented for 'relational=="MATE"' or
          interactions between male and female variables.

   merge: logical; if 'TRUE' then beta is the log odds ratio of an
          offspring's parent belonging to category A compared to
          category B, where A and B are levels of 'x'.  If 'FALSE' then
          beta is the log odds ratio of an individual belonging to
          category A being the parent of an offspring compared to an
          individual of category B.  Is not implemented for
          'relational=="MATE"' or interactions between male and female
          variables, and is only valid for  categorical variables.

     ...: further arguments to be passed

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

     The design matrix for each offspring represents the state of each
     parental (dam/sire) combination for each explanatory variable. The
     number of rows in the design matrix (the number of parental
     combinations) is free to vary across offspring, but the number of
     explanatory variables remain the same.  As with standard
     generalised linear modelling the columns of the design matrices
     take on numerical values or inidicator values for continuous and
     categorical variables, respectively.  When 'relational=FALSE',
     elements of the design matrices refering to specific parental
     combinations will not vary across offspring (unless longitudinal
     data are being used) and the associated vector of parameters will
     relate the explanatory variables to overall fecundity. For these
     variables the model is essentially the multinomial analogue of the
     more familiar Poisson model often used to analyse such data. 
     However, the counts of the multinomial are not known with
     certainty because uncertainty exists around the maternity and/or
     paternity of each offspring.

     Additional variables can fitted that relate specific parental
     combinations to specific offspring, or specific dams to specific
     sires.  Elements of the design matrices refering to specific
     parental combinations are then free to vary across offspring.  The
     most obvious variable of this type is the mendelian transition
     probability obtained from the genetic data themsleves. However, by
     specifying 'relational="OFFSPRING"', or  'relational="MATE"'
     non-genetic variables are free to vary across offspring. When 'x'
     is 'numeric' the Euclidean distances between parents and
     offspring, or between mates enter into the design matrix.   When
     'x' is a 'factor' then an indicator variable is set up indicating
     whether parent and offspring, or mate, factor levels match. 
     Often, each offspring will have a variable number of candidate
     parents as some parents may be excluded _a priori_. When 'x' is a
     'factor' and both 'relational="OFFSPRING"' and 'restrict=TRUE',
     only those potential parents that have factor levels matching the
     offspring factor level are retained.  When 'relational=FALSE',
     'restrict' can take on factor levels which exclude parents that
     have non-matching factor levels. 

     If a time variable ('timevar') is not passed to 'PdataPed' the
     data are assumed to be cross-sectional and each indivdiual only
     respresented once.  If a time variable ('timevar') is passed to
     'PdataPed' then 'lag' and 'lag_mate' can be set so that time
     specific covariates are used.  'lag' designates time units
     realtive to the offspring record when 'relational=FALSE'; for
     example, if 'lag=c(0,0)' the value of 'x' is taken for that parent
     during the same time period as the offspring record.   If
     'relational="OFFSPRING"' or 'relational="MATE"' then 'lag'
     determines the time units relative to the record of the offspring
     or mate to which the focal inidvidual is being compared.  This
     record can be specified by using 'lag_relational', which is always
     relative to the offspring record. Negative lags refer to previous
     time intervals (e.g. 'lag=c(-1,-1)' takes 'x' from the previous
     time step), and if the elements of 'lag' or 'lag_relational'
     differ then the average value of 'x' during this period is taken
     (e.g 'lag=c(-1,0)' averages 'x' in the record matching and
     preceding the offspring record).  This is not applicable when 'x'
     is a 'factor' unless 'restrict=TRUE' in which case parents are
     retained when factor levels match for any times in the specified
     interval. 

     Below are models that can be fitted using 'varPed', where 'x' is a
     univariate continuous variable:

     'varPed(x, gender="Female")'

                       p(i,j) = exp(b*x(i)...)


     'varPed(x, gender="Male")'

                       p(i,j) = exp(b*x(j)...)


     'varPed(x)'

                    p(i,j) = exp(b*(x(i)+x(j))...)


     'varPed(x, gender="Female", relational="OFFSPRING")'

                  p(i,j) = exp(b*abs(x(i)-x(o))...)


     'varPed(x, gender="Female", relational="MATE")'

                  p(i,j) = exp(b*abs(x(i)-x(j))...)


     'varPed(x, gender="Female", lag=c(-1,-1))'

                     p(i,j) = exp(b*x(i,t-1)...)


     'varPed(x, gender="Female", lag=c(-1,-1), relational="OFFSPRING")'

               p(i,j) = exp(b*abs(x(i,t-1)-x(o,t))...)


     'varPed(x, gender="Female", lag=c(0,0), relational="MATE",'

     '   lag_relational=c(-1,-1))'

                 p(i,j) = exp(b*(x(i,t)+x(j,t-1))...)


     For a categorical variable with two levels ('A' and 'B') the model
     specified by 'varPed(x, gender="Female")' takes on the form


                       p(i,j) = exp(b*I(i)...)


     where I(i) is an indicator variable taking the value 1 if x(i) is
     equal to the first level of 'x' and zero otherwise. beta is then
     the log odds ratio of the two levels of 'x' with respect to
     maternity.  If 'merge=TRUE' is specified then beta may vary across
     offspring, and b_m is estimated. b_m is related to b:


         b_m = logit(((theta*N_A)/(N_A*theta+N_B*(1-theta)))


     where theta is the inverse logit transformation of b, and N_A and
     N_B are the number of potential mothers that have level 'A' and
     'B' for 'x'. If N_A and N_B are invariant over offspring the
     models are functionally equivalent.

     The denominator of the multinomial likelihood is the summed linear
     predictors of all possible parents (after setting up a contrast
     with the baseline parents).  Designating the first set of parents
     as baseline, the contrast for each set of parents is simply:


                     eta(i,j)=log(p(i,j)/p(1,1))


     and the likelihood of b is 


     Pr(x| b) = prod(no)(exp(eta(d,s))/sum(ni*nj)(exp(eta(i,j))))


     where no, ni and nj are the number of offspring, the number of
     potential mothers for offspring o, and the number of potential
     fathers for offspring o, respectively.  d and s are the actual
     parents of offspring o. The set of possible parents  in the
     denominator of the multinomial likelihood are those that are not
     excluded using the argument 'restrict'. However, if the argument
     'keep=TRUE' is used then the denominator of the likelihood will
     include excluded parents depsite the fact that d!=i and s!=j.

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

     list containing the design matrix for variable 'x', the identity
     of retained parents and the gender of the parents

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

     Jarrod Hadfield j.hadfield@sheffield.ac.uk

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

     Hadfield J.D. _et al_ (2006) Molecular Ecology 15 3715-31

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

     'MCMCped'

