scripts/channelClasses/standard/AvRef.java

/////////////////////////////////////////////////////////////////
// Processes data by rereferencing EEG channels to the 
// instantaneous spatial average of EEG values
//
// This code is compiled at runtime, but compilation can be tested by:
//    javac -cp build scripts/channelClasses/standard/AvRef.java
//    rm scripts/channelClasses/standard/AvRef.class 
/////////////////////////////////////////////////////////////////
package standard;

import java.io.*;
import java.util.*;

import generalClasses.*;
import recordingClasses.Recording;
import seriesClasses.*;
import channelClasses.ChannelScript;
import static channelClasses.Channel.*;

/////////////////////////////////////////////////////////////////

/** Processes data by rereferencing EEG channels to the instantaneous 
 * spatial average of EEG values.  <b>It may be applied only to common-ref
 * data, and should be called only following rejection of noisy channels.</b>
 *
 * <p>First caveats.  This algorithm simply forms the average of all
 * EEG waveforms and subtracts this from each of these waveforms.
 * <b>As such, the supplied waveforms MUST all have a common reference.</b>
 * The common reference can be AvEars, Cz, etc; so long as it is indeed
 * common to all EEG channels.
 * <p>Second caveat.  Subtracting the average only makes sense if 
 * artifact-affected channels are excluded.  Accordingly this 
 * rereferencing operation assumes (and doesn't check) that noisy 
 * channels have already been excluded.  This can be ensured by
 * only ever calling this option <i>subsequent to</i> one that 
 * performs channel rejection, e.g.<pre>
 *    -scriptChannel Standard:AvRef
 * </pre>
 *
 * <p>The effect of average referencing can be seen be comparing the result 
 * of <pre>
 *    java -cp build:lib/derby.jar frontendClasses/CLI -fn data/10006636.EC.NS5 -scriptChannel Standard:AvRef -paradigm ec -scriptEpoch OneLong -chanSelection "Mode='EEG'" -reviewSeries
 * </pre>
 * with and without ':AvRef' in the command line.
 */
public class AvRef extends ChannelScript
{
    /** Recording instance to be operated on */
    Recording rec = null;
    /** Log of warnings generated during update */
    ArrayList<String> warnings = new ArrayList<String>();

    ////////////////////////////////////////////////////////////////////
    /** Initialize instance by setting its parameters to default values.
     */
    public AvRef(Recording rec) {
        this.rec = rec;
    } // AvRef


    ////////////////////////////////////////////////////////////////////
    /** Update recording data by performing channel-oriented operations.
     * <p>Available modes are EEG, EOG, REF, EMG, EDA, RES, ECG, EVE.
     */
    public void update() {
        // Partition results into EEG and non-EEG channels
        ArrayList<SeriesAnalog> result = selectMode(rec, DataMode.EEG);
        ArrayList<SeriesAnalog> rest = discardMode(rec, DataMode.EEG);

        // Ideally, check that all EEG channels have a common reference,
        // and, if not, create a warning or error.

        // Rereference the EEG, and merge with non-EEG channels
        subtractScalpMean(result);
        result = listsUnion(result, rest);

        // Update Recording object
        replaceAllSeries(rec, result);
    } // update


    ////////////////////////////////////////////////////////////////////
    /** Dump summary of this class or object
     * @return String representation of this object
     */
    public String toString() {
        String s = "<<<"+this.getClass().toString()+">>>\n";
        s += "References EEG channels by subtracting the instantaneous mean\n";

        for(String w: warnings)
            s += w+"\n";
        return s;
    } // toString
}