inst/doc/getting-started.R

In rbiogeme: Interface to 'Biogeme'

## ----setup, include = FALSE---------------------------------------------------
knitr::opts_chunk$set(
  echo = TRUE,
  eval = FALSE,
  collapse = TRUE,
  comment = "#>"
)

## ----installation-------------------------------------------------------------
# install.packages(
#   "/path/to/rbiogeme_0.1.2.tar.gz",
#   repos = NULL,
#   type = "source"
# )

## ----configuration------------------------------------------------------------
# library(rbiogeme)
# 
# biogeme_setup(
#   python = "/absolute/path/to/python",
#   biogeme_requirement = "biogeme==3.3.5"
# )
# 
# # This reports the versions visible to reticulate.
# biogeme_diagnostics()

## ----managed-setup------------------------------------------------------------
# library(rbiogeme)
# check <- biogeme_setup()
# stopifnot(check$ready)

## ----readiness----------------------------------------------------------------
# check <- biogeme_check()
# if (!check$ready) {
#   print(check)
#   stop("The rbiogeme environment is not ready.")
# }

## ----existing-environment-----------------------------------------------------
# biogeme_setup(python = "/path/to/rbiogeme-venv/bin/python")

## ----data---------------------------------------------------------------------
# data <- data.frame(
#   choice = c(1, 2, 1, 2, 1, 2, 1, 2),
#   time = c(10, 8, 12, 7, 11, 9, 13, 8),
#   cost = c(5, 7, 6, 8, 5, 7, 6, 9),
#   income = c(1, 2, 1, 3, 2, 1, 3, 2)
# )
# 
# database <- biogeme_database("demo", data)
# 
# # variable() is symbolic: it refers to a database column, not to an R vector.
# time <- variable("time")
# cost <- variable("cost")
# income <- variable("income")
# 
# # biogeme_beta() creates a named native parameter. The name is part of the
# # equivalence contract and will appear unchanged in the result.
# b_time <- biogeme_beta("b_time", start = 0)
# b_cost <- biogeme_beta("b_cost", start = 0)
# asc_2 <- biogeme_beta("asc_2", start = 0)
# 
# utility_1 <- b_time * time + b_cost * cost
# utility_2 <- asc_2 + b_time * time + b_cost * cost

## ----expression-syntax--------------------------------------------------------
# available_2 <- (cost < 10) & (income >= 1)
# not_available_2 <- !(available_2)
# either_condition <- (time < 9) | (cost > 8)
# 
# # Native-safe mathematical primitives are available as expression functions.
# safe_probability <- logzero(logit_probability(
#   utilities = list(`1` = utility_1, `2` = utility_2),
#   availability = list(`1` = 1, `2` = available_2),
#   alternative = variable("choice")
# ))

## ----mnl-model----------------------------------------------------------------
# model <- logit_model(
#   database = database,
#   choice = "choice",
#   utilities = list(
#     `1` = utility_1,
#     `2` = utility_2
#   ),
#   availability = list(
#     `1` = 1,
#     `2` = available_2
#   )
# )
# 
# # Check the native specification before running the optimizer.
# validation <- validate_model(model)
# stopifnot(validation$valid)
# 
# # A fresh temporary output directory prevents an old YAML or iteration file
# # from being reused during an equivalence test.
# output_directory <- tempfile("rbiogeme-demo-")
# dir.create(output_directory)
# 
# fit <- estimate(
#   model,
#   model_name = "rbiogeme_demo",
#   control = biogeme_control(
#     output_directory = output_directory,
#     generate_html = FALSE,
#     generate_yaml = FALSE,
#     save_iterations = FALSE
#   )
# )

## ----result-methods-----------------------------------------------------------
# summary(fit)
# coef(fit)
# vcov(fit)
# logLik(fit)
# nobs(fit)

## ----output-directory---------------------------------------------------------
# output_directory <- "/absolute/path/to/my-biogeme-results"
# fit_with_reports <- estimate(
#   model,
#   model_name = "my_model_with_reports",
#   control = biogeme_control(
#     output_directory = output_directory,
#     generate_html = TRUE,
#     generate_yaml = TRUE,
#     save_iterations = TRUE
#   )
# )

## ----generic-model------------------------------------------------------------
# probability <- logit_probability(
#   utilities = list(`1` = utility_1, `2` = utility_2),
#   availability = list(`1` = 1, `2` = available_2),
#   alternative = variable("choice")
# )
# 
# generic_model <- biogeme_model(
#   database = database,
#   formula = logzero(probability),
#   probability = probability,
#   simulations = list(
#     probability = probability,
#     time_cost_ratio = time / cost
#   )
# )
# 
# generic_fit <- estimate(
#   generic_model,
#   model_name = "rbiogeme_generic",
#   control = biogeme_control(
#     output_directory = output_directory,
#     generate_html = FALSE,
#     generate_yaml = FALSE,
#     save_iterations = FALSE
#   )
# )
# 
# simulated <- simulate(
#   generic_model,
#   beta = generic_fit,
#   control = biogeme_control(output_directory = output_directory)
# )
# as.data.frame(simulated)

## ----database-operations------------------------------------------------------
# database_with_ratio <- biogeme_database_define_variable(
#   database,
#   name = "time_cost_ratio",
#   expression = variable("time") / variable("cost")
# )
# 
# database_without_high_cost <- biogeme_database_remove(
#   database_with_ratio,
#   condition = variable("cost") > 8
# )
# 
# biogeme_database_columns(database_without_high_cost)
# biogeme_database_nrow(database_without_high_cost)
# biogeme_database_filtered_row_count(database_without_high_cost)
# biogeme_database_row_ids(database_without_high_cost)
# 
# # Native derived columns and filters are materialized explicitly when their
# # resulting data frame or row count is needed in R.
# materialized <- biogeme_database_materialize(database_without_high_cost)
# as.data.frame(materialized)

## ----panel-database-----------------------------------------------------------
# panel_data <- data.frame(
#   person = c(1, 1, 2, 2, 3, 3),
#   choice = c(1, 2, 2, 1, 1, 2),
#   time = c(10, 8, 9, 11, 12, 7)
# )
# 
# panel_database <- biogeme_panel_database(
#   name = "demo_panel",
#   data = panel_data,
#   panel_id = "person"
# )
# 
# biogeme_database_is_panel(panel_database)

## ----reproducibility----------------------------------------------------------
# clean_control <- biogeme_control(
#   output_directory = tempfile("rbiogeme-output-"),
#   seed = 1234,
#   generate_html = FALSE,
#   generate_yaml = FALSE,
#   save_iterations = FALSE
# )

## ----help---------------------------------------------------------------------
# ?rbiogeme
# ?biogeme_check
# ?biogeme_model
# ?estimate
# ?simulate