unify and cleanup docs, add package-level docs

bips-hb · May 27, 2024 · 8b31843 · 8b31843
1 parent 4d9c6b0
commit 8b31843
Show file tree

Hide file tree

Showing 21 changed files with 194 additions and 22 deletions.
diff --git a/R/adversarial_rf.R b/R/adversarial_rf.R
@@ -63,12 +63,28 @@
 #' 
 #' 
 #' @examples
+#' # Train ARF and estimate leaf parameters
 #' arf <- adversarial_rf(iris)
+#' psi <- forde(arf, iris)
 #' 
+#' # Generate 100 synthetic samples from the iris dataset
+#' x_synth <- forge(psi, n_synth = 100)
+#'
+#' # Condition on Species = "setosa" and Sepal.Length > 6
+#' evi <- data.frame(Species = "setosa",
+#'                   Sepal.Length = "(6, Inf)")
+#' x_synth <- forge(psi, n_synth = 100, evidence = evi)
 #' 
-#' @seealso
-#' \code{\link{forde}}, \code{\link{forge}}
+#' # Estimate average log-likelihood
+#' ll <- lik(psi, iris, arf = arf, log = TRUE)
+#' mean(ll)
 #' 
+#' # Expectation of Sepal.Length for class setosa
+#' evi <- data.frame(Species = "setosa")
+#' expct(psi, query = "Sepal.Length", evidence = evi)
+#' 
+#' @seealso
+#' \code{\link{arf}}, \code{\link{forde}}, \code{\link{forge}}, \code{\link{expct}}, \code{\link{lik}}
 #' 
 #' @export
 #' @import ranger 

diff --git a/R/arf-package.R b/R/arf-package.R
@@ -0,0 +1,34 @@
+#' @seealso
+#' \code{\link{adversarial_rf}}, \code{\link{forde}}, \code{\link{forge}}, \code{\link{expct}}, \code{\link{lik}}
+#' 
+#' Useful links:
+#' \itemize{
+#'   \item \url{https://github.com/bips-hb/arf}
+#'   \item \url{https://bips-hb.github.io/arf/}
+#'   \item Report bugs at \url{https://github.com/bips-hb/arf/issues}
+#' }
+#' @examples
+#' # Train ARF and estimate leaf parameters
+#' arf <- adversarial_rf(iris)
+#' psi <- forde(arf, iris)
+#' 
+#' # Generate 100 synthetic samples from the iris dataset
+#' x_synth <- forge(psi, n_synth = 100)
+#'
+#' # Condition on Species = "setosa" and Sepal.Length > 6
+#' evi <- data.frame(Species = "setosa",
+#'                   Sepal.Length = "(6, Inf)")
+#' x_synth <- forge(psi, n_synth = 100, evidence = evi)
+#' 
+#' # Estimate average log-likelihood
+#' ll <- lik(psi, iris, arf = arf, log = TRUE)
+#' mean(ll)
+#' 
+#' # Expectation of Sepal.Length for class setosa
+#' evi <- data.frame(Species = "setosa")
+#' expct(psi, query = "Sepal.Length", evidence = evi)
+"_PACKAGE"
+
+## usethis namespace: start
+## usethis namespace: end
+NULL
diff --git a/R/expct.R b/R/expct.R
@@ -45,7 +45,7 @@
 #' 
 #' 
 #' @examples
-#' # Train ARF and corresponding circuit
+#' # Train ARF and estimate leaf parameters
 #' arf <- adversarial_rf(iris)
 #' psi <- forde(arf, iris)
 #' 
@@ -67,7 +67,7 @@
 #' x_synth <- expct(psi, evidence = evi)
 #' 
 #' @seealso
-#' \code{\link{adversarial_rf}}, \code{\link{forde}}, \code{\link{lik}}
+#' \code{\link{arf}}, \code{\link{adversarial_rf}}, \code{\link{forde}}, \code{\link{forge}}, \code{\link{lik}}
 #' 
 #'
 #' @export

diff --git a/R/forde.R b/R/forde.R
@@ -69,13 +69,28 @@
 #' 
 #' 
 #' @examples
+#' # Train ARF and estimate leaf parameters
 #' arf <- adversarial_rf(iris)
 #' psi <- forde(arf, iris)
-#' head(psi)
 #' 
+#' # Generate 100 synthetic samples from the iris dataset
+#' x_synth <- forge(psi, n_synth = 100)
+#'
+#' # Condition on Species = "setosa" and Sepal.Length > 6
+#' evi <- data.frame(Species = "setosa",
+#'                   Sepal.Length = "(6, Inf)")
+#' x_synth <- forge(psi, n_synth = 100, evidence = evi)
+#' 
+#' # Estimate average log-likelihood
+#' ll <- lik(psi, iris, arf = arf, log = TRUE)
+#' mean(ll)
+#' 
+#' # Expectation of Sepal.Length for class setosa
+#' evi <- data.frame(Species = "setosa")
+#' expct(psi, query = "Sepal.Length", evidence = evi)
 #' 
 #' @seealso
-#' \code{\link{adversarial_rf}}, \code{\link{forge}}, \code{\link{lik}}
+#' \code{\link{arf}}, \code{\link{adversarial_rf}}, \code{\link{forge}}, \code{\link{expct}}, \code{\link{lik}}
 #' 
 #'
 #' @export

diff --git a/R/forge.R b/R/forge.R
@@ -47,8 +47,11 @@
 #'
 #'
 #' @examples
+#' # Train ARF and estimate leaf parameters
 #' arf <- adversarial_rf(iris)
 #' psi <- forde(arf, iris)
+#' 
+#' # Generate 100 synthetic samples from the iris dataset
 #' x_synth <- forge(psi, n_synth = 100)
 #'
 #' # Condition on Species = "setosa"
@@ -82,7 +85,7 @@
 #' x_synth <- forge(psi, n_synth = 100, evidence = evi)
 #'
 #' @seealso
-#' \code{\link{adversarial_rf}}, \code{\link{forde}}
+#' \code{\link{arf}}, \code{\link{adversarial_rf}}, \code{\link{forde}}, \code{\link{expct}}, \code{\link{lik}}
 #' 
 #' @export
 #' @import data.table

diff --git a/R/lik.R b/R/lik.R
@@ -52,9 +52,11 @@
 #' 
 #' 
 #' @examples
-#' # Estimate average log-likelihood
+#' # Train ARF and estimate leaf parameters
 #' arf <- adversarial_rf(iris)
 #' psi <- forde(arf, iris)
+#' 
+#' # Estimate average log-likelihood
 #' ll <- lik(psi, iris, arf = arf, log = TRUE)
 #' mean(ll)
 #' 
@@ -75,7 +77,7 @@
 #' lik(psi, query = iris[1, 1:3], evidence = evi)
 #' 
 #' @seealso
-#' \code{\link{adversarial_rf}}, \code{\link{forge}}
+#' \code{\link{arf}}, \code{\link{adversarial_rf}}, \code{\link{forde}}, \code{\link{forge}}, \code{\link{expct}}
 #' 
 #'
 #' @export

diff --git a/R/utils.R b/R/utils.R
@@ -5,7 +5,7 @@
 #' 
 #' @param cn Column names.
 #' @param old_name Name of column to be renamed.
-#' 
+#' @keywords internal
 
 col_rename <- function(cn, old_name) {
   k <- 1L
@@ -26,6 +26,7 @@ col_rename <- function(cn, old_name) {
 #' @param cn Old column names.
 #'
 #' @return New columns names.
+#' @keywords internal
 
 col_rename_all <- function(cn) {
 
@@ -56,6 +57,7 @@ col_rename_all <- function(cn) {
 #' @param ... Further arguments for sample().
 #'
 #' @return A vector of length size with elements drawn from x.
+#' @keywords internal
 
 resample <- function(x, ...) {
   x[sample.int(length(x), ...)]
@@ -66,6 +68,7 @@ resample <- function(x, ...) {
 #' @param x A numeric vector.
 #'
 #' @return Index of maximum value in x, with random tie-breaking.
+#' @keywords internal
 
 which.max.random <- function(x) {
   if (all(is.na(x))) {
@@ -79,7 +82,7 @@ which.max.random <- function(x) {
 #' This function prepares input data for ARFs.
 #' 
 #' @param x Input data.frame.
-#' 
+#' @keywords internal
 
 prep_x <- function(x) {
   # Reclass all non-numeric features as factors
@@ -129,7 +132,7 @@ prep_x <- function(x) {
 #' @param params Circuit parameters learned via \code{\link{forde}}.
 #' 
 #' @import data.table
-#'
+#' @keywords internal
 
 post_x <- function(x, params) {
 
@@ -204,7 +207,7 @@ post_x <- function(x, params) {
 #' @importFrom foreach foreach %dopar%
 #' @importFrom truncnorm dtruncnorm ptruncnorm 
 #' @importFrom stats dunif punif
-#' 
+#' @keywords internal
 
 cforde <- function(params, evidence, row_mode = c("separate", "or"), stepsize = 0, parallel = TRUE) {
 
@@ -494,7 +497,7 @@ cforde <- function(params, evidence, row_mode = c("separate", "or"), stepsize =
 #' 
 #' @import data.table
 #' @import stringr
-#' 
+#' @keywords internal
 
 prep_cond <- function(evidence, params, row_mode) {
 

diff --git a/man/adversarial_rf.Rd b/man/adversarial_rf.Rd
diff --git a/man/arf-package.Rd b/man/arf-package.Rd
diff --git a/man/cforde.Rd b/man/cforde.Rd
diff --git a/man/col_rename.Rd b/man/col_rename.Rd
diff --git a/man/col_rename_all.Rd b/man/col_rename_all.Rd
diff --git a/man/expct.Rd b/man/expct.Rd
diff --git a/man/forde.Rd b/man/forde.Rd
diff --git a/man/forge.Rd b/man/forge.Rd