Package 'rbiogeme'

Description

rbiogeme is a complete R-facing interface to the native Biogeme estimation engine. Data, parameters, expressions, models, estimation controls, and post-estimation operations are specified from R. The bridge compiles the complete expression tree once before native numerical work begins.

Details

Start a new session with biogeme_setup() to provision or verify the runtime and receive corrective actions. Configure the runtime with biogeme_config() before the first call that initializes Python when selecting an existing interpreter. The default runtime is lazy. A typical workflow is to create a numeric data frame, wrap it with biogeme_database(), build symbolic expressions with variable() and biogeme_beta(), construct a specialized or generic model, and call estimate(). The returned fit supports the ordinary R methods summary(), coef(), vcov(), logLik(), and nobs().

Specialized constructors cover multinomial, nested, cross-nested, panel, Bayesian, MDCEV, hybrid-choice, catalog, assisted-specification, and sampled-alternative workflows. Generic models use a complete likelihood expression and can additionally hold a probability, named simulation expressions, weights, panel aggregation, draw metadata, subsets, and parameter overrides.

Expressions are symbolic. Arithmetic, comparisons, logical operators, transformations, probability functions, draws, integration nodes, and derivatives create neutral expression nodes; they do not evaluate a local R likelihood. Native Biogeme performs compilation, differentiation, integration, optimization, simulation, and reporting.

The expression operators +, -, *, /, and ^ build arithmetic nodes. Comparisons ==, !=, <, <=, >, and >= build indicator nodes. Logical conjunction, disjunction, and negation use \&, |, and !. Use logzero() and safe_exp() when the native numerically safe form is required.

Use estimate() for fresh estimation. Use estimate_or_load() only when explicit YAML loading or recycling is desired, and choose a fresh temporary output directory for equivalence tests. Random-draw and sampling examples should fix the native draw design and seed and document any remaining simulation noise.

Start with ?biogeme_setup or ?biogeme_check, then read vignette("getting-started", package = "rbiogeme") and vignette("modeling-workflows", package = "rbiogeme") for the R syntax and the complete workflow. Advanced Bayesian, Monte Carlo, MDCEV, catalog, hybrid-choice, and sampled-alternative examples are in vignette("advanced-models", package = "rbiogeme").

The whole package was implemented by ChatGPT 5.6 Luna under the supervision of Michel Bierlaire.

Value

Depending on the function, a database, expression, model, diagnostics list, estimation result, or result-derived object.

See Also

biogeme_config, biogeme_database, biogeme_model, logit_model, estimate, simulate, summary.biogeme_fit, coef.biogeme_fit, vcov.biogeme_fit, logLik.biogeme_fit

Description

Absolute value of a Biogeme expression

Usage

## S3 method for class 'biogeme_expression'
abs(x)

Arguments

Value

A Biogeme expression.

Description

The complete catalog search, quick-estimation objective evaluation, Pareto persistence, and final re-estimation are delegated to native Biogeme. The R interface accepts named objective and validity descriptors rather than exposing Python callback objects. The selected validity rule is created and executed inside the Python bridge between native estimates.

Usage

assisted_specification(
  model,
  objectives = "loglikelihood_dimension",
  pareto_file_name = NULL,
  model_name = "rbiogeme_assisted",
  controls = list(),
  force = TRUE,
  control = NULL,
  validity = NULL
)

run_assisted_specification(
  model,
  objectives = "loglikelihood_dimension",
  pareto_file_name = NULL,
  model_name = "rbiogeme_assisted",
  controls = list(),
  force = TRUE,
  control = NULL,
  validity = NULL
)

Arguments

Value

An object of class biogeme_assisted_fit containing native final results, the summary table, descriptions, and Pareto metadata.

Description

The complete R expression tree is compiled once, then native Biogeme builds and samples the PyMC model. The returned R object contains the native posterior summary and the paths of any generated NetCDF/YAML/HTML files; posterior draws are not represented as manually managed Python objects.

Usage

bayesian_estimate(
  model,
  model_name = "rbiogeme_model",
  controls = list(),
  starting_values = NULL,
  control = NULL
)

Arguments

Details

NetCDF and YAML output are enabled by default for this operation. Additional Bayesian controls such as bayesian_draws, warmup, chains, target_accept, calculate_likelihood, calculate_waic, calculate_loo, and mcmc_sampling_strategy are passed to native Biogeme through controls. Because those default Bayesian files are persistent, supply an explicit output_directory through biogeme_control() (or disable both output types explicitly).

Value

An object of class biogeme_bayesian_fit containing the native posterior summary and output paths.

Description

Loads the NetCDF result with Biogeme's public BayesianResults API and delegates the observation-level posterior mean calculation to native Biogeme. No posterior-draw or ArviZ object is exposed to R.

Usage

bayesian_posterior_mean_by_observation(bayesian_results, variable_name,
  control = NULL)

Arguments

Value

A data frame indexed by the native observation coordinate, with one column named after variable_name.

Description

Returns the serialized result of native Biogeme's BayesianResultsSummary.report_stored_variables() operation. No PyMC or ArviZ object is exposed to R.

Usage

bayesian_stored_variables(x)

Arguments

Value

A data frame describing each native stored variable by result group, variable name, dimensions, and shape.

Description

Create a Biogeme parameter

Usage

biogeme_beta(
  name,
  start = 0,
  lower = NULL,
  upper = NULL,
  fixed = FALSE,
  sigma_prior = 5,
  prior = NULL
)

Arguments

Details

Parameter names are preserved exactly by the bridge and are therefore part of the equivalence contract with native Biogeme. Bounds and fixed are passed to the native parameter definition.

Value

A parameter expression.

Examples

b_cost <- biogeme_beta("b_cost", start = -1, upper = 0)
b_cost

Description

Create a native-compatible expression catalog

Usage

biogeme_catalog(name, expressions, controller = NULL)

catalog(name, expressions, controller = NULL)

Arguments

Value

A catalog expression compiled to native Biogeme.

Description

Catalog controllers select the same named specification in every catalog that shares the controller. The object remains an R specification until the complete expression is compiled to native Biogeme.

Usage

biogeme_catalog_controller(name, specification_names, selected_name = NULL)

catalog_controller(name, specification_names, selected_name = NULL)

Arguments

Value

A neutral catalog controller.

Description

This is the runtime-only validation used by biogeme_setup() and is also useful when the environment has already been configured. It initializes the configured runtime, verifies the minimum R and Python versions, checks that native Biogeme can be imported, and compares its version with the configured requirement when that requirement pins an exact version. The check does not construct or estimate a model.

Usage

biogeme_check(verbose = interactive())

Arguments

Value

An object of class biogeme_check with elements ready, diagnostics, and issues. issues is a data frame with columns check, status, message, and action.

Description

Native Biogeme performs the repeated simulation and quantile calculation. R supplies ordinary parameter mappings and receives two ordinary data frames; no native simulation or result objects are exposed.

Usage

biogeme_confidence_intervals(
  model,
  beta_values,
  expressions = NULL,
  interval_size = 0.9,
  control = NULL
)

Arguments

Value

A list with left and right data frames and native metadata.

Description

Configuration must be performed before Python is initialized in the R session. The default requirement is ⁠biogeme==3.3.5⁠; use this function to select a different compatible Biogeme requirement explicitly.

Usage

biogeme_config(python = NULL, biogeme_requirement = NULL, debug = NULL)

Arguments

Details

biogeme_config(python = ...) selects an existing Python interpreter; it does not install Biogeme into that interpreter. If python is omitted, reticulate can provision the configured requirement in its managed environment.

Value

The current configuration, invisibly when changes are requested and visibly otherwise.

Description

Unspecified fields are omitted so native Biogeme defaults remain in force. Additional named arguments are passed through to the native bridge.

Usage

biogeme_control(
  model_name = NULL,
  output_directory = NULL,
  seed = NULL,
  numerically_safe = NULL,
  second_derivatives = NULL,
  second_derivatives_percentage = NULL,
  optimization_algorithm = NULL,
  number_of_draws = NULL,
  draw_type = NULL,
  draw_seed = NULL,
  bootstrap_samples = NULL,
  user_notes = NULL,
  variance_covariance_type = NULL,
  save_iterations = NULL,
  generate_html = NULL,
  generate_yaml = NULL,
  validation_folds = NULL,
  ...
)

Arguments

Details

Unspecified values are omitted. This lets native Biogeme apply its normal defaults. The control object can be stored in a model or passed to an estimation or simulation operation; it is not a Python object.

Value

A named list of controls.

Examples

biogeme_control(
  seed = 1234,
  generate_html = FALSE,
  generate_yaml = FALSE,
  save_iterations = FALSE
)

Description

The database remains an R object until a model is compiled. Data are copied and validated at construction time, so later modifications to the original data frame do not alter the model database.

Usage

biogeme_database(name, data)

Arguments

Details

The input must contain only numeric, named, non-empty columns. The original row identifiers are retained separately from the data columns and are carried through native filtering and row-extraction operations.

Value

An object of class biogeme_database.

Examples

database <- biogeme_database(
  "demo",
  data.frame(choice = c(1, 2), income = c(10, 20))
)
biogeme_database_columns(database)

Description

Return the columns available in a Biogeme database

Usage

biogeme_database_columns(database)

Arguments

Value

A character vector of column names.

Description

Define a derived database variable using a complete Biogeme expression

Usage

biogeme_database_define_variable(database, name, expression)

database_define_variable(database, name, expression)

define_variable(database, name, expression)

Arguments

Details

The expression is retained symbolically and is compiled by the Python bridge together with the model. It is not evaluated by an R callback during estimation or simulation.

Value

A new database specification.

Examples

database <- biogeme_database(
  "demo",
  data.frame(time = c(10, 12), cost = c(5, 6))
)
database <- biogeme_database_define_variable(
  database, "time_cost", variable("time") / variable("cost")
)
biogeme_database_columns(database)

Description

This is the R equivalent of native Database.extract_rows(). Indices are deliberately one-based, as in the rest of the R interface, and the original row identifiers are retained in the returned database.

Usage

biogeme_database_extract_rows(database, indices)

database_extract_rows(database, indices)

Arguments

Value

A new biogeme_database containing the selected observations.

Description

Return the number of observations excluded by native database filters

Usage

biogeme_database_filtered_row_count(database)

Arguments

Value

An integer, or NA until lazy filters are materialised.

Description

Test whether a Biogeme database contains a column

Usage

biogeme_database_has_column(database, column)

Arguments

Value

A single logical value.

Description

Return whether a database has a declared panel structure

Usage

biogeme_database_is_panel(database)

Arguments

Value

One logical value.

Description

Materialize lazy database operations through native Biogeme

Usage

biogeme_database_materialize(database)

Arguments

Value

A database with native derived columns and filters applied.

Description

Return the number of rows currently represented by a database

Usage

biogeme_database_nrow(database)

Arguments

Value

An integer, or NA until lazy native filters are materialised.

Description

Declare and validate a panel identifier

Usage

biogeme_database_panel(database, panel_id)

Arguments

Details

The identifier must be numeric and finite. Observations belonging to one identifier must be contiguous; the constructor rejects interleaved panel rows rather than silently reordering them.

Value

A new panel database specification.

Examples

panel_database <- biogeme_panel_database(
  "panel_demo",
  data.frame(person = c(1, 1, 2, 2), choice = c(1, 2, 2, 1)),
  panel_id = "person"
)
biogeme_database_is_panel(panel_database)

Description

Remove observations satisfying a Biogeme logical expression

Usage

biogeme_database_remove(database, condition)

database_remove(database, condition)

remove_observations(database, condition)

Arguments

Details

condition is a symbolic indicator. Rows for which it is true are removed when the database is materialized by native Biogeme.

Value

A new database specification.

Examples

database <- biogeme_database(
  "demo",
  data.frame(choice = c(1, 2, 1), income = c(10, 20, 30))
)
filtered <- biogeme_database_remove(database, variable("income") > 10)
biogeme_database_nrow(filtered)

Description

Return the original row identifiers of a Biogeme database

Usage

biogeme_database_row_ids(database)

Arguments

Value

A character vector of row identifiers.

Description

Generate a native-compatible segmentation specification from a database

Usage

biogeme_database_segmentation(database, variable, mapping, reference = NULL)

database_generate_segmentation(database, variable, mapping, reference = NULL)

Arguments

Value

A biogeme_segmentation specification.

Description

This function initializes the configured runtime. For a check that catches initialization failures and returns an actionable status object, use biogeme_check().

Usage

biogeme_diagnostics()

Value

A named list containing environment diagnostics.

See Also

biogeme_check(), biogeme_config()

Description

Declare first-class draw metadata for a model

Usage

biogeme_draws(
  name,
  draw_type = "NORMAL",
  number_of_draws = NULL,
  seed = NULL,
  matrix = NULL,
  generator = NULL
)

Arguments

Value

A biogeme_draws object.

Description

Return the diagnostic details attached to a Biogeme error

Usage

biogeme_error_details(error)

Arguments

Value

A named list with operation, suggestion, parent, and optional Python traceback details.

Description

Return native Biogeme general estimation statistics

Usage

biogeme_general_statistics(fit)

Arguments

Value

A named list of native Biogeme statistics.

Description

This is the neutral R counterpart of native Biogeme's generic_alt_specific_catalogs(). Each returned element is a named list of catalogs, one for every alternative. The catalogs share one native controller with the exact specifications generic and altspec; when segmentations are supplied, the segmentation catalogs are nested below that controller in the same order as native Biogeme.

Usage

biogeme_generic_alt_specific_catalogs(
  generic_name,
  beta_parameters,
  alternatives,
  potential_segmentations = NULL,
  maximum_number = 5L
)

generic_alt_specific_catalogs(
  generic_name,
  beta_parameters,
  alternatives,
  potential_segmentations = NULL,
  maximum_number = 5L
)

Arguments

Value

A list of named lists of catalog expressions, one list per Beta.

Description

Maximum of Biogeme expressions

Usage

biogeme_max(...)

Arguments

Value

A Biogeme expression.

Description

This is a declarative model object. The alternative utilities, shape parameters, and observed consumptions remain neutral R expression trees until the Python bridge sends the complete specification to the native Biogeme engine. The likelihood and forecasting algorithms are therefore provided by Biogeme itself.

Usage

biogeme_mdcev_model(
  database,
  model_type = c("gamma_profile", "generalized", "translated", "non_monotonic"),
  baseline_utilities,
  gamma_parameters,
  alpha_parameters = NULL,
  mu_utilities = NULL,
  scale_parameter = NULL,
  prices = NULL,
  weights = NULL,
  number_of_chosen_alternatives,
  consumed_quantities,
  subset = NULL,
  control = NULL
)

mdcev_model(
  database,
  model_type = c("gamma_profile", "generalized", "translated", "non_monotonic"),
  baseline_utilities,
  gamma_parameters,
  alpha_parameters = NULL,
  mu_utilities = NULL,
  scale_parameter = NULL,
  prices = NULL,
  weights = NULL,
  number_of_chosen_alternatives,
  consumed_quantities,
  subset = NULL,
  control = NULL
)

Arguments

Value

An object of class biogeme_mdcev_model.

Description

Minimum of Biogeme expressions

Usage

biogeme_min(...)

Arguments

Value

A Biogeme expression.

Description

The formula is a neutral R expression. It is compiled once into a native Biogeme expression graph before any estimation or simulation starts.

Usage

biogeme_model(
  database,
  formula = NULL,
  weight = NULL,
  probability = NULL,
  simulations = NULL,
  panel_trajectory = FALSE,
  draws = NULL,
  subset = NULL,
  parameter_overrides = NULL,
  control = NULL,
  availability = NULL
)

Arguments

Details

formula is the native log-likelihood expression. A named list may contain log_like (or loglike) and additional expressions, but a generic model must still provide a likelihood, probability, or simulation expressions. simulations is a named list evaluated only when simulate() is called.

Value

An object of class biogeme_model.

Examples

database <- biogeme_database("demo", data.frame(choice = c(1, 2), x = c(1, 2)))
probability <- logit_probability(
  utilities = list(`1` = 0, `2` = biogeme_beta("b") * variable("x")),
  alternative = variable("choice")
)
model <- biogeme_model(
  database,
  formula = logzero(probability),
  simulations = list(probability = probability)
)
model

Description

Return the parameter definitions in a model

Usage

biogeme_model_parameters(model)

Arguments

Value

A data frame of parameter definitions.

Description

Unlike biogeme_model_parameters(), this operation also sees parameters generated by native helpers such as segmentation and parameters in every catalog branch. When configuration_id is supplied, native Biogeme first resolves that configuration and the returned names describe the flattened selected expression.

Usage

biogeme_native_parameter_names(
  model,
  configuration_id = NULL,
  model_name = "rbiogeme_parameters",
  controls = list()
)

Arguments

Value

A list with all, free, and fixed character vectors.

Description

Construct a panel database in one call

Usage

biogeme_panel_database(name, data, panel_id)

Arguments

Value

A biogeme_database object.

Description

Creates a data-only prior descriptor. The Python bridge compiles it into a native PyMC prior before estimation; R callbacks are not used by the sampler.

Usage

biogeme_prior(distribution = c("normal", "student_t"), sigma = 5, nu = 5)

Arguments

Value

A declarative biogeme_prior object.

Description

Initialize and return the Python interpreter used by rbiogeme

Usage

biogeme_python()

Value

A reticulate Python configuration object. If no interpreter was selected, reticulate may provision the configured native requirement in its managed environment.

Description

Stores the strata and sample sizes used by Biogeme's sampling-of-alternatives API. The segments must cover full_set, and no sample size may exceed the size of its segment.

Usage

biogeme_sampling_partition(segments, sample_sizes, full_set = NULL)

Arguments

Value

A declarative biogeme_sampling_partition object. Native Biogeme performs the actual random sampling when the model is estimated.

See Also

sampled_alternatives_model()

Description

Define a discrete parameter segmentation

Usage

biogeme_segmentation(variable, mapping, reference = NULL)

Arguments

Value

A biogeme_segmentation specification.

Description

This is the structural counterpart of native Biogeme's segmentation_catalogs(). It only enumerates catalog names and builds neutral expression nodes; native Biogeme still creates the segmented parameters and evaluates the selected specification.

Usage

biogeme_segmentation_catalogs(
  generic_name,
  beta_parameters,
  potential_segmentations,
  maximum_number,
  selected_name = NULL
)

segmentation_catalogs(
  generic_name,
  beta_parameters,
  potential_segmentations,
  maximum_number,
  selected_name = NULL
)

Arguments

Value

A list of synchronized catalog expressions, one per beta.

Description

This is the recommended first command for a new user. With no python argument, reticulate provisions an isolated managed environment containing the configured Biogeme requirement when the runtime is first initialized. If python is supplied, that existing interpreter is selected instead and must already contain the requested Biogeme package. In both cases the function returns the same actionable status object as biogeme_check().

Usage

biogeme_setup(
  python = NULL,
  biogeme_requirement = NULL,
  debug = NULL,
  verbose = interactive()
)

Arguments

Value

An object of class biogeme_check. Its ready element is TRUE when the runtime can be used for model operations.

See Also

biogeme_check(), biogeme_config()

Description

Box–Cox transformation

Usage

boxcox(x, lambda)

Arguments

Value

A Biogeme expression.

Description

Return catalog configuration identifiers using native Biogeme

Usage

catalog_configuration_ids(
  model,
  model_name = "rbiogeme_catalog",
  controls = list(),
  control = NULL
)

Arguments

Value

Character vector of exact native configuration identifiers.

Description

This delegates to the public BIOGEME.check_derivatives() operation. The complete expression tree is compiled first; no R callback is evaluated by the derivative checker.

Usage

check_derivatives(
  model,
  model_name = "rbiogeme_model",
  controls = list(),
  control = NULL,
  verbose = FALSE
)

Arguments

Value

A list containing the native function value, analytical and finite difference gradients and Hessians, and their error vectors.

Description

The model is compiled once and the supplied fixed estimate is passed to native BIOGEME.check_monte_carlo_stability(). Native Biogeme evaluates the objective and gradient at fresh draw designs and writes its YAML checkpoint and Markdown report.

Usage

check_monte_carlo_stability(
  model,
  fit,
  model_name = "rbiogeme_model",
  controls = list(),
  output_directory = NULL,
  basename = NULL,
  resume = TRUE,
  control = NULL
)

Arguments

Value

An object of class biogeme_monte_carlo_diagnostic containing the native status, conclusion, recommendation, data, and output paths.

Description

Count catalog specifications using native Biogeme

Usage

count_number_of_specifications(
  model,
  model_name = "rbiogeme_catalog",
  controls = list(),
  control = NULL
)

Arguments

Value

The native number of catalog configurations, or NULL when native Biogeme cannot determine a count.

Description

Construct a native cross-nested-logit log-probability expression

Usage

cross_nested_log_probability(
  utilities,
  availability,
  nests,
  alternative,
  alternative_codes = NULL,
  scale_parameter = NULL
)

Arguments

Value

A Biogeme expression compiled to native biogeme.models.logcnl.

Description

Calculate the native cross-nested-logit error-term correlation matrix

Usage

cross_nested_logit_correlation(
  model,
  beta_values = NULL,
  alternatives_names = NULL
)

Arguments

Value

A numeric correlation matrix.

Description

Define a cross-sectional cross-nested-logit model

Usage

cross_nested_logit_model(
  database,
  choice,
  utilities,
  nests,
  availability = NULL,
  alternative_codes = NULL,
  scale_parameter = NULL,
  control = NULL
)

Arguments

Value

An object of class biogeme_cross_nested_logit_model.

Description

Define one cross-nested-logit nest

Usage

cross_nested_nest(nest_parameter, allocation, name = NULL)

Arguments

Value

A biogeme_cross_nested_nest specification.

Description

Define the complete cross-nested-logit nest structure

Usage

cross_nested_nests(choice_set, nests, sparse = FALSE)

Arguments

Value

A biogeme_cross_nested_nests specification.

Description

Construct a native cross-nested-logit probability expression

Usage

cross_nested_probability(
  utilities,
  availability,
  nests,
  alternative,
  alternative_codes = NULL
)

Arguments

Value

A Biogeme expression compiled to native biogeme.models.cnl.

Description

Summarize the structural sparsity of a CNL nest specification

Usage

cross_nested_sparsity_report(nests)

Arguments

Value

A data frame with one row per nest and membership counts.

Description

Represents native Biogeme's CrossVariableTuple. The Python bridge expands the expression after native choice-set sampling; R callbacks are not used during estimation.

Usage

cross_variable(name, formula)

Arguments

Value

A declarative biogeme_cross_variable object.

Description

Symbolically differentiate an expression with respect to a named variable

Usage

derive(expression, name)

Derive(expression, name)

Arguments

Value

A Biogeme expression.

Description

Wraps a child expression in native Biogeme's DistributedParameter node. The wrapper preserves the named variable in Bayesian output and is compiled before native estimation; it is not evaluated by R during sampling.

Usage

distributed_parameter(name, expression)

Arguments

Details

This helper is a thin interface to native Biogeme and does not implement a sampling or likelihood engine in R.

Value

A symbolic Biogeme expression compiled to native DistributedParameter.

Examples

beta <- biogeme_beta("b_time")
random_coefficient <- distributed_parameter(
  "b_time_rnd",
  beta + biogeme_beta("b_time_s", start = 1) * draw("b_time_eps", "NORMAL")
)
format(random_coefficient)

Description

Create a named Biogeme draw node

Usage

draw(name, draw_type = "NORMAL")

Arguments

Value

A Biogeme expression.

Description

Select an expression from a numeric mapping

Usage

Elem(mapping, index)

elem(mapping, index)

Arguments

Value

A Biogeme expression.

Description

Estimate a Biogeme model

Usage

estimate(
  model,
  model_name = "rbiogeme_model",
  controls = list(),
  starting_values = NULL,
  run_bootstrap = FALSE,
  yaml_file_name = NULL,
  control = NULL
)

Arguments

Details

estimate() always requests a fresh native estimation. It does not load a previous YAML or iteration file implicitly. Use estimate_or_load() when explicit result loading or recycling is required.

Value

An object of class biogeme_fit.

Examples

## Not run: 
fit <- estimate(
  model,
  model_name = "demo",
  control = biogeme_control(
    output_directory = tempfile("rbiogeme-estimate-"),
    generate_html = FALSE,
    generate_yaml = FALSE,
    save_iterations = FALSE
  )
)
summary(fit)

## End(Not run)

Description

Catalog choices, synchronized controllers, estimation, result summaries, Pareto selection, and parameter comparison are all handled by native Biogeme. The returned object only contains ordinary R representations of those native results.

Usage

estimate_catalog(
  model,
  model_name = "rbiogeme_catalog",
  controls = list(),
  quick_estimate = FALSE,
  run_bootstrap = FALSE,
  force = TRUE,
  control = NULL
)

Arguments

Value

An object of class biogeme_catalog_fit containing native model results, summaries, Pareto-optimal specifications, and LaTeX comparison.

Description

The configuration identifier is resolved by native BIOGEME.from_configuration(). R only supplies the compiled expression tree and receives ordinary serialized estimation results; no R expression or callback is evaluated during estimation.

Usage

estimate_configuration(
  model,
  configuration_id,
  model_name = "rbiogeme_configuration",
  controls = list(),
  starting_values = NULL,
  run_bootstrap = FALSE,
  yaml_file_name = NULL,
  control = NULL
)

Arguments

Value

An object of class biogeme_fit containing native results.

Description

force = FALSE permits loading the named YAML file; force = TRUE always performs fresh estimation. The default estimate() path never recycles an old result file.

Usage

estimate_or_load(
  model,
  yaml_file_name,
  force = FALSE,
  model_name = "rbiogeme_model",
  controls = list(),
  starting_values = NULL,
  run_bootstrap = FALSE
)

Arguments

Value

A biogeme_fit object.

Description

Regenerates the sampled choice sets with recycling disabled, compiles the sampled likelihood once in native Biogeme, and delegates estimation to the native engine. No Python source is generated by the R interface.

Usage

estimate_sampled_alternatives(
  model,
  model_name = "rbiogeme_sampled",
  controls = list(),
  starting_values = NULL,
  run_bootstrap = FALSE,
  control = NULL
)

Arguments

Value

A biogeme_fit object with native sampling-context and sampled-file metadata attached.

See Also

sampled_alternatives_model()

Description

The expression is compiled once by the Python bridge. The initial result contains the native function value, gradient, Hessian, and BHHH matrix. If points is supplied, the same compiled native callable evaluates each row with the requested free-parameter values. R does not evaluate the expression locally and no Python object is returned.

Usage

evaluate_biogeme_expression(
  expression,
  beta = NULL,
  points = NULL,
  numerically_safe = FALSE,
  use_jit = TRUE
)

Arguments

Value

An object of class biogeme_expression_evaluation with initial, free_beta_names, and evaluations components.

Description

This operation delegates to Biogeme's public get_value_c calculator. The expression is compiled before the native evaluator runs; R receives only a numeric vector or scalar.

Usage

evaluate_biogeme_expression_c(
  model,
  expression,
  beta,
  aggregation = FALSE,
  number_of_draws = 1000L,
  numerically_safe = FALSE,
  use_jit = TRUE
)

Arguments

Value

A numeric vector, or one numeric scalar when aggregation = TRUE.

Description

Integrate an expression over a standard normal random variable

Usage

integrate_normal(expression, name, number_of_quadrature_points = 30L)

Arguments

Value

A Biogeme expression.

Description

Define one coefficient-variable term for a linear utility

Usage

linear_term(beta, x)

LinearTermTuple(beta, x)

Arguments

Value

A linear-utility term.

Description

Construct a native linear utility expression

Usage

linear_utility(terms)

LinearUtility(terms)

Arguments

Value

A Biogeme expression compiled to native LinearUtility.

Description

This is the log-probability counterpart of logit_probability(). It is compiled directly to Biogeme's public models.loglogit constructor, which preserves the native numerically stable likelihood used by examples such as Swissmetro b20.

Usage

logit_log_probability(
  utilities,
  availability = NULL,
  alternative,
  alternative_codes = NULL
)

Arguments

Value

A Biogeme logit log-probability expression.

Description

Define a cross-sectional multinomial logit model

Usage

logit_model(
  database,
  choice,
  utilities,
  availability = NULL,
  alternative_codes = NULL,
  weight = NULL
)

Arguments

Details

The utility list is named by alternative. If the names are not integer codes, pass alternative_codes as a named integer vector. Availability and weights may be constants or symbolic expressions.

Value

An object of class biogeme_logit_model.

Examples

database <- biogeme_database(
  "demo",
  data.frame(choice = c(1, 2), x = c(1, 2))
)
b <- biogeme_beta("b")
model <- logit_model(
  database,
  choice = "choice",
  utilities = list(`1` = 0, `2` = b * variable("x"))
)
model

Description

Construct a native logit probability expression

Usage

logit_probability(
  utilities,
  availability = NULL,
  alternative,
  alternative_codes = NULL
)

logit(utilities, availability = NULL, alternative, alternative_codes = NULL)

Arguments

Value

A probability expression compiled to native biogeme.models.logit.

Description

A numerically safe logarithm that returns zero at zero

Usage

logzero(x)

safe_log(x)

Arguments

Value

A Biogeme expression.

Description

The MDCEV likelihood is generated by the native Biogeme MDCEV class after compilation. This convenience wrapper has the same fresh-estimation semantics as estimate().

Usage

mdcev_estimate(
  model,
  model_name = "rbiogeme_mdcev",
  controls = list(),
  starting_values = NULL,
  run_bootstrap = FALSE,
  yaml_file_name = NULL,
  control = NULL
)

Arguments

Value

A biogeme_fit object.

Description

Forecast MDCEV consumption using native Biogeme algorithms

Usage

mdcev_forecast(
  model,
  fit,
  database = NULL,
  total_budget,
  epsilons = NULL,
  number_of_draws = NULL,
  seed = NULL,
  brute_force = FALSE,
  tolerance_dual = 1e-10,
  tolerance_budget = 1e-10
)

Arguments

Value

A biogeme_mdcev_forecast object containing R data frames.

Description

Return native pandas description tables for an MDCEV forecast

Usage

mdcev_forecast_describe(forecast)

Arguments

Value

A list of ordinary R data frames corresponding to native pandas DataFrame.describe() output.

Description

Generate native MDCEV error-term draws

Usage

mdcev_generate_epsilons(
  model,
  number_of_observations,
  number_of_draws,
  seed = NULL
)

Arguments

Value

A list of numeric matrices, one matrix per observation.

Description

Return native Biogeme's estimated-parameter table for an MDCEV fit

Usage

mdcev_parameter_table(fit, variance_covariance_type = NULL)

Arguments

Value

A named list of ordinary R data frames returned by native Biogeme.

Description

Return native Biogeme's compact MDCEV estimation summary

Usage

mdcev_short_summary(fit)

Arguments

Value

The native Biogeme summary string.

Description

Validate the two native MDCEV forecasting algorithms

Usage

mdcev_validate_forecast(
  model,
  fit,
  database = NULL,
  total_budget,
  epsilons = NULL,
  number_of_draws = NULL,
  seed = NULL,
  tolerance_dual = 1e-13,
  tolerance_budget = 1e-13
)

Arguments

Value

TRUE when native validation completes without an exception.

Description

Monte Carlo average of an expression

Usage

monte_carlo(expression)

Arguments

Value

A Biogeme expression.

Description

Construct a native nested-logit log probability with endogenous-sampling correction

Usage

nested_endogenous_sampling_log_probability(
  utilities,
  availability,
  nests,
  correction,
  alternative,
  alternative_codes = NULL
)

Arguments

Value

A Biogeme expression compiled through native get_mev_for_nested and logmev_endogenous_sampling.

Description

Construct a native nested-logit log-probability expression

Usage

nested_log_probability(
  utilities,
  availability,
  nests,
  alternative,
  alternative_codes = NULL,
  scale_parameter = NULL
)

Arguments

Value

A Biogeme expression compiled to native biogeme.models.lognested.

Description

Calculate the native nested-logit error-term correlation matrix

Usage

nested_logit_correlation(
  model,
  beta_values = NULL,
  alternatives_names = NULL,
  mu = 1
)

Arguments

Value

A numeric correlation matrix.

Description

Define a cross-sectional nested-logit model

Usage

nested_logit_model(
  database,
  choice,
  utilities,
  nests,
  availability = NULL,
  alternative_codes = NULL,
  scale_parameter = NULL,
  control = NULL
)

Arguments

Value

An object of class biogeme_nested_logit_model.

Description

Define one non-trivial nested-logit nest

Usage

nested_nest(nest_parameter, alternatives, name = NULL)

Arguments

Value

A biogeme_nested_nest specification.

Description

Alternatives not listed in a non-trivial nest are treated by native Biogeme as trivial nests containing one alternative.

Usage

nested_nests(choice_set, nests)

Arguments

Value

A biogeme_nested_nests specification.

Description

Construct a native nested-logit probability expression

Usage

nested_probability(
  utilities,
  availability,
  nests,
  alternative,
  alternative_codes = NULL
)

Arguments

Value

A Biogeme expression compiled to native biogeme.models.nested.

Description

Normal cumulative distribution function

Usage

normal_cdf(x)

Arguments

Value

A Biogeme expression.

Description

Normal probability density function

Usage

normal_pdf(x)

Arguments

Value

A Biogeme expression.

Description

Constructs a neutral expression node. The complete node is compiled once to Biogeme's public ordered-logit expression before estimation or simulation.

Usage

ordered_logit_log_probability(eta, cutpoints, alternative,
  categories = NULL, neutral_labels = numeric(),
  enforce_order = TRUE, eps = 1e-12)

Arguments

Value

A Biogeme expression compiled to native OrderedLogLogit.

Description

Constructs a neutral expression node. The complete node is compiled once to Biogeme's public ordered-probit expression before estimation or simulation.

Usage

ordered_probit_log_probability(eta, cutpoints, alternative,
  categories = NULL, neutral_labels = numeric(),
  enforce_order = TRUE, eps = 1e-12)

Arguments

Value

A Biogeme expression compiled to native OrderedLogProbit.

Description

Aggregate an observation-level likelihood over a panel trajectory

Usage

panel_likelihood_trajectory(expression)

Arguments

Value

A Biogeme expression.

Description

The Pareto file is read by native ParetoPostProcessing. Re-estimation, summary compilation, model descriptions, and optional Pareto plotting all remain native operations; the returned object contains ordinary R values.

Usage

pareto_post_processing(
  model,
  pareto_file_name,
  model_name = "rbiogeme_pareto",
  controls = list(),
  recycle = FALSE,
  plot_file_name = NULL,
  objective_x = 0L,
  objective_y = 1L,
  label_x = NULL,
  label_y = NULL,
  control = NULL
)

Arguments

Value

An object of class biogeme_pareto_fit containing native results, the compiled summary, descriptions, Pareto statistics, and plot path.

Description

Piecewise-linear expression using native Biogeme naming rules

Usage

piecewise(
  expression,
  thresholds,
  betas = NULL,
  transform = c("formula", "variable")
)

Arguments

Value

A Biogeme expression.

Description

Predict native probabilities or simulation expressions

Usage

## S3 method for class 'biogeme_fit'
predict(object, newdata = NULL, expressions = NULL, control = NULL, ...)

Arguments

Details

predict() is a convenience wrapper around simulate(). It does not calculate probabilities in R and does not refit the model. Use simulate() directly when several named quantities, posterior draws, or a custom simulation workflow are needed.

Value

A data frame containing values calculated by native Biogeme.

Examples

database <- biogeme_database(
  "demo",
  data.frame(choice = c(1, 2), x = c(1, 2))
)
model <- logit_model(
  database,
  choice = "choice",
  utilities = list(`1` = 0, `2` = biogeme_beta("b") * variable("x"))
)
# After fitting: predict(fit) or predict(fit, newdata = data.frame(...))

Description

The complete expression tree is compiled once, then native Biogeme's CompiledFormulaEvaluator is used for each requested evaluation mode. Each mode is evaluated twice, matching the native profiling example's first call and steady-state measurements. Only ordinary environment and timing summaries cross back to R.

Usage

profile_jax(
  model,
  beta_values = NULL,
  cases = list(
    list(
      label = "Function only", gradient = FALSE, hessian = FALSE, bhhh = FALSE
    ),
    list(
      label = "Function + gradient", gradient = TRUE, hessian = FALSE, bhhh = FALSE
    ),
    list(
      label = "Function + gradient + Hessian",
      gradient = TRUE, hessian = TRUE, bhhh = FALSE
    ),
    list(
      label = "Function + gradient + BHHH",
      gradient = TRUE, hessian = FALSE, bhhh = TRUE
    )
  ),
  model_name = "rbiogeme_model",
  controls = list(),
  numerically_safe = FALSE,
  control = NULL
)

Arguments

Details

Timing values depend on the active Python, JAX, hardware, and thread configuration. The operation is a profiling diagnostic, not an estimation operation.

Value

An object of class biogeme_jax_profile containing the native JAX environment and serialized profile data for each case.

See Also

biogeme_control

Description

quick_estimate() delegates to native BIOGEME.quick_estimate(). It returns parameter values and the statistics that native Biogeme makes available without the ordinary post-estimation derivative calculations. Use save_results() when a standard YAML result is required.

Usage

quick_estimate(
  model,
  model_name = "rbiogeme_model",
  controls = list(),
  control = NULL
)

Arguments

Value

An object of class biogeme_fit.

Description

Create a random variable for native numerical integration

Usage

random_variable(name)

Arguments

Value

A Biogeme expression.

Description

Read standard Biogeme YAML results

Usage

read_results(filename)

Arguments

Value

A biogeme_fit object.

Description

Numerically safe exponential

Usage

safe_exp(x)

Arguments

Value

A Biogeme expression.

Description

Defines the protocol for a native sampling-of-alternatives model. Sampling, cross-variable expansion, likelihood construction, differentiation, and optimization are performed by native Biogeme through the Python bridge. Sampling is regenerated with recycling disabled by default.

Usage

sampled_alternatives_model(
  alternatives,
  individuals,
  choice_column,
  id_column,
  utility,
  partition,
  biogeme_file_name,
  model_type = c("logit", "nested", "cnl"),
  combined_variables = list(),
  mev_partition = NULL,
  mev_sample_sizes = NULL,
  nests = NULL,
  control = NULL
)

Arguments

Value

A biogeme_sampled_alternatives_model object containing ordinary R data and a neutral expression specification.

See Also

estimate_sampled_alternatives()

Description

Creates sampling protocol metadata equivalent to native generate_segment_size(); native Biogeme still performs validation and sampling.

Usage

sampling_segment_sizes(sample_size, number_of_segments)

Arguments

Value

An integer vector whose entries differ by at most one. Any remainder is assigned to the first segments, matching native Biogeme.

Description

Save standard Biogeme YAML results

Usage

save_results(fit, filename)

Arguments

Value

fit, invisibly.

Description

The generated native parameters follow Biogeme's public naming contract: ⁠<base>_ref⁠ for the reference and ⁠<base>_diff_<segment>⁠ for differences.

Usage

segment_beta(beta, segmentations, prefix = "segmented")

segmented_beta(beta, segmentations, prefix = "segmented")

Arguments

Value

A Biogeme expression compiled through native Segmentation.

Description

Simulate named native Biogeme expressions at fixed estimates

Usage

simulate(model, expressions = NULL, beta, control = NULL, database = NULL)

Arguments

Details

expressions is a named list of complete symbolic expressions. When it is omitted, the model's simulations list is used. Native Biogeme evaluates these expressions at the supplied parameter values and returns ordinary R data frames.

Value

A biogeme_simulation object containing a data frame of values.

Examples

## Not run: 
simulation_model <- biogeme_model(
  database,
  formula = choice_log_probability,
  simulations = list(probability = choice_probability)
)
simulated <- simulate(
  simulation_model,
  beta = fit,
  control = biogeme_control(output_directory = tempfile("rbiogeme-sim-"))
)
as.data.frame(simulated)

## End(Not run)

Description

Evaluates named simulation formulas over native Bayesian posterior draws and returns the native mean and quantile summaries without exposing PyMC objects.

Usage

simulate_bayesian(model, bayesian_results, expressions = NULL,
  percentage_of_draws_to_use = 10, lower_quantile = 0.025,
  upper_quantile = 0.975, control = NULL)

Arguments

Value

A biogeme_simulation object containing native summaries.

Description

This operation delegates to Biogeme's public calculate_single_formula_from_expression evaluator. Unlike simulate(), it returns one native aggregated value, which is useful for panel likelihood formulas.

Usage

simulate_single_formula(
  model,
  expression,
  beta,
  number_of_draws,
  seed = NULL,
  numerically_safe = FALSE,
  use_jit = TRUE
)

Arguments

Value

One numeric scalar returned by native Biogeme.

Description

Square root of a Biogeme expression

Usage

## S3 method for class 'biogeme_expression'
sqrt(x)

Arguments

Value

A Biogeme expression.

Description

This uses native LinearUtility and Segmentation during bridge compilation. The generated parameter names are ⁠asc_*_ref⁠ and ⁠asc_*_diff_*⁠, matching the Python example.

Usage

swissmetro_b01b_model(
  database,
  user_notes =
    paste0("Example of a logit model with three alternatives: Train, Car and ",
    "Swissmetro. Same as 01logit and introducing LinearUtility and ",
    "automatic segmentation of parameters.")
)

Arguments

Value

A biogeme_logit_model.

Description

The transformation is deliberately expressed as native database operations. It removes rows with PURPOSE other than 1 or 3 and rows with CHOICE == 0, then defines the cost, availability, and ⁠/100⁠ scaled variables used by plot_b01a_logit.py. Row order and original row IDs are retained. Set panel = TRUE to declare ID as the panel identifier.

Usage

swissmetro_data(
  data,
  name = "swissmetro",
  panel = FALSE,
  filter_purpose = TRUE
)

prepare_swissmetro(
  data,
  name = "swissmetro",
  panel = FALSE,
  filter_purpose = TRUE
)

Arguments

Value

A biogeme_database specification.

Description

Build the baseline Swissmetro MNL specification

Usage

swissmetro_mnl_model(database)

Arguments

Value

A biogeme_logit_model.

Description

Validate a model using native Biogeme cross-validation

Usage

validate(model, fit, folds = 5L, groups = NULL, seed = NULL, control = NULL)

Arguments

Value

A native-bridge validation result.

Description

Model construction, database operations, and native Biogeme model creation are checked without running an optimizer or writing estimation results. The returned diagnostics are ordinary R values; the native model object is created and discarded inside the bridge.

Usage

validate_model(model, control = NULL)

Arguments

Details

This is specification validation, not cross-validation. Use validate() after estimation when the goal is out-of-sample fold evaluation.

Value

An object of class biogeme_model_validation containing the native validation status, database information, formula names, and parameter count.

Examples

## Not run: 
database <- biogeme_database(
  "demo",
  data.frame(choice = c(1, 2), x = c(1, 2))
)
model <- logit_model(
  database,
  choice = "choice",
  utilities = list(`1` = 0, `2` = biogeme_beta("b") * variable("x"))
)
validate_model(model)

## End(Not run)

Description

Create a Biogeme data variable

Usage

variable(name)

Arguments

Details

variable() creates a symbolic reference. It does not extract an R column or calculate a vector immediately. Use it in arithmetic and model expressions after the corresponding database column has been defined.

Value

A variable expression.

Examples

x <- variable("income")
b <- biogeme_beta("b_income")
b * x + 1