Proc4-package {Proc4}R Documentation

Four Process Assessment Database and Dispatcher

Description

Extracts observables from a sequence of events.

Details

The DESCRIPTION file: This package was not yet installed at build time.
Index: This package was not yet installed at build time.

This package exists to supply core functionality to other processes implementing processes in the four process architecture (Almond, Steinberg and Mislevy, 2002). In particular, it contains low level code dealing with implementing message queues in a document database (mongo) and reading/writing messages from JSON.

There are five major features of this package documented below:

  1. The P4Message object and the protocol for converting messages to JSON and saving them in the mongo database.

  2. A withFlogging function which wraps the flog.logger protocol.

  3. A number of Listener objects which implement an observer protocol for messages.

  4. The config directory contains a number of javascript files for building database schemas and indexes.

  5. The dongle directory contains a number of PHP scripts for exposing the database via a web server.

P4 Messages

The extended four process architecture defines a message object (P4Message) with the following fields:

_id:

Used for internal database ID.

app:

Object of class "character" which specifies the application in which the messages exit.

uid:

Object of class "character" which identifies the user (student).

context:

Object of class "character" which identifies the context, task, or item.

sender:

Object of class "character" which identifies the sender. This is usually one of "Presentation Process", "Evidence Identification Process", "Evidence Accumulation Process", or "Activity Selection Process".

mess:

Object of class "character" a general title for the message context.

timestamp:

Object of class "POSIXt" which gives the time at which the message was generated.

data:

Object of class "list" which contains the data to be transmitted with the message.

processed:

A logical value: true if the message has been processed, and false if the message is still in queue to be processed. This field is set with markAsProcessed.

pError:

If a error occurs while processing this event, information about the error can be stored here, either as an R object, or as an R object of class error (or any class). This field is accessed with processingError and set with markAsError.

Other classes can extend this message protocol by adding additional fields, but the header fields of the message object allow it to be routed.

In particular, the processed field allows a database collection of messages to be used as queue. Simply search for unprocessed message and begin processing them oldest first, using markAsProcessed to mark the complete process and markAsError to mark errors.

The functions saveRec, getOneRec and getManyRecs facilitate saving and loading message objects from the database. These build on the mongolite (mongo) and jsonlite (toJSON) packages. The function buildJQuery gives R-like syntactic sugar to building mongo (JSON) queries.

The jsonlite package provides minimal support for storing S4 objects in the mongo database. In particular, toJSON provides too little support and serializeJSON wraps the object in R-specific metadata which makes the data difficult for other applications to extract. Instead, Proc4 introduces a new protocol which is suitable for saving S4 classes: a generic as.json function for converting the class to JSON, and a parseXXX function for reversing the process.

The as.json function calls attributes to convert the S4 object into a list, and then calls the function as.jlist to massage the elements of the list for export into JSON. The function unboxer is useful for preventing elements which should be scalars from being converted into lists. The as.json function then runs the result through toJSON to get the result.

The parseXXX messages reverse this process. In particular, the record is retrieved from the database and converted into a list using fromJSON. The parsing function is then called on the result to build the object. The function parseMessage provides an example. The function cleanMessageJlist does much of the interior work of the parsing and is intended for subclasses of P4Message. The getOneRec and getManyRecs functions take a parseXXX function as an argument to construct objects from the database.

Logging

The logging system for the Proc4 processes is mostly just the flog.logger protocol. Aside from importing the futile.logger package, Proc4 makes one addition. The function withFlogging executes a series of statements in an environment in which the error messages will be logged, and at higher logging levels, stack traces for errors and warnings are given. The intention is that most message handling functions will be wrapped in withFlogging, so that information about the message causing the error/warning will be available for debugging.

Listeners

The Proc4 package implements an observer protocol called Listener. A listener is an abstract class which implements the receiveMessage function. The argument of this function is a P4Message object, which the listener then does something with. (In most of the implemented examples, this is to save it in a database.) Note that listeners should also define a isListener method to indicate that it is a listener.

Four listeners are currently implemented (see ListenerConstructors or the individal listener classes):

CaptureListener

Creates an object of class CaptureListener which stores the messages in a list.

InjectionListener

Creates an object of class InjectionListener which inserts the message into the designated database.

UpdateListener

Creates an object of class UpdateListener which updates the designated field.

UpsertListener

Creates an object of class UpsertListener which insert or replaces the message in the designated collection.

TableListener

Creates an object of class TableListener which adds details from message to rows of a data frame.

The ListenerSet class is a mixin to associate a collection of listeners with an object (the EIEngine and EAEngine classes use this). The generic function notifyListeners can be called. This logs information about the message (see logging system above), save a copy of the message in a “Messages” database, and calls the receiveMessage method on all of the listener objects in its collection.

Configuration Files

Using the mongo database, both security (user IDs and passwords) is optional. Running mongo without security turned on is probably okay as long as the installation is (a) behing a firewall, and (b) the firewall is configured to not allow connections on the mongo port except from localhost. However, other users may want to turn on security.

The recommended security setup is to create four users, “EIP”, “EAP”, “ASP”, and “C4” for the four processes and to assign a password to each. The URI's of the database connections then need to be modified to include the username and passwords. Each process would have an ini.R file which contains its password which is stored in an appropriate configuration directory. (On *nix systems, the recommend location is /usr/local/share/Proc4.)

The files Proc4.ini (PHP format) and Proc4.js (javascript format) can be used for saving the key usernames and passwords. These files are located in the directory file.path( library(help="Proc4")$path, "config"). To install these files it is necessary to copy the files to the configuration directory and edit them so that the password reflects local preferences.

The file setupDatabases.js in the config directory creates databases for each of the processes and stores the appropriate login credentials. (Note that this calls Proc4.js to get these credentials so that file must be established first.) This is a javascript file designed to be run directly in mongo, i.e., mongo setupDatabases.js. Note that it must be run by a user which has the appropriate priveleges to create databases and modify their security (a “root” user).

The file setupProc4.js in the config directory sets up schemas and indexes for collections in the Proc4 database which are used by the dongle process. Schemas are optional in mongo, but the indexes should speed up operations.

Dongle Files

The directory file.path(library(help="Proc4")$path, "config") contains files that facilitate direct communciation with the mongo database. In particular, there are a number of PHP scripts which if put in a directory available to the web server will allow remote processes to get information about users in the system. The scripts are:

PlayerStart.php

Called when player logs in on a given day. As data returns information needed to restore gaming session (currently bank balance and list of trophies earned). Note that player details are updated by the EI process.

PlayerStop.php

Called when player logs out. Currently not used. It is designed to help automatically shut down unneeded processed.

PlayerStats.php

Called when current player competency estimates are required, e.g., when displaying player scores. It returns a list of statistics and their values in the data field; the exact statistics returned depend on the configuration of the EA process. This database collection is updated by the EA process after each game level is processed.

PlayerLevels.php

Called when the game wants the next level. The message data should contain information about what topic the player is currently addressing and a list of played and unplayed levels, with the unplayed levels sorted so the next level according to protocol is first on the list. The complete list of levels should be returned so that if levels on the list have already been completed, a new level would be entered. Although the PHP script has been built, the AS process to feed it has not.

In addition, there is a file called LLtoP4 in that directory which is a bash script for translating between xAPI and Proc4 message formats. The function LLtoP4Loop repeatedly downloads xAPI statements from the learning locker database, translates them to P4 format, and uploads them to the EI process database.

The vingette file Dongle.pdf describes the dongle and database structure in more detail.

Acknowledgements

Work on the Proc4, EIEvent and EABN packages has been supported by the National Science foundation grants DIP: Game-based Assessment and Support of STEM-related Competencies (#1628937, Val Shute, PI) and Mathematical Learning via Architectual Design and Modeling Using E-Rebuild. (#1720533, Fengfeng Ke, PI).

The Proc4 package developement was led by Russell Almond (Co-PI).

Author(s)

Russell Almond

Maintainer: Russell Almond <ralmond@fsu.edu>

References

Almond, R. G., Steinberg, L. S., and Mislevy, R.J. (2002). Enhancing the design and delivery of Assessment Systems: A Four-Process Architecture. Journal of Technology, Learning, and Assessment, 1, http://ejournals.bc.edu/ojs/index.php/jtla/article/view/1671.

See Also

flog.logger, EIEvent, EABN


[Package Proc4 version 0.4-6 Index]