Documentation

This page outlines all functions available through the module via

import robustocs

with links to a full breakdown of input parameters, return values, and example usages. Similar documentation can be obtained within a Python interpreter by using the help command, for example

help(robustocs.makeA)

It assumed some understanding of the basic concepts discussed in the Examples and Modelling pages, though if anything here is unclear please do open an issue.

Functions

Loaders

Genetics data can be presented in multiple formats, so we provide several functions for loading these into RobustOCS correctly. These can be used by importing the full module or this submodule via

from robustocs import loaders

The functions contained are:

• load_ped : read pedigree files into a dictionary,
• load_problem : load an optimal contribution selection problem.

Pedigree

One of the options for modelling the relationships with $\Sigma$ is to use Wright's Numerator Relationship Matrix. Doing so enables some additional tricks, particularly where the inverse $\Sigma^{-1}$ is needed, which we include here. These can be used by importing the full module or this submodule via

from robustocs import pedigree

The functions contained are:

• makeA : form Wright's Numerator Relationship Matrix.
• make_invA : form the inverse of Wright's Numerator Relationship Matrix.

Solvers

There are various models and methods that can be used to solve optimal contribution selection problems, each of which has a corresponding function here. These can be used by importing the full module or this submodule via

from robustocs import solvers

The functions contained are:

• gurobi_robust_genetics : solve robust OCS with Gurobi,
• gurobi_robust_genetics_conic : solve robust OCS with Gurobi using conic programming,
• gurobi_robust_genetics_sqp : solve robust OCS with Gurobi using sequential quadratic programming,
• gurobi_standard_genetics : solve non-robust OCS with Gurobi,
• highs_robust_genetics : solve robust OCS with HiGHS,
• highs_robust_genetics_sqp : solve robust OCS with HiGHS using sequential quadratic programming,
• highs_standard_genetics : solve non-robust OCS with HiGHS.

Utilities

Aside from the core loading and solving functions, there are additional utility functions the module provides for analysing, checking, and presenting output from the solvers. These can be used by importing the full module or this submodule via

from robustocs import utils

The functions contained are:

• check_uncertainty_constraint : assess the gap between $z$ and $\sqrt{\mathbf{w}^{T}\Omega\mathbf{w}}$ in the robust problem (see modelling),
• cond - compute the condition number of a matrix,
• eigmax - compute the maximum eigenvalue of a matrix,
• expected_genetic_merit : compute the expected genetic merit, $\mathbf{w}^{T}\boldsymbol\mu$,
• group_coancestry : compute the group co-ancestry, $\mathbf{w}^{T}\Omega\mathbf{w}$,
• group_coancestry_fast : compute the group co-ancestry quicker using solution data,
• print_compare_solutions : formatting for printing two solution alongside each other,
• solveROCS : wrapper for quick-starting RobustOCS,
• sparsity : give the sparsity of a NumPy or SciPy matrix.

Parameters

Across the functions the module provides, particularly the solvers, many of the parameters are held in common. Below is a top-level summary of these and what each of them do, though specific function documentation pages should be consulted for order and usage.

Problem Variables

These are passed as parameters and are outlined below with their name in the module, their mathematical symbol, and usage notes.

Name	Symbol	Notes
sigma	$\Sigma$	Covariance matrix of the candidates in the cohorts for selection. This must be symmetric positive definite; if using an estimated model any correction should be done before being passed to RobustOCS.
mubar	$\boldsymbol{\bar{\mu}}$	Vector of expected values of the expected returns for candidates in the cohort for selection. In the non-robust problems this is mu ($\boldsymbol{\mu}$).
omega	$\Omega$	Covariance matrix for expected returns for candidates in the cohort for selection. This must be symmetric positive definite; any estimation or correction should be done before being passed to RobustOCS.
sires	$\mathcal{S}$	Identifies sires (male candidates) in the cohort.
dams	$\mathcal{D}$	Identifies dams (female candidates) in the cohort.
lam	$\lambda$	Controls the balance between risk and return, with lower values giving riskier selections and higher more conservative ones. This can take any real value, but $\lambda<0$ effectively corresponds to rewarding inbreeding so should not be considered. Note that the parameter is specifically not lambda because this is a Python keyword.
kappa	$\kappa$	Controls how resilient the solution must be to variation in expected breeding values. Can take any positive real values, with higher values representing a higher tolerance for uncertainty. Taking $\kappa = 0$ corresponds to assuming $\boldsymbol{\mu}$ is known exactly, while $\kappa = \infty$ corresponds to unlimited tolerance for uncertainty.
dimension	$n$	Number of candidates in the cohort, i.e. the dimension of the problem. While strictly speaking this is evident from the other parameters, it's asked for as a convenience.
upper_bound	$\mathbf{u}$	Upper bound on the proportion each candidate can contribute, so $0\leq l_i \leq u_i \leq 1$.
lower_bound	$\mathbf{l}$	Lower bound on the proportion each candidate can contribute, so $0\leq l_i \leq u_i \leq 1$.

RobustOCS doesn't support passing arbitrary linear constraints $A\mathbf{w} = \mathbf{b}$ at this time.

Control Variables

In addition, there are parameters which control the running of the optimization tools themselves.

Name	Notes
time_limit	How many seconds to give the underling solver (not RobustOCS overall) to find a solution.
max_iterations	A limit on how many constraints the SQP method may add if it does not converge.
robust_gap_tol	Maximum absolute difference allowed between $z$ and $\sqrt{ \mathbf{w}^T \Omega \mathbf{w} }$ in the robust constraint.

Debug Variables

Finally, there are parameters which control how much output the user receives.

Name	Notes
solution_output	Filename to save the solution portfolio to, if desired. Uses the CSV format.
model_output	Filename to save the model file to, if desired. Uses the MPS format.
debug	Boolean which specifies whether to spew output to the terminal.