Source code: MAEPlugin/analysis/NormalizationPlugin.java
1 /** File: NormalizationPlugin.java */
2
3 package MAEPlugin.analysis;
4
5 import MAEPlugin.*;
6 import java.util.*;
7
8 /**
9 * This class extends the analysis MAEPlugin base class to implement the Normalization base class.
10 *
11 * The "active normalization" is a static reference that all Normalization
12 * classes share. Whichever one is active will be the one used.
13 *
14 * Created on September 7, 2001, 5:46 PM
15 *<P>
16 * This work was produced by Peter Lemkin of the National Cancer
17 * Institute, an agency of the United States Government. As a work of
18 * the United States Government there is no associated copyright. It is
19 * offered as open source software under the Mozilla Public License
20 * (version 1.1) subject to the limitations noted in the accompanying
21 * LEGAL file. This notice must be included with the code. The MAExplorer
22 * Mozilla and Legal files are available on http://maexplorer.sourceforge.net/.
23 *<P>
24 * @author Jai Evans (DECA/CIT), C. Santos (DECA/CIT), P. Lemkin (NCI-FCRDC)
25 * @version $Date: 2003/03/03 16:22:10 $ / $Revision: 1.6 $
26 * @see <A HREF="http://maexplorer.sourceforge.net/">MAExplorer Home</A>
27 */
28
29 public abstract class NormalizationPlugin extends AnalysisPlugin
30 implements Normalization
31 {
32
33 /** Pointer to the current active Normalization object. Reference to this
34 * object allows normalization methods to find the active normalization.
35 * This is static since only one normalization method may be active at a time.
36 * If the value is null, then there is NO active NormalizationPlugin
37 * even if several are loaded.
38 */
39 protected static Normalization
40 activeNormalization= null;
41
42 /* gives index access to sample for access to variables */
43 protected Object
44 sample;
45
46
47 /**
48 * NormalizationPlugin() - Default Constructor puts default menu name in menu.
49 */
50 public NormalizationPlugin()
51 {
52 super("Normalization");
53 }
54
55
56 /**
57 * NormalizationPlugin() - Default Constructor puts menu name in menu.
58 * @param menuLabel is the name of the plugin for use as the menu item
59 */
60 public NormalizationPlugin(String menuLabel)
61 {
62 super(menuLabel);
63 }
64
65
66 /**
67 * NormalizationPlugin() - Default Constructor puts menu name in menu and file name.
68 * @param menuLabel is the name of the plugin for use as the menu item
69 * @param pluginFileName name of the plugin without the ".jar"
70 */
71 public NormalizationPlugin(String menuLabel, String pluginFileName)
72 {
73 super(menuLabel, pluginFileName);
74 }
75
76
77 /**
78 * pluginMain() is the method activated when end-users check a checkbox API.
79 * This is unlike other plugins in that analysis will be done passively.
80 */
81 public final void pluginMain()
82 { /* MenuActivated */
83 /* if this plugin is checked, then point normalization
84 * pointer to us.
85 */
86 if (this.getState())
87 {
88 setActiveNormalization(this);
89 //getMAEStub().setNormalizationStateFromPlugin(this.getPluginName());
90
91 /* do normalization and refresh */
92 getMAEStub().recalcNorms(this.getPluginName(), this.getState());
93 }
94 } /* MenuActivated */
95
96
97 /**
98 * disableNormalizationPlugin() - clear activeNormalization state.
99 * If the state is null, then there are no active normalization plugins
100 * even if one or more is loaded.
101 */
102 public final static void disableNormalizationPlugin()
103 { /* disableNormalizationPlugin */
104 activeNormalization= null;
105 } /* disableNormalizationPlugin */
106
107
108 /**
109 * getNormalizationState() - Static method for using testing getActiveNormalization().
110 * It is used in MaeJavaAPI.
111 * If there is no active NormalizationPlugin instance, then this is false.
112 * @return state of normalization plugin. True if active.
113 */
114 public final static boolean getNormalizationState()
115 { return(activeNormalization != null); }
116
117
118 /**
119 * getActiveNormalization() - Bean-style method for getting the activeNormalization.
120 * If there is no active NormalizationPlugin instance, then this is null.
121 * @return Normalization instance
122 */
123 public static final synchronized Normalization getActiveNormalization()
124 { return(activeNormalization); }
125
126
127 /**
128 * setActiveNormalization() - Bean-style method for setting the activeNormalization.
129 * This method calls underlying methods in MAExplorer to treat the checkbox
130 * as a radio button and make sure that it disables other Normalization
131 * methods whether built-in or other normalization plugins.
132 * @param obj is Normalization plugin object
133 */
134 public final synchronized void setActiveNormalization(Normalization obj)
135 { /* setActiveNormalization */
136 /* turn off whichever normalization is on now */
137 if (activeNormalization != null)
138 {
139 activeNormalization.setState(false);
140 }
141
142 /* Change to the parameter and then turn on null value indicates that
143 * we are dumping the Normalization plugin that is current.
144 */
145 activeNormalization= obj;
146 if (activeNormalization != null)
147 { /* set this normalization method as active */
148 activeNormalization.setState(true);
149
150 /* Do a quick double check and set the NormStateFromPLugin */
151 if ( obj instanceof NormalizationPlugin)
152 { /* notify built-in radio-button code for this normalization */
153 /* This is required so that there is only one normalization method.
154 * It then figures out which plugin is active by using
155 * getActiveNormalization() and calling this Normalize method
156 * as required.
157 */
158 String pluginName= ((NormalizationPlugin) obj).getPluginName();
159 getMAEStub().setNormalizationStateFromPlugin(pluginName);
160 }
161 else
162 getMAEStub().setNormalizationStateFromPlugin(null);
163 } /* set this normalization method as active */
164 else
165 { /* disable this normalization method */
166 getMAEStub().setNormalizationStateFromPlugin(null);
167 }
168
169 } /* setActiveNormalization */
170
171
172 /**
173 * pluginHalt() - stop the plugin
174 */
175 public void pluginHalt()
176 { /* pluginHalt */
177 if (this == getActiveNormalization())
178 { /* disable this normalization in built-in radio button code */
179 setActiveNormalization(null);
180 getMAEStub().setNormalizationStateFromPlugin(null);
181 }
182 } /* pluginHalt */
183
184
185 /**
186 * getSample() - used to Get the primary sample, to get the variables
187 * @return sample as Object
188 */
189 public final Object getSample()
190 { return(this.sample); }
191
192
193 /**
194 * setSample() - method used to set primary variables from the sample.
195 * @param obj is the NormalizationPlugin sample object
196 */
197 public final void setSample(Object obj)
198 { /* setSample */
199 this.sample= obj;
200 } /* setSample */
201
202
203 /**
204 * resetPipeline() - reset filter at start of data Normalization.
205 * We will test for ALL GENES (if required) using the midOK[] boolean
206 * created here to later determine if we actually perform the test.
207 * This sets up the state that may be used during the pipeline operation.
208 * @param optArg - optional argument
209 * @return true if succeed
210 */
211 public abstract boolean resetPipeline(int optArg);
212
213
214 /**
215 * finishPipeline() - finish filter at end of normalization of all genes (if required).
216 * This may be used to clean up the state after the pipeline operation.
217 * @param optArg - optional argument
218 * @return true if succeed
219 */
220 public abstract boolean finishPipeline(int optArg);
221
222
223 /**
224 * calcIntensityScaleExtrema() - compute scaled Intensity upper
225 * and lower limits of raw data for each sample. It is called
226 * to get extrema for use in scaling displays and other computations
227 * where the limits must be known.
228 * @param maxRI maximum raw ratio intensity
229 * @param minRI minimum raw ratio intensity
230 * @param maxRaw maximum raw intensity max(rawF1,rawF2)
231 * @param minRaw minimum raw intensity min(rawF1,rawF2)
232 * @param sampleNbr for the sample sample number in the range [1:maxSamples]
233 * @return an array with the following scaled data:
234 *<PRE>
235 * element 0 = maxDataS
236 * element 1 = minDataS
237 * element 2 = maxRawS
238 * element 3 = minRawS
239 *</PRE>
240 */
241 public abstract float[] calcIntensityScaleExtrema(float maxRI, float minRI,
242 float maxRaw, float minRaw,
243 int sampleNbr);
244
245
246 /**
247 * scaleIntensityData() - scale raw intensity data as fct of normalization
248 * mode. This is called on a per-spot basis.
249 * @param rawData is unnormalized data for spot
250 * @return scaled normalized spot data
251 */
252 public abstract float scaleIntensityData(float rawData);
253
254
255 /**
256 * scaleIntensityData() - scale raw intensity data as fct of normalization mode.
257 * There is a (gid,sampleNbr) dependence on the normalization.
258 * This is called on a per-spot basis.
259 * @param rawData is unnormalized data for spot
260 * @param mid is MID of the spot
261 * @param gid is GID of the spot
262 * @param sampleNbr for the sample array
263 * @return normalized spot data
264 */
265 public abstract float scaleIntensityData(float rawData, int mid, int gid,
266 int sampleNbr);
267
268
269 /**
270 * scaleIntensityData() - the gene normalization operating on gene mid
271 * for sampleIdx where the data is ether extracted here or from the resetPipeline
272 * pre-analysis.
273 * If the normalization is inoperative, then just return 0.0.
274 * The mid must be >=0 since -1 indicates an illegal gene.
275 * The midOK[mid] must be true, else it indicates an illegal gene.
276 *
277 * [NOTE] The plugin writer should try to avoid doing special analyses here that
278 * need to be computed DURING the processing and instead do the computations
279 * during the resetPipeline() operation if possible. That may be able to
280 * optimized and the data cached to avoid constant recomputation.
281 * @param rawIntensity is intensity value to be normalized
282 * @param rawBkgrd is background intensity to be used in normalization
283 * if the use Background flag is set.
284 * @param mid is the Master Gene ID to test if not -1 and the gene exists
285 * @param gid is the spot Geometry Gene Index to test if not -1 and the spot exists
286 * @param sampleIdx is the HybridSample index number for single sample HP-X or HP-Y.
287 * For Cy3 vs Cy5 mode, it is 0 for Cy3 (F1), and 1 for Cy5 (F2).
288 * For HP-X 'set' vs HP-Y 'set' mode,
289 * it is 0 for HP-X 'set', and 1 for HP-Y 'set'
290 * @return scaled data if normalization is active, else 0.0F
291 */
292 public abstract float scaleIntensityData(float rawIntensity, float rawBkgrd,
293 int mid, int gid, int sampleIdx);
294
295 /**
296 * recalcNormalizationExtrema() - set the extreama for all samples for this plugin
297 */
298 public abstract void recalcNormalizationExtrema();
299
300
301 /* ---------- ADDITONAL METHODS USER MUST IMPLEMENT -------------- */
302
303 /**
304 * updateCurGene() - abstract method end-users must implement to use
305 * the API. It is called by the popup Registry for the user to update
306 * any dependent data since the current gene has changed.
307 * @param mid is the MID (Master Gene ID) that is the new current gene.
308 */
309 public abstract void updateCurGene(int mid);
310
311
312 /**
313 * updateFilter() - abstract method end-users must implement to use the API.
314 * It is called by the popup Registry for the user to update
315 * any dependent data since the data Filter has changed.
316 */
317 public abstract void updateFilter();
318
319
320 /**
321 * updateSlider() - abstract method end-users must implement to use the API.
322 * It is called by the popup Registry for the user to update
323 * any dependent data since the threshold sliders have changed.
324 * This is invoked from the PopupRegistry.
325 */
326 public abstract void updateSlider();
327
328
329 /**
330 * updateLabels() - abstract method end-users must implement to use the API.
331 * It is called by the popup Registry for the user to update
332 * any dependent data since some global labels have changed.
333 */
334 public abstract void updateLabels();
335
336
337 /**
338 * close() - close the plugin
339 * @param preserveDataStructuresFlag to save data structures
340 */
341 public abstract void close(boolean preserveDataStructuresFlag);
342
343 } /* end of class NormalizationPlugin */