| Title: | Decision Reliability for Genotype Advancement under Prediction and Target Environment Uncertainty |
|---|---|
| Description: | A model-agnostic research layer for genotype advancement decisions from externally fitted genomic prediction models. It propagates full joint coefficient prediction-error covariance together with finite sampling from a specified target population of environments to calculate conditional advancement probabilities, expected selected-set reliability, and the relative contributions of prediction and target-environment uncertainty. It also compares uncertainty formulations and reports geometric support diagnostics. Probabilities are conditional on supplied inputs and are not guaranteed to be calibrated in new populations or environments. |
| Authors: | Ashutosh Sawarkar [aut, cre] (ORCID: <https://orcid.org/0000-0002-1016-8822>), Santosh Patil [aut] (ORCID: <https://orcid.org/0000-0002-5370-3522>) |
| Maintainer: | Ashutosh Sawarkar <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.1 |
| Built: | 2026-10-16 17:39:39 UTC |
| Source: | https://github.com/cran/BreedReliabR |
A research prototype implementing a model-agnostic decision-reliability layer for genotype advancement from genomic genotype-by-environment predictions. It propagates correlated prediction uncertainty together with finite sampling of a user-specified target population of environments.
The package does not fit genomic prediction models. It consumes predicted environmental response coefficients and their full joint covariance, then evaluates uncertainty and advancement reliability conditional on a specified target population of environments.
Ashutosh Sawarkar and Santosh Patil
Implements point ranking (M0), prediction-uncertainty propagation (M1), finite-TPE uncertainty with fixed predictions (M2), or joint propagation of correlated prediction uncertainty and finite-TPE sampling (M3).
br_advance(prediction, tpe, H = 5L, k, nsim = 5000L, method = c("M3", "M1", "M2", "M0"), seed = NULL, tol = 1e-10)br_advance(prediction, tpe, H = 5L, k, nsim = 5000L, method = c("M3", "M1", "M2", "M0"), seed = NULL, tol = 1e-10)
prediction |
A |
tpe |
A |
H |
Number of future environments. |
k |
Number of candidates to advance. |
nsim |
Number of Monte Carlo draws for M1–M3. |
method |
One of |
seed |
Optional random seed for reproducibility. |
tol |
Numerical tolerance. |
Advancement probabilities are conditional on the supplied predictive
distribution, TPE specification, and H; they are not guaranteed to be empirically
calibrated. Set reliability is the expected retained fraction (the mean advancement
probability over members of the specified set), not the probability of recovering
the entire set. M0 returns deterministic 0/1 selection indicators in
p_advance, not probability forecasts, and returns NA set reliability.
Candidate MCSE quantifies simulation error conditional on the supplied distribution,
not empirical prediction accuracy.
The probability-selected set is selected and evaluated with the same simulations.
Future environments are independent draws with replacement from fixed TPE weights,
independent of the Gaussian coefficient uncertainty. Candidate IDs break ties.
A supplied seed sets and advances the session RNG state.
An object of class br_advancement containing expected merit, advancement probabilities, Monte Carlo standard errors, selected sets and selected-set reliability.
br_prediction, br_tpe, br_compare, br_curve
data(maize_demo) p <- do.call(br_prediction, maize_demo$prediction_inputs) t <- br_tpe(maize_demo$tpe_basis, maize_demo$tpe_states$weight) br_advance(p, t, H = 3, k = 3, nsim = 100, seed = 1)data(maize_demo) p <- do.call(br_prediction, maize_demo$prediction_inputs) t <- br_tpe(maize_demo$tpe_basis, maize_demo$tpe_states$weight) br_advance(p, t, H = 3, k = 3, nsim = 100, seed = 1)
Runs M0, M1, M2 and M3 with the same prediction, TPE, H and k using the frozen advancement implementation.
br_compare(prediction, tpe, H = 5L, k, nsim = 5000L, seed = NULL, tol = 1e-10)br_compare(prediction, tpe, H = 5L, k, nsim = 5000L, seed = NULL, tol = 1e-10)
prediction |
A |
tpe |
A |
H |
Positive integer number of independent future environments. |
k |
Number of candidates advanced. |
nsim |
Monte Carlo draws per stochastic scenario, at least two. |
seed |
Optional seed, passed unchanged to each core call. |
tol |
Numerical tolerance passed to |
M0 ranks expected merit; M1 propagates prediction uncertainty; M2 propagates finite-environment sampling with fixed coefficients; M3 propagates both. Set reliability means expected retained fraction, not exact-set recovery probability. M0 reliability is NA. The probability-selected set is evaluated using the same draws that selected it, so its estimated reliability can be optimistically selected. Candidate MCSE is Monte Carlo error only. A common seed makes calls reproducible but does not establish a paired Monte Carlo comparison. As in the core, a supplied seed changes the session RNG state. Results are conditional on the inputs.
A br_comparison list with summary (one row per method),
candidates (long candidate table with method and H), analyses
(named core results), seed, and conditionality.
br_advance, br_curve, br_omega
data(maize_demo) p <- do.call(br_prediction, maize_demo$prediction_inputs) t <- br_tpe(maize_demo$tpe_basis, maize_demo$tpe_states$weight) x <- br_compare(p, t, H = 3, k = 3, nsim = 100, seed = 1) summary(x)data(maize_demo) p <- do.call(br_prediction, maize_demo$prediction_inputs) t <- br_tpe(maize_demo$tpe_basis, maize_demo$tpe_states$weight) x <- br_compare(p, t, H = 3, k = 3, nsim = 100, seed = 1) summary(x)
Combines br_omega and M0–M3 comparisons for user-specified H values without smoothing or thresholds.
br_curve(prediction, tpe, H = c(1L, 3L, 5L, 10L, 20L), k, nsim = 5000L, seed = NULL, tol = 1e-10)br_curve(prediction, tpe, H = c(1L, 3L, 5L, 10L, 20L), k, nsim = 5000L, seed = NULL, tol = 1e-10)
prediction |
A |
tpe |
A compatible |
H |
Nonempty numeric vector of positive integers. Duplicates are removed preserving first occurrence order. |
k |
Number advanced. |
nsim |
Monte Carlo draws per stochastic method and H. |
seed |
Optional seed reused at every H and method. |
tol |
Tolerance passed to the advancement core. |
H counts independent future draws with replacement from the fixed TPE. It is not training size. Omega scales as 1/H for fixed nonzero prediction variance; ranking reliability need not be monotone. Reliability is an expected retained fraction, not exact-set recovery. M0 reliability is NA. With a fixed seed M1 is identical across H. Shared seeds induce dependence across evaluations; no paired precision or set-level MCSE is claimed. Memory and time grow with H, nsim and candidate count. Infinite Omega values remain in returned tables.
A br_curve list with H, omega (core object),
summary, candidates, comparisons (named by H),
seed, and conditionality.
br_advance, br_compare, br_omega
data(maize_demo) p <- do.call(br_prediction, maize_demo$prediction_inputs) t <- br_tpe(maize_demo$tpe_basis, maize_demo$tpe_states$weight) x <- br_curve(p, t, H = c(1, 5), k = 3, nsim = 100, seed = 2) summary(x) plot(x)data(maize_demo) p <- do.call(br_prediction, maize_demo$prediction_inputs) t <- br_tpe(maize_demo$tpe_basis, maize_demo$tpe_states$weight) x <- br_curve(p, t, H = c(1, 5), k = 3, nsim = 100, seed = 2) summary(x) plot(x)
Computes the decision-reliability diagnostic that contrasts uncertainty in predicted TPE-average genetic merit with uncertainty arising from finite representation of the specified target population of environments.
br_omega(prediction, tpe, H = c(1L, 3L, 5L, 10L, 20L))br_omega(prediction, tpe, H = c(1L, 3L, 5L, 10L, 20L))
prediction |
A |
tpe |
A |
H |
Positive integer vector giving future testing-network sizes. |
Omega is the ratio of the finite-TPE environmental variance to prediction variance for each candidate and requested H. It is a relative uncertainty diagnostic, not a probability, calibration measure, or universal threshold for choosing H or a method. Its interpretation is conditional on the supplied prediction covariance and TPE.
An object of class br_omega containing candidate-level prediction variance, finite-TPE variance and their ratio for each requested value of H, plus summary statistics.
data(maize_demo) p <- do.call(br_prediction, maize_demo$prediction_inputs) t <- br_tpe(maize_demo$tpe_basis, maize_demo$tpe_states$weight) br_omega(p, t, H = c(1, 5))data(maize_demo) p <- do.call(br_prediction, maize_demo$prediction_inputs) t <- br_tpe(maize_demo$tpe_basis, maize_demo$tpe_states$weight) br_omega(p, t, H = c(1, 5))
Creates and validates the model-agnostic prediction object used by BreedReliabR. The full joint prediction covariance is retained because advancement probabilities depend on covariance among candidate coefficients and candidates.
br_prediction(candidates, coef_mean, coef_vcov, basis_names = colnames(coef_mean), source = NULL, metadata = list(), tol = 1e-08)br_prediction(candidates, coef_mean, coef_vcov, basis_names = colnames(coef_mean), source = NULL, metadata = list(), tol = 1e-08)
candidates |
Unique candidate identifiers. |
coef_mean |
Numeric matrix with one row per candidate and one column per environmental basis coefficient. |
coef_vcov |
Full prediction-error covariance matrix for all candidate coefficients, stacked candidate by candidate. |
basis_names |
Optional names for the environmental basis coefficients. |
source |
Optional label identifying the source prediction model. |
metadata |
Optional named list of metadata. |
tol |
Numerical tolerance used for symmetry and positive-semidefinite checks. |
The covariance must be a finite symmetric positive-semidefinite matrix in candidate-major order: all basis coefficients for candidate 1, then all coefficients for candidate 2, and so on. It is the full prediction-error covariance supplied by an external fitting workflow. Do not substitute marginal standard errors or a diagonal matrix unless that is the validated covariance from the upstream model. BreedReliabR does not fit or validate that model.
An object of class br_prediction.
br_tpe, br_advance, br_compare
data(maize_demo) p <- do.call(br_prediction, maize_demo$prediction_inputs) pdata(maize_demo) p <- do.call(br_prediction, maize_demo$prediction_inputs) p
Reports marginal range departures and nearest-training Euclidean distances standardized by training sample standard deviations. It does not certify biological correctness of a TPE.
br_support(tpe, training_basis, tol = 1e-10)br_support(tpe, training_basis, tol = 1e-10)
tpe |
A |
training_basis |
Finite numeric matrix with at least two rows and identical basis column names and order to the TPE. Use the same transformations for training and TPE. |
tol |
Non-negative absolute tolerance for marginal range departures, in each supplied basis column's units. |
These are geometric diagnostics in the supplied environmental basis. A state outside marginal training ranges or farther away than training leave-one-out neighbours may be extrapolative, but the diagnostics do not prove biological validity, prediction accuracy, or calibration. Correlation among basis dimensions can affect distances. Exactly constant training columns are excluded from finite distances. Departures greater than tol in such columns produce infinite distance and an explicit constant-mismatch flag. Other columns use their sample standard deviations. The largest leave-one-out nearest-neighbour training distance is an empirical reference, not a calibrated cutoff. Duplicate training rows have zero nearest distance. Correlated or redundant columns can distort distances; marginal ranges do not describe a joint convex hull. Zero-weight states are diagnosed but do not contribute to weighted masses. All-constant training spaces are supported. Geometric support does not establish model calibration, biological relevance, or defensibility of the supplied weights.
A list of per-state diagnostics, weighted summaries, training ranges, standardized nearest-neighbour distances, and a conditionality statement.
data(maize_demo) t <- br_tpe(maize_demo$tpe_basis, maize_demo$tpe_states$weight) s <- br_support(t, maize_demo$training_basis) s$states plot(s)data(maize_demo) t <- br_tpe(maize_demo$tpe_basis, maize_demo$tpe_states$weight) s <- br_support(t, maize_demo$training_basis) s$states plot(s)
Defines the user-specified target population of environments used to evaluate finite-environment deployment uncertainty.
br_tpe(basis, weights = NULL, state_id = NULL, metadata = list())br_tpe(basis, weights = NULL, state_id = NULL, metadata = list())
basis |
Numeric matrix with one row per TPE state and environmental basis columns matching the prediction object. |
weights |
Non-negative state weights. Values are normalised to sum to one. |
state_id |
Optional unique identifiers for TPE states. |
metadata |
Optional named list of metadata. |
Weights are normalized to sum to one and describe the assumed distribution over supplied states. They are not automatically production-area or acreage weights. Conclusions are conditional on the chosen states, basis, and weights. Zero-weight states are retained for diagnostics but contribute no probability mass.
An object of class br_tpe.
br_prediction, br_support, br_omega
data(maize_demo) t <- br_tpe(maize_demo$tpe_basis, maize_demo$tpe_states$weight) tdata(maize_demo) t <- br_tpe(maize_demo$tpe_basis, maize_demo$tpe_states$weight) t
A synthetic yield scenario for demonstrating import and analysis. No real observations or fitted genomic model are included.
data(maize_demo)data(maize_demo)
A list with:
12 rows: environment ID, flowering water-deficit fraction and hot days during flowering.
12 by 3 matrix: intercept, water (deficit minus 0.35 divided by 0.20), heat (days minus 7 divided by 5).
240 rows: 10 training genotype IDs by 12 environments by two replicates, with simulated yield in t/ha.
Eight distinct unphenotyped candidate IDs and false phenotyped indicators.
Arguments to br_prediction: IDs, 8 by 3 coefficient means, 24 by 24 joint candidate-major prediction covariance, source and metadata.
Five states with IDs, water-deficit fraction, hot days and fixed weights.
Five by three matrix using the training transformations.
Simulation indicator, seed and explanation.
The extreme hot-dry state is deliberately outside the training ranges. Yield coefficients reflect illustrative negative stress responses, not estimated biological parameters. Prediction covariance is a positive definite Kronecker construction with correlated candidates. Prediction inputs are stipulated, not estimated from the illustrative training phenotypes. The reproducible generation script is in inst/scripts/maize_demo.R in the source package and installed in scripts.
Generated for BreedReliabR with seed 260926; no external data.
data(maize_demo) str(maize_demo, max.level = 1)data(maize_demo) str(maize_demo, max.level = 1)
Prints a compact summary of a genotype-advancement reliability analysis.
## S3 method for class 'br_advancement' print(x, ...)## S3 method for class 'br_advancement' print(x, ...)
x |
A |
... |
Additional arguments, currently unused. |
The input object, invisibly.
Prints the uncertainty-ratio summary across future network sizes.
## S3 method for class 'br_omega' print(x, ...)## S3 method for class 'br_omega' print(x, ...)
x |
A |
... |
Additional arguments, currently unused. |
The input object, invisibly.
Prints a compact description of a BreedReliabR prediction object.
## S3 method for class 'br_prediction' print(x, ...)## S3 method for class 'br_prediction' print(x, ...)
x |
A |
... |
Additional arguments, currently unused. |
The input object, invisibly.
Prints a compact description of a target population of environments.
## S3 method for class 'br_tpe' print(x, ...)## S3 method for class 'br_tpe' print(x, ...)
x |
A |
... |
Additional arguments, currently unused. |
The input object, invisibly.
Compact tabular and base-graphics displays. Curve plots sort H for display; returned input order is preserved. Support plots mark marginal departures in red and show the maximum training nearest-neighbour distance as a dashed reference.
## S3 method for class 'br_comparison' print(x, ...) ## S3 method for class 'br_comparison' summary(object, ...) ## S3 method for class 'br_comparison' plot(x, ...) ## S3 method for class 'br_curve' print(x, ...) ## S3 method for class 'br_curve' summary(object, ...) ## S3 method for class 'br_curve' plot(x, type = c("reliability", "omega"), set = c("expected_merit", "probability"), ...) ## S3 method for class 'br_support' print(x, ...) ## S3 method for class 'br_support' summary(object, ...) ## S3 method for class 'br_support' plot(x, ...)## S3 method for class 'br_comparison' print(x, ...) ## S3 method for class 'br_comparison' summary(object, ...) ## S3 method for class 'br_comparison' plot(x, ...) ## S3 method for class 'br_curve' print(x, ...) ## S3 method for class 'br_curve' summary(object, ...) ## S3 method for class 'br_curve' plot(x, type = c("reliability", "omega"), set = c("expected_merit", "probability"), ...) ## S3 method for class 'br_support' print(x, ...) ## S3 method for class 'br_support' summary(object, ...) ## S3 method for class 'br_support' plot(x, ...)
x, object
|
An object of the corresponding class. |
type |
Plot expected retained fraction or median candidate Omega. |
set |
Which selected-set reliability to plot. |
... |
Additional print or graphics arguments, excluding arguments already set by the method. Ignored by summary methods. |
Nonfinite distances or Omega values are omitted with a warning; if none are finite plotting stops with an error. Inspect the returned tables for those values. M0 is omitted from reliability plots because it does not estimate reliability.
Print and plot methods invisibly return x. Summary methods return the summary data frame, or for curves a list containing reliability and Omega summary tables.