BDVAL/Adding New Mode

From Icbwiki

Jump to: navigation, search

This section describes the process of extending the BDVal source code to include a new mode. A basic understanding of Java programming is assumed.

Contents

Prerequisites

This example assumes the source distribution has been downloaded and extracted to a local directory. In addition to the requirements described in the installation and configuration sections, a Java Development Kit (JDK) and apache Ant is required. Familiarity with the Java Simple Argument Parser (JSAP) is desirable.

Details

Let's assume we would like to add a new mode that uses a cox regression model (partial likelihood and p-value) for feature selection into BDVal. The following sections describe which classes need to be modified and/or extended to integrate this into BDVal. This mode will be referred to as "cox-regression".

Define Parameters for the Mode

The parameters for the cox regression mode will be similar to those in the existing T-Test mode. An additional parameter that specifies a "survival file" will be required.

Implement the Mode

Modes in BDVal all extend org.bdval.DAVMode.java. The implementation of the cox regression mode will extend this class.

Since the new mode is similar to an existing mode, it may be helpful to use the code from the existing class org.bdval.DiscoverWithTTest.java as a reference. Our new class will be called DiscoverWithCoxRegression and reside in the org.bdval package .

Set the mode options

The method defineOptions(JSAP jsap) of DAVMode is responsible for defining the options that a particular mode expects. The class DiscoverWithCoxRegression will override this method add any parameters using JSAP. For example, adding the option for a "survival file" would be done as follows:

 final Parameter survivalFilenameOption = new FlaggedOption("survival")
         .setStringParser(JSAP.STRING_PARSER).setDefault(JSAP.NO_DEFAULT)
               .setRequired(true).setLongFlag("survival")
               .setHelp("Survival filename. This file contains survival data "
                       + "in tab delimited table; column 1: chipID has to match cids and "
                       + "tmm, column 2: time to event, column 3 censor with 1 as event 0 "
                       + "as censor, column 4 and beyond are all numerical covariates that "
                       + "will be included in the regression model");
 jsap.registerParameter(survivalFilenameOption);

Interpret the mode options

Each mode will need to handle any options it requires. The method interpretArguments(JSAP jsap, JSAPResult result, DAVOptions options) of DAVMode is responsible for interpreting the options that a particular mode expects. DiscoverWithCoxRegression will override this method validate any options using JSAP and JSAPResult. Any BDVal general options may be stored or read from the options parameter. For example, the option for a "survival file" could be interpreted as follows:

 super.interpretArguments(jsap, result, options);
 final String survivalFileName = result.getString("survival");
 try {
    readSurvival(survivalFileName);
 } catch (IOException e) {
     LOG.fatal("Cannot read input file \"" + options.input + "\"", e);
 }

Note, the final processing will typically not be executed at this step. This is intended as a validation and preprocessing stage.

Process the mode options

Once all options have been interpreted and validated, the method process(DAVOptions options) of DAVMode will be invoked. DiscoverWithCoxRegression will override this method to filter features appropriately. The parsed options would have been stored during the previous interpret stage and/or stored by BDVal into the options parameter.

Register the Mode

The main class for BDVal is org.bdval.DiscoverAndValidate.java. This class is essentially responsible for taking command line arguments from the user and delegating these to the appropriate mode(s) for processing.

In order to expose the new mode for use, it must be "registered" so that it is recognized as a valid --mode option. A method for registering modes exists in org.bdval.DAVMode.java and is called registerMode. There are a series of registration calls in DiscoverAndValidate and adding the following to that list will register the new mode.

 davMode.registerMode("cox-regression", DiscoverWithCoxRegression.class);

Integrate the Mode into the rest of BDVal

Once the new mode has been compiled into BDVal, it will be available for use in other parts of BDVal. The file coxreg-svmglobal.sequence illustrates how the cox-regression mode can be used with the Sequence mode.

Additional Information

Personal tools