Proc4-package {Proc4} | R Documentation |
Extracts observables from a sequence of events.
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:
The P4Message
object and the protocol for
converting messages to JSON and saving them in the mongo database.
A withFlogging
function which wraps the
flog.logger
protocol.
A number of Listener
objects which implement an
observer protocol for messages.
The config
directory contains a number of javascript
files for building database schemas and indexes.
The dongle
directory contains a number of PHP scripts for
exposing the database via a web server.
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
parse
XXX 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 parse
XXX 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 parse
XXX
function as an argument to construct objects from the database.
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.
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.
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.
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.
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).
Russell Almond
Maintainer: Russell Almond <ralmond@fsu.edu>
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.