Title: Maximizing Polyclonal Selection Gains Using Integer Programming
Version: 1.0.2
Description: Implements an Integer Programming-based method for optimising genetic gain in polyclonal selection, where the goal is to select a group of genotypes that jointly meet multi-trait selection criteria. The method uses predictors of genotypic effects obtained from the fitting of mixed models. Its application is demonstrated with grapevine data, but is applicable to other species and breeding contexts. For more details see Surgy et al. (2025) <doi:10.1007/s00122-025-04885-0>.
License: GPL (≥ 3)
Encoding: UTF-8
RoxygenNote: 7.3.2
BugReports: https://github.com/soniasurgy/maxRgain/issues
Imports: lpSolve, utils, stats
Suggests: knitr, rmarkdown, roxygen2, devtools, usethis
VignetteBuilder: knitr
Depends: R (≥ 3.5.0)
LazyData: true
NeedsCompilation: no
Packaged: 2025-07-30 12:12:50 UTC; Asus
Author: Sónia Surgy [aut, cre], Elsa Gonçalves [aut], Jorge Cadima [aut]
Maintainer: Sónia Surgy <soniasurgy@isa.ulisboa.pt>
Repository: CRAN
Date/Publication: 2025-08-18 14:30:02 UTC

maxRgain: Polyclonal genetic selection in grapevine varieties based on integer programming

Description

maxRgain is a package that optimizes polyclonal selection using integer programming. The optimization aims to select groups of clones while maximizing genetic gains and simultaneously complying with user-defined constraints on several traits. This method is described in Surgy, S., Cadima, J. & Gonçalves, E. (2025) Integer programming as a powerful tool for polyclonal selection in ancient grapevine varieties. Theor Appl Genet 138, 122 . doi:10.1007/s00122-025-04885-0 Some examples from the publication are included.

Author(s)

Maintainer: Sónia Surgy soniasurgy@isa.ulisboa.pt

Authors:

See Also

Useful links:

Gouveio variety dataset

Description

A dataset containing the Empirical Best Linear Unbiased Predictors (EBLUP) of genotypic effects obtained by the fitting of linear mixed models with the observations from polyclonal selection field trials of variety Gouveio.

Usage

Gouveio

Format

An object of class data.frame with 150 rows and 6 columns.

Details

Clone

the genotype label

yd

EBLUP of the genotypic effect of yield

pa

EBLUP of the genotypic effect of potential alcool

ta

EBLUP of the genotypic effect of total acidity

bw

EBLUP of the genotypic effect of berry weight

ph

EBLUP of the genotypic effect of pH

Results for output_rmaxa objects

Description

Objects of class output_rmaxa represent maximum admissible gains for each trait.

Usage

## S3 method for class 'output_rmaxa'
print(x, ...)

Arguments

x

An object of class output_rmaxa

...

Additional arguments passed to methods (currently unused)

Value

Invisibly returns the input object x

Results for output_rmaxp objects

Description

Objects of class output_rmaxp represent maximum possible gains for each trait.

Usage

## S3 method for class 'output_rmaxp'
print(x, ...)

Arguments

x

An object of class output_rmaxp

...

Additional arguments passed to methods (currently unused)

Value

Invisibly returns the input object x

Integer programming calculations

Description

This function maximizes the predicted genetic gain in the selection of groups of genotypes based on the predictors of genotypic effects.

Usage

polyclonal(
  traits,
  ref = NULL,
  clmin = 2,
  clmax,
  dmg = NULL,
  meanvec = NULL,
  criteria = NULL,
  data
)

Arguments

traits

A vector with the names of the columns in the data corresponding to the target traits to be optimized, i.e., those included in the objective function.

ref

Name of the reference column (e.g., genotype ID). Defaults to the first column.

clmin

An integer specifying the minimum group size. If omitted, equal to 2.

clmax

An integer specifying the maximum group size. If omitted, equal to clmin.

dmg

A data.frame with three columns defining constraints: trait names; constraints signs (">=", "<=" or "=="); and right-hand side values of the constraints.

meanvec

A named numeric vector of trait means; if omitted, data are assumed to be already normalized by the mean.

criteria

A named numeric vector indicating the selection criterion for each trait: 1 for traits to be increased, -1 for traits to be decreased. If omitted, all traits are assumed to be selected for increase.

data

A data frame comprising the input data consisting of the Predictors of genetic effects, which serve as the basis for the selection procedure.

Value

A list with the following components:

Note

The order of traits must be consistent across traits, dmg, meanvec, and criteria. Both meanvec and criteria must include values for all traits specified in traits and dmg.

References

Surgy, S., Cadima, J. & Gonçalves, E. Integer programming as a powerful tool for polyclonal selection in ancient grapevine varieties. Theor Appl Genet 138, 122 (2025). doi:10.1007/s00122-025-04885-0

Examples

mymeanvec <- c(yd = 3.517, pa = 12.760, ta = 4.495, ph = 3.927, bw = 1.653)
mytraits <- c("yd", "pa",  "ta", "ph", "bw")
mydmg <- data.frame(
  lhs = c("yd", "pa", "ta", "ph", "bw"),
  rel = c(">=", ">=", ">=", ">=", ">="),
  rhs = c(20, 3, 3, 1, 2)
  )
mycriteria <- c(yd = 1, pa = 1, ta = 1, ph = -1, bw = -1)
selections <- polyclonal(
   traits = mytraits,
   clmin = 7,
   clmax = 20,
   dmg = mydmg,
   meanvec = mymeanvec,
   criteria = mycriteria,
   data = Gouveio
   )
selections
summary(selections)

Polyclonal selection results

Description

Objects of class polyresult contain the results returned by the polyclonal function.

Prints the predicted genetic gains and selected genotypes.

Provides a summary of the results returned by polyclonal().

Usage

## S3 method for class 'polyresult'
print(x, ...)

## S3 method for class 'polyresult'
summary(object, ...)

Arguments

x

An object of class polyresult

...

Further arguments passed to methods (currently unused)

object

An object of class polyresult

Value

Invisibly returns the input object x

Invisibly returns the input object object

Maximum admissible gain

Description

The maximum admissible genetic gain in one trait that can be achieved without decreasing any of the other traits, as a percentage of the overall mean. This function calculates the maximum admissible gains achieved in the specified traits.

Usage

rmaxa(
  traits,
  ref = NULL,
  clmin = 2,
  clmax,
  constraints = NULL,
  meanvec = NULL,
  criteria = NULL,
  data
)

Arguments

traits

A vector with the names of the columns in the data corresponding to the target traits to be optimized, i.e., those included in the objective function.

ref

Name of the reference column (e.g., genotype ID). Defaults to the first column.

clmin

An integer specifying the minimum group size. If omitted, equal to 2.

clmax

An integer specifying the maximum group size. If omitted, equal to clmin.

constraints

Vector with traits to which constraints apply. If omitted, all except ref are used.

meanvec

A named numeric vector of trait means; if omitted, data are assumed to be already normalized by the mean.

criteria

A named numeric vector indicating the selection criterion for each trait: 1 for traits to be increased, -1 for traits to be decreased. If omitted, all traits are assumed to be selected for increase.

data

A data frame comprising the input data consisting of the Predictors of genetic effects, which serve as the basis for the selection procedure.

Value

A list with the following components:

Note

The order of traits must be consistent across traits, constraints, meanvec, and criteria. Both meanvec and criteria must include values for all traits specified in traits and constraints. If constraints is omitted, all traits in the dataset are considered; in that case, meanvec and criteria must provide values for all of them.

References

Surgy, S., Cadima, J. & Gonçalves, E. Integer programming as a powerful tool for polyclonal selection in ancient grapevine varieties. Theor Appl Genet 138, 122 (2025). doi:10.1007/s00122-025-04885-0

Examples

mymeanvec <- c(yd = 3.517, pa = 12.760, ta = 4.495, ph = 3.927, bw = 1.653)
mytraits <- c("yd", "pa")
mycriteria <- c(yd = 1, pa = 1, ta = 1, ph = -1, bw = -1)
maxadm <- rmaxa(
   traits = mytraits,
   clmin = 7,
   clmax = 20,
   meanvec = mymeanvec,
   criteria = mycriteria,
   data = Gouveio
   )
maxadm

Maximum possible gain

Description

The maximum possible is the mean of the EBLUPs of the genotypic effects of the best n clones in a given trait, as a percentage of the overall mean. This function calculates the maximum possible gain achieved in the specified traits.

Usage

rmaxp(
  traits,
  ref = NULL,
  clmin = 2,
  clmax,
  meanvec = NULL,
  criteria = NULL,
  data
)

Arguments

traits

A vector with the names of the columns in the data corresponding to the target traits to be optimized, i.e., those included in the objective function.

ref

Name of the reference column (e.g., genotype ID). Defaults to the first column.

clmin

An integer specifying the minimum group size. If omitted, equal to 2.

clmax

An integer specifying the maximum group size. If omitted, equal to clmin.

meanvec

A named numeric vector of trait means; if omitted, data are assumed to be already normalized by the mean.

criteria

A named numeric vector indicating the selection criterion for each trait: 1 for traits to be increased, -1 for traits to be decreased. If omitted, all traits are assumed to be selected for increase.

data

A data frame comprising the input data consisting of the Predictors of genetic effects, which serve as the basis for the selection procedure.

Value

A list with the following components:

Note

The order of the traits must be consistent across traits, meanvec, and criteria.

References

Surgy, S., Cadima, J. & Gonçalves, E. Integer programming as a powerful tool for polyclonal selection in ancient grapevine varieties. Theor Appl Genet 138, 122 (2025). doi:10.1007/s00122-025-04885-0

Examples

mymeanvec <- c(pa = 12.760)
mytraits <- c("pa")
maxpos <- rmaxp(
   traits = mytraits,
   clmin = 7,
   clmax = 20,
   meanvec = mymeanvec,
   data = Gouveio
   )
maxpos