Package 'rbpengine'

Default prefix used by install_engine().

Description

Default prefix used by install_engine().

Usage

default_engine_home()

Value

A directory path.

Examples

default_engine_home()

---

Locate and load the private RBP Math Engine runtime.

Description

The open rbpengine package is a thin client. Predictions require the private RBP Math Engine shared library (librbp_math_lib.dylib / .so / rbp_math_lib.dll) plus platform companions (OpenBLAS/LAPACK where needed) and a valid license.

Usage

engine_candidate_paths()

engine_available()

find_engine_path()

Details

Discovery order (first path that loads and exposes the expected ABI symbols):

1. RBP_ENGINE_LIB (full path to the shared library)

2. RBP_ENGINE_HOME / ⁠lib/⁠ (+ OS filename)

3. install_engine() prefix (default_engine_home())

4. Well-known install prefixes (⁠/Library/rbp-engine/lib⁠, ⁠$HOME/.local/share/rbp-engine/lib⁠, ...)

5. Developer cargo tree (RBP_MATH_LIB_ROOT, sibling rbp-math-lib/target, or ../target when this package still sits next to a cargo workspace)

Value

engine_available() returns a logical. engine_candidate_paths() returns character paths that may be probed. find_engine_path() and engine_load() return the loaded path (invisibly). engine_unload() returns TRUE invisibly after releasing the loaded library. ensure_engine() returns TRUE invisibly when the engine is available.

See Also

library_path(), abi_version(), install_engine()

Examples

engine_available()
length(engine_candidate_paths()) >= 1

---

Load the engine shared library at an explicit path.

Description

Load the engine shared library at an explicit path.

Usage

engine_load(path = NULL)

Arguments

path	Full path to ⁠librbp_math_lib.*⁠ (or set RBP_ENGINE_LIB and call engine_load() with no args after relying on find_engine_path()).

Value

Invisibly, the path loaded.

---

Public HTTPS prefix for runtime tarballs.

Description

Override with env RBP_ENGINE_RELEASES_URL (no trailing slash).

Usage

engine_releases_url()

Value

Character scalar.

Examples

engine_releases_url()

---

Platform id matching manifest.json artifacts (macos-arm64, …).

Description

Platform id matching manifest.json artifacts (macos-arm64, …).

Usage

engine_runtime_id()

Value

Character scalar.

Examples

engine_runtime_id()

---

Release a loaded engine shared library.

Description

install_engine() calls this before replacing a runtime that this session already has mapped, so the file is not locked for the copy.

Usage

engine_unload()

Value

Invisibly TRUE.

---

Ensure the engine is loaded; stop with install instructions if not.

Description

Called by prediction helpers. Safe to call repeatedly.

Usage

ensure_engine()

Value

Invisibly TRUE when available.

---

Adopt a default on-disk license when the process environment has none.

Description

Matches the Python rbp_engine._license resolution order:

1. RBP_LICENSE

2. RBP_LICENSE_FILE

3. ⁠~/.rbp-engine/license.txt⁠

4. ⁠/Library/rbp-engine/license.txt⁠ (macOS system install)

Usage

ensure_license_env()

Details

Never errors. Called automatically from .onLoad.

Value

The path adopted (invisibly), or NULL when the environment already carries a license or no default file exists.

---

Grid search options for predict_grid.

Description

Same censor / scale / inversion knobs as PredictOptions, plus combination search settings. Does not take verify_missing_data / missing_moments: Grid chooses complete vs pairwise moments per combination.

Usage

GridOptions(
  threshold = c(0, 0.2, 0.5, 0.8),
  censor_type = "both",
  censor_unit = "percent",
  censor_operator = "greater_than_or_equal_to",
  prediction_scale = "response",
  adj_fit_multiplier = "k",
  inv_method = "gaussian",
  include_linear_regression = FALSE,
  verbose = FALSE,
  max_iter = 1000L,
  min_k = NULL,
  max_k = NULL,
  allowed_k = NULL,
  k = 1L,
  seed = 42L,
  retain_all = FALSE,
  retain_grid_objects = NULL,
  attribute_combi = NULL,
  required_attributes = NULL,
  attribute_groups = NULL,
  adjust_impact_for_missing = TRUE,
  inner_parallel = "auto"
)

Arguments

threshold	Numeric vector of thresholds. Default c(0, 0.2, 0.5, 0.8).
censor_type	"relevance", "similarity", or "both" (default).
censor_unit	"percent" or "score".
censor_operator	Comparison vs threshold. Default "greater_than_or_equal_to".
prediction_scale	"response" or "logistic".
adj_fit_multiplier	"k", "identity", or "log".
inv_method	"gaussian", "cholesky", or "pseudoinverse".
include_linear_regression	Logical; fills yhat_linear when available.
verbose	Logical; engine diagnostics (default FALSE).
max_iter	Combination search budget.
min_k	Minimum number of attributes turned on in a combination. Combinations may be larger, up to max_k or all attributes, until max_iter is filled. Default 1.
max_k	Maximum number of attributes turned on. Omit it to allow every attribute. Set it equal to min_k for that exact size.
allowed_k	Integer vector of exact combination sizes, such as c(1L, 3L, 7L, 10L). Replaces min_k and max_k.
k	Alias of min_k. Still accepted.
seed	RNG seed.
retain_all	Retain all grid cell objects.
retain_grid_objects	Character policy string (overrides retain_all).
attribute_combi	Optional matrix of attribute combinations. Cannot be combined with required_attributes or attribute_groups.
required_attributes	Length-K 0/1 mask of attributes that are on in every generated combination.
attribute_groups	G by K 0/1 mask. Each row is a group of attributes selected together.
adjust_impact_for_missing	Logical; incomplete-column IOF/IOP vs a μ+σZ include-k null (default TRUE). FALSE is the pre-adjustment / PSR-parity baseline.
inner_parallel	"auto" or "off" (within-call parallelism).

Value

A named list with class GridOptions.

See Also

PredictOptions, predict_grid

Examples

GridOptions(min_k = 2L, max_iter = 100L)

---

Install the private RBP Math Engine runtime.

Description

The open rbpengine package is a thin client. Predictions need the private engine (shared library + companions + rbp-license-info). This helper fetches the platform tarball from ⁠https://docs.csanalytics.io/releases/⁠ (or unpacks a local archive) into a well-known prefix that engine_candidate_paths() already searches.

Usage

install_engine(
  version = "latest",
  dest = NULL,
  url = NULL,
  path = NULL,
  load = TRUE,
  quiet = FALSE
)

Arguments

version	Math runtime to fetch (docs.csanalytics.io/releases). "latest" (default) or a math-lib semver such as "1.3.7". Ignored when path or url is set.
dest	Install prefix. Default is default_engine_home() (⁠~/.local/share/rbp-engine⁠ on Unix, ⁠%LOCALAPPDATA%/rbp-engine⁠ on Windows).
url	Full URL of a .tar.gz (skips the manifest). sha256 is not verified unless manifest_url is also reachable via version.
path	Local .tar.gz or an already-staged runtime directory (⁠lib/⁠, ⁠bin/⁠).
load	If TRUE (default), engine_load() the newly installed library.
quiet	Suppress download progress.

Details

This is a user-called step, never run at package install time and never invoked from examples, tests, or vignettes (CRAN policy). Analogous to ⁠pip install rbp-engine⁠ for the engine files only. Typical calls are install_engine() for the latest math runtime for this machine, install_engine(version = "1.3.7") to pin an rbp-math-lib tarball (not the PyPI rbp-engine 2.x version), or install_engine(path = "macos-arm64.tar.gz") for a local archive. Calling it again upgrades in place. A library this session already loaded from dest is unloaded first. A file another process still has mapped is renamed aside and the new file is written under the original name, because a loaded shared library cannot be overwritten in place.

Value

The install prefix, invisibly.

See Also

ensure_engine(), engine_available(), uninstall_engine()

---

Run the rbp-license-info CLI shipped with the engine runtime.

Description

Looks in the installed runtime ⁠bin/⁠ (see install_engine()), well-known prefixes, cargo ⁠target/⁠, then PATH.

Usage

license_info(...)

Arguments

...	Arguments passed to the binary (character; e.g. "--viewlicense").

Value

Exit status (invisibly).

---

Human-readable description of where the license is coming from.

Description

Human-readable description of where the license is coming from.

Usage

license_source()

Value

A short character string such as "RBP_LICENSE (environment)", "RBP_LICENSE_FILE=...", or a message indicating none is configured.

Examples

license_source()

---

rbp-math-lib semver embedded in the shared library on this machine.

Description

Reads the RBP-ENGINE-VERSION= record compiled into the engine dll, dylib, or so. This does not read package, config, or version files, and it does not load the library, so a missing BLAS companion or a wrong-architecture binary can still report the version baked into that file.

Usage

math_lib_version(path = NULL)

Arguments

path	Optional full path to a shared library. When NULL, the library on this system is located as described above.

Details

When path is omitted, RBP_ENGINE_LIB is the only file inspected if it is set. Otherwise each existing file from engine_candidate_paths() is read until one contains the record. A binary without that record is skipped, so an older install does not hide a newer build. The filename depends on the OS: librbp_math_lib.dylib (macOS), librbp_math_lib.so (Linux), or rbp_math_lib.dll (Windows).

Prints one line to the terminal, rbp-math-lib <version> (<path>).

Value

The semver string (for example "1.3.7"), invisibly.

See Also

engine_candidate_paths(), abi_version(), package_version_rbpengine()

---

Fit-weighted composite across attribute combinations.

Description

Evaluates combinations of predictive attributes across relevance and similarity thresholds, then forms a fit-weighted composite prediction for circumstances theta. Combinations that fit this task more reliably pull harder on the forecast. The result also includes variable-level Impact on Fit and Impact on Prediction.

Usage

predict_grid(y, X, theta, options = NULL)

Arguments

y	Numeric outcomes, length N.
X	Numeric matrix, N rows by K columns (R column-major is native).
theta	Circumstances vector, length K.
options	Optional PredictOptions, MaxFitOptions, or GridOptions.

Details

Recommended default path for analysis.

Value

A nested list of class PredictionResults (same field layout as Python rbp_engine.PredictionResults). Access fields with $, e.g. result$yhat, result$insights$relevance.

Examples

PredictOptions(threshold = 0.5)
if (engine_available()) {
  set.seed(1)
  N <- 40; K <- 3
  X <- matrix(rnorm(N * K), N, K)
  y <- rnorm(N)
  theta <- colMeans(X)
  out <- predict_grid(y, X, theta, GridOptions(k = 1L, max_iter = 50L))
  as.numeric(out$yhat[1])
  best <- predict_maxfit(y, X, theta)
  res <- predict_psr(y, X, theta, PredictOptions(threshold = 0.5))
  res$yhat
}

---

Strongest prediction on a fixed set of attributes.

Description

Searches candidate thresholds and returns the single winner on your objective: fit, adjusted fit, or k-fit (the default).

Usage

predict_maxfit(y, X, theta, options = NULL)

Arguments

y	Numeric outcomes, length N.
X	Numeric matrix, N rows by K columns (R column-major is native).
theta	Circumstances vector, length K.
options	Optional PredictOptions, MaxFitOptions, or GridOptions.

Details

Useful when you want that maximum on one attribute set, without a full combination grid. For primary analysis, prefer predict_grid(), which diversifies across attribute combinations and thresholds, then blends by fit.

Value

A nested list of class PredictionResults. yhat, fit, and thresholds have length 1 (the winner).

Examples

if (engine_available()) {
  set.seed(1)
  N <- 40; K <- 3
  X <- matrix(rnorm(N * K), N, K)
  y <- rnorm(N)
  theta <- colMeans(X)
  best <- predict_maxfit(y, X, theta)
  best$yhat
  best <- predict_maxfit(y, X, theta, MaxFitOptions(objective = "fit"))
}

---

Partial-sample regression at thresholds you choose.

Description

Forms a relevance-weighted forecast at the censoring thresholds you choose. The prediction uses the informative, relevant subset of the sample, rather than treating every past observation equally.

Usage

predict_psr(y, X, theta, options = NULL)

Arguments

y	Numeric outcomes, length N.
X	Numeric matrix, N rows by K columns (R column-major is native).
theta	Circumstances vector, length K.
options	Optional PredictOptions, MaxFitOptions, or GridOptions.

Details

This is the evaluation inside each Grid cell and inside MaxFit. Use predict_psr() when the attribute set and thresholds are already fixed. For primary analysis, prefer predict_grid().

Named predict_psr (not predict) so base R's stats::predict is not masked.

Value

A nested list of class PredictionResults. yhat has one prediction per threshold.

Examples

if (engine_available()) {
  set.seed(1)
  N <- 40; K <- 3
  X <- matrix(rnorm(N * K), N, K)
  y <- rnorm(N)
  theta <- colMeans(X)
  res <- predict_psr(y, X, theta, PredictOptions(threshold = 0.5))
  res$yhat
}

---

Configuration objects (named lists) for predict / maxfit / grid.

Description

Mirrors Python PredictOptions, MaxFitOptions, and GridOptions. Pass the list to predict_psr, predict_maxfit, or predict_grid. Fields set to NULL are omitted so the engine applies its defaults.

Usage

PredictOptions(
  threshold = NULL,
  censor_type = "relevance",
  censor_unit = "percent",
  censor_operator = "greater_than_or_equal_to",
  prediction_scale = "response",
  adj_fit_multiplier = "k",
  inv_method = "gaussian",
  verify_missing_data = FALSE,
  include_linear_regression = FALSE,
  verbose = FALSE
)

MaxFitOptions(
  threshold = c(0, 0.2, 0.5, 0.8),
  censor_type = "both",
  censor_unit = "percent",
  censor_operator = "greater_than_or_equal_to",
  prediction_scale = "response",
  adj_fit_multiplier = "k",
  inv_method = "gaussian",
  verify_missing_data = FALSE,
  include_linear_regression = FALSE,
  verbose = FALSE,
  objective = "kfit",
  inner_parallel = "auto"
)

Arguments

threshold	Numeric vector of thresholds, or NULL for engine default.
censor_type	Character: "relevance", "similarity", or "both" ("both" only for maxfit/grid).
censor_unit	"percent" or "score".
censor_operator	Comparison vs threshold. Default "greater_than_or_equal_to" (">=").
prediction_scale	"response" or "logistic".
adj_fit_multiplier	"k", "identity", or "log".
inv_method	"gaussian", "cholesky", or "pseudoinverse".
verify_missing_data	Logical. Predict / MaxFit only (not GridOptions).
include_linear_regression	Logical; fills yhat_linear when available.
verbose	Logical; when TRUE, the engine may print library status diagnostics (default FALSE).
objective	MaxFit objective: "kfit", "fit", or "adjusted_fit".
inner_parallel	"auto" or "off" (within-call parallelism).

Value

A named list with class PredictOptions or MaxFitOptions.

See Also

GridOptions, predict_psr, predict_maxfit

Examples

PredictOptions(threshold = 0.5)
MaxFitOptions(objective = "kfit")

---

Print a compact summary of prediction results.

Description

Print a compact summary of prediction results.

Usage

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

Arguments

x	A PredictionResults object from predict_grid, predict_maxfit, or predict_psr.
...	Unused.

Value

x, invisibly.

---

Standalone insight scores (no prediction call required).

Description

These call the loaded RBP Math Engine directly. Use ensure_engine() / engine_available() if you need to check the runtime first.

Usage

relevance(X, theta)

similarity(X, theta)

info_x(X)

info_theta(X, theta)

relevance_metrics(X, theta)

Arguments

X	Numeric matrix, N rows by K columns.
theta	Circumstances vector, length K (not used by info_x()).

Value

For relevance() and similarity(), a numeric vector of length N. info_x() returns a numeric vector of length K. info_theta() returns a single numeric. relevance_metrics() returns a named list of metric vectors/scalars from the engine.

Examples

X <- matrix(rnorm(20 * 3), 20, 3)
theta <- colMeans(X)
if (engine_available()) {
  relevance(X, theta)
  similarity(X, theta)
  info_x(X)
  info_theta(X, theta)
  relevance_metrics(X, theta)
}

---

Process-wide percentile cut algorithm used when censor_unit is percent.

Description

Process-wide percentile cut algorithm used when censor_unit is percent.

Usage

set_percentile_value_algorithm(algorithm)

get_percentile_value_algorithm()

Arguments

algorithm

Integer code or string naming the algorithm (for example "full_sort", "order_statistics"). Exact accepted values are defined by the loaded engine ABI.

Value

set_percentile_value_algorithm() returns NULL invisibly. get_percentile_value_algorithm() returns the current algorithm code as an integer.

---

Remove a runtime tree installed by install_engine().

Description

Refuses to delete a directory that does not look like an RBP runtime (⁠lib/librbp_math_lib.*⁠ or lib/rbp_math_lib.dll present).

Usage

uninstall_engine(dest = NULL)

Arguments

dest	Prefix to remove. Default default_engine_home().

Value

TRUE invisibly if removed.

---

Package / ABI version and path diagnostics.

Description

Package / ABI version and path diagnostics.

Usage

package_version_rbpengine()

abi_version()

engine_path_loaded()

library_path()

Value

package_version_rbpengine() returns the installed package version as a string. abi_version() returns the loaded engine C ABI version as an integer (errors if the engine is not loaded). engine_path_loaded() returns the resolved engine library path, or NA_character_ when none is loaded. library_path() returns a named list of engine/license diagnostics including candidate search paths.

See Also

engine_available(), ensure_engine(), license_source(), math_lib_version()

Examples

package_version_rbpengine()
engine_path_loaded()

---