From 0332b11bef06235058c3aced33baeb15350f1be3 Mon Sep 17 00:00:00 2001
From: Ed Ionides <ionides@umich.edu>
Date: Wed, 7 Aug 2024 13:10:28 -0400
Subject: [PATCH] add ibpf documentation example

---
 R/ibpf.R    | 26 ++++++++++++++++++++++++++
 man/ibpf.Rd | 27 +++++++++++++++++++++++++++
 2 files changed, 53 insertions(+)

diff --git a/R/ibpf.R b/R/ibpf.R
index 940c73c..75eded9 100644
--- a/R/ibpf.R
+++ b/R/ibpf.R
@@ -27,6 +27,32 @@
 ##' each unit.
 ##' @param spat_regression fraction of each extended parameter regressed toward the unit mean. Not required when all parameters are unit-specific.
 ##'
+##' @examples
+##' # Complete examples are provided in the package tests
+##' \dontrun{
+##' # Create a simulation of a Brownian motion, for an extended model with
+##' # unit-specific parameters for all estimated, even if the parameter
+##' # takes the same shared value for each unit.
+##' U <- 4
+##' b2 <- bm2(U=U,N=5,unit_specific_names="rho")
+##'
+##' # Run ibpf with two blocks of two units each. estimating rho as a
+##' # shared parameter with all other parameters being fixed.
+##' b2_ibpf <- ibpf(b2,
+##'   sharedParNames="rho",
+##'   unitParNames=NULL,
+##'   Nbpf=5,
+##'   spat_regression=0.1,
+##'   Np=50,
+##'   rw.sd=do.call(rw_sd,setNames(rep(list(0.01),times=U),paste0("rho",1:U))),
+##'   cooling.fraction.50=0.5,
+##'   block_size=2
+##' )
+##'
+##' # Get a likelihood estimate
+##' logLik(b2_ibpf)
+##' }
+##'
 ##' @return
 ##' Upon successful completion, \code{ibpf} returns an object of class
 ##' \sQuote{ibpfd_spatPomp}.
diff --git a/man/ibpf.Rd b/man/ibpf.Rd
index 77fd868..275c37e 100644
--- a/man/ibpf.Rd
+++ b/man/ibpf.Rd
@@ -132,6 +132,33 @@ The following methods are available for such an object:
 }
 }
 
+\examples{
+# Complete examples are provided in the package tests
+\dontrun{
+# Create a simulation of a Brownian motion, for an extended model with
+# unit-specific parameters for all estimated, even if the parameter
+# takes the same shared value for each unit.
+U <- 4
+b2 <- bm2(U=U,N=5,unit_specific_names="rho")
+
+# Run ibpf with two blocks of two units each. estimating rho as a
+# shared parameter with all other parameters being fixed.
+b2_ibpf <- ibpf(b2,
+  sharedParNames="rho",
+  unitParNames=NULL,
+  Nbpf=5,
+  spat_regression=0.1,
+  Np=50,
+  rw.sd=do.call(rw_sd,setNames(rep(list(0.01),times=U),paste0("rho",1:U))),
+  cooling.fraction.50=0.5,
+  block_size=2
+)
+
+# Get a likelihood estimate
+logLik(b2_ibpf)
+}
+
+}
 \references{
 \ionides2022
 }