solveROCS

solveROCS(sigma_filename, mu_filename, sex_filename, lam, omega_filename, kappa, upper_bound, lower_bound, method, solver, issparse, time_limit, max_iterations, robust_gap_tol, solution_output, model_output, debug)

A convenient wrapper which allows for accessing all the main features of RobustOCS through a single interface. It handles everything from loading the data from file right through to analysing the solution found. It's best suited for single calls where no further work with the same input data is expected. For anything more complicated like repeated calls or tweaking parameters it's highly recommended that one of the granular solver functions is used instead.

Parameters

• sigma_filename : str
  Filename for a file which encodes $\Sigma$, whether that's stored in sparse coordinate format or pedigree format (see more). This must include the extension (not necessarily .ped) and full path from the current working directory.
• mu_filename : str
  Filename for a file which encodes $\boldsymbol\mu$ if working with a non-robust problem and $\boldsymbol{\bar\mu}$ when working with a robust problem, with a single value per line. This must include the extension (not necessarily .ped) and full path from the current working directory.
• sex_filename : str
  Filename for a file which encodes the sex data and labels for candidates in the cohort, used to populate $\mathcal{S}$ and $\mathcal{D}$.
• lam : float
  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.
• omega_filename : str, optional
  Filename for a file which encodes $\Omega$, which will be in sparse coordinate format. This does not have to be provided (if for example, you're working with a non-robust problem) or can be skipped by providing None.
• kappa : float
  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 is known exactly, while $\kappa = \infty$ corresponds to unlimited tolerance for uncertainty. This is specific to robust optimization and will be ignored if doing standard optimization.
• upper_bound : ndarray or float, optional
  Upper bound on how much each candidate can contribute. This can be an array of differing bounds for each candidate, or a float which applies to all candidates equally. This value should be such that $0\leq l_i \leq u_i \leq 1$ and the default is, $\mathbf{u} = \mathbf{1}$, enforced by the contributions $\mathbf{w}$ being a vector proportions rather than absolute values.
• lower_bound : ndarray or float, optional
  Lower bound on how much each candidate can contribute. This can be an array of differing bounds for each candidate, or a float which applies to all candidates equally. This value should be such that $0\leq l_i \leq u_i \leq 1$ and the default is, $\mathbf{l} = \mathbf{0}$, enforced by the contributions $\mathbf{w}$ being a vector proportions rather than absolute values.
• method : str, optional
  String which specifies whether to carry out standard (standard, the default) or robust (robust) optimization
• solver : str, optional
  String which specifies whether to use HiGHS (highs, the default) or Gurobi (gurobi) as the solver.
• upper_bound : ndarray or float, optional
  Upper bound on how much each candidate can contribute. This can be an array of differing bounds for each candidate, or a float which applies to all candidates equally. This value should be such that $0\leq l_i \leq u_i \leq 1$ and the default is, $\mathbf{u} = \mathbf{1}$, enforced by the contributions $\mathbf{w}$ being a vector proportions rather than absolute values.
• lower_bound : ndarray or float, optional
  Lower bound on how much each candidate can contribute. This can be an array of differing bounds for each candidate, or a float which applies to all candidates equally. This value should be such that $0\leq l_i \leq u_i \leq 1$ and the default is, $\mathbf{l} = \mathbf{0}$, enforced by the contributions $\mathbf{w}$ being a vector proportions rather than absolute values.
• time_limit : float, optional
  Maximum amount of time in seconds to give the solver to solve the problem. Optional, with the default being no time limit.
• max_iterations : int, optional
  Maximum number of iterations that can be taken in solving at can be taken in solving the robust problem using SQP. Optional, with a default value of 1000.
• robust_gap_tol : float, optional
  Tolerance when checking whether an approximating constraint is active and whether the SQP overall has converged. This is specific to robust optimization and will be ignored if doing standard optimization. Default value is $10^{-7}$.
• solution_output : str, optional
  Name to use if saving the solution vector to a CSV file in the working directory. If given, the string is used as the file name, {solution_output}.csv. This is optional, and by default the file isn't saved.
• model_output : str, optional
  Name to use if saving the model file to the working directory. If given, the string is used as the file name, {model_output}.mps. This is optional, and by default the file isn't saved.
• debug : bool, optional
  Flag which controls whether the solver prints its output to terminal. Default value is False.

Returns

• ndarray
  Portfolio vector $\mathbf{w}$ which the solver has determined is a solution. Note that solveROCS will not return $z$ if solving a robust problem. If this is required, use one of the solver functions.
• float
  Value of the objective function for returned solution $\mathbf{w}$.
• float
  The expected genetic merit of the returned solution $\mathbf{w}$.
• float
  The group co-ancestry of the returned solution $\mathbf{w}$.

Examples

Given file input data included in the repository, example usage may look like

>>> selection, objective, merit, coancestry = rocs.solveROCS(
...     sigma_filename="examples/04/A04.txt",
...     mu_filename="examples/04/EBV04.txt",
...     omega_filename="examples/04/S04.txt",
...     sex_filename="examples/04/SEX04.txt",
...     method='robust', lam=0.5, kappa=1
... )
Running HiGHS 1.7.2 (git hash: 184e327): Copyright (c) 2024 HiGHS under MIT licence terms
>>> selection
array([0.38225694, 0.38225694, 0.11774306, 0.11774306])
>>> objective
0.7768406233697358
>>> merit
1.2354861108597817
>>> coancestry
1.8345819499601834 

If we in addition use the parameter solution_output="filename", the selection will also be saved to a CSV file filename.csv in the working directory. This gives optimal contributions alongside the candidates identifiers, which are loaded alongside sex data from SEX04.txt.

candidate,contribution
1,0.3822569445737661
2,0.3822569445664524
3,0.11774305542623399
4,0.11774305543354763