% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bcf.R
\name{BCFSerialization}
\alias{BCFSerialization}
\alias{saveBCFModelToJson}
\alias{saveBCFModelToJsonFile}
\alias{saveBCFModelToJsonString}
\alias{createBCFModelFromJson}
\alias{createBCFModelFromJsonFile}
\alias{createBCFModelFromJsonString}
\alias{createBCFModelFromCombinedJson}
\alias{createBCFModelFromCombinedJsonString}
\title{BCF Serialization Routines}
\usage{
saveBCFModelToJson(object)

saveBCFModelToJsonFile(object, filename)

saveBCFModelToJsonString(object)

createBCFModelFromJson(json_object)

createBCFModelFromJsonFile(json_filename)

createBCFModelFromJsonString(json_string)

createBCFModelFromCombinedJson(json_object_list)

createBCFModelFromCombinedJsonString(json_string_list)
}
\arguments{
\item{object}{Object of type \code{bcfmodel} containing draws of a Bayesian causal forest model and associated sampling outputs.}

\item{filename}{String of filepath, must end in ".json"}

\item{json_object}{Object of type \code{CppJson} containing Json representation of a BCF model}

\item{json_filename}{String of filepath, must end in ".json"}

\item{json_string}{JSON string dump}

\item{json_object_list}{List of objects of type \code{CppJson} containing Json representation of a BCF model}

\item{json_string_list}{List of JSON strings which can be parsed to objects of type \code{CppJson} containing Json representation of a BCF model}
}
\value{
\code{saveBCFModelToJson} return an object of type \code{CppJson}.
\code{saveBCFModelToJsonFile} returns nothing, but writes to the provided filename.
\code{saveBCFModelToJsonString} returns a string dump of the BCF model's JSON representation.

\code{createBCFModelFromJson}, \code{createBCFModelFromJsonFile}, \code{createBCFModelFromJsonString},
\code{createBCFModelFromCombinedJson}, and \code{createBCFModelFromCombinedJsonString} all return
objects of type \code{bcfmodel}.
}
\description{
BCF models contains external pointers to C++ objects, which means they cannot
be correctly serialized to \code{.Rds} from an R session in their default state.
These functions allow us to convert between C++ data structures and a persistent JSON
representation. The \code{CppJson} class wraps a performant C++ JSON API, and the functions
\code{saveBCFModelToJson} and \code{createBCFModelFromJson} save to and load from this format.
This representation, of course, also relies on external C++ pointers, so in order to
save and reload BCF models across sessions, we provide two other interfaces.

\code{saveBCFModelToJsonFile} and \code{createBCFModelFromJsonFile} save or reload a BCF model's JSON
representation directly to / from a \code{.json} file.

\code{saveBCFModelToJsonString} and \code{createBCFModelFromJsonString} handle in-memory strings containing JSON data,
which can be written to disk or passed between processes.

Finally, for cases in which multiple BCF models have been sampled (for instance, sampled in multiple processes
via \code{doParallel}), we offer \code{createBCFModelFromCombinedJson} and \code{createBCFModelFromCombinedJsonString} for
loading a new combined BCF model from a list of BCF JSON objects or strings.
}
\examples{
# Generate data
n <- 100
p <- 5
X <- matrix(runif(n*p), ncol = p)
pi_X <- runif(n, 0.3, 0.7)
Z <- rbinom(n, p = pi_X, size = 1)
y <- X[,1] + Z + rnorm(n, 0, 1)

# Sample BCF model
bcf_model <- bcf(X_train = X, Z_train = Z, propensity_train = pi_X, y_train = y,
                 num_gfr = 0, num_burnin = 0, num_mcmc = 10)

# Save to in-memory JSON
bcf_json <- saveBCFModelToJson(bcf_model)
# Save to JSON string
bcf_json_string <- saveBCFModelToJsonString(bcf_model)
# Save to JSON file
tmpjson <- tempfile(fileext = ".json")
saveBCFModelToJsonFile(bcf_model, file.path(tmpjson))

# Reload BCF model from in-memory JSON object
bcf_model_roundtrip <- createBCFModelFromJson(bcf_json)
# Reload BCF model from JSON string
bcf_model_roundtrip <- createBCFModelFromJsonString(bcf_json_string)
# Reload BCF model from JSON file
bcf_model_roundtrip <- createBCFModelFromJsonFile(file.path(tmpjson))
unlink(tmpjson)
# Reload BCF model from list of JSON objects
bcf_model_roundtrip <- createBCFModelFromCombinedJson(list(bcf_json))
# Reload BCF model from list of JSON strings
bcf_model_roundtrip <- createBCFModelFromCombinedJsonString(list(bcf_json_string))

}
