January 12, 2001
This documentation is out of date. November 2000
A command-driven DataBase handling program with extensive PLOTting
capabilities. Can be used by itself for plotting simple functions
without need for recompiling or task building (thanks to LOC_EVAL)
or with ".DB" EDTable data files of a standard but VERY free format.
The prompt of DB is (obviously) DB>
Note that data can be input "by hand" using the commands of DB or
loaded from a ".DB" file via DB>@filename.DB Whichever way
the data comes in, it has the SAME FORMAT, including commands defining
data structures, etc. Thus there is NO distinction between "manual input"
and "stored-file input". This makes it especially easy to remember the
format of the files, once you have become familiar with DB.
DB intercepts Error Traps and CTRL-C Traps.
This command has no arguments; it activates a search of
subsequent input for at most 100 80-character lines of
"Abstract", the significance of which is up to the user.
At the moment, DB uses the Abstract only for detailed
identification of the contents of ".DB" files.
The input is terminated by a (COMPLETELY) blank line.
This command has no arguments; it activates a search of
subsequent input for at most 10 80-character "Comment"
lines, the significance of which is up to the user.
At the moment, DB uses the Comment only for detailed
identification of the contents of ".DB" files.
The input is terminated by a (COMPLETELY) blank line.
NOTE: NOT IMPLIMENTED for use with PGPLOT graphics library!
This command initiates entry of a succession of ordered
triplets (one triplet to a line, separated by commas)
terminated by a completely blank line, describing a 3D
space curve to be drawn by DOPL3D. Thus
DB>CURVE
>1,1,1
>2,4,1
>3,9,1
>4,16,1
>
will cause DOPL3D to draw a roughly parabolic line of
connected points (X=1,Y=1), (X=2,Y=4), (X=3,Y=9), (X=4,Y=16)
at constant Z=1.
This command MUST have arguments, namely the Names of the
Variables to be loaded as (X,dX+,dX-), (Y,dY+,dY-), ... etc.
on subsequent lines, terminated by a (COMPLETELY) blank line.
The best way to explain this format is by example:
DB>DATA T A B
> 5,1,1.5, 10,1,2, 55.1,18,, [Remark 1]
> 7.5,2,, 18.1,5.4,2.3, 127.5,22,, [Remark 2]
> 14,2,, 21.2,7,, 337.4,45,, [Remark 3]
would load the Variable array "T" with the numbers in the first column,
storing the Value, its Positive Error and its Negative Error, and
similarly for the Variable "A" in column 2 and "B" in column 3.
Any zero Negative Errors (e.g., where you see 14,2,, above) are
automatically set equal to the Positive Error for that entry.
Each Point (row) may be identified by a Remark after all the numbers.
This command deletes a column of data.
DB>DELELTE T
Exits the program.
NOTE: Needs updating!
This command has arguments which will be prompted for
if omitted. The most general form is
DB>FIT X Y
Here we are fitting the Independent Variable named "X"
and the Dependent Variable named "A" to a form which
may be given by an Expression (MINUIT fits).
You will be queried to find out which you want. After FITting you
may draw the data points and a line through them, if desired.
It is wise to store the parameters and theoretical
formula in a macro file.
Note: eventially the fitting program will use the
covariance mentrix when MAXHES or HESMAX is present.
Not implimented yet.
DB> fit b max
MINUIT Fit? y
Point type?
DB>
MINUIT RELEASE 93.11 INITIALIZED. DIMENSIONS 100/ 50 EPSMAC= 0.44E-15
TITLE (or @Filename) > Fit to gaussian
Parameter # LABEL VALUE ERR LLIM ULIM REMARK > 1 amp 775 1.5 0.001 1000.
Parameter # LABEL VALUE ERR LLIM ULIM REMARK > 2 b0 0.0095 2.8E-7 0.007 0.011
Parameter # LABEL VALUE ERR LLIM ULIM REMARK > 3 bwid 1.3E-4 3.3E-7 1.E-9 0.005
Parameter # LABEL VALUE ERR LLIM ULIM REMARK >
For curve # 1
Enter theoretical formula for MAX
in terms of Parameters (by name) and B
>max = amp*exp(-0.5*(b-b0)*(b-b0)/(bwid*bwid))
...
Want to PLOT? n
Enter i to Modify P(i) >
New P [, dP, Pmin, Pmax] > 780
Enter i to Modify P(i) >
New Theory?
Replot? y
Plot Diff between Theory & Data?
Default range [Min,Max,Npts] =0.0070023, 0.011975, 99
Enter range [Min,Max,Npts] of B
for plot:
DOPLOT>
Enter i to Modify P(i) >
...
MINUIT> migr
MINUIT> exit
Want to PLOT?
Finished Plotting? y
Write results to a MINUIT input file? y
Enter file name > gaus3.ixy
DB>
DB> FRACERR INVAR OUTVAR
Calculates the fractional error of the
data column invar and places the result in
in a new data column outvar.
One may Generate a new Data Variable (Column) from the
values of all the existing Variables (Columns) with this
command. Any LOC_EVALuatable expression referring to the
other Variables by their Names is allowed. DB does
the best it can (without calculating partial derivatives
analytically) to generate Errors for the new Variable
that include the Errors of the old Variables; but the
result is necessarily symmetrical (Positive Error =
Negative Error) and crude. User beware!
The muSR Maxium Entropy program MaxErr saves its output P(b)
in a DB file *.mdb, which has an extra DB command MaxHes (or HesMax),
which contains information about the hessian matrix, from which the
covariance matrix can be re-constructed. The covariance matrix
may be used in place of the independent errors, when fitting
(NOT IMPLIMENTED YET).
The formats for MaxHes and HesMax differ slightly.
It contains the entropy S(b) and grad grad chi^2 with respect to
the field b.
Use IMPORT to copy over the entropy and/or grad grad chi^2
to the DATA array, so you can plot.
The command allows the vectors which are read by by HESMAX and MAXHES
(referred to as ENTROPY and GGCHI2) to be copied over to a new column of
data. Then you can plot it, or manipulate it as you wish.
DB> IMPORT ENTROPY
DB> IMPORT GGCHI2
The muSR Maxium Entropy program MaxErr saves its output P(b)
in a DB file *.mdb, which has an extra DB command MaxHes (or HesMax),
which contains information about the hessian matrix, from which the
covariance matrix can be re-constructed. The covariance matrix
may be used in place of the independent errors, when fitting
(NOT IMPLIMENTED YET).
The formats for MaxHes and HesMax differ slightly.
It contains the entropy S(b) and grad grad chi^2 with respect to
the field b.
Use IMPORT to copy over the entropy and/or grad grad chi^2
to the DATA array, so you can plot.
This command can be used with or without arguments.
With no arguments, it activates a search of subsequent
input for at most nineteen Labels of 80 characters or less
describing the meanings of the corresponding variables
in the DATA array (which see). DB automatically
uses these Labels in any PLOTs of the data (which see).
The input is terminated by a (COMPLETELY) blank line.
With one of the existing DATA Variable Names as an argument,
this command can be used to modify an existing label
(namely, the one for that Variable). E.g.,
DB>LABEL T
>Temperature [K] gives the new Label "Temperature [K]" to
the existing Variable "T".
This command initiates entry of a succession of ordered pairs
(one pair to a line, separated by commas) terminated by a
completely blank line, describing a 2D curve to be drawn
by DOPLOT. Thus
DB>LINE
>1,1
>2,4
>3,9
>4,16
>
will cause DOPLOT to draw a roughly parabolic line of
connected points (1,1), (2,4), (3,9), (4,16).
One may Modify any Column of the Data array. For example,
DB>MODIFY FREQ
...(remarks by DB)...
>FREQ = FREQ/(2*PI)
will convert frequencies in radians/sec into Hz.
One may also take square roots, logs, invert, etc....
Restore DB database contents from a binary file (for whose name
you will be asked) previously generated by the SAVE command
(which see).
One form of Modification which is special enough to have
its own separate command is Normalization, the meaning
of which should be obvious.
Not implimented.
This command has arguments which will be prompted for if omitted.
The most general form is
DB>PLOT T A [B] [IF Expression(s)]
Point type? [expression2]
Here we are plotting Data Points with the Variable named "T"
on the X axis, "A" on the Y axis, and [if specified] "B" on the
Z axis. Note that the choice of 2-D or 3-D plot is determined
by context alone. All error bars are drawn automatically.
Note that no distinction is made between "dependent" and
"independent" variables in the Data Points.
NOTE: 3D plots are NOT IMPLIMENTED for use with
PGPLOT graphics library!
The "IF Expression(s)" option allows one to display only
that subset of the Points for which up to 4 "Expressions"
are separately and individually satisfied; an Expression
may contain an "==" sign, in which case the left and right
sides must be equal to satisfy the condition, or not, in
which case the expression must be GREATER THAN ZERO following
evaluation by LOC_EVAL. Each "Expression" can refer to
the current value (for this Point) of any of the Variables
by Variable Name, but can be no more than 32 characters long
and MUST NOT CONTAIN ANY EMBEDDED BLANKS! (Blanks are used
as delimiters between Expressions.)
See the ASK help, for more information about Expressions,
Functions, and Operators.
Plotting all the points, but with different symbols,
is also possible using the choise of point type.
See also PointType
If a number is entered, then a symbol corresponding to the number
is plotted. If a variable or an expression is entered, the point type
(a.k.a. symbol) is then calculated for each point.
See DOPLOT help for documentation on the symbols (and color) available.
Point type? (carriage return)
Defaults to type 0, squares.
Point type? 2
Circles
Point type? 637
Hershey symbol lambda.
Point type? (1*(t.lt.30) + 2*(t.ge.30))
Circles if t < 30 and triangles if t >= 30
(Note: This can be done another way using PLOT [x] [y] IF [expression].)
DB>PLOT T A will plot A(T) for all available Points.
DB>PLOT A B IF T==15 will plot B(A) for all Points having T=15.
DB>PLOT A B IF 10-T will plot B(A) for all Points having T<10.
DB>PLOT T A B IF 20-T T-10 will plot (T,A,B) Points in 3-D
for all Points having 10<T<20.
DB>PLOT T A IF 20-T T-10 B==1 will plot (T,A) Points in
2-D for all Points having
10<T<20 and B=1.
The current contents stored by the program (Title, Labels,
Comment, Abstract and Data) can be written out to a new
file in a reasonably aesthetic format for line-printer style printer.
Exits the program.
Variables, once entered, may be RENAMEd for aesthetic or
mnemonic reasons. E.g.,
DB>RENAME T TEMP
renames the variable "T" to "TEMP".
This command causes the current contents of the DB database
to be saved in a binary file (for whose name you will be asked).
The results can be restored later by the LOAD command (which see).
The only advantage over WRITE (which see) is that it is slightly
more compact for databases containing more numbers than text.
The disadvantage is that you can't alter the result with any
normal text editor. (I suppose this might appeal to paranoids.)
One often forgets just what Data etc. have been loaded.
This command allows one to recall without reloading or
plotting unnecessarily. One can SHOW the following:
TITLE ABSTRACT COMMENTS LABELS DATA
Of these, only DATA needs further explanation.
For practical and aesthetic reasons one may only
SHOW one Column of Data at a time; if the command
line does not say which, e.g.,
DB>SHOW DATA T
then you will be prompted to tell which Variable (Column)
you want to see.
Not implimented.
The current contents stored by the program (Title, Labels,
Comment, Abstract and Data) can be written out to a new
spreadsheet-ready file (suggest ".SPR") in a reasonably aesthetic format.
The title is included, and the variable's names.
Columns labled "ep" and "em" indicate the high and low errors, for
each variable. Unfortunately, only three columns fit across,
so the contents of the data are written in batches of three.
This command has arguments, the first of which will be
prompted for if omitted. The most general form is
DB>STAT X [N] [Xmin] [Xmax]
which gives the UNWEIGHTED Min, Max, Sum, Avg and StdDev
of variable "X" and asks if you want a Histogram of the
frequency spectrum from Xmin to Xmax broken into N bins.
If you don't want a plot, the optional arguments are
unnecessary and will be ignored; if you omit them but
ask for a plot anyway, DB will use my judgement in
choosing aesthetic binning.
BUG report: STATS crashes DB if you try to bin the results.
This command allows one to load theoretical curves to be plotted,
either superimposed on the data or independently. I.e., if
any Data has already been loaded for plotting (see PLOT)
but has not yet been plotted (see blank_line), the Theory curve
will go onto the same plot; if the plot buffer is empty, the
Theory curve will be plotted by itself (if no Data is loaded
after the Theory and before plotting).
For Theory curves, the variable names are the conventional names
of the coordinate axes, namely "X", "Y" and "Z". One must first
specify which is the independent and which the dependent variable.
The choices are
Y(X) Z(X) X(Y) Z(Y) X(Z) Y(Z)
Note that if either variable is "Z" then you imply a 3-D plot. Then
you must specify TWO algorithms, one for each dependent variable as a
function of the independent variable. This will define a SPACE CURVE
in three dimensions. This is loads of fun but hard to visualize
satisfactorily.
NOTE: 3D plots are NOT IMPLIMENTED for use with
PGPLOT graphics library!
You will be prompted to enter an algorithm for (e.g.) Y(X);
this character string must be interpreted by LOC_EVAL
(as in $CALC) which will have the current value of the
independent variable (in this example, "X") defined when it
tries to evaluate the answer for (in this case) "Y". You may
use any global constants (e.g., "PI") that you have assigned,
but you are restricted to the function names that LOC_EVAL will
accept. We hope this repertoire will grow with time. For example,
> Y = EXP(-SQRT(X))*COS(2*PI*X) should be OK.
If there is Data to be plotted on the same graph, the Data Labels
and Title will override the Theory; if not, then the expression
entered will also be used as a Title for the plot.
This command has no arguments; it merely signals that the
following input line contains a Title of at most 80 characters
identifying the contents of the ".DB" file. This Title
will automatically be displayed on any plots generated from
the associated data.
Not implimented.
The current contents stored by the program (Title, Labels,
Comment, Abstract and Data) can be written out to a new
".DB" file in a reasonably aesthetic format for long-term
storage. This may or may not be the best way to create
such ".DB" files in the first place.
This command deletes any Data arrays presently loaded.
Both the commands and the variable names can be abbreviated
to as little as a single letter. This may sometimes lead to
ambiguities, about which DB will NOT complain; instead, it
will just take the FIRST on its list (of commands or variables)
-- which may not be the one you wanted! So it is advisable
to use long enough abbreviations (2-3 characters are often
enough) to resolve such ambiguities.
A blank line (COMPLETELY blank) is used to terminate
an ABSTRACT, a COMMENT, a LABELS list or a DATA list.
When you plot Data via the PLOT command or a Theory curve
via the THEORY command, the results are not plotted
immediately; you may wish to add more Points, curves,
etc. The actual plotting (with DOPLOT and DOPLOT_3D)
is done when you enter a blank line to the DB> prompt.
Anywhere that DB wants a NUMBER as input, you may substitute
an EXPRESSION, including named variables and/or any of the
functions defined in LOC_EVAL. This is because all DB I/O
goes through the ASK subroutine, about which you can get
more information by the command
DB>\h
anytime DB is waiting for your instructions.
TITLE ABSTRACT COMMENTS LABELS ZERO DATA PLOT QUIT EXIT QUIT
MAXHES HESMAX MODIFY GENERATE DELETE SHOW LINE CURVE RENAME STATS SPREAD
FIT THEORY LINE CURVE IMPORT
SAVE LOAD WRITE PRINT
SAVE LOAD
STATs crashes DB if you try to bin the results.
CURVE SORT PACK WEED
Variable Names can be no more than 8 characters long
and must be acceptable as variable names in LOC_EVAL
(as in $CALC).
There can be (at the moment) no more than 19 Variables (columns).
The product of the number of Variables (columns) with the number
of Points (rows) cannot exceed 9000 without recompiling DB.
This document was generated using the LaTeX2HTML translator Version 99.2beta6 (1.42)
Copyright © 1993, 1994, 1995, 1996,
Nikos Drakos,
Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999,
Ross Moore,
Mathematics Department, Macquarie University, Sydney.
The command line arguments were:
latex2html -split 0 -show_section_numbers dbonly.tex
The translation was initiated by Dr TM Riseman on 2001-01-12