NOTE:   NimsUtils is not in general used by TSplot, except to
support reading of NIMS data files!

Directory TSplot contains matlab functions which are used
for plotting EM time series.  There is a simple driver,
in TSplot.m.  This is a simple script that prompts the
user for a single data file name.  The file is loaded,
and a plotting window is initialized.  The TSplot script
is configured here for plotting NIMS data.  At present three
file formats are supported: *.bin files output by John Booker's
nimsread program, *.dbn files (decimated files in the same
format as the NIMS bin files, output by program decNIMS.f90,
and NIMS *.mat files produced by the SS reading program.
Matlab functions for reading these types of data files are included
in this directory.  However, the actual time series plotting
interface is completely independent of file formats.  Rather,
some data structures containing data and associated metadata have
to be initialized before (and after) calling "plotTSwin" to
set everything up for the plotting interface to work.  

In practice, this initialization and call to plotTSwin may
be done by some other program: SS and ArrayManager (and also the
"PKDSAO" interface) are examples.  Thus TSplot.m is just an
example driver.  Similar drivers could be easily implemented
for different data formats/applications (e.g., plotting data
from more than one site, or concatenating data from multiple
files from the same site.)

Some key points to note:  

The following data structures are global symbols, referenced
by callbacks for GUI objects of the plotting interface:
TSdata{},TSd{},TSw{},TSc{},TSp{}, TSfigInd()
The first five of these are cell arrays; the last is
an array of integers.  

NB: In the TSplot example there is only
one cell in all of these arrays.  This is because TSplot
is not setup to manage more than a single timeseries plot
at one time.  (If you run TSplot, and make a plotting window,
(Figure 1, say), then run it again and make another (Figure 2, say)
only the second one will actually work.  This could easily
be changed by making a more complicated driver program 
(the PKDSAO interface is an example ... not sure ArrayManager
or SS are currently configured to allow multiple plotting windows to
be active at the same time.  

The idea is the following: TSw (and TSc, TSp, but you don't
need to worry about these except to initialize as empty cell arrays)
are indexed by the figure number used for the plotting interface
(the handle of the figure object, in matlab terminology).
These contain data that are specific to the plotting window:
the current plotting ranges and scaling factors, which channels are
active, etc.  Whenever a callback is activated
that needs access to this sort of information, the current figure
window handle (iFig) is determined, and the information 
is accessed from TSw{iFig}.  The other two cell arrays (TSdata, TSd)
contain a series of mutli-channel time series (data) and the corresponding
meta data (TSd).  FigInd is used to keep track of which time
series is being plotted in window iFig: TSdata{TSfigInd(iFig)} is the data
for window iFig, and TSd{FigInd(iFig)} is the metadata (e.g., the
sampling interval dt, channel and site names for each component, etc.)

The following steps are in general required to initialize for TS plotting.
TSplot provides a simplified example.

1)  Run function plotSetup.m to create structure  plotStart.
This is used to initialize the plotting window (e.g., how
many data points are plotted in one window).

2)  Get file names and load in data files.
Note that when making the array data one could merge data from several
files (this is done in the ArrayManager interface). 
In any event all data needs to be merged into a single array
which will be stored in data{k} as a real array of size (nch,npts) where
nch is number of channels (e.g., 5 for a single MT site, 10 for
a pair of MT sites) and npts is the total number of points.  
If data from two files are loaded for plotting with different 
first data times (the usual situation) the time series should be
aligned, with any missing data for either site (in particular at
the beginning and end of the merged time series array) should be set to NaN.

3) Initialize the corresponding time series metadata TSd{k}.
There is a function setTSd.m which does much of this.
Inputs to this function are y (the data), t0 (the start
time of the first point in the array, in seconds relative to 
some "clock zero"); ch,sta (a list of channel and 
site names--e.g, Hx, ORH09, one of each for
each of the nch total data channels); and SysTF, a data structure
containing system response information (this can be a "dummy", as it
is when we read NIMS files; see the NIMS reading programs).
(There are a few things done outside of setTSd (in TSplot)
which could perhaps be moved into setTSd  ... but then all
users of TSplot (at present, SS, ArrayManager, TSplot) will need
to be modified also.)

4) Call plotTSwin. to set up the plotting window.  This function
takes TSd and plotStart as inputs, and returns the figure number
and the initialized TSw1 structure. 

5) The first segment of the the time series is then plotted 
with a call to "plotPage".  This requires setting the
portion of the full time series to plot, saving the indices
in TSw1, and a few other things.  TSw1 is then placed in
the correct cell of TSw.

All subsequent plotting works the same for all applications.
Documentation of features of the plotting window will be
done ... some day ... maybe!

To allow multiple plotting windows to be active at the same time
all that is necessary is to make sure that new loaded data sets are put
into new cells of data{} (with metadata in corresponding TSd{k}) and
similarly for TSw with regard to figure handles.  I.e., you just
have to do the bookeeping with regard to TSdata{TSfigInd(iFig)}, 
TSd{TSfigInd(iFig)}, TSw{iFIg}, TSfigInd(.), etc.