Draco Plugin System Technical Details

Description

The Draco Plugin System allows for the authoring of regressions or analyses using JRuby code. Draco implements the plugins using the Apache Bean Scripting Framework to ensure compatibility with Java runtimes. Approximatrix has extended the Ruby Matrix and Vector classes to ensure maximum accuracy and improve functionality. The Draco data model can easily be accessed by plugins for read operations only.

JRuby Details

Draco uses the full JRuby runtime for all calculations. By default, Draco enables JRuby's Just-In-Time (JIT) compiling for all Ruby code to ensure maximum performance. JIT compiling should produce code that runs at nearly the same speed as equivalent compiled Java code.

Plugin System Architecture

Currently Draco is configured to search a single directory for all available plugins. For example, the default in GNU/Linux environments is /usr/share/draco/scripts/ruby/plugins. At program startup, Draco scans the directory for any files ending in the "rb" extension and attempts to execute them in JRuby. The resulting filename, class name, and plain text name of each plugin are registered by Draco and made available to the user.

When the plugin is selected from the menu system, the Ruby code is again executed, and an object of the appropriate class is instantiated and stored. When the analysis or regression is executed, the appropriate run() method is called on the Ruby object resulting from the instantiation. When the run() method completes, the results() method is called immediately.

If the plugin is selected again from the menus, an entirely new plugin object is instantiated from the appropriate Ruby code.

At this time, Draco will only save plugin results Information about the plugin is not currently stored, but may be in the future.

Extensions to JRuby

The Draco plugin system utilizes the JLMatrix (Java LAPACK Matrix) library to improve upon and extend Ruby's built-in Matrix and Vector classes. JLMatrix replaces essential matrix and vector operations with the required LAPACK code. Additional matrix and vector operations have been added as well.

Matrix

The Matrix class extended by JLMatrix has the following notable changes:

Method	JLMatrix Implementation
* (multiplication)	If the argument is a Matrix or a Vector, utilizes LAPACK DGEMM or DGEMV respectively.
** (power)	Raises all elements of the matrix to the specified power individually
diagonal	Returns a Vector of all the matrix's diagonal elements
inverse	Uses LAPACK DGETRF and DGETRI functions to perform matrix inversion
reciprocal_condition (or rcond)	Computes the reciprocal condition of a matrix using LAPACK DLANGE->DGETRF->DGECON calls
to_java	Returns a two-dimensional Java array of doubles with elements equal to those in the matrix
Matrix.from_java(x)	Creates a Matrix from a two-dimensional Java array
Matrix.zeroes(m,n)	Creates a Matrix of dimension m-by-n filled with zeroes

Vector

The Vector class as extended by JLMatrix has the following notable additions:

Method	JLMatrix Implementation
** (power)	Raises all elements of the matrix to the specified power individually
count (or length)	Alias for the size method
dot(x)	Computes the dot product with another vector using the LAPACK DDOT function
each	Yields each element of a vector to a block
mean	Calculates the mean of the vector
sort	Sorts the elements of a vector in ascending order and returns a new, resulting vector
standard_deviation	Computes the standard deviation of a vector using a series of LAPACK calls
sum	Computes the sum of all elements
sum_squared	Calculates the sum of the squares of all elements
to_java	Returns a one-dimensional Java array of doubles containing values equivalent to those in the vector.
Vector.from_java(x)	Creates a vector from a one-dimensional Java array
Vector.ones(n)	Creates a vector of length n filled with ones
Vector.zeroes(n)	Creates a vector of length n filled with zeroes

Further Extensions

JLMatrix also extends the following methods:

Method	JLMatrix Implementation
(Fixnum).* (multiplication) (Bignum).* (multiplication) (Float).* (multiplication)	If the argument is a Matrix or Vector, all elements are multiplied by the value, and an object of the same type and size as the argument is returned
Math::sqrt(x)	If the argument is a Matrix or Vector, an object of the same type and size is returned containing the square root of all elements.

Access to the Data Model

When the Ruby object based on the plugin class is instantiated, the data model is passed in via the constructor. The data model is available to all plugins as the @model attribute. The data model can be converted into a matrix via the to_matrix method; this method call accepts variable names and returns all rows where observations exist for all selected variables.