doRunrun: This runs the Evidence Accumulation Bayes net engine to scor...

In ralmond/EABN: Evidence Accumulation Bayes Net Engine

This runs the Evidence Accumulation Bayes net engine to scor or rescore an assessment.

Description

This is a system to run the Bayes net scoring engine, taking most of the details from a configuration file. It creates the BNEngine instance then and then runs it in either scoring or rescoring mode. Configuration information in taken from the EA.config and EAeng.local parameters.

Usage

doRunrun(appid, sess, EA.config, EAeng.local, config.dir,
outdir=config.dir, override = FALSE, logfile="", noprep=FALSE)

Arguments

appid	A character string giving the global unique identifier for the application being run. This is normally formatted like a URL, and basename(app) is used as a short name.
sess	A NeticaSession object to use for the Netica link.
EA.config	A named list containing the configuration details. See the ‘Configuration’ section below.
EAeng.local	A named list containing additional parameters for the engine constructor. The intention that these are local configuraiton paramete (e.g., database names and passwords) as opposed to more global information. Note this must have an element named “dburi” which gives the URI for the database, or which should be blank if the no database engine is to be used.
config.dir	The pathname of the directory that contains the the nets subdirectories.
outdir	The pathname of the directory to which output files will be written.
override	A logical flag. If true, the code will ignore locks and restart the run anyway.
logfile	Name for the file in which to do logging.
noprep	Logical flag. If true, then the database and listener preparation steps will be skipped. This is for forcing a continuation without resetting the configuration.

Details

The goal is to start a run for scoring (evidence accumultion step) an assessment using the BNEngine class. This function takes care of many of the configuration details and preparatory steps and then calls mainLoop to do the major work. In particular, the steps done by this system are as follows:

1. Configure the listeners.

2. Configure the engine, including loading manifest and scoring list.

3. Clean old scores from the database (optional depending on configuration.)

4. Remove selected evidence sets from the collection. Import new evidence sets into the database and mark selected evidence as unprocessed.

5. Launch engine using mainLoop.

6. Build and register the statistics and history file.

Note that this will run in either rerun mode, where it will score an selection of existing records and stop, or in server mode where it will continue waiting for new messages until it gets a shut down signal.

Value

This returns the engine invisibly, in case the calling program wants to do something with it.

Configuration

There are a large number of parameters which can be configured. These are passed in through the EA.config argument, which is a list of parameters. The intention is that this can be read in from a JSON file (using fromJSON). The RunEABN.R script loads these from a file called config.json. A sample of this file is available on github https://github.com/ralmond/PP-EA.

The following fields are available:

ConfigName

An identifier for the configuration. Default value "PP-main". Documentation only, not used by doRunrun.

Branch

The branch name for the git branch for this configuraiton. Default value "PP-main". Documentation only, not used by doRunrun.

Version

A version number for the configuration. Documentation only, not used by doRunrun.

Date

A edit date for the configuration. Documentation only, not used by doRunrun.

appStem

A list of app stems that will be affected. Sample value ["P4Test"].

rebuildNets

A logical flag, should the nets be rebuilt. Example value true.

logLevel

This controls the flog.threshold. Default value "INFO". Note that doRunrun does not set the log value, that should be done in the calling script.

logname

This is the name of the file to which logs should be sent. Example value "EA_<app>0.log". Note that doRunrun does not set the log file, that should be done in the calling script.

Tables

This is a whole object describing the EA.tables field see doBuild.

sender

The sender field on output messages. Example value "EA_<app>".

lscolname

The name of the column to which the listener set should log messages. Example value "Messages".

listeners

This is a list of listener descriptions. See the section ‘Listner Configuration’ below.

SRreset

Logical value, should the student records be reset before running. Example value true.

listenerReset

Which listeners should be reset before running. This should be a character scalar or vector. The values should be names of listeners. The special value “Self” refers to the ListenerSet object, and the special value “ALL” resets all listeners. See resetListeners. Example value "ALL".

netdir

The name of the subdirectory of config.dir which contains the nets. Default value "nets".

EAEngine

A complex object describing engine parameters. See the section ‘Engine Configuration’ below.

filter

A complex object describing how to prefilter the database. See the section ‘Database Filters’ below.

extensions

This should be a list of paths (relative to config.dir) containing additional R code to load. This is not used by doRunrun, but is supplied for use in scripts that might use doRunrun.

limitNN

An integer: how many events should be processed. Two special string values are also accepted. “ALL” will process all records currently in the database and stop. “Inf” will cause the process to run in server mode until it is shut down.

listenerExports

Information about data tables which should be exported at the end of the run. See generateListenerExports.

A number of these values do “<app>” substitution, that is they will substitute the string “<app>” for the short name of the application.

Listener Configruation

The listeners consist of a ListenerSet and a collection of Listener objects. The listener objects are made by using the information from the “listeners” element of the EA.config argument. This should be a list of specifications (each specification itself is a list). These are passed to buildListener, which provides some examples. The “listenerExports” part of the configuration is used to call generateListenerExports when the engine stops.

The listener set is controlled by the EAeng.local$dburi value and the “lscolname” field. If dbuir is a name of a database, then the ListenerSet is logged into the “lscolname” collection. If dburi is null or an empty string, then the listener set will not do logging.

Engine Configruation

The type of engine used is controlled by the EAeng.local$dburi value. If this is a URI, then the BNEngineMongo class is used. If it is null or the empty string, then the BNEngineNDB class is used instead.

The arguments to the appropriate constructor are found between the EAeng.local and EA.config$EAEngine collections. The intent is for the former to include details (e.g., database user names and passwords) which are local to the server on which EABN is running, and for EA.config$EAEngine to include more public details which are local to a particular run.

See BNEngineMongo or BNEngineNDB for the expected fields. Note that the “processN” field is taken care of separately after the database operations (next section).

Database Filtering

The EA.config$filter field controls the database filtering process. There are four steps:

Remove

old records from the database.

Import

new records into the database.

Purge

unused records from the database.

Reprocess

Reset the processed flag to ensure records get reprocessed.

These are controlled by the following elements in the EA.config$filter list:

doRemove

Logical, should records be removed before import.

remove

Filter to use for removal. The value {} will remove all records for the given app.

importFile

A list of filenames (in the config.dir) which contain evidence sets to be imported before scoring.

doPurge

Logical, should records be removed after import.

purge

Filter for the purging (after import removal). Leaving this empty will probably not be satisfactory.

doReprocess

Logical, should existing records have the processed flag cleared? Typically TRUE for rerun mode and FALSE for server mode.

reprocess

Filter for the selected records to be marked for reprocessing. The value {} will mark all records (for this app) for reprocessing.

Locking

It is probably a bad idea to rebuild the nets which a different incarnation is using the net directory to score. It is almost certainly a bad idea for two different programs to rebuild the nets in the same directory at the same time.

To prevent such clashes, the doRunrun function adds a file with the extension .lock to the directory when it is scoring. The doBuild function adds the file netbuilder.lock while it is rebuilding the nets.

If when doBuild starts, if a .lock file is found in the “nets” directory, it issues an warning, and unless the override parameter is set to TRUE it stops. Use the override only with extreme caution.

The BNEngineMongo version also checks the database for a running flag. If it is found, then again the engine will not start unless the override flag is true.

Data Files

If the value of EA.config$statListener is not null, then the final statistic values for all users are put into a table which is exported (to the file EA.config$statfile).

If the value of EA.config$histListener is not null, then the history of all statistic values for all users are put into a table which is exported (to the file EA.config$histfile).

Both the statfile and histfile are registered using the ListenerSet$registerOutput method.

Logging

Logging is done through the futile.logger{flog.logger} mechanism. This allows logs to be save to a file.

The “logLevel” and “logname” fields are put in the configuration specification to assist scripts in configuring the logging system.

Both the log file is registered using the ListenerSet$registerOutput method.

Note

This function is meant to be called by the RunEABN.R script found in the config directory. (file.path(help(package="EABN")$path,"conf","RunEABN.R"))

The shell script EABN found in the same directory will run this script.

Author(s)

Russell Almond

References

The Bobs (1983) Psychokiller. My I'm Large. Rhino Records. https://www.youtube.com/watch?v=-Gu4PKnCLDg. (Reference is about 2:30 minutes into song.)

See Also

BNEngine, mainLoop, doBuild

resetProcessedMessages, cleanMessageQueue, importMessages

ListenerSet, buildListenerSet, generateListenerExports, resetListeners

Examples

## This example is in:
file.path(help(package="EABN")$path,"conf","RunEABN.R")
## Not run: 
library(R.utils)
library(EABN)
library(PNetica)

appStem <- cmdArg("app",NULL)
if (FALSE) {
  appStem <- "userControl"
}

source("/usr/local/share/Proc4/EAini.R")

EA.config <- jsonlite::fromJSON(file.path(config.dir,"config.json"),FALSE)

app <- as.character(Proc4.config$apps[appStem])
if (length(app)==0L || any(app=="NULL")) {
  stop("Could not find app for ",appStem)
}

## Start Netica
sess <- NeticaSession(LicenseKey=NeticaLicenseKey)
startSession(sess)

logfile <- (file.path(logpath, sub("<app>",appStem,EA.config$logname)))
if (interactive()) {
  futile.logger::flog.appender(appender.tee(logfile))
} else {
  futile.logger::flog.appender(appender.file(logfile))
}
futile.logger::flog.threshold(EA.config$logLevel)

eng <- doRunrun(app,sess,EA.config,EAeng.local,config.dir,outdir,
                logfile=logfile)


## End(Not run)

ralmond/EABN documentation built on Aug. 30, 2023, 12:52 p.m.