Class MaeJavaAPI

java.lang.Object
  |
  +--MaeJavaAPI
All Implemented Interfaces:
MAEPlugin.MAEStub

public class MaeJavaAPI
extends java.lang.Object
implements MAEPlugin.MAEStub

This class implements MAEPlugin.MAEStub and is the Open Java API. The Application Programming Interface (API) is used to access MAExplorer data structures in a uniform way. This hides the actual complexity of the internal data structures making it much easier for MAEPlugin writters to use. It is designed to be used with MAExplorer MAEPlugins.

The technique we use to expose MAExplorer data structures is called "gather-scatter". For each group of data requested by a user, a collection of this data is "gathered" from internal MAExplorer data stuctures and assembled into a portable object that is returned to the user. Conversely, when the user wishes to save a (known type of) complex object back into MAExplorer, it disassembles the user'sobject and "scatters" the data (remapped back to internal data structures if necessary) into the internal MAExplorer data structures.

Because of this independence between programming domains, the MAEPlugin-writer can code to the API rather than to the underlying MAExplorer data structures. The added advantage is that the internal data structures may then be changed and improved without affecting existing user plugins.

1. Design
Data is passed in the API using standard JDK data objects so the plugin-writer does not need to understand the internal MAExplorer data structures.

Data objects that the user sees - packed collections of data
The data types include (int, short, float, double, byte, char, String, Hashtable) and arrays of these types. We use Hashtable as a (Name,Value) collection packaging class. Each Hashtable entry holds triples (String name; Object value; class-type). Each entry is saved as an Object, so it can be interrogated to determine its class type (see Class and Object class definitions) - although the types and names of the objects put into the hash tables are listed in the method descriptions.

To access any array or complex object just cast it to the required type:

 E.g.  Hashtable ht = (some MJA method that returns a Hashtable)
       float abc[][] = (float[][]) ht.get("abc");
       String xyz = (String) ht.get("xyz");
To access a scalar object, the user needs to cast the hash table object and then use a converter method:
 E.g.  Hashtable ht = (some MJA method that returns a Hashtable)
       float a = ((Float)ht.get("a")).floatValue();
       int b = ((Integer)ht.get("b")).intValue();
       short c = ((Short)ht.get("c")).shortValue();
       long d = ((Long)ht.get("d")).longValue();
       boolean e = ((Boolean)ht.get("e")).booleanValue();
       byte f = ((Byte)ht.get("f")).byteValue();
       char g = ((Character)ht.get("g")).charValue();

The MAEPlugin writer may access many of the internal MAExplorer data structures using get_xxxx() and set_xxxx() access methods in the MJAxxxx classes.

2. List of categories of MJAxxxx classes

 MJAxxxx Class     Objects and method access
 -------------     -------------------------
 MJAbase            constants used by other MJA classes
 MJAcluster         cluster data structures and support
 MJAcondition       condition lists of samples and ordered lists of condition lists
 MJAeval            MAExplorer command interpreter
 MJAexprProfile     expression profiles data
 MJAfilter          gene data filters
 MJAgene            single gene data (genomic and quantitative)
 MJAgeneList        lists of genes and get sets
 MJAgenomicDB       genomic databases on the Internet 
 MJAgeometry        array geometry, spot to gene maps, etc.
 MJAhelp            popup browser help methods
 MJAhistogram       histogram plots and methods
 MJAmath            built-in math functions
 MJAnormalziation   normalization data and methods
 MJAplot            scrollable 2D plot support [Future]
 MJAproperty        get and put individual properties
 MJApropList        get lists of properties
 MJAReval           Execute R program .R scripts using MAExplorer data
 MJAsample          get and put single sample top-level data
 MJAsampleList      get lists of samples top-level data
 MJAscrollablePlot  scrollable 2D plot support [Future]
 MJAsort            built-in sort methods
 MJAstatistics      built-in statistics methods
 MJAstate           get and save state, get additional state info
 MJAutil            built-in utility methods

3. [TODO] Adding a plugin to particular stub in the MAExplorer menu Plugins are added by adding the following triple to the Configuration file or .mae startup file (each entry is defined by a 4-tuple for '#' being (1, 2, etc.) PluginMenuName# New sample report PluginMenuStubName# ReportMenu:sample PluginClassFile# NewSampleReport.class PluginCallAtStartup# "TRUE" Plugins may also be added at run time and either inserted into the Plugin menu, or [TODO] using information in the Plugin itself may insert itself into the appropriate menu stub.

3.1 List of acceptable Menu stub names for: PluginMenuStubName (When enabled), you will be able to insert plugins into specified parts of the MAExplorer menu. If the menu stub is not found, it will install them in the generic "Plugin" pull-down menu.

4. List of public MJA access instances for Plugin-writers in this class

 MJAbase majBase - access constants and methods used by other MJA classes 
 MJAcluster mjaCluster - access cluster data structures and methods
 MJAexprProfile mjaExprProfile - access expression profile library MJA methods
 MJAfilter mjaFilter - access data filter state and methods 
 MJAgene mjaGene - access single gene data methods
 MJAgeneList mjaGeneList - access lists of genes and gene set operations
 MJAgenomicDB mjaGenomicDB - access genomic Internet databases methods
 MJAgeometry mjaGeometry - array geometry, spot to gene maps, etc. methods
 MJAhelp mjaHelp - access popup browser help methods
 MJAhistogram mjaHistogram - histogram plots methods
 MJAmath majMAth - built-in math methods
 MJAnormalization mjaNormalization - access normalization data and methods
 MJApopupRegistry mjaPopupRegistry - access popup registry of active windows methods
 MJAplot mjaPlot - 2D plot base class methods [Future]
 MJAproperty mjaProperty - access individual properties methods
 MJApropList mjaPropList - access lists of properties methods
 MJAreport mjaReport - access report methods
 MJAsample mjaSample - access single sample top-level data methods
 MJAsampleList mjaSampleList - access lists of samples top-level data
 MJAscrollablePlot mjaScrollablePlot - access scrollable 2D plot base class methods [Future]
 MJAstate mjaState - access MAExplorer state saving, additional state info, methods
 MJAstatistics mjaStatistics - access built-in statistics methods 
 MJAutil mjaUtil - access built-in general utility methods

4.1 List of public methods implemented for Plugin-writers in this class
 [NOTE: this will be changed as we migrate some of these methods out of the top
       level MaeJavaAPI into the MJAxxxx classes where appropriate.]

 refreshDataFilter() - regenerate scrollers, refresh the data filter and repaint
 insertPluginMenu() - insert plugin into menu using (menuName:menuSubtreeName)
 removePluginMenu() - remove plugin from the menubar.
 loadPluginsAtStartup() - load plugins from file via startup
 getMenuHook() - insert plugin into menu
 getFrame() - provide the dominate Frame for other AWT components
 loadPluginsStartup() - load plugins from file via startup
 setMenuHook() - set menu hook for the plugin
 getMenuHook() - get the menu hook for the plugin
 getFrame() - provide the dominate Frame for other AWT components
 recalcNorms() - recalculate normalizations of all samples 
 getNormalizationState() - update the Normalization state based on normalization method 
 setNormalizationState() - update Normalization state based on normalization method 
 setNormalizationStateFromPlugin() - set normalization state from plugin.
 getActiveNormalization() - get active normalization.
 showMsg() - display string in text field 1 in main window.
 getSampleTotHistStats() - get Hashtable list of a sample's total histogram statistics.
 logZero() - compute log10((x==0.0 ? 0.0 : x) - avoid log(0.0)!

This work was produced by Peter Lemkin of the National Cancer Institute, an agency of the United States Government. As a work of the United States Government there is no associated copyright. It is offered as open source software under the Mozilla Public License (version 1.1) subject to the limitations noted in the accompanying LEGAL file. This notice must be included with the code. The MAExplorer Mozilla and Legal files are available on http://maexplorer.sourceforge.net/.

Version:
$Date: 2003/04/10 16:40:04 $ $Revision: 1.11 $
Author:
P. Lemkin (NCI), J. Evans (CIT), C. Santos (CIT), G. Thornwall (SAIC), NCI-Frederick, Frederick, MD
See Also:
MAExplorer Home, MJAbase, MJAcluster, MJAcondition, MJAeval, MJAexprProfile, MJAfilter, MJAgene, MJAgeneList, MJAgenomicDB, MJAgeometry, MJAhelp, MJAhistogram, MJAmath, MJAnormalization, MJAplot, MJAscrollablePlot, MJApopupRegistry, MJAproperty, MJApropList, MJAmath, MJAReval, MJAreport, MJAsample, MJAsampleList, MJAsort, MJAstatistics, MJAstate,


Field Summary
static MJAbase mjaBase
          constants and methods used by other MJA classes
static MJAcluster mjaCluster
          cluster data structures and methods
 MJAcondition mjaCondition
          condition lists of samples, and ordered lists of condition lists
 MJAeval mjaEval
          command interpreter
 MJAexprProfile mjaExprProfile
          expression profile data and methods
static MJAfilter mjaFilter
          data filter flags and methods
static MJAgene mjaGene
          single gene data
static MJAgeneList mjaGeneList
          lists of genes and gene sets methods
static MJAgenomicDB mjaGenomicDB
          genomic databases on the Internet
static MJAgeometry mjaGeometry
          array geometry, spot to gene maps, etc.
static MJAhelp mjaHelp
          popup browser help methods
static MJAhistogram mjaHistogram
          histogram plots
static MJAmath mjaMath
          built-in math methods
static MJAnormalization mjaNormalization
          Access normalization data and methods
static MJAplot mjaPlot
          2D plot popup window base class [Future]
static MJApopupRegistry mjaPopupRegistry
          popup registry of active windows
static MJAproperty mjaProperty
          individual MAExplorer properties methods
static MJApropList mjaPropList
          lists of MAExplorer properties methods
static MJAreport mjaReport
          report methods
static MJAReval mjaReval
          Execute R program .R scripts using MAExplorer data
static MJAsample mjaSample
          single sample top-level data methods
static MJAsampleList mjaSampleList
          get lists of samples top-level data methods
static MJAscrollablePlot mjaScrollablePlot
          Scrollable 2D plot base class [Future]
static MJAsort mjaSort
          built-in sorting methods
static MJAstate mjaState
          MAExplorer state saving, additional state info, methods
static MJAstatistics mjaStatistics
          built-in statistics methods
static MJAutil mjaUtil
          built-in general utility methods
 
Fields inherited from interface MAEPlugin.MAEStub
menuHook
 
Method Summary
 void disableNormalizationPlugin()
          disableNormalizationPlugin() - clear activeNormalization state.
 MAEPlugin.Normalization getActiveNormalization()
          getActiveNormalization() - get active normalization.
 java.awt.Frame getFrame()
          getFrame() - provide the dominate Frame for other AWT components
 java.awt.Menu getMenuHook()
          getMenuHook() - get the menu hook for the plugin
 boolean getNormalizationState()
          getNormalizationState() - update Normalization state based on normalization method selected in plugins.
 java.util.Hashtable getSampleTotHistStats(java.lang.Object o)
          getSampleTotHistStats() - get Hashtable list of a sample's total histogram statistics.
 void insertPluginMenu(java.awt.MenuItem mi)
          insertPluginMenu() - insert plugin into menu using (menuName:menuSubtreeName) [TODO]
 void loadPluginsAtStartup()
          loadPluginsAtStartup() - load plugins from file via startup.
 void loadPluginsStartup()
          loadPluginsStartup() - load plugins from file via startup
 double logZero(double x)
          logZero() - compute log10((x==0.0 ? 0.0 : x) - avoid log(0.0)! This defaults log10(0.0) to log(1.0).
 void recalcNorms(java.lang.String msg, boolean flag)
          recalcNorms() - recalculate normalizations of all samples
 void refreshDataFilter()
          refreshDataFilter() - regenerate scrollers, refresh the data filter and repaint
 void removePluginMenu(java.awt.MenuItem mi)
          removePluginMenu() - remove plugin from the menubar.
 void setMenuHook(java.awt.Menu menu)
          setMenuHook() - set menu hook for the plugin
 void setNormalizationState(boolean flag)
          setNormalizationState() - update Normalization state based on normalization method selected in non-plugin menus
 void setNormalizationStateFromPlugin(java.lang.String methodName)
          setNormalizationStateFromPlugin() - set normalization state FROM the plugin.
 void showMsg(java.lang.String str)
          showMsg() - display string in text field 1 in main window.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

mjaBase

public static MJAbase mjaBase
constants and methods used by other MJA classes

mjaCluster

public static MJAcluster mjaCluster
cluster data structures and methods

mjaCondition

public MJAcondition mjaCondition
condition lists of samples, and ordered lists of condition lists

mjaEval

public MJAeval mjaEval
command interpreter

mjaExprProfile

public MJAexprProfile mjaExprProfile
expression profile data and methods

mjaFilter

public static MJAfilter mjaFilter
data filter flags and methods

mjaGene

public static MJAgene mjaGene
single gene data

mjaGeneList

public static MJAgeneList mjaGeneList
lists of genes and gene sets methods

mjaGenomicDB

public static MJAgenomicDB mjaGenomicDB
genomic databases on the Internet

mjaGeometry

public static MJAgeometry mjaGeometry
array geometry, spot to gene maps, etc. data

mjaHelp

public static MJAhelp mjaHelp
popup browser help methods

mjaHistogram

public static MJAhistogram mjaHistogram
histogram plots

mjaMath

public static MJAmath mjaMath
built-in math methods

mjaNormalization

public static MJAnormalization mjaNormalization
Access normalization data and methods

mjaPopupRegistry

public static MJApopupRegistry mjaPopupRegistry
popup registry of active windows

mjaPlot

public static MJAplot mjaPlot
2D plot popup window base class [Future]

mjaProperty

public static MJAproperty mjaProperty
individual MAExplorer properties methods

mjaPropList

public static MJApropList mjaPropList
lists of MAExplorer properties methods

mjaReport

public static MJAreport mjaReport
report methods

mjaReval

public static MJAReval mjaReval
Execute R program .R scripts using MAExplorer data

mjaSample

public static MJAsample mjaSample
single sample top-level data methods

mjaSampleList

public static MJAsampleList mjaSampleList
get lists of samples top-level data methods

mjaScrollablePlot

public static MJAscrollablePlot mjaScrollablePlot
Scrollable 2D plot base class [Future]

mjaSort

public static MJAsort mjaSort
built-in sorting methods

mjaState

public static MJAstate mjaState
MAExplorer state saving, additional state info, methods

mjaStatistics

public static MJAstatistics mjaStatistics
built-in statistics methods

mjaUtil

public static MJAutil mjaUtil
built-in general utility methods
Method Detail

refreshDataFilter

public final void refreshDataFilter()
refreshDataFilter() - regenerate scrollers, refresh the data filter and repaint
Specified by:
refreshDataFilter in interface MAEPlugin.MAEStub

loadPluginsAtStartup

public final void loadPluginsAtStartup()
loadPluginsAtStartup() - load plugins from file via startup. [TODO]

insertPluginMenu

public final void insertPluginMenu(java.awt.MenuItem mi)
insertPluginMenu() - insert plugin into menu using (menuName:menuSubtreeName) [TODO]
Specified by:
insertPluginMenu in interface MAEPlugin.MAEStub
Parameters:
maeplugin - MAEPlugin.MAEPlugin to load

removePluginMenu

public final void removePluginMenu(java.awt.MenuItem mi)
removePluginMenu() - remove plugin from the menubar.
Specified by:
removePluginMenu in interface MAEPlugin.MAEStub

loadPluginsStartup

public final void loadPluginsStartup()
loadPluginsStartup() - load plugins from file via startup
Specified by:
loadPluginsStartup in interface MAEPlugin.MAEStub

setMenuHook

public final void setMenuHook(java.awt.Menu menu)
setMenuHook() - set menu hook for the plugin
Specified by:
setMenuHook in interface MAEPlugin.MAEStub
Parameters:
menu - menu to set as the menu hook

getMenuHook

public final java.awt.Menu getMenuHook()
getMenuHook() - get the menu hook for the plugin
Specified by:
getMenuHook in interface MAEPlugin.MAEStub
Returns:
menu hook where attach new plugin.

getFrame

public final java.awt.Frame getFrame()
getFrame() - provide the dominate Frame for other AWT components
Specified by:
getFrame in interface MAEPlugin.MAEStub

recalcNorms

public final void recalcNorms(java.lang.String msg,
                              boolean flag)
recalcNorms() - recalculate normalizations of all samples
Specified by:
recalcNorms in interface MAEPlugin.MAEStub
Parameters:
msg - title string
flag - flag passed to recalcNorms...

disableNormalizationPlugin

public final void disableNormalizationPlugin()
disableNormalizationPlugin() - clear activeNormalization state. If the state is false, then there are no active normalization plugins even if one or more is loaded.
Specified by:
disableNormalizationPlugin in interface MAEPlugin.MAEStub

getNormalizationState

public final boolean getNormalizationState()
getNormalizationState() - update Normalization state based on normalization method selected in plugins.
Specified by:
getNormalizationState in interface MAEPlugin.MAEStub
Returns:
true if normalization plugin is active

setNormalizationState

public final void setNormalizationState(boolean flag)
setNormalizationState() - update Normalization state based on normalization method selected in non-plugin menus
Specified by:
setNormalizationState in interface MAEPlugin.MAEStub

setNormalizationStateFromPlugin

public final void setNormalizationStateFromPlugin(java.lang.String methodName)
setNormalizationStateFromPlugin() - set normalization state FROM the plugin. This is called from the MAEStub. It is called from the plugin when it becomes active to notify MAExplorer to treat the checkbox as the active Normalization radio button and make sure that it disables other Normalization methods whether built-in or other normalization plugins.
Specified by:
setNormalizationStateFromPlugin in interface MAEPlugin.MAEStub
Parameters:
methodName - name of the method

getActiveNormalization

public MAEPlugin.Normalization getActiveNormalization()
getActiveNormalization() - get active normalization.
Returns:
normalization method

showMsg

public final void showMsg(java.lang.String str)
showMsg() - display string in text field 1 in main window.
Specified by:
showMsg in interface MAEPlugin.MAEStub
Following copied from interface: MAEPlugin.MAEStub
Parameters:
str - message to draw in top text line of main window.

getSampleTotHistStats

public java.util.Hashtable getSampleTotHistStats(java.lang.Object o)
getSampleTotHistStats() - get Hashtable list of a sample's total histogram statistics. This data is currently computed on non-data Filtered (i.e. all genes) list of data. [TODO] to [DEPRICATE] this and instead use mjaSample.getSampleTotHistStats()
 The Hashtable list returned is defined as:
 name          - Value
 "minHistData"     - float total array: min hist data value
 "maxHistData"     - float total array: max hist data value
 "mnHPri"          - float total array: rawIntens mean, all genes in HP
                     sample without background
 "sdHPri"          - float total array: rawIntens StdDev, all genes in HP
                     sample without background
 "madHPri"         - float total array: rawIntens meanAbsDev, all genes
                     in HP sample without background
 "mnHPri1"         - float total array: rawIntens f1 mean, all genes in
                     HP sample without background
 "sdHPri1"         - float total array: rawIntens f1 StdDev, all genes
                     in HP sample without background
 "mnHPri2"         - float total array: rawIntens f2 mean, all genes
                     in HP sample without background
 "sdHPri2"         - float total array: rawIntens f2 StdDev, all genes
                     in HP sample without background
 "scaleToMaxIV"    - float total array: maxFV/maxRI scale factor to
                     compute the maximum range
 "maxFV"           - float maximum and fractions of dynamic range
 "logMeanRI"       - float total array: std dev of log of means
 "logStdDevRI"     - float total array: std dev of log of means
 "logMeanAbsDevRI" - float total array: Filter hist: log of mean absolute
                     deviation raw intensity
 "logMaxRI"        - float total array: log of maxRI
 "logMinRI"        - float total array: log of minRI
  . . .
 

Specified by:
getSampleTotHistStats in interface MAEPlugin.MAEStub
Parameters:
sampleNbr - sample number data to access
Returns:
hashtable else null if not found or error.

logZero

public double logZero(double x)
logZero() - compute log10((x==0.0 ? 0.0 : x) - avoid log(0.0)! This defaults log10(0.0) to log(1.0).
Specified by:
logZero in interface MAEPlugin.MAEStub
Parameters:
x - argument for log
Returns:
log10((x==0.0 ? 0.0 : x) - avoid log(0.0)!