function qscanlite(eventTime, configurationFile, frameCacheFile, outputDirectory)
% QSCANLITE Search multiple channels for statistically significant content
%
% QSCANLITE Examines gravitational-wave channels, auxiliary interferometer
% channels, and environmental channels around times of interest.  QScanLite is a
% simplified version of QScan that only produces TXT and XML summary
% information, and does not produce images or an html report.  It has the same
% command line syntax and reads the same configuration files used by QScan.
%
% usage: qscanlite(eventTime, configurationFile, frameCacheFile, outputDirectory);
%
%   eventTime             GPS time of candidate event
%   configurationFile     path name of channel configuration file
%   frameCacheFile        path name of frame file cache file
%   outputDirectory       path name of directory to write results
%
% To allow use as a stand-alone executable, the specified eventTime should be
% a string, not a number.
%
% The configuration file is an ASCII text file describing the parameters for
% each channel to be analyzed.  The entries should have the following syntax.
%
% {
%   channelName:                 'H1:LSC-AS_Q'
%   frameType:                   'RDS_R_L1'
%   sampleFrequency:             4096
%   searchTimeRange:             16
%   searchFrequencyRange:        [64 1024]
%   searchQRange:                [4 64]
%   searchMaximumEnergyLoss:     0.2
%   whiteNoiseFalseRate:         1e-2
%   searchWindowDuration:        0.1
%   plotTimeRanges:              [0.1 1.0 10.0]
%   plotFrequencyRange:          [64 1024]
%   plotMaximumEnergyLoss:       0.02
%   plotNormalizedEnergyRange:   [0 25.5]
%   alwaysPlotFlag:              0
% }
%
% Groups of related channels may optionally be separated by a section title
% specifier with the following form.
%
% [index_entry:section_title]
%
% The QCONFIGURE.SH script can be used to automatically generate a reasonable
% configuration file for sample frame files.
%
% If no configuration file is specified, QSCANLITE looks for the file
% configuration.txt in the current working directory.  Similarly, if not frame
% cache file is specified, QSCANLITE looks for the file framecache.txt in the
% current working directory.
%
% For information on the frameCacheFile, see READFRAMEDATA.
%
% The resulting TXT and XML summary files are are written along with a log file
% and a copy of the configuration file to an event sub-directory that is created
% in the specified output directory and is labelled by the GPS time of the event
% under analysis.  If no output directory is specified, a default output
% directory called qscans is created in the current working directory.
%
% See also READFRAMEDATA, QTILE, QSCANCONDITION, QTRANSFORM, QTHRESHOLD,
% QSELECT, QSPECTROGRAM, QEVENTGRAM, QTIMESERIES, QCONFIGURE.SH, QSCAN,
% QSCAN.sh, and QSCANLITE.SH.

% Shourov K. Chatterji
% shourov@ligo.mit.edu

% $Id: qscanlite.m,v 1.4 2007/08/16 16:45:24 shourov Exp $

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                debug settings                                %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% specify debug level for log output
debugLevel = 1;

% enable or disable warnings
if debugLevel >= 2,
  warning on QSCAN:incompleteConfiguration
else
  warning off QSCAN:incompleteConfiguration
end

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                   defaults                                   %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% default parameter file names
defaultConfigurationFile = 'configuration.txt';
defaultFrameCacheFile = 'framecache.txt';
defaultOutputDirectory = 'qscans';

% default configuration parameters
defaultSampleFrequency = 4096;
defaultSearchTimeRange = 64;
defaultSearchFrequencyRange = [0 Inf];
defaultSearchQRange = [4 64];
defaultSearchMaximumEnergyLoss = 0.2;
defaultWhiteNoiseFalseRate = 1e-2;
defaultSearchWindowDuration = [0.1];
defaultPlotTimeRanges = [1 4 16];
defaultPlotFrequencyRange = [];
defaultPlotMaximumEnergyLoss = 0.2;
defaultPlotNormalizedEnergyRange = [0 25.5];
defaultAlwaysPlotFlag = 0;

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                            hard coded parameters                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% search parameters
outlierFactor = 2.0;
durationInflation = 1.0;
bandwidthInflation = 1.0;

% limits on number of significant tiles
maximumSignificants = 1e4;
maximumMosaics = 1e4;

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                        process command line arguments                        %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% verify correct number of input arguments
error(nargchk(1, 4, nargin));

% apply default arguments
if (nargin < 2) || isempty(configurationFile),
  configurationFile = defaultConfigurationFile;
end
if (nargin < 3) || isempty(frameCacheFile),
  frameCacheFile = defaultFrameCacheFile;
end
if (nargin < 4) || isempty(outputDirectory),
  outputDirectory = defaultOutputDirectory;
end

% convert string event time to a number
if isstr(eventTime),
  eventTimeString = eventTime;
  eventTime = str2num(eventTime);
else
  eventTimeString = sprintf('%#019.9f', eventTime);
end

% string name of event type
eventType = 'Event';

% event directory name
eventDirectory = [outputDirectory '/' eventTimeString];

% name of text summary file
textSummaryFile = 'summary.txt';

% name of xml summary file
xmlSummaryFile = 'summary.xml';

% set random number generator seeds based on event time
rand('state', eventTime);
randn('state', eventTime);

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                      write log file header information                       %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% report status
if debugLevel >= 0,
  fprintf(1, 'QScan of %s at %s\n', eventType, eventTimeString);
  fprintf(1, 'created by %s on %s at %s\n', ...
          getenv('USER'), datestr(clock, 29), datestr(clock, 13));
end

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                           read configuration file                            %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% report status
if debugLevel >= 0,
  fprintf(1, 'reading configuration file %s...\n', configurationFile);
end

% initialize configuration structure
configuration = [];
channelNumber = 0;
sectionIndex = [];
sectionName = [];
sectionNumber = 0;
sectionStart = [];

% open configuration file for reading
configurationFID = fopen(configurationFile, 'r');

% begin loop over configuration file
while ~feof(configurationFID),

  % read one line from configuration file
  configurationLine = fgetl(configurationFID);

  % remove any comments
  commentIndices = findstr(configurationLine, '#');
  if ~isempty(commentIndices),
    configurationLine = configurationLine(1 : (commentIndices(1) - 1));
  end

  % remove leading and trailing blanks
  configurationLine = fliplr(deblank(fliplr(deblank(configurationLine))));

  % if empty line, skip to the next line
  if isempty(configurationLine),
    continue;
  end

  % check for new section
  if configurationLine(1) == '[',

    % locate field separator
    commaIndex = strfind(configurationLine, ',');

    % if field separator not located, report syntax error
    if isempty(commaIndex),
      error('syntax error processing configuration file "%s":\n%s\n', ...
            configurationFile, configurationLine);
    end

    % select first field separator
    commaIndex = commaIndex(1);

    % increment section number
    sectionNumber = sectionNumber + 1;

    % exract section index
    sectionIndex{sectionNumber} = configurationLine(2 : commaIndex - 1);

    % extract section name
    sectionName{sectionNumber} = configurationLine((commaIndex + 1) : end - 1);

    % remove leading and trailing blanks
    sectionIndex{sectionNumber} = ...
        fliplr(deblank(fliplr(deblank(sectionIndex{sectionNumber}))));
    sectionName{sectionNumber} = ...
        fliplr(deblank(fliplr(deblank(sectionName{sectionNumber}))));

    % standardize section names
    sectionIndex{sectionNumber} = strrep(sectionIndex{sectionNumber}, ';', ':');
    sectionName{sectionNumber} = strrep(sectionName{sectionNumber}, ';', ':');

    % determine initial visibility
    switch sectionIndex{sectionNumber},
      case 'Context',
        sectionChecked{sectionNumber} = 'checked';
        sectionDisplay{sectionNumber} = 'block';
      case 'Gravitational',
        sectionChecked{sectionNumber} = 'checked';
        sectionDisplay{sectionNumber} = 'block';
      otherwise
        sectionChecked{sectionNumber} = 'checked';
        sectionDisplay{sectionNumber} = 'block';
        % sectionChecked{sectionNumber} = '';
        % sectionDisplay{sectionNumber} = 'none';
    end

    % record first channel in section
    sectionStart(sectionNumber) = channelNumber + 1;

    % continue to next line
    continue;

  end

  % check for beginning of new channel configuration
  if configurationLine == '{',

    % increment channel number
    channelNumber = channelNumber + 1;

    % initialize configuration parameters
    configuration{channelNumber}.channelName = [];
    configuration{channelNumber}.frameType = [];
    configuration{channelNumber}.sampleFrequency = [];
    configuration{channelNumber}.searchTimeRange = [];
    configuration{channelNumber}.searchFrequencyRange = [];
    configuration{channelNumber}.searchQRange = [];
    configuration{channelNumber}.searchMaximumEnergyLoss = [];
    configuration{channelNumber}.searchMaximumEnergyLoss = [];
    configuration{channelNumber}.searchWindowDuration = [];
    configuration{channelNumber}.plotTimeRanges = [];
    configuration{channelNumber}.plotFrequencyRange = [];
    configuration{channelNumber}.plotMaximumEnergyLoss = [];
    configuration{channelNumber}.plotNormalizedEnergyRange = [];
    configuration{channelNumber}.alwaysPlotFlag = [];

    % continue to next line
    continue;

  end

  % check for end of existing channel configuration
  if configurationLine == '}',

    % validate channel configuration
    if isempty(configuration{channelNumber}.channelName),
      error(['channel name not specified for ' ...
             'channel number %d'], channelNumber);
    end
    if isempty(configuration{channelNumber}.frameType),
      error(['frame type not specified for ' ...
             'channel number %d'], channelNumber);
    end
    if isempty(configuration{channelNumber}.sampleFrequency),
      warning('QSCAN:incompleteConfiguration', ...
              ['sample frequency not specified for ' ...
               'channel number %d'], channelNumber);
      configuration{channelNumber}.sampleFrequency = ...
          defaultSampleFrequency;
    end
    if isempty(configuration{channelNumber}.searchTimeRange),
      warning('QSCAN:incompleteConfiguration', ...
              ['search time range not specified for ' ...
               'channel number %d'], channelNumber);
      configuration{channelNumber}.searchTimeRange = ...
          defaultSearchTimeRange;
    end
    if isempty(configuration{channelNumber}.searchFrequencyRange),
      warning('QSCAN:incompleteConfiguration', ...
              ['search frequency range not specified for ' ...
               'channel number %d'], channelNumber);
      configuration{channelNumber}.searchFrequencyRange = ...
          defaultSearchFrequencyRange;
    end
    if isempty(configuration{channelNumber}.searchQRange),
      warning('QSCAN:incompleteConfiguration', ...
              ['search Q range not specified for ' ...
               'channel number %d'], channelNumber);
      configuration{channelNumber}.searchQRange = ...
          defaultSearchQRange;
    end
    if isempty(configuration{channelNumber}.searchMaximumEnergyLoss),
      warning('QSCAN:incompleteConfiguration', ...
              ['search maximum energy loss not specified for ' ...
               'channel number %d'], channelNumber);
      configuration{channelNumber}.searchMaximumEnergyLoss = ...
          defaultSearchMaximumEnergyLoss;
    end
    if isempty(configuration{channelNumber}.whiteNoiseFalseRate),
      warning('QSCAN:incompleteConfiguration', ...
              ['white noise false rate not specified for ' ...
               'channel number %d'], channelNumber);
      configuration{channelNumber}.searchMaximumEnergyLoss = ...
          defaultWhiteNoiseFalseRate;
    end
    if isempty(configuration{channelNumber}.searchWindowDuration),
      warning('QSCAN:incompleteConfiguration', ...
              ['search window duration not specified for ' ...
               'channel number %d'], channelNumber);
      configuration{channelNumber}.searchWindowDuration = ...
          defaultSearchWindowDuration;
    end
    if isempty(configuration{channelNumber}.plotTimeRanges),
      warning('QSCAN:incompleteConfiguration', ...
              ['plot time ranges not specified for ' ...
               'channel number %d'], channelNumber);
      configuration{channelNumber}.plotTimeRanges = ...
          defaultPlotTimeRanges;
    end
    if isempty(configuration{channelNumber}.plotFrequencyRange),
      warning('QSCAN:incompleteConfiguration', ...
              ['plot frequency range not specified for ' ...
               'channel number %d'], channelNumber);
      configuration{channelNumber}.plotFrequencyRange = ...
          defaultPlotFrequencyRange;
    end
    if isempty(configuration{channelNumber}.plotMaximumEnergyLoss),
      warning('QSCAN:incompleteConfiguration', ...
              ['plot maximum energy loss not specified for ' ...
               'channel number %d'], channelNumber);
      configuration{channelNumber}.plotMaximumEnergyLoss = ...
          defaultPlotMaximumEnergyLoss;
    end
    if isempty(configuration{channelNumber}.plotNormalizedEnergyRange),
      warning('QSCAN:incompleteConfiguration', ...
              ['plot normalized energy range not specified for ' ...
               'channel number %d'], channelNumber);
      configuration{channelNumber}.plotNormalizedEnergyRange = ...
          defaultPlotNormalizedEnergyRange;
    end
    if isempty(configuration{channelNumber}.alwaysPlotFlag),
      warning('QSCAN:incompleteConfiguration', ...
              ['always plot flag not specified for ' ...
               'channel number %d'], channelNumber);
      configuration{channelNumber}.alwaysPlotFlag = ...
          defaultAlwaysPlotFlag;
    end

    % continue to next line
    continue;

  end

  % locate field separator
  colonIndex = strfind(configurationLine, ':');

  % if field separator not located, report syntax error
  if isempty(colonIndex),
    error('syntax error processing configuration file "%s":\n%s\n', ...
          configurationFile, configurationLine);
  end

  % parse configuration line
  colonIndex = colonIndex(1);
  parameterName = configurationLine(1 : colonIndex);
  parameterValue = configurationLine((colonIndex + 1) : end);
  parameterName = fliplr(deblank(fliplr(deblank(parameterName))));
  parameterValue = fliplr(deblank(fliplr(deblank(parameterValue))));

  % assign parameters based on name
  switch parameterName
    case 'channelName:'
      configuration{channelNumber}.channelName = ...
          eval(parameterValue);
    case 'frameType:'
      configuration{channelNumber}.frameType = ...
          eval(parameterValue);
    case 'sampleFrequency:'
      configuration{channelNumber}.sampleFrequency = ...
          eval(parameterValue);
    case 'searchTimeRange:'
      configuration{channelNumber}.searchTimeRange = ...
          eval(parameterValue);
    case 'searchFrequencyRange:'
      configuration{channelNumber}.searchFrequencyRange = ...
          eval(parameterValue);
    case 'searchQRange:'
      configuration{channelNumber}.searchQRange = ...
          eval(parameterValue);
    case 'searchMaximumEnergyLoss:'
      configuration{channelNumber}.searchMaximumEnergyLoss = ...
          eval(parameterValue);
    case 'whiteNoiseFalseRate:'
      configuration{channelNumber}.whiteNoiseFalseRate = ...
          eval(parameterValue);
    case 'searchWindowDuration:'
      configuration{channelNumber}.searchWindowDuration = ...
          eval(parameterValue);
    case 'plotTimeRanges:'
      configuration{channelNumber}.plotTimeRanges = ...
          eval(parameterValue);
    case 'plotFrequencyRange:'
      configuration{channelNumber}.plotFrequencyRange = ...
          eval(parameterValue);
    case 'plotMaximumEnergyLoss:'
      configuration{channelNumber}.plotMaximumEnergyLoss = ...
          eval(parameterValue);
    case 'plotNormalizedEnergyRange:'
      configuration{channelNumber}.plotNormalizedEnergyRange = ...
          eval(parameterValue);
    case 'alwaysPlotFlag:'
      configuration{channelNumber}.alwaysPlotFlag = ...
          eval(parameterValue);
    otherwise
      error(['unknown configuration parameter ' parameterName]);
  end

% end loop over channel configuration file
end

% close configuration file
fclose(configurationFID);

% number of configured channels
numberOfChannels = length(configuration);

% number of sections
numberOfSections = length(sectionName);

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                            load frame cache file                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% report status
if debugLevel >= 0,
  fprintf(1, 'reading framecache file %s...\n', frameCacheFile);
end

% load frame file cache
frameCache = loadframecache(frameCacheFile);

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                           create output directory                            %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% report status
if debugLevel >= 0,
  fprintf(1, 'creating event directory...\n');
end

% create spectrogram directory
unix(['mkdir -p ' eventDirectory]);

% copy configuration file
unix(['cp ' configurationFile ' ' eventDirectory '/configuration.txt']);

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                        initialize text summary report                        %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% report status
if debugLevel >= 0,
  fprintf(1, 'opening text summary...\n');
end

% open text summary file
textSummaryFID = fopen([eventDirectory '/' textSummaryFile], 'w');

% write column definitions
fprintf(textSummaryFID, '# channelName\n');
fprintf(textSummaryFID, '# peakTime\n');
fprintf(textSummaryFID, '# peakFrequency\n');
fprintf(textSummaryFID, '# peakQ\n');
fprintf(textSummaryFID, '# peakSignificance\n');
fprintf(textSummaryFID, '# peakAmplitude\n');

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                        initialize xml summary report                         %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% report status
if debugLevel >= 0,
  fprintf(1, 'opening xml summary...\n');
end

% open xml summary file
xmlSummaryFID = fopen([eventDirectory '/' xmlSummaryFile], 'w');

% write channel definitions
fprintf(xmlSummaryFID, '<?xml version=''1.0'' encoding=''utf-8'' ?>\n');
fprintf(xmlSummaryFID, '<LIGO_LW>\n');
fprintf(xmlSummaryFID, '<Table Name="qscan:summary:table">\n');
fprintf(xmlSummaryFID, '<Column Name="qscan:summary:channelName" Type="lstring"/>\n');
fprintf(xmlSummaryFID, '<Column Name="qscan:summary:peakTime" Type="real_8"/>\n');
fprintf(xmlSummaryFID, '<Column Name="qscan:summary:peakFrequency" Type="real_8"/>\n');
fprintf(xmlSummaryFID, '<Column Name="qscan:summary:peakQ" Type="real_8"/>\n');
fprintf(xmlSummaryFID, '<Column Name="qscan:summary:peakSignificance" Type="real_8"/>\n');
fprintf(xmlSummaryFID, '<Column Name="qscan:summary:peakAmplitude" Type="real_8"/>\n');
fprintf(xmlSummaryFID, '<Stream Name="qscan:summary:table" Type="Local" Delimiter=",">\n');

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                       loop over configuration channels                       %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% begin loop over channel configurations
for channelNumber = 1 : numberOfChannels,

  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  %               identify statistically significant channels                  %
  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

  % extract search configuration for channel
  channelName = configuration{channelNumber}.channelName;
  frameType = configuration{channelNumber}.frameType;
  sampleFrequency = configuration{channelNumber}.sampleFrequency;
  timeRange = configuration{channelNumber}.searchTimeRange;
  frequencyRange = configuration{channelNumber}.searchFrequencyRange;
  qRange = configuration{channelNumber}.searchQRange;
  maximumEnergyLoss = configuration{channelNumber}.searchMaximumEnergyLoss;
  searchWindowDuration = configuration{channelNumber}.searchWindowDuration;
  whiteNoiseFalseRate = configuration{channelNumber}.whiteNoiseFalseRate;
  alwaysPlotFlag = configuration{channelNumber}.alwaysPlotFlag;

  % string name of channel
  if iscell(channelName),
    channelNameString = ...
        strrep(deblank(sprintf('%s ', channelName{:})), ' ', '-');
  else
    channelNameString = channelName;
  end

  % standardize channel names
  channelNameString = strrep(channelNameString, ';', ':');

  % display status
  if debugLevel >= 0,
    fprintf(1, 'processing channel %s...\n', channelNameString);
  end

  % censor channels used for "blind" injections
  if any(strcmp(channelNameString, {'H1:LSC-ETMY_EXC_DAQ', ...
                                    'H2:LSC-ETMY_EXC_DAQ', ...
                                    'L1:LSC-ETMY_EXC_DAQ'})),
    fprintf(1, '  WARNING: %s censored for "blind" injections.\n', ...
            channelNameString);
    continue
  end

  % override censor for channels used in "blind" injections
  if any(strcmp(channelNameString, {'H1:LSC-ETMY_EXC_DAQ!', ...
                                    'H2:LSC-ETMY_EXC_DAQ!', ...
                                    'L1:LSC-ETMY_EXC_DAQ!'})),
    channelName = strrep(channelName, '!', '');
    channelNameString = strrep(channelName, '!', '');
    fprintf(1, '  WARNING: overriding censor for %s.\n', ...
            channelNameString);
  end
  
  % find closest sample time to event time
  centerTime = floor(eventTime) + ...
               round((eventTime - floor(eventTime)) * ...
                     sampleFrequency) / sampleFrequency;

  % determine segment start and stop times
  startTime = centerTime - timeRange / 2;
  stopTime = centerTime + timeRange / 2;

  % generate search tiling
  if debugLevel >= 2,
    fprintf(1, '  tiling for search...\n');
  end
  highPassCutoff = [];
  lowPassCutoff = [];
  whiteningDuration = [];
  transientFactor = 2;
  tiling = qtile(timeRange, qRange, frequencyRange, sampleFrequency, ...
                 maximumEnergyLoss, highPassCutoff, lowPassCutoff, ...
                 whiteningDuration, transientFactor);

  % read data from frame file
  if debugLevel >= 2,
    fprintf(1, '  reading data...\n');
  end
  timeShifts = [];
  [rawData, rawSampleFrequency] = ...
      qreaddata(frameCache, channelName, frameType, ...
                startTime, stopTime, timeShifts, debugLevel);

  % check for read error
  if ~all(rawSampleFrequency),
    if debugLevel >= 1,
      fprintf(1, '  ERROR: cannot load frame data\n');
    end
    continue
  end

  % test multiple channels for consistency
  if length(rawData) > 1,
    if debugLevel >= 2,
      fprintf(1, '  subtracting data...\n');
    end
    rawData{1} = rawData{1} - rawData{2};
    rawData = rawData(1);
    rawSampleFrequency = rawSampleFrequency(1);
  end

  % check for all zeros
  if (min(rawData{1}) == max(rawData{1})),
    if debugLevel >= 1,
      fprintf(1, '  WARNING: channel contains no information\n');
    end
    continue
  end

  % resample data
  if debugLevel >= 2,
    fprintf(1, '  resampling data...\n');
  end
  rawData = qresample(rawData, rawSampleFrequency, sampleFrequency);

  % high pass filter and whiten data
  if debugLevel >= 2,
    fprintf(1, '  conditioning data...\n');
  end
  [rawData, highPassedData, whitenedData, calibration] = ...
      qscancondition(rawData, tiling);

  % apply q transform to search for significant events
  if debugLevel >= 2,
    fprintf(1, '  transforming data...\n');
  end
  whitenedTransform = ...
      qtransform(whitenedData, tiling, calibration, outlierFactor);

  % identify significant Q transform tiles
  if debugLevel >= 2,
    fprintf(1, '  thresholding data...\n');
  end
  thresholdReferenceTime = centerTime;
  thresholdTimeRange = 0.5 * searchWindowDuration * [-1 +1];
  thresholdFrequencyRange = [];
  thresholdQRange = [];
  whitenedSignificants = ...
      qthreshold(whitenedTransform, tiling, startTime, whiteNoiseFalseRate, ...
                 thresholdReferenceTime, thresholdTimeRange, ...
                 thresholdFrequencyRange, thresholdQRange, ...
                 maximumSignificants, [], [], [], [], channelNameString, ...
                 debugLevel);

  % if no significant events are found
  if length(whitenedSignificants{1}.time) == 0,

    % if always plot flag is set
    if alwaysPlotFlag ~= 0,

      % identify the most significant tile
      temporaryWhiteNoiseFalseRate = 1e3;
      temporaryMaximumSignificants = 1;
      temporaryDebugLevel = 0;
      whitenedSignificants = ...
          qthreshold(whitenedTransform, tiling, startTime, ...
                     temporaryWhiteNoiseFalseRate, ...
                     thresholdReferenceTime, thresholdTimeRange, ...
                     thresholdFrequencyRange, thresholdQRange, ...
                     temporaryMaximumSignificants, [], [], [], [], ...
                     channelNameString, temporaryDebugLevel);

    % otherwise
    else

      % report status and skip to the next channel
      if debugLevel >= 1,
        fprintf(1, ['  channel not significant at white noise false rate ' ...
                    '%7.1e\n'], whiteNoiseFalseRate);
      end
      fprintf(textSummaryFID, ...
              '%-30s %#019.9f %#09.3e %#09.3e %#09.3e %#09.3e\n', ...
              channelNameString, 0, 0, 0, 0, 0);
      fprintf(xmlSummaryFID, ...
              '"%s",%#019.9f,%#09.3e,%#09.3f,%#09.3e,%#09.3e,\n', ...
              channelNameString, 0, 0, 0, 0, 0);
      continue

    % end test for always plot flag
    end

  % end test for no significant events
  end

  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  %                analyze statistically significant channels                  %
  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

  % identify most significant tile
  if debugLevel >= 2,
    fprintf(1, '  getting peak properties...\n');
  end
  [ignore, mostSignificantIndex] = ...
      max(whitenedSignificants{1}.normalizedEnergy);

  % most significant tile properties
  mostSignificantTime = ...
      whitenedSignificants{1}.time(mostSignificantIndex);
  mostSignificantFrequency = ...
      whitenedSignificants{1}.frequency(mostSignificantIndex);
  mostSignificantQ = ...
      whitenedSignificants{1}.q(mostSignificantIndex);
  mostSignificantNormalizedEnergy = ...
      whitenedSignificants{1}.normalizedEnergy(mostSignificantIndex);
  mostSignificantAmplitude = ...
      whitenedSignificants{1}.amplitude(mostSignificantIndex);

  % write most significant tile properties to text summary file
  if debugLevel >= 2,
    fprintf(1, '  writing text summary...\n');
  end
  fprintf(textSummaryFID, ...
          '%-30s %#019.9f %#09.3e %#09.3e %#09.3e %#09.3e\n', ...
          channelNameString, mostSignificantTime, mostSignificantFrequency, ...
          mostSignificantQ, mostSignificantNormalizedEnergy, ...
          mostSignificantAmplitude);

  % write most significant tile properties to xml summary file
  if debugLevel >= 2,
    fprintf(1, '  writing xml summary...\n');
  end
  fprintf(xmlSummaryFID, ...
          '"%s",%#019.9f,%#09.3e,%#09.3e,%#09.3e,%#09.3e,\n', ...
          channelNameString, mostSignificantTime, mostSignificantFrequency, ...
          mostSignificantQ, mostSignificantNormalizedEnergy, ...
          mostSignificantAmplitude);

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                     end loop over configuration channels                     %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% end loop over configuration channels
end

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                          close text summary report                           %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% report status
if debugLevel >= 0,
  fprintf(1, 'closing text summary...\n');
end

% close text summary file
fclose(textSummaryFID);

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                           close xml summary report                           %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% report status
if debugLevel >= 0,
  fprintf(1, 'closing xml summary...\n');
end

% end summary table
fprintf(xmlSummaryFID, '</Stream>\n');
fprintf(xmlSummaryFID, '</Table>\n');
fprintf(xmlSummaryFID, '</LIGO_LW>\n');

% close xml summary file
fclose(xmlSummaryFID);

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                     exit                                     %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% report completion
if debugLevel >= 0,
  fprintf(1, 'finished on %s at %s\n', ...
          datestr(clock, 29), datestr(clock, 13));
end

% close all figures and quit
exit