Preparations to fit a genetic-spatial competition models for forestry

This function builds the genetic competition matrix ($\mathbf{Z}_c$), and prepares the dataset to be used for model fitting. It also computes the competition intensity factor.

prepfor(
  data,
  gen,
  row,
  col,
  trait,
  plt = NULL,
  effs = NULL,
  dist.row,
  dist.col,
  method = "SK",
  area = NULL,
  age = NULL,
  n.dec = 2,
  verbose = FALSE
)

Arguments

data: A data frame containing the phenotypic data.
gen, row, col, trait: A string. The name of the columns that correspond to the genotype, row, column, and trait information, respectively.
plt: A string or NULL. The name of the column that contain the plot information. Useful to properly indicate the direction of data collection. If NULL (default), the function will automatically generate a column after ordering the data set by row and col
effs: a string vector with column names of other effects that will be considered in model fitting step. Defaults to NULL (if there is no further effect).
dist.row, dist.col: An integer. The distance between rows and columns in the trial.
method: A string. The method for computing the competition intensity in $\mathbf{Z}_c$. It has three options: "MU" for the method proposed by Muir (2005), "CC" for the method proposed by Cappa and Cantet (2008), and "SK" for the method proposed by Costa e Silva and Kerr (2013) (default). See Details for more information.
area: A string. The name of the column that corresponds to the area information. Valid if the trial has non-contiguous blocks, for e.g., blocks 1 and 2 in area 1, and blocks 3 and 4 in area 2. NULL (default) otherwise.
age: A string. The name of the column that corresponds to the age information. Necessary for fitting a multi-age model. NULL (default) otherwise.
n.dec: An integer. The number of decimal digits to be displayed in $\mathbf{Z}_c$. Defaults to 2.
verbose: A logical value. If TRUE, a progress bar will be displayed in the console. Defaults to FALSE.

Value

The function returns:

Z : The $\mathbf{Z}_c$ matrix
data : A data frame composed of the built $\mathbf{Z}_c$ merged with the dataset provided by the user.
neigh_check : A data frame containing the phenotypic records of each focal plant and its neighbours.

Details

Three methods are available for estimating the competition intensity and building the $\mathbf{Z}_c$, the genetic competition matrix:

Muir (2005): "MU"

The average competition intensity is the inverse of the distance between the focal plant and its neighbours:

$$f_{D_v} = \frac{1}{\sqrt{d_R^2 + d_C^2}}$$

$$f_{R_v} = \frac{1}{d_R}$$

$$f_{C_v} = \frac{1}{d_C}$$

where $f_{D_v}$, $f_{R_v}$ and $f_{C_v}$ are the average competition intensities in the diagonal, row, and column directions of the $v^{th}$ clone, respectively; and $d_R$ and $d_C$ are the inter-row and inter-column distances.

Cappa and Cantet (2008): "CC"

The average competition intensity depends on the number of neighbours in each direction

$$f_{D_v} = \frac{1}{\sqrt{2(n_{C_v} + n_{R_v}) + n_{D_v}}}$$

$$f_{R_v} = \sqrt{\frac{2}{2(n_{C_v} + n_{R_v}) + n_{D_v}}}$$

$$f_{C_v} = \sqrt{\frac{2}{2(n_{C_v} + n_{R_v}) + n_{D_v}}}$$

where $n_{D_v}$, $n_{R_v}$ and $n_{C_v}$ are the number of neighbours in the diagonal, row and column directions of the $v^{th}$ clone, respectively. Note that, in this case, it is assumed that the distance between rows and columns are the same.

Costa e Silva and Kerr (2013): "SK"

The average competition intensity depends on both the distance between the focal tree and its neighbours, and the number of neighbours in each direction:

$$f_{D_v} = \frac{p}{\sqrt{(n_{R_v} p^4) + (n_{R_v} p^2) + (n_{C_v} p^2) + (n_{D_v} p^2) + n_{C_v}}}$$

$$f_{R_v} = f_{D_v} \sqrt{1 + p^2}$$

$$f_{C_v} = \frac{f_{D_v} \sqrt{1 + p^2}}{p}$$

where $p = \frac{d_C}{d_R}$.

The overall competition intensity factor ($CIF$) is estimated by taking the mean of the competition intensities provided by the equations described above, and the mean number of neighbours in each direction:

$$CIF = \overline{n_D} \overline{f_D} + \overline{n_R} \overline{f_R} + \overline{n_C} \overline{f_C}$$

References

Cappa, E.P., Cantet, R.J.C., 2008. Direct and competition additive effects in tree breeding: Bayesian estimation from an individual tree mixed model. Silvae Genetica 57, 45–56. doi:10.1515/sg-2008-0008

Costa e Silva, J., Kerr, R.J., 2013. Accounting for competition in genetic analysis, with particular emphasis on forest genetic trials. Tree Genetics & Genomes 9, 1–17. doi:10.1007/s11295-012-0521-8

Muir, W.M., 2005. Incorporation of competitive effects in forest tree or animal breeding programs. Genetics 170, 1247–1259. doi:10.1534/genetics.104.035956

Examples

# \donttest{
 library(gencomp)
 comp_mat = prepfor(data = euca, gen = 'clone', area = 'area',
                    plt = 'tree', age = 'age', row = 'row', col = 'col',
                    dist.col = 3, dist.row = 2, trait = 'MAI', method = 'SK',
                    n.dec = 3, verbose = FALSE, effs = c("block"))
# }