SelectionProtocol#

class pybrops.breed.prot.sel.SelectionProtocol.SelectionProtocol(ncross, nparent, nmating, nprogeny, nobj, obj_wt=None, obj_trans=None, obj_trans_kwargs=None, nineqcv=None, ineqcv_wt=None, ineqcv_trans=None, ineqcv_trans_kwargs=None, neqcv=None, eqcv_wt=None, eqcv_trans=None, eqcv_trans_kwargs=None, ndset_wt=None, ndset_trans=None, ndset_trans_kwargs=None, rng=None, soalgo=None, moalgo=None, **kwargs)[source]#

Bases: object

A semi-abstract class implementing several key properties common to most, if not all, constrained selection protocols.

Constructor for the semi-abstract class SelectionProtocol.

Parameters:

ncross (Integral) – Number of cross configurations to consider.
nparent (Integral) – Number of parents per cross configuration.
nmating (Integral, numpy.ndarray) –
Number of matings per configuration.

If nmating is Integral, then broadcast to a numpy.ndarray of shape (ncross,).

If nmating is numpy.ndarray, then the array must be of type Integral and of shape (ncross,).
nprogeny (Integral, numpy.ndarray) –
Number of progeny to derive from each mating event.

If nprogeny is Integral, then broadcast to a numpy.ndarray of shape (ncross,).

If nprogeny is numpy.ndarray, then the array must be of type Integral and of shape (ncross,).
nobj (Integral) – Number of optimization objectives when constructing a SelectionProblem. This is equivalent to the vector length returned by the obj_trans function. Must be Integral greater than 0.
obj_wt (numpy.ndarray, Real, None) –
Objective function weights. Weights from this vector are applied to objective function values via the Hadamard product. If values are 1.0 or -1.0, this can be used to specify minimizing and maximizing objectives, respectively.

If obj_wt is numpy.ndarray, then the array must be of shape (nobj,).

If obj_wt is Real, then the value is broadcast to a numpy.ndarray of shape (nobj,).

If obj_wt is None, then the value 1.0 is broadcast to a numpy.ndarray of shape (nobj,). This assumes that all objectives are to be minimized.
obj_trans (Callable, None) –
A function which transforms values from a latent objective space to the objective space. This transformation function must have the following signature:
```
def obj_trans(
        decnvec: numpy.ndarray,
        latentvec: numpy.ndarray,
        **kwargs: dict
    ) -> numpy.ndarray:
    # do stuff
    return output
```
Where:
- decnvec is a numpy.ndarray containing the decision vector.
- latentvec is a numpy.ndarray containing the latent space
  objective function values which are to be transformed.
- kwargs is a dict containing additional keyword arguments.
If obj_trans is None, then default to an identity objective transformation function.
obj_trans_kwargs (dict) –
Keyword arguments for the latent space to objective space transformation function.

If obj_trans_kwargs` is None, then default to an empty dictionary.
nineqcv (Integral, None) –
Number of inequality constraint violation functions. This is equivalent to the vector length returned by the ineqcv_trans function. Must be Integral greater than or equal to zero.

If nineqcv is None, then set to zero.
ineqcv_wt (numpy.ndarray, None) –
Inequality constraint violation function weights. Weights from this vector are applied to inequality constraint violation function values via the Hadamard product. If values are 1.0 or -1.0, this can be used to specify minimizing and maximizing constraints, respectively.

If ineqcv_wt is numpy.ndarray, then the array must be of shape (nineqcv,).

If ineqcv_wt is Real, then the value is broadcast to a numpy.ndarray of shape (nineqcv,).

If ineqcv_wt is None, then the value 1.0 is broadcast to a numpy.ndarray of shape (nineqcv,). This assumes that all constraints are to be minimized.
ineqcv_trans (Callable, None) –
A function which transforms values from a latent objective space to the inequality constraint violation space. This transformation function must have the following signature:
```
def ineqcv_trans(
        decnvec: numpy.ndarray,
        latentvec: numpy.ndarray,
        **kwargs: dict
    ) -> numpy.ndarray:
    # do stuff
    return output
```
Where:
- decnvec is a numpy.ndarray containing the decision vector.
- latentvec is a numpy.ndarray containing the latent space
  objective function values which are to be transformed.
- kwargs is a dict containing additional keyword arguments.
If ineqcv_trans is None, then default to a transformation function returning an empty vector.
ineqcv_trans_kwargs (dict, None) –
Keyword arguments for the latent space to inequality constraint violation transformation function.

If ineqcv_trans_kwargs` is None, then default to an empty dictionary.
neqcv (Integral, None) –
Number of equality constraint violations. This is equivalent to the vector length returned by the eqcv_trans function. Must be Integral greater than or equal to zero.

If neqcv is None, then set to zero.
eqcv_wt (numpy.ndarray, None) –
Equality constraint violation function weights. Weights from this vector are applied to equality constraint violation function values via the Hadamard product. If values are 1.0 or -1.0, this can be used to specify minimizing and maximizing constraints, respectively.

If eqcv_wt is numpy.ndarray, then the array must be of shape (neqcv,).

If eqcv_wt is Real, then the value is broadcast to a numpy.ndarray of shape (neqcv,).

If eqcv_wt is None, then the value 1.0 is broadcast to a numpy.ndarray of shape (neqcv,). This assumes that all constraints are to be minimized.
eqcv_trans (Callable, None) –
A function which transforms values from a latent objective space to the equality constraint violation space. This transformation function must have the following signature:
```
def eqcv_trans(
        decnvec: numpy.ndarray,
        latentvec: numpy.ndarray,
        **kwargs: dict
    ) -> numpy.ndarray:
    # do stuff
    return output
```
Where:
- decnvec is a numpy.ndarray containing the decision vector.
- latentvec is a numpy.ndarray containing the latent space
  objective function values which are to be transformed.
- kwargs is a dict containing additional keyword arguments.
If eqcv_trans is None, then default to a transformation function returning an empty vector.
eqcv_trans_kwargs (dict, None) –
Keyword arguments for the latent space to equality constraint violation transformation function.

If eqcv_trans_kwargs` is None, then default to an empty dictionary.
ndset_wt (Real, None) –
Nondominated set weight. The weight from this function is applied to outputs from ndset_trans. If values are 1.0 or -1.0, this can be used to specify minimizing and maximizing objectives, respectively.

If ndset_wt is None, then it is set to the default value of 1.0. This assumes that the objective is to be minimized.
ndset_trans (Callable, None) –
A function which transforms values from the non-dominated set objective space to the single-objective space. This transformation function must have the following signature:
```
def ndset_trans(
        mat: numpy.ndarray,
        **kwargs: dict
    ) -> numpy.ndarray:
    # do stuff
    return output
```
Where:
- mat is a numpy.ndarray containing a point coordinate array
  of shape (npt, nobj) where npt is the number of points and nobj is the number of objectives (dimensions). This array contains input points for calculating the distance between a point to the vector vec_wt.
- kwargs is a dict containing additional keyword arguments.
If ndset_trans is None, then default to a transformation function calculating the distance between a weight vector and provided points
ndset_trans_kwargs (dict, None) –
Nondominated set transformation function keyword arguments.

If ndset_trans_kwargs is None, then default to defaults for the default ndset_trans function:
```
ndset_trans_kwargs = {
    "obj_wt": numpy.repeat(1.0, nobj),
    "vec_wt": numpy.repeat(1.0, nobj)
}
```
rng (numpy.random.Generator, numpy.random.RandomState, None) –
Random number source.

If rng is None, default to the global random number generator.
soalgo (OptimizationAlgorithm, None) –
Single-objective optimization algorithm.

If soalgo is None, then use a default single-objective optimization algorithm.
moalgo (OptimizationAlgorithm, None) –
Multi-objective opimization algorithm.

If moalgo is None, then use a default multi-objective optimization algorithm.
kwargs (dict) – Additional keyword arguments.

Methods

`mosolve`	Solve the selection problem using a multi-objective optimization algorithm.
`problem`	Create an optimization problem definition using provided inputs.
`select`	Select a single selection configuration of individuals for breeding.
`sosolve`	Solve the selection problem using a single-objective optimization algorithm.

Attributes

`eqcv_trans`	Function which transforms outputs from `latentfn` to equality constraint violation values.
`eqcv_trans_kwargs`	Keyword arguments for the latent space to equality constraint violation transformation function.
`eqcv_wt`	Equality constraint violation function weights.
`ineqcv_trans`	Function which transforms outputs from `latentfn` to inequality constraint violation values.
`ineqcv_trans_kwargs`	Keyword arguments for the latent space to inequality constraint violation transformation function.
`ineqcv_wt`	Inequality constraint violation function weights.
`moalgo`	Multi-objective opimization algorithm.
`ncross`	Number of cross configurations to consider.
`ndset_trans`	Nondominated set transformation function.
`ndset_trans_kwargs`	Nondominated set transformation function keyword arguments.
`ndset_wt`	Nondominated set weights.
`neqcv`	Number of equality constraint violations.
`nineqcv`	Number of inequality constraint violation functions.
`nmating`	Number of matings per cross configuration.
`nobj`	Number of optimization objectives.
`nparent`	Number of parents per cross configuration.
`nprogeny`	Number of progeny to derive from each mating event.
`nselindiv`	Number of selected individuals.
`obj_trans`	Function which transforms outputs from `latentfn` to objective function values.
`obj_trans_kwargs`	Keyword arguments for the latent space to objective space transformation function.
`obj_wt`	Objective function weights.
`rng`	rng.
`soalgo`	Single-objective optimization algorithm.

property eqcv_trans: Callable[[ndarray, ndarray, dict], ndarray]#: Function which transforms outputs from latentfn to equality constraint violation values.

property eqcv_trans_kwargs: dict#: Keyword arguments for the latent space to equality constraint violation transformation function.

property eqcv_wt: ndarray#: Equality constraint violation function weights.

property ineqcv_trans: Callable[[ndarray, ndarray, dict], ndarray]#: Function which transforms outputs from latentfn to inequality constraint violation values.

property ineqcv_trans_kwargs: dict#: Keyword arguments for the latent space to inequality constraint violation transformation function.

property ineqcv_wt: ndarray#: Inequality constraint violation function weights.

abstract property moalgo: OptimizationAlgorithm#: Multi-objective opimization algorithm.

abstract mosolve(pgmat, gmat, ptdf, bvmat, gpmod, t_cur, t_max, miscout, **kwargs)[source]#

Solve the selection problem using a multi-objective optimization algorithm. This calculates a Pareto frontier for the objectives.

Parameters:

pgmat (PhasedGenotypeMatrix) – Genomes
gmat (GenotypeMatrix) – Genotypes
ptdf (pandas.DataFrame) – Phenotype dataframe
bvmat (BreedingValueMatrix) – Breeding value matrix
gpmod (GenomicModel) – Genomic prediction model
t_cur (int) – Current generation number.
t_max (int) – Maximum (deadline) generation number.
miscout (dict, None) – Pointer to a dictionary for miscellaneous user defined output. If dict, write to dict (may overwrite previously defined fields). If None, user defined output is not calculated or stored.
kwargs (dict) – Additional keyword arguments.

Returns:

out – A multi-objective solution to the posed selection problem.

Return type:

Solution

property ncross: Integral#: Number of cross configurations to consider.

property ndset_trans: Callable[[ndarray, dict], ndarray]#: Nondominated set transformation function.

property ndset_trans_kwargs: dict#: Nondominated set transformation function keyword arguments.

property ndset_wt: Real#: Nondominated set weights.

property neqcv: Integral#: Number of equality constraint violations.

property nineqcv: Integral#: Number of inequality constraint violation functions.

property nmating: ndarray#: Number of matings per cross configuration.

property nobj: Integral#: Number of optimization objectives.

property nparent: Integral#: Number of parents per cross configuration.

property nprogeny: ndarray#: Number of progeny to derive from each mating event.

property nselindiv: Integral#: Number of selected individuals.

property obj_trans: Callable[[ndarray, ndarray, dict], ndarray]#: Function which transforms outputs from latentfn to objective function values.

property obj_trans_kwargs: dict#: Keyword arguments for the latent space to objective space transformation function.

property obj_wt: ndarray#: Objective function weights.

abstract problem(pgmat, gmat, ptdf, bvmat, gpmod, t_cur, t_max, **kwargs)[source]#

Create an optimization problem definition using provided inputs.

Parameters:

pgmat (PhasedGenotypeMatrix) – Genomes
gmat (GenotypeMatrix) – Genotypes
ptdf (pandas.DataFrame) – Phenotype dataframe
bvmat (BreedingValueMatrix) – Breeding value matrix
gpmod (GenomicModel) – Genomic prediction model
t_cur (int) – Current generation number.
t_max (int) – Maximum (deadline) generation number.
kwargs (dict) – Additional keyword arguments.

Returns:

out – An optimization problem definition.

Return type:

SelectionProblem

property rng: Generator | RandomState#: rng.

abstract select(pgmat, gmat, ptdf, bvmat, gpmod, t_cur, t_max, miscout, **kwargs)[source]#

Select a single selection configuration of individuals for breeding.

If there is a single objective, then optimize using a single-objective optimization algorithm and create a selection configuration from the identified solution.

If there is are multiple objectives, then optimize using a multi-objective optimization algorithm, apply a transformation on the non-dominated set of solutions to find the single best solution among the set, and create a selection configuration from the identified solution.

Parameters:

pgmat (PhasedGenotypeMatrix) – Genomes
gmat (GenotypeMatrix) – Genotypes
ptdf (pandas.DataFrame) – Phenotype dataframe
bvmat (BreedingValueMatrix) – Breeding value matrix
gpmod (GenomicModel) – Genomic prediction model
t_cur (int) – Current generation number.
t_max (int) – Maximum (deadline) generation number.
miscout (dict, None) – Pointer to a dictionary for miscellaneous user defined output. If dict, write to dict (may overwrite previously defined fields). If None, user defined output is not calculated or stored.
kwargs (dict) – Additional keyword arguments.

Returns:

out – A selection configuration object, requiring all necessary information to mate individuals.

Return type:

SelectionConfiguration

abstract property soalgo: OptimizationAlgorithm#: Single-objective optimization algorithm.

abstract sosolve(pgmat, gmat, ptdf, bvmat, gpmod, t_cur, t_max, miscout, **kwargs)[source]#

Solve the selection problem using a single-objective optimization algorithm.

Parameters:

pgmat (PhasedGenotypeMatrix) – Genomes
gmat (GenotypeMatrix) – Genotypes
ptdf (pandas.DataFrame) – Phenotype dataframe
bvmat (BreedingValueMatrix) – Breeding value matrix
gpmod (GenomicModel) – Genomic prediction model
t_cur (int) – Current generation number.
t_max (int) – Maximum (deadline) generation number.
miscout (dict, None) – Pointer to a dictionary for miscellaneous user defined output. If dict, write to dict (may overwrite previously defined fields). If None, user defined output is not calculated or stored.
kwargs (dict) – Additional keyword arguments.

Returns:

out – A single-objective solution to the posed selection problem.

Return type:

Solution