PnetSerialize: Writes/restores network from a string.

In ralmond/Peanut: Parameterized Bayesian Networks, Abstract Classes

Writes/restores network from a string.

Description

The PnetSerialize method writes the network to a string and returns a list containting both the serialized data and type information. The PnetUnserialize method restores the data. Note that the serialized form must contain either the name of the type or the name of the factory used to restore the object (see details).

Usage

PnetSerialize(net)
PnetUnserialize(serial)
unserializePnet(factory,data)
WarehouseUnpack(warehouse, serial)

Arguments

net	A Pnet to be serialized.
factory	A character scalar containing the name of a global variable which contains a factory object capable of recreating the network from the data.
warehouse	A object of the type PnetWarehouse which will contain a link to the appropriate factory.
serial	A list containing at least three elements. One is the name of the network. One is the data element which contains the serialized data as a raw vector. The third is either a factory element containing the name of a global symbol containing a factory for reading the object or a type argument giving the name of the constructor.
data	A list containing at least two elements. One is the name of the network. One is the data element which contains the serialized data as a raw vector.

Details

The intention of this function is to serialize the network in such a way that it can be saved to a database and restored. The result of a call to PnetSerialize is a list with three elements. One element is called data and contains the actual serialize data. The second element is called name and it should be an identifier for the network (the result of PnetName). The last element is either factory or type. In either case, they should be a string. The list may contain other elements, but these may be ignored by other programs.

The intent is to provide a representation that can be saved to a database. The data element should be a raw vector (e.g., the output of serialize(...,NULL)) and will be stored as a blob (binary large object) and the other elements should be strings. Document based databases (e.g., mongo) may handle the additional fields but relational database will have difficulty with them, so implementers should only rely on the three fields.

The function PnetUnserialize reverses this operation. If factory is supplied, then the factory protocol is used for restoration. If type is supplied instead, then the type string protocol is used. If both are supplied, then the factory protocol is preferred, and if neither is supplied, an error is signaled. The function unserializePnet is a generic function used by the factory protocol. If a Pnet already exists with the given name, then it is replaced, otherwise a new one is created.

Value

The PnetSerialize function returns a list with the following elements:

name	The name of the network. If this matches an existing network, then it will be replaced on unserialize, otherwise a new network will be created.
data	Serialized data for the network. This should be a raw vector.
factory	The name of a global object which can restore networks from serialized data.
type	The name of a class for which an PnetUnserialize.type method exits.
...	There may be other data, but note that programs saving/restoring the serialized representation may not know how to handle these extra fields.

The PnetUnserialize and unserializePnet functions return an object of type Pnet.

Factory Protocol

A factory is an object of a class for which a method for the unserializePnet generic function is defined. This method should return an object of type Pnet. Thus the Peanut package doesn't need to know the implementaiton details.

Typically factories are global (static in java lanugage) objects. In this case the factory object should be the name of the factory (as it will need to be serialized). The get function is used to retrieve its value, so typically it is stored in .GlobalEnv.

The factory protocol allows other kind of flexibility as well, including being able to encapsulate a reference to loaded objects, so this is the preferred method.

Type String Protocol

This mechanism mimics the S3 method dispatch method, although it doesn't really use it. If the argument to PnetUnserialize has a type field (but no factory field) then it will call a funciton called PnetUnserialize.type.

Note

The first use of this function was designed to save/restore a network from a mongo database. This format easily supports extra fields in the return list. The samething is true if the network is serialized using either JSON/BSON or the normal R dump mechanism.

On the other hand, if the network is to be stored in a SQL database, the using program will not have places to store the extra fields.

Author(s)

Russell Almond

See Also

Pnet, Warehouse

Examples

## Not run: 
library(mongolite)
library(jsonlite)
library(PNetica)
sess <- NeticaSession()
startSession(sess)

collect <- mongo("studentModels","test",
                     "mongodb://127.0.0.1:27017/test")
## Or "mongodb://user:pwd@127.0.0.1:27017/test"

## An example network manifest.
netman1 <- read.csv(system.file("auxdata", "Mini-PP-Nets.csv",
                                package="Peanut"),
                    row.names=1, stringsAsFactors=FALSE)
netpath <- system.file("testnets", package="PNetica")
netman1$Pathname <- file.path(netpath,netman1$Pathname)

Nethouse <- BNWarehouse(manifest=netman1,session=sess,key="Name")

pm.net <- WarehouseSupply(Nethouse, "miniPP_CM")
sm.net <- CopyNetworks(pm.net,"Student1")

sm.ser <- PnetSerialize(sm.net)
## base 64 encode the data to make it easier to store.
sm.ser$data <- base64_enc(sm.ser$data)

collect$replace(paste('{"name":"',sm.ser$name,'"}'),
                toJSON(lapply(sm.ser,unbox)),
                upsert=TRUE)

## Use iterator method to find, so we get in list rather than data frame
## representation. 

it <- collect$iterate(sprintf('{"name":"%s"}',"Student1"),limit=1)
sm1.ser <- it$one()
## Decode back to the raw vector.
sm1.ser$data <- base64_dec(sm1.ser$data)

DeleteNetwork(sm.net)
sm1 <- WarehouseUnpack(Nethouse,sm1.ser)
stopifnot(PnetName(sm1)=="Student1")

DeleteNetwork(sm1)
sm1a <- unserializePnet(sess,sm1.ser)
stopifnot(PnetName(sm1a)=="Student1")

DeleteNetwork(sm1a)
#Unserialize needs a reference to the "factory" (in this case session.).
sm1.ser$factory <- "sess"
sm1b <- PnetUnserialize(sm1.ser)
stopifnot(PnetName(sm1b)=="Student1")

stopSession(sess)

## End(Not run)

ralmond/Peanut documentation built on Sept. 19, 2023, 8:27 a.m.