% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bart.R
\name{BARTSerialization}
\alias{BARTSerialization}
\alias{saveBARTModelToJson}
\alias{saveBARTModelToJsonFile}
\alias{saveBARTModelToJsonString}
\alias{createBARTModelFromJson}
\alias{createBARTModelFromJsonFile}
\alias{createBARTModelFromJsonString}
\alias{createBARTModelFromCombinedJson}
\alias{createBARTModelFromCombinedJsonString}
\title{BART Serialization Routines}
\usage{
saveBARTModelToJson(object)

saveBARTModelToJsonFile(object, filename)

saveBARTModelToJsonString(object)

createBARTModelFromJson(json_object)

createBARTModelFromJsonFile(json_filename)

createBARTModelFromJsonString(json_string)

createBARTModelFromCombinedJson(json_object_list)

createBARTModelFromCombinedJsonString(json_string_list)
}
\arguments{
\item{object}{Object of type \code{bartmodel} containing draws of a BART 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 BART 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 BART model}

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

\code{createBARTModelFromJson}, \code{createBARTModelFromJsonFile}, \code{createBARTModelFromJsonString},
\code{createBARTModelFromCombinedJson}, and \code{createBARTModelFromCombinedJsonString} all return
objects of type \code{bartmodel}.
}
\description{
BART 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.
This group of serialization 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{saveBARTModelToJson} and \code{createBARTModelFromJson} save to and load from this format.
This representation, of course, also relies on external C++ pointers, so in order to
save and reload BART models across sessions, we provide two other interfaces.

\code{saveBARTModelToJsonString} converts a BART model to an in-memory string containing the model's
JSON representation and \code{createBARTModelFromJsonString} converts this representation back to a BART model object.

\code{saveBARTModelToJsonFile} and \code{createBARTModelFromJsonFile} save or reload a BART model
directly to / from a \code{.json} file.

Finally, for cases in which multiple BART models have been sampled (for instance, multiple processes
run via \code{doParallel}), we offer \code{createBARTModelFromCombinedJson} and \code{createBARTModelFromCombinedJsonString} for
loading a new combined BART model from a list of BART JSON objects / strings.
}
\examples{
# Generate data
n <- 100
p <- 5
X <- matrix(runif(n*p), ncol = p)
y <- X[,1] + rnorm(n, 0, 1)

# Sample BART model
bart_model <- bart(X_train = X, y_train = y, num_gfr = 0,
                   num_burnin = 0, num_mcmc = 10)

# Save to in-memory JSON
bart_json <- saveBARTModelToJson(bart_model)
# Save to JSON string
bart_json_string <- saveBARTModelToJsonString(bart_model)
# Save to JSON file
tmpjson <- tempfile(fileext = ".json")
saveBARTModelToJsonFile(bart_model, file.path(tmpjson))

# Reload BART model from in-memory JSON object
bart_model_roundtrip <- createBARTModelFromJson(bart_json)
# Reload BART model from JSON string
bart_model_roundtrip <- createBARTModelFromJsonString(bart_json_string)
# Reload BART model from JSON file
bart_model_roundtrip <- createBARTModelFromJsonFile(file.path(tmpjson))
unlink(tmpjson)
# Reload BART model from list of JSON objects
bart_model_roundtrip <- createBARTModelFromCombinedJson(list(bart_json))
# Reload BART model from list of JSON strings
bart_model_roundtrip <- createBARTModelFromCombinedJsonString(list(bart_json_string))

}
