ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng)/ProfitPress-MegaCDROM2.B6I/MISC/MATH/DELPX02.ZIP/NVMANUAL.DOC

Text File | 1991-10-23 | 27.5 KB | 566 lines

***********************************************************************
*                                                                     *
*              *      *   *        ******  *           *              *
*              *      *   *        *        *    *    *               *
*               *    *    *        ***       *   *   *                *
*                *  *     *        *          * * * *                 *
*                 **      *        ******      *   *                  *
*                                                                     *
***********************************************************************


                       A data analysis suite,
          incorporating the exponential fitting routine DELP.

    DELP algorithm due to Dr J Martin, Dept Physics, Kings College, Strand,
LONDON WC2R 2LS,  and implemented by DJ Maconochie, Washington University
BOX 8054, 660 S Euclid, St Louis MO 63110 (to whom correspondence may be
initially addressed.
E-mail [e-mail]

   Feel free to use this program, but please reference
Martin and Maconochie (1989) J Physiol 418:9P7 in any publications that
contain data analysed using DELP.


                            INTRODUCTION

  1) This software comes free,  with no guarantees.  Feel free to distribute
it in its entirety, with all the associated files.
____________________________________________________________________________

  2) System requirements:

a)  Processor- Any IBM PC or compatible should be able to run this program,
but note that it is designed to operate on large data sets,  and on a 8086
machine will run painfully slowly.

b)  Maths co-processor- By default,  the code is compiled for use with a
maths co-processor.  There is no reason for this except that I have always
had one,  and without one the program will be excruciatingly slow.  For
exmaple,  filtering the data digitally might take 4 seconds on a 33 MHz 486
machine,  and 20 minutes on a 286 machine without a co-processor.

c)  Screen-  The suite was written with standard 16 colour VGA in mind.  It
will run on any screen,  but some of the boxes and colours in the menu tree
will be difficult to decipher, especially with mono- screens.

d)  Printer-  Hard copy was available originally on a dot matrix printer.
Most dot matrix printers should give something resembling a screen dump.
Fancy plots are supported on HP II and HP III.  You are however limited to
the landscape fonts available (for example the HP II only has "line printer"
and "courier").

e)  Data-  The most important part.  Any file is acceptable that contains a
(optional) header string,   followed by a string of 2-byte integers.  The
following extensions are reserved,  and cause the program to try to read
a particular type of header from the start of the file: ".SVG", ".OLV",
".CX4" and "CX5".
____________________________________________________________________________

  3) Brief overview:

The program runs entirely in graphics mode.  There is a central menu root,
from which branches extent vertically in levels.  <Return> and <Esc> move
up and down the levels.  Items may be selected in one of four ways:

a) items in the root may be selected from anywhere in the program by
typeing <Alt> plus the first letter.

b) from any other level by typing the first letter.

c) by moving the highlighted bar using the arrow keys,  pressing <Return>.

d) By taking one of a number of shortcuts such as <Alt>+"R" to run DELP,
<Alt>+"L" to load a file,  <Alt>+"X" to leave the program and <Alt>+"G"
to get the data display screen.  The shortcuts are indicated to the right
of the item in the menu tree.

    4) Getting started quickly:

It is assumed that
a) you have some data in a file called "filename.dat" or some equivalent.
b) the data is a string of 2 byte integers.
c) that you wish to fit a sum of exponentials to the data

i) from the DOS prompt, type "VIEWMENU" <Return>.  If you are connected to
a laser printer,  and you want hardcopy,  then type "VIEW" <Return>.
ii) type <Return> twice.  After the first,  you enter the File menu.  After
the second,  you invoke the last data file that was used.  The filename may
be edited.   Then press <Return> again.

ii) hold the <Alt> key and press "G" (ie type <Alt>+"G").  You are now in the
display mode.

iii) press the <Home> key.  This has the effect of displaying the data on
screen at minimum magnification.  If the trace is an inconvenient size, then
read the following section to find out how to change the size of the diplayed
trace:  section Graph-Display-  below.

iv) press <Return>.  Now you should see two cursors on screen.   Position them
around the section of data to be fitted,  using <Ctrl> and the arrow keys.
Press <Esc> when you are finished.

v) type <Alt>+"D".   You are now in the fitting menu for DELP.  Type "i" and
enter the number of exponentials to be fitted (Integration level).  Type "p"
and enter the polynomial degree to be used.  Ten is usually sufficient,  but
experiment with more or less.

vi) If next to "Baseline" the word "SET" appears, then press "B".  In this
mode the baseline or offset in your data is calculated.

vii) now press "R" to begin the fit.  First a red line overlays the data.
This is a curve calculated from the polynomial coefficients used to represent
the data.   Next the complete fit is drawn in yellow,  and a box with the
caluculated coefficients appears.  Each coefficient appears as a complex
number,  for example "-0.5067 + 0.003j".  If a pair of coefficients is
complex,  then the data has been fitted with an oscillatory component (ie
not a simple decaying exponential).

viii) type <Alt>+"G" to return to the display mode,  or <Alt>+"X" to exit
the program.
___________________________________________________________________________

    5)  In the following sections,  the functions available after
selecting the indicate item are given.
___________________________________________________________________________

                           FILE MENU

  File-Load-   re-load the last file you used by pressing <Return>,
or select a new one by typing the full path and name.   When you load a file
successfully,  if the file does not have a recognised header that gives the
digitisation frequeny etc,  you will be asked "retain scale values? N".  If
you answer "Y" (deleting the "N" first),  the last values used will be
retained,  otherwise default values will be set.

  File-Pick-   pick one of the last six that you used.

  File-Change dir- type in a new directory to  begin a search.

  File-Directory-  first add a file name template such as "*.*" or
"*.dat".  To begin the search,  type <Return>.  A box with a list of file
names should appear.  Directory names will be pre-fixed with "\".  The
symbol "\.." in the top left corner indicates a route back towards the
root directory or drive.  If in doubt,  exit by typing <Esc>, and giving the
template "*.*", work your way out from the current directory (where the
program is, usually "C:\VIEW").  The operation of this item can be a little
confusing.  Also note that I have experienced difficulty with networked
drives.

  File-Quit-  Exit the program,  saving to disk all the parameters that have
been altered,  so that  when you restart the program everything is exactly
as you left it.
____________________________________________________________________________

                     GRAPH MENU

  Graph-Display-  from here,  a special set of functions are available
for manipulating the data on screen,  Briefly these are:
a) move the trace: arrows, and <Ctrl>+arrows.
b) resize it: arrows, <insert>, <delete>, <pageUp>, <pagedown>, <home>.
c) next sweep: <spacebar>, previous sweep <Tab>,  jump by "j" followed
by number of sweeps by which to jump.
d) create a window in the display: "w",  resize it with arrows and <Ctrl>
+arrows, <return> to fix it.
e) select a section of the data on screen: <Return> followed by arrows
and <Ctrl>+arrows to move the cursor,  <Return> to toggle between the
"start" cursor and the "end" cursor, and <Esc> to exit this sub-routine.
f) clear the screen and re-draw the trace "c".
g) toggle between either displaying all the points or drawing lines
between a reduced number of points, "p".
h) toggle between a display with scale lines across the whole screen, or
just at the edges, "s".  Note that you may have to follow with "c" to
clear the screen to see the effect of turning the scale lines off.
i) add the current trace to the average buffer, "+".
j) invert the current trace, "-".
k) exchange the "average/fitting" buffer for the "data" buffer, "x".
l) <Alt>+"z" to clear the average buffer.
m) to rotate the trace in the current buffer, "<",  ">", and <shift>+
"<" or ">".  This is used for example to align events in a data sample
before adding to the average buffer.
n) to reset the current trace to an un-rotated state, "z".  To reset all
the traces, <shift>+"z" (ie "Z").  Note that the state of rotation of the
first 100 sweeps is retained even after exiting the program,  and may cause
confusion unless "Z" is used.
o) to temporarily disble the screen while still changing the data around
press "u" once.  Pressing "u" a second time restores the screen.
g) the command "g" adds a 20x14 grid to the screen (useful for making up
a complex picture to print).
r) rotate the trace automatically,  using the rectangular event located
between the points where you last left the data selection cursors.  This
complex function is not recommended for most purposes.

summary:
C : clear display
G : add grid
J : jump to another sweep
P : toggle points/lines
R : rotate current trace
S : toggle scale lines across the whole screen
U : toggle update screen ON/OFF
W : create window in display
X : exchange data buffer and average buffer
z : zero rotation on current trace
Z : zero rotation on all traces
+ : add current trace to buffer (or the buffer that is not current)
- : invert the trace
<Alt>+Z : zero the buffer
<spacebar>     : next trace
<Tab>          : previous trace
<Insert>/<Delete : trace up/down
<Home>           : default size
<PageUp>/<PageDown> : enlarge, diminish X scale
arrows/<Ctrl>+arrows : move trace around screen

  Graph-StartFit1..EndPlot-  Set manually the cursors for selecting the
part of the data to fit,  and to display on screen.

  Graph-Sweep number-  Type in the number of the sweep to display on screen
and to fit.

                         GRAPH-AVERAGE MENU

  Graph-Average-Clear buffer-  Reset the average buffer.

  Graph-Average-File name-  This is the name of the file to which the average
buffer will be saved when using "Append" or "Overwrite"

  Graph-Average-Overwrite file-  The contents of the average buffer is written
together with the current header (if any) to the file  given,  replacing any
file of the same name that exists.

  Graph-Average-Append file-  The contents of the average buffer is added to
the end of the file given above.

  Graph-Average-Tag to data file-  The contents of the average buffer is added
to the end of the data file.

  Graph-Average-"+" list-  Type in a sequence of integers, punctuated with
commas.  On pressing "Run",  these sweeps of data wil be averaged.

  Graph-Average-"-" list  Type in the sweeps (punctuated with commas) that
should be subtracted from the average.  On pressing "Run",  these sweeps will
be inverted and then averaged along with the sweeps in the "+" list.

  Graph-Average-Run-  Make an average of all the sweeps in the "+" and "-"
lists.

  Graph-Average-Set thresholds-  Automatically rotate all the sweeps in the
current file, using a rectangular event presumed to be located between
"startFit1" and "endFit1".

  Graph-Average-With filtering-  The automatic rotation sequence will begin
by filtering the section of data between "startFit1" and "endFit1" using the
parameters in the "Filter" menu.

  Graph-Average-Buffer size-  The automatic rotation function works by taking
the Fourier transform of the data,  looking for a pattern in the relative
phase of the first "Buffer size" Fourier components.   The more closely the
signal event in the data corresponds to a rectangular event,   then the
larger the "Buffer size" can be.  In general a larger "Buffer size" will give
a more accurate result.  Somewhere between 2 and 6 is suitable.
___________________________________________________________________________

                          COPY MENU

  Copy-Dot matrix dump-  This puts out a pixel-by-pixel plot of the current
screen display.  It works on a Epsom LX-80 and LQ-800.  It should work with
others as well,  but you may have to fiddle with Dip switches.

  Copy-Laser menu-  High resolution output (every point between startPlot
and endPlot is printed) is available on a laser printer,  with some control
over the final format.  Landscape mode only at the moment is available,
but if the current display is a window in the top left corner of the screen
for example, then the plotted output will also appear in the top left corner.

                        COPY-LASER MENU

  Copy-Laser menu-Plot style- This function toggles between plotting individual
points, or drawing lines (continuous or dashed) between the points.

  Copy-Laser menu-Dot size- Whatever symbol is selected, printed in a size
ranging from 1 (almost invisible) to 16 (about 4 mm across).

  Copy-Laser menu-Symbol-  Toggle between a range of  symbols.  Not all are
currently availble.

  Copy-Laser menu-Laser plot-  When this function is selected,  the current data
sweep as displayed on screen is output to the printer.  At the same time a scale
bar may also be printed, along with some information such as the location of the
cursors marking the fitted region,  the file name and sweep number,  and the
results of the last DELP fit.

  Copy-Laser menu-Bar scale-  Toggle On/Off;  when On a scale bar will be
printed along with the data.

  Copy-Laser menu-Text start point-  All text printed out,  the file name,  the
fit results etc will be printed out started from the "Text start point".  A
target will appear on screen on selecting this function.  It may be moved using
the arrow keys.  Press <Return> to fix the position and return to the menu.

  Copy-Laser menu-Write over-  When this function is selected,  a window
appears on screen showing the last message that was entered here.  It may be
edited.  On pressing <Return>, the message will be written immediatly to the
printer,  and also to the screen in roughly the comparable position.

  Copy-Laser menu-Eject page-  This function sends to the printer the signal
to dump out a sheet.

  Copy-Laser menu-Fitted output-  This toggles On/Off.  When "On",  the
results of the last DELP fit will be sent to the printer when the next data
trace is printed using "Laser plot".  It will appear below the point set by
"Text start point".

  Copy-Laser menu-Change font-  Some control over the fonts used in printing
is available from this menu.  The selected fonts differ in the laser output
only,  not on the screen.

  Copy-Laser menu-Number of copies-  Select how many copies of the completed
output to be dumped on selecting "Eject page".

  Copy-Laser menu-Indicate fit window- Toggles On/Off.  When "On",  vertical
dashed lines appear in the printer output corresponding to the region of data
used in the fitting procedures.

  Copy-Laser menu-Reset plot default-  All the parameters in the Laser menu
will be returned to default values.

                       COPY-LASER MENU-CHANGE FONT MENU

  Copy-Laser menu-Change font-scale bar size-   An integer value given here
will select the size of the text associated with the scale bar.  Note that
this must correspond to the size of a font available on the printer.

  Copy-Laser menu-Change font-scale bar font-  Toggle between the various
fonts supported (those found on a standard HP II and HP III printer).

  Copy-Laser menu-Change font-scale bar weight-  If this available on your
printer, then you can select various weights of text to be used with the
scale bar.

  Copy-Laser menu-text size, font, weight-  These relate to all other text
output to the printer:  the fitted output,  the text entered in "Write over"
and the file information printed automatically.

  Copy-Laser menu-Reset default-  These fonts are reset to those that work
with a HP II printer.
______________________________________________________________________________

                            DELP MENU

  DELP-Int.Level  DELP is an alogorithm for obtaining a very fast fit of
a sum of exponentials.  It works on the principle that a sum of exponentials
is a solution of a linear homogeneous differential equation with constant
coefficients.  The integral form of the equation is used.  "Int.level" is the
degree of the integral equation,  and so is equal to the number of exponentials
being fitted.   The maximum here is 8,  minimum 1.

  DELP-Poly.degree  As an intermediate step,  the data is first represented
by a finite Legendre polynomial series.  This has the twin benefits of reducing
the data set to a manageable size,  and of filtering the data.  The maximum is
50 (but oscillation may occur if there are less than 4x50 data points),  the
minimum is 2x(Int.level+1). If you need more than a 20 component series to
adequately describe the data,  then it is likely that the underlying
exponentials are not closely spaced (there is a factor of ten or more between
their rate constants),  and so the components may be fitted separately by
selecting the section of trace to fit.

  DELP-Run fit   Start the DELP fitting procedure.

  DELP-Baseline  The baseline may be calulated autoematically ("Baseline AUTO"),
or an estimate may be made in advance ("Basline SET"). Use this function to
toggle between the two.
What comes out of the "least squares" fit of an integral
equation to the data,  are the exponential rate constants (inverse time
constants).  If the baseline is unknown,  then one coefficient of the
polynomial series has to be discarded.  If the baseline is known,  then
a more accurate estimate of the rate constants may be made.  On selecting
"Baseline SET",  a line and a box should appear on screen.  If they do not,
then press "Z" to zero the baseline.  The horizontal cursor may be moved up
and down using the arrow keys.  Note that the steps widen with frequent key
strokes.  Press <Return> when you have positioned the cursor to your
satisfaction.
Note that the exponential amplitudes and offset are calculated as a second
and separate procedure,  so if the calculated baseline differs by more than
1 % from your estimate,  then  this suggests that the original estimate
was incorrect.

  DELP-Split run  There is the option of running the fit simultaneously on
two separate sections of data.  This is useful for example if there is a
glitch in the middle of an otherwise good trace.  It is advisable to avoid
this function where possible.

  DELP-Append  Write the results of the last fit as an ASCII string,  to
the end of the ASCII output file.

  DELP-Overwrite  Replace the contents of the output file with the results of
the last fit.

  DELP-Delp file name   The name of the text file to which the results of the
last fit will be written.

  DELP-Clear  Clear the screen.

  DELP-Skip points   There is the option to decimate the data.  This may be
useful if you have 32,000  data points to be fitted  (the maximum allowed),
and you have only a 8086 processor running at 4 MHz!  Note that entering
10 here means that only every tenth point is used in the fit,  so if there
is a large component of random noise,  then filter the data first.

  DELP-With pathname  This toggles On/Off.  When it is "ON", then the path
and filename,  sweep, file time and estimated baseline written to the output
file,  along with the results of the last fit.
_____________________________________________________________________________

                              PATTERN SEARCH (PtnSch)

  This is an iterative (read VERY SLOW) procedure to find a set of
coefficients that in this application finds a pattern that leads to a reduction
in the "sum of squares",  and repeats it or changes it to improve the rate
of convergence.
  This fitting procedure is not recommended for fitting exponentials for a
number of reasons.  Quite apart from the fact that it frequently converges
to false minima close to the true minimum,  it is time consuming to set up
and painfully slow compared to DELP.
  Its advantages are that any function (in general, although not here) may
be fitted,  and any variable may be selectively tweaked or held constant.

1) Select the required equation,  and make a note of the number of variables.
2) Go to the Parameter menu.
3) Enter the number of variables.
4) Set the "maximum number of iterations to 100"
5) Set "skip points" to the maximum indicated
6) Enter your first guess at the parameters in the left column only.  The
other two columns will be updated automatically.
7) Leave the Paramter menu <Esc>.
8) Use the function Keep to preserve the values you have just typed.  (You
can restore them with Reset values.)
9) Use the function Search to begin the search for a solution.  This is just
a trial run to see if your estimates are anywhere near.  The screen is only
updated every tenth time that an improved fit is found (hence the maximum
iterations needs to be quite high).
10) If the fit is converging,  then go back to the Parameter menu and increase
the number of iterations,  and decrease the number of points to skip.

  For the meaning of Append,  Overwite and Clear,  see DELP MENU
_____________________________________________________________________________

                         TRANSFORM MENU

  Transform-Re-Scale-   This function is useful if your data does not have
a recognisable header,  and so the digitisation frequency,  number of
point,  gain etc are set to default.

  Transform-Filter-  Digital implementation of analogue filter characteristics
is available for filtering a single sweep or part of a sweep.  Note that this
menu can be reached by <Alt>+"Q".

  Transform-FFT-,  Transform-Histogram-  These are not written yet.

                        TRANSFORM-RE-SCALE MENU

  Transform-Re-scale-Full scale Y-  This should be the value of your measured
variable (eg voltage) at the full range of a 16-bit ADC.  For example, suppose
you have a 16 bit ADC,  with a +/- 10 V input range,  then you should enter
"Full scale Y" as "10".  Many ADC's are only 12 bit,  moreover some devices
write to the highest 12 bits of a 16 bit integer (as read by the computer)
an example is the CED 1401,  and others (AXON) write to the lowest 12 bits.
The latter case becomes apparent when you data appears in the "display" mode
to be very small.  In this case,  the input range (10 V) should be multiplied
by 2 to the power 4, ie 16,  so the correct number to type for "Full scale Y"
would be "160".

  Transform-Re-scale-Zero scale Y-  Suppose that the input signal to the ADC
was offset by  1 V (ie you added 1 V DC to the input signal) then the value
you should type for "Zero scale Y" is "-1".  Alternatively,  suppose that
your ADC input range is zero to 10 V,  then  "Zero scale Y" will be "5",  and
"Full scale Y" will be "10".

  Transform-Re-scale-Dig. freq.-  The digitisation frequency  should be
entered here in Herz.   For example 1 kHz should be entered as "1000".

  Transform-Re-scale-Points per sweep-  If your data consists of a string of
repeated traces,  each of the same length,  then you can give the length of
a single trace or sweep as the number of data points.

  Transform-Re-scale-Time zero/ End of trace-  "Time zero" is the time you
wish to use to refer to the beginning of a trace.  "End of trace"  is the time
for the end of the trace.   If you enter these two times,  then "Points per
sweep"  will be re-adjusted automatically.

  Transform-Re-scale-Header size-  If your data has a header,  ie a string of
bytes that refer to the digitisation frequency, the number of sweeps etc,
that cannot be read by this program,  and you do not wish the header bytes to
be displayed as data points,  then you can give the size of the header here
in words (a word is two bytes).

  Transform-Re-scale-Y scale label-   The label out on the scale bar,  is
either the label read from the header file,  or a default label.  This is an
option to change it to something else.


                       TRANSFORM-FILTER MENU

  Transform-Filter-Filter data-  This function starts the filtering of the
current buffer or data sweep.  The filter function is first generated using
the last parameters selected.  The number of points filtered is the "Points
per sweep" (see above Re-scale menu).

  Transform-Filter-Type of filter-  There is a choice of digital
approximations to common analogue filters.  The choice depends on your parti-
cular requirements.  If minimum phase shift is required,  then use the Bessel
filter,   if maximum attenuation above the roll-off frequency is required
then use the  Tchebyshev filter.

  Transform-Filter-Poles-  The number of poles determines for a given filter
type how steep is the attenuation above the roll-off frequency.  The more poles
then the steeper the attenuation,  but also the longer it takes to filter the
data.

  Transform-Filter-Roll off -3dB-  The frequency at which the signal will be
attenuated by 3 decibels should be given here.

  Transform-Filter-Local filter-  Sometimes you may want to see the result of
filtering just the part of a data sweep that you have displayed rather than the
whole sweep.  This function does that.
_______________________________________________________________________________

                             MACRO MENU

  Macro-Go-   Start running a macro.  Characters are read from the current
macro file  whose file name is the last one to be entered as "Macro file name".
These characters are then interpreted as keystrokes.

  Macro-Macro file name-  Enter the name of the file that you wish to record to
or run.

  Macro-Record-  This function toggles "ON/OFF".  When you turn this function
on,   each subsequent key stroke is written to the file given by "Macro file
name",  starting at the beginning of the file.  To stop recording a macro, then
use this function again, ie toggle it "OFF".

  Macro-Delete-  At some point in the future,  a version of this program  may
have further options that make deleting a file before recording to it necessary.

NB Editing a macro file using a text editor.  Ideally you should use a text
editor that allows you to enter any character from #0 to #255.  Note that for
example the keystroke <Right Arrow> generate two charcters, a null character
(#0) plus another character ('M').  For convenience,  the character '^' is
interpreted to mean the null character (#0),  so instead of using the null
character followed by a capital 'M' to mean <Right Arrow>,  the symbols ^M
may be used instead.




a)  To start the program,  type "VIEWMENU" (the name of the program),  or
"VIEW" (the name of the batch file that loads and unloads some soft fonts
to a HP laser printer).

b)  Suppose you have just started the program.  You will see the root menu
File, Graph, Copy, Delp, PtnSch etc. across the top of the screen.  If you
do not, then you probably have an  incompatible screen.  You should see
"File"  highlighted.  Press <Return>,  to go down a level in the menu
(<Esc> takes you back up).
   Now you should see the "File" menu diplayed vertically