Package {BreedReliabR}

Type:	Package
Title:	Decision Reliability for Genotype Advancement under Prediction and Target Environment Uncertainty
Version:	0.1.1
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.
URL:	https://github.com/annusawarkar-sys/BreedReliabR
BugReports:	https://github.com/annusawarkar-sys/BreedReliabR/issues
License:	MIT + file LICENSE
Encoding:	UTF-8
Depends:	R (≥ 3.6.0)
Imports:	stats, graphics
Suggests:	testthat (≥ 3.0.0), knitr, rmarkdown
VignetteBuilder:	knitr
LazyData:	true
Config/testthat/edition:	3
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2026-10-01 16:47:52 UTC; User
Author:	Ashutosh Sawarkar [aut, cre], Santosh Patil [aut]
Maintainer:	Ashutosh Sawarkar <annu.sawarkar@gmail.com>
Repository:	CRAN
Date/Publication:	2026-10-16 15:10:18 UTC

Decision Reliability for Genomic Genotype Advancement Across Target Environments

Description

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.

Details

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.

Author(s)

Ashutosh Sawarkar and Santosh Patil

Estimate genotype advancement probabilities

Description

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).

Usage

br_advance(prediction, tpe, H = 5L, k, nsim = 5000L,
  method = c("M3", "M1", "M2", "M0"), seed = NULL,
  tol = 1e-10)

Arguments

Details

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.

Value

An object of class br_advancement containing expected merit, advancement probabilities, Monte Carlo standard errors, selected sets and selected-set reliability.

See Also

br_prediction, br_tpe, br_compare, br_curve

Examples

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)

Compare four advancement uncertainty scenarios

Description

Runs M0, M1, M2 and M3 with the same prediction, TPE, H and k using the frozen advancement implementation.

Usage

br_compare(prediction, tpe, H = 5L, k, nsim = 5000L,
  seed = NULL, tol = 1e-10)

Arguments

Details

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.

Value

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.

See Also

br_advance, br_curve, br_omega

Examples

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)

Compute uncertainty and reliability over future network sizes

Description

Combines br_omega and M0–M3 comparisons for user-specified H values without smoothing or thresholds.

Usage

br_curve(prediction, tpe, H = c(1L, 3L, 5L, 10L, 20L),
  k, nsim = 5000L, seed = NULL, tol = 1e-10)

Arguments

Details

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.

Value

A br_curve list with H, omega (core object), summary, candidates, comparisons (named by H), seed, and conditionality.

See Also

br_advance, br_compare, br_omega

Examples

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)

Quantify prediction versus finite-TPE uncertainty

Description

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.

Usage

br_omega(prediction, tpe, H = c(1L, 3L, 5L, 10L, 20L))

Arguments

Details

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.

Value

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.

See Also

br_tpe, br_advance, br_curve

Examples

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))

Construct a genomic prediction object

Description

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.

Usage

br_prediction(candidates, coef_mean, coef_vcov,
  basis_names = colnames(coef_mean), source = NULL,
  metadata = list(), tol = 1e-08)

Arguments

Details

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.

Value

An object of class br_prediction.

See Also

br_tpe, br_advance, br_compare

Examples

data(maize_demo)
p <- do.call(br_prediction, maize_demo$prediction_inputs)
p

Diagnose geometric environmental support of a specified TPE

Description

Reports marginal range departures and nearest-training Euclidean distances standardized by training sample standard deviations. It does not certify biological correctness of a TPE.

Usage

br_support(tpe, training_basis, tol = 1e-10)

Arguments

Details

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.

Value

A list of per-state diagnostics, weighted summaries, training ranges, standardized nearest-neighbour distances, and a conditionality statement.

See Also

br_tpe, br_omega, br_curve

Examples

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)

Define a target population of environments

Description

Defines the user-specified target population of environments used to evaluate finite-environment deployment uncertainty.

Usage

br_tpe(basis, weights = NULL, state_id = NULL, metadata = list())

Arguments

Details

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.

Value

An object of class br_tpe.

See Also

br_prediction, br_support, br_omega

Examples

data(maize_demo)
t <- br_tpe(maize_demo$tpe_basis, maize_demo$tpe_states$weight)
t

Explicitly simulated maize advancement demonstration

Description

A synthetic yield scenario for demonstrating import and analysis. No real observations or fitted genomic model are included.

Usage

data(maize_demo)

Format

A list with:

training_environments

12 rows: environment ID, flowering water-deficit fraction and hot days during flowering.

training_basis

12 by 3 matrix: intercept, water (deficit minus 0.35 divided by 0.20), heat (days minus 7 divided by 5).

training_phenotypes

240 rows: 10 training genotype IDs by 12 environments by two replicates, with simulated yield in t/ha.

candidates

Eight distinct unphenotyped candidate IDs and false phenotyped indicators.

prediction_inputs

Arguments to br_prediction: IDs, 8 by 3 coefficient means, 24 by 24 joint candidate-major prediction covariance, source and metadata.

tpe_states

Five states with IDs, water-deficit fraction, hot days and fixed weights.

tpe_basis

Five by three matrix using the training transformations.

provenance

Simulation indicator, seed and explanation.

Details

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.

Source

Generated for BreedReliabR with seed 260926; no external data.

Examples

data(maize_demo)
str(maize_demo, max.level = 1)

Print a BreedReliabR advancement analysis

Description

Prints a compact summary of a genotype-advancement reliability analysis.

Usage

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

Arguments

Value

The input object, invisibly.

Print a BreedReliabR uncertainty diagnostic

Description

Prints the uncertainty-ratio summary across future network sizes.

Usage

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

Arguments

Value

The input object, invisibly.

Print a BreedReliabR prediction object

Description

Prints a compact description of a BreedReliabR prediction object.

Usage

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

Arguments

Value

The input object, invisibly.

Print a BreedReliabR TPE object

Description

Prints a compact description of a target population of environments.

Usage

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

Arguments

Value

The input object, invisibly.

Display research-facing results

Description

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.

Usage

## 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, ...)

Arguments

Details

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.

Value

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.