optiSel (version 0.9.1)

opticont: Calculates Optimum Contributions of Selection Candidates

Description

Calculates optimum genetic contributions of selection candidates to the next generation.

Usage

opticont(method, K, phen, con=list(), solver="auto", quiet=FALSE, 
    make.definite=solver=="csdp", ...)

Arguments

method

Possible values are "min.VAR", and "max.VAR", where VAR is the name of a column in data frame phen, or "min.KIN", where KIN is the name of a kinship as defined by function kinlist. Use help.opticont to see the available objective functions.

K

List created by function kinlist, containing e.g. kinship matrices of the selection candidates.

phen

Data frame with IDs of selection candidates in column 1, and sex in column 2. The other columns may contain breeding values or migrant contributions. The sex is coded as 'male' and 'female'.

con

List defining the constraints. The compomnents are described in the Details section. If a component is missing, then the respective constraint is not applied. Use help.opticont to see the available constraints.

solver

Name of the algorithm for optimization. Available solvers are "alabama", "cccp", "cccp2", "csdp", and "slsqp". The default "auto" means that the solver is chosen automatically. The solvers are described in the Details section.

quiet

If quiet=FALSE then detailed information is shown.

make.definite

If make.definite=TRUE then all non-definite matrices are approximated by positive definite matrices before optimization. This is the default setting for the solver csdp.

...

Tuning parameters of the solver. The available parameters depend on the solver and will be printed when function opticont is used with default values. An overview is given in the Details section.

Value

A list with class "opticont" which has component parent. This is the data frame phen with the additional column oc containing the optimum genetic contribution of each selection candidate to the next generation, lb containing the lower bounds, and ub containing the upper bounds.

Details

Computation of optimum genetic contributions of selection candidates.

Constraints

Constraints are defined in argument con, which is a list whose components may have the following names:

ub.KIN: Upper bound for the mean kinship in the offspring, where KIN must be replaced by the name of a kinship as defined by function kinlist. Upper bounds for an arbitrary number of different kinships may be provided.

lb: Either a named vecor of the form c(M=a, F=b) containing lower bounds for the contributions of males (a) and females (b), or a N-vector containing the minimum permissible contribution of each selection candidate. The default is c(M=0, F=0).

ub: Either a named vecor of the form c(M=a, F=b) containing upper bounds for the contributions of males (a) and females (b), or a N-vector containing the maximum permissible contribution of each selection candidate. For M=-1 (F=-1) it is assumed that all males (females) have equal contributions to the offspring. If a number is NA then the number of offspring for that sex/individual is not bounded. The default is c(M=NA, F=NA).

lb.VAR: Lower bound for the expected mean value of variable VAR from data frame phen in the offspring. For example lb.BV=a defines a lower bound for the mean breeding value in the offspring to be a if data frame phen has column BV with breeding values of the parents. Lower bounds for an arbitrary number of variables can be defined.

ub.VAR: Upper bound for the mean value of variable VAR from data frame phen in the offspring. For example ub.MC=a defines the upper bound for the genetic contributions from migrant breeds in the offspring to be a if data frame phen has column MC with migrant contributions for the parents. Upper bounds for an arbitrary number of variables can be defined.

eq.VAR: Equality constraint for the mean value of variable VAR from data frame phen in the offspring. Equality constraints for an arbitrary number of variables can be defined.

Solver

"alabama": The augmented lagrangian minimization algorithm auglag from package alabama. The method combines the objective function and a penalty for each constraint into a single function. This modified objective function is then passed to another optimization algorithm with no constraints. If the constraints are violated by the solution of this sub-problem, then the size of the penalties is increased and the process is repeated. The default methods for the uncontrained optimization in the inner loop is the quasi-Newton method called BFGS. The available parameters used for the outer loop are described in the details section of the help page of function auglag. The available parameters used for the inner loop are described in the details section of the help page of function optim.

"cccp", "cccp2": Function cccp from package cccp for solving cone constrained convex programs. For cccp quadratic constraints are defined as second order cone constraints, whereas for cccp2 quadratic constraints are defined by functions. The implemented algorithms are partially ported from CVXOPT. The parameters are those from function ctrl. They are among others the maximum count of iterations as an integer value (maxiters), the feasible level of convergence to be achieved (feastol) and whether the solver's progress during the iterations is shown (trace). If numerical problems are encountered increase the optimization parameter feastol or reduce parameter stepadj.

"csdp": The problem is reformulated as a semidefinite programming problem and solved with the CSDP library. Non-definite matrices are approximated by positive definite matrices. This solver is not suitable when the objective is to minimize kinship at native alleles. Available parameters are described in the CSDP User's Guide: https://projects.coin-or.org/Csdp/export/49/trunk/doc/csdpuser.pdf.

"slsqp": The sequential (least-squares) quadratic programming (SQP) algorithm slsqp for gradient-based optimization from package nloptr. The algorithm optimizes successive second-order (quadratic/least-squares) approximations of the objective function, with first-order (affine) approximations of the constraints. Available parameters are described in nl.opts

Remark

If the function does not provide a valid result due to numerical problems then try the following modifications:

*	modify the optimization parameters,
*	use another solver,
*	change the order of the kinship constraints if more than one kinship is constrained,
*	define upper or lower bounds instead of equality constraints.
*	increase the upper bounds for the kinships.

Validity of the result can be checked with function summary.opticont. Use help.opticont to see available objective functions and constraints.

References

Borchers, B. (1999). CSDP, A C Library for Semidefinite Programming Optimization Methods and Software 11(1):613-623 http://euler.nmt.edu/~brian/csdppaper.pdf

Kraft, D. (1988). A software package for sequential quadratic programming, Technical Report DFVLR-FB 88-28, Institut fuer Dynamik der Flugsysteme, Oberpfaffenhofen, July 1988.

Lange K, Optimization, 2004, Springer.

Madsen K, Nielsen HB, Tingleff O, Optimization With Constraints, 2004, IMM, Technical University of Denmark.

Examples

# NOT RUN {
#################################################
# Example 1: Advanced OCS using pedigree data   #
# Objective: maximize genetic gain              #
# Constraints:                                  #
#   - mean kinship                              #
#   - mean kinship at native alleles            #
#   - genetic contributions from other breeds   #
#################################################
data(PedigWithErrors)
data(Phen)

keep  <- Phen$Indiv
Pedig <- prePed(PedigWithErrors, keep=keep, thisBreed="Hinterwaelder", lastNative=1970)
Pedig$MC <- 1-pedBreedComp(Pedig, thisBreed="Hinterwaelder")$native
Phen  <- merge(Pedig, Phen[,c("Indiv", "BV")], by="Indiv")
Kin   <- kinlist(pKin    = pedIBD(Pedig, keep.only=keep), 
                 pKinatN = pedIBDatN(Pedig, thisBreed="Hinterwaelder",  keep.only=keep))

head(Phen)
cor(Phen$MC, Phen$BV)
help.opticont(Kin, Phen)

# Compute offspring parameters for unselected population
noSel      <- opticont(method="min.pKin", K=Kin, phen=Phen, con=list(ub=c(M=-1, F=-1)))
noSel.s    <- summary(noSel)
round(noSel.s[,c("pKin","pKinatN", "meanMC", "meanBV")],4)
meanMC     <- noSel.s$meanMC
meanKin    <- noSel.s$pKin
meanKinatN <- noSel.s$pKinatN
meanBV     <- noSel.s$meanBV

# Define Constraints
Ne <- 100

con            <- list(ub=c(M=NA, F=-1))
con$ub.pKin    <- meanKin    + (1-meanKin   )*(1/(2*Ne))
con$ub.pKinatN <- meanKinatN + (1-meanKinatN)*(1/(2*Ne))
con$ub.MC      <- 0.97*meanMC

# Compute the genetic progress achievable
maxBV   <- opticont("max.BV", K=Kin, phen=Phen, con=con)
maxBV.s <- summary(maxBV)
maxBV.s$meanBV 
# [1] 0.5428925

# Get optimum contributions of sires
Sire <- maxBV$parent[maxBV$parent$Sex=="male",]
ord  <- order(Sire$oc, decreasing=TRUE)
head(Sire[ord,])

#################################################
# Example 2: Advanced OCS using genotype data   #
# Objective: minimize inbreeding                #
# Constraints:                                  #
#   - breeding values                           #
#   - mean kinship at native alleles            #
#   - genetic contributions from other breeds   #
#################################################

data(map)
data(Cattle)
dir   <- system.file("extdata", package = "optiSel")
files <- paste(dir, "/Chr", 1:2, ".phased", sep="")
Kin   <- kinlist(sKin    = segIBD(files, map, minSNP=20, minL=2.0), 
                 sKinatN = segIBDatN(files, Cattle, map, thisBreed="Angler", 
                                     ubFreq=0.01, minSNP=20, minL=2.0))
Haplo <- haplofreq(files, Cattle, map, thisBreed="Angler", 
                   minSNP=20, minL=2.0, ubFreq=0.01, what="match")
Comp  <- segBreedComp(Haplo$match, map)
Comp$MC <- 1-Comp$native
Phen  <- merge(Cattle, Comp[,c("Indiv", "MC")], by="Indiv", all=FALSE)

help.opticont(Kin, Phen)

cor(Phen$MC, Phen$BV,use="complete.obs")
#[1] 0.5033714

# Compute offspring parameters for unselected population
noSel      <- opticont(method="min.sKin", K=Kin, phen=Phen, con=list(ub=c(M=-1, F=-1)))
noSel.s    <- summary(noSel)
round(noSel.s[,c("sKin","sKinatN", "meanMC", "meanBV")],4)
meanMC     <- noSel.s$meanMC
meanKin    <- noSel.s$sKin
meanKinatN <- noSel.s$sKinatN
meanBV     <- noSel.s$meanBV

# Define Constraints
Ne <- 100

con            <- list(ub=c(M=NA, F=-1))
con$ub.sKinatN <- meanKinatN + (1-meanKinatN)*(1/(2*Ne))
con$ub.MC      <- 0.97*meanMC
con$lb.BV      <- meanBV

# Compute the smallest mean kinship achievable
minKin   <- opticont("min.sKin", K=Kin, phen=Phen, con=con)
minKin.s <- summary(minKin)
minKin.s$sKin
# [1] 0.03881304

# Get optimum contributions of sires
Sire <- minKin$parent[minKin$parent$Sex=="male",]
ord  <- order(Sire$oc, decreasing=TRUE)
head(Sire[ord,])
# }