BE) Details concerning the DESL
learn command.Determines the coefficients and possibly the most important terms contained in up to 100 polynomials for a set of data contained on up to 100 SIF files. The resulting polynomials can be written to an equation file for future use. Each polynomial is a least-squares solution to the complete data set. The maximum number of data points considered per polynomial is a function of the number of polynomial terms specified. A measure of how well the polynomial actually fit the original data can be reported. The degree to which the determined polynomials will predict values of dependent variables is a function of how "complete" the sets of independent variables used in the polynomials are. Two measures of the "confidence" levels of the matches can be reported.
Any names enclosed in brackets are required or are in a set of options, one of which must be specified. Any non-blinking names enclosed in brackets are optional or are in a set of options, only one of which can be specified.
In cases where the option name is one of a set each different set number is indicated by a red numeric set number superscript trailing the respectiveright bracket :
BEaltvars)
(Command :learn) Details for the altvars option. BEbackward)
(Command :learn) Details for the backward option. BEconfidence)
(Command :learn) Details for the confidence option.
The confidence interval is defined as a band about an estimated mean value (the least squares fit) within which there is an "xx" percent confidence that the true mean value will be found. The "xx" percent confidence is referred to as the confidence level. The resulting "dci" parameter, which will be added to each SIF file produced if "newfiles" or "newfilex" is also specified, is an increment, to be interpreted as a positive and negative increment about the computed value of the dependent variable.
The prediction interval is defined as a band about an estimated mean value (least squares fit) within which there is an "xx" percent chance that the next measured data point be found. The resulting "dpi" parameter, which will be added to each SIF file produced if "newfiles" or "newfilex" is also specified, is an increment, to be interpreted as a positive and negative increment about the computed value of the dependent variable.
The confidence percent values specified must lie between 68.268 (1 sigma) and 99.994 (4 sigma). Specification of a confidence percent value outside of this range will force the use of 95 percent.
Example : confidence 95 dci1 dpi1
BEcset)
(Command :learn) Details for the cset option.
The item immediately following "cset" is the file sequence number in the "files" list for which the following up-to-20 conditions will be applicable.
Each file-specific 3-item condition, like its global 3-item condition counterpart, is made up of (1) a SIF variable name, (2) a 2-character logical conjunction, and (3) a second SIF variable name or a constant.
Example : cset 3 alpha gt phi mach lt 1.2
Here, the user has indicated that, along with whatever
other GLOBAL conditions may have been specified, the
pertinent DESL function, for the THIRD file specified
or implied by the "files" list, will have its application
ALSO limited to records which satisfy BOTH of the two
conditions :
All file-specific conditions are implicitly joined by
an "and" conjunction; ie, by default, all file-specific
conditions would have to be true SIMULTANEOUSLY for
the applicable record to be retained.
If one or more file-specific conditions following
the file sequence number is to be connected to other
file-specific conditions for the same file number by
an "or" conjunction, then the 2-character item "or"
must immediately follow the file number.
Example : cset 2 or alpha lt 0 alpha gt 4
Here, the user has indicated that, along with whatever
other GLOBAL conditions may have been specified, the
pertinent DESL function, for the SECOND file specified
or implied by the "files" list, will have its application
ALSO limited to records in which the value of the SIF
variable "alpha" satisfies at least ONE of the conditions :
Additionally, if the file number following the "cset"
option is negative, the absolute value of this negative
file number is used for the actual file number and the
associated "and" or "or" condition(s) are NOT used in the
traditional sense of filtering the records read but
are ONLY used to indicate when READING of the associated
file is to STOP. This ability is useful in preventing
the reading of a long file when it is known that the
data required is relatively near the beginning of the
file.
Example : cset -1 or run eq 3 alpha gt 24
Here, the user has indicated that when a record is
encountered for which either or both of the two conditions
is/are TRUE, reading of the current SIF file should end.
BEeqfile)
(Command :learn) Details for the eqfile option.Example : eqfile eq1
BEeqtol)
(Command :learn) Details for the eqtol option.Example : eqtol .5
BEfiles)
(Command :learn) Details for the files option.An example of this type of file name specification is the following :
t43r{runs}.sif
Here, the list "runs" will have its elements used, in turn, in place of the {runs} substring.
| . |
(Begin modifications on 052102)
Each file name, whether it includes the {...} or not,
can be a maximum of 256 characters long.
If a file name is more than 16 characters long it
must be enclosed in question marks (?) .
(End modifications on 052102) |
Up to 100 file names can be specified.
Example : files run10 run11 run12
BEneglect)
(Command :learn) Details for the neglect option.Example : neglect
BEnewfiles)
(Command :learn) Details for the newfiles option.There is an understood 1:1 correspondence between files in the "files" list and files in the "newfiles" list. A new file name prefixed with the 4-character string "null" can be used as a place holder in the "newfiles" file names list. This type of name is converted to a blank string before it is used; ie, using a "null" prefixed name is equivalent to having not specified that name at all. By default, all files explicitly named via this "newfiles" list will be flagged as a file "to be RETAINED at cleanup. (See the "cleanup" command.) The default file name generated for a new file not explicitly named via "newfiles" or "newfilex" is the 3-character string "gen" followed by a unique numeric suffix. Up to 100 new files can be specified.
The list of the names of the new files actually produced can be saved via the use of the ">list"- or ">>list"- type argument, which can appear among the specified new file names. If a ">list"- or ">>list"-type argument is specified, where "list" is the specified file name list, the names of the new files which DESL actually produces during the execution of the current command will be saved in the specified file name list.
This file name list can later be referenced by the "files"/"xfiles" options to imply the file names contained therein. Up to 100 new file names can be saved in any one list. If the ">list" argument is specified the named list will be created if it does not already exist, or will overwrite a like-named list if one exists. If the ">>list" argument is specified the named list will be appended to if it exists or will be created if it does not exist. All file name lists are in existence for the current DESL session only. Each "list" name can be up to 15 characters long.
In all but a few noted cases, it is acceptable to use the ">list" or ">>list"-type argument without specifying a full complement of actual new file names. Any new file produced whose NAME is GENERATED by DESL is ALWAYS marked as a file to "PURGE at cleanup".
A suffix which may be in effect as established via the filesuffix DESL command will be added to any expressed or implied new file name. New file names can also include the {...} construct. This type specification within a file name implies that the list name given between the curly brackets ( {} ), is to be used to have each of its elements substituted in turn for the { ... }, inclusively, such that an implicit lengthening of the new file list is accomplished, up to the maximum number of new files allowed. Any time such a {...} usage occurs, all lists mentioned must exist; i.e., must have been previously defined in the current DESL session. Only one {...} construct can be included in a new file name. Including more than one such construct will result in unpredictable results.
An example of this type of new file name specification is the following :
t43r{runs}.sif
Here, the list "runs" will have its elements used, in turn, in place of the {runs} substring.
| . |
(Begin modifications on 052102)
Each new file name, whether it includes the {...} or
not can be a maximum of 256 characters long.
If a newfile name is more than 16 characters long
it must be enclosed in question marks (?).
(End modifications on 052102) |
Example : newfiles nf1 nf2 >nflist21
BEnewfilex)
(Command :learn) Details for the newfilex option.Example : newfilex newr1 thru newr4 newr201
BEnewterms)
(Command :learn) Details for the newterms option.Example : "alphasqd = alpha^2". The left-hand side is an up-to 8-character temporary variable name to be defined by the phrase. The right-hand side is an up to 32-character string which MUST contain either (a) a single-variable operator (such as "sin", "cos") and its argument, or (b) an argument, an arithmetic operator, and another argument. An example of the type of string described in (a) above is : "sin(angle)". An example of the type of string described in (b) above is : "alpha*beta".
The set of single-variable operators is the following :
abs ..........absolute value acos .........arc cosine, result in radians aint .........integral part of number anint ........rounded value of number asin .........arc sine, result in radians atan .........arc tangent, result in radians cos ..........cosine, argument in radians cosh .........hyperbolic cosine, argument in radians exp ..........exponential (e to the ...) log ..........natural log log10 ........log to base 10 sin ..........sine, argument in radians sinh .........hyperbolic sine, argument in radians sqrt .........square root tan ..........tangent, argument in radians tanh .........hyperbolic tangent, argument in radians sind .........sin, argument in degrees cosd .........cosine, argument in degrees tand .........tangent, argument in degrees asind ........arc sine, result in degrees acosd ........arc cosine, result in degrees atand ........arc tangent, result in degrees
An example of the type of string described in (b) above is "cd*cl". The set of operator symbols which can be used in type (b) strings is the following :
^ ...........exponentiation; 2^3 = 8 * ...........multiplication / ...........division + ...........addition - ...........subtraction
New terms thus defined can be used in any or all of the polynomials to be determined. Up to 200 new terms can be defined. The string on the right-hand side should contain no blanks.
If "newfiles" or "newfilex" is also specified, the left-hand side (LHS) of each renaming phrase (see above) is added to the SIF file being created unless the string "local" follows immediately after "newterms". All of the new terms which are contained in a "newterms" argument list, in which "local" follows the option, are, themselves, termed "local" and will therefore NOT be written to the SIF file(s) produced. Following another occurrence of "newterms", if "local" is NOT present, the new terms so defined are NOT local; ie, they WILL be written to the SIF file(s) produced.
Example : newterms local beta2 = beta*beta
BEnobias)
(Command :learn) Details for the nobias option. BEnoop)
(Command :learn) Details for the noop option. BEoutput)
(Command :learn) Details for the output option.Example : output outeq
BEpathfile)
(Command :learn) Details for the pathfile option.
An example of such a file is the following :
* * Example path file for test xxx * * item 1 = path to be translated : MUST * match VERBATIM with name given * specified/implied via "paths" * * item 2 = resulting name translation * data56 ? \usr\home2\ people\test56\ ? up ?..\? way-up ? ..\..\..\ Temp46\?
Example : pathfile pathA
BEpaths)
(Command :learn) Details for the paths option.Example : paths ..\ ..\Main\ sub1\
BEpolyterms)
(Command :learn) Details for the polyterms option.
... polyterms cl alpha beta mach ...
Another example of a "polyterms" argument list is
given below. Here, the bracket construct is used to
imply that more than one polynomial argument list -
more than one polynomial - will be defined, each one
being associated with a different dependent variable
but the SAME set of independent variables.
Either the square brackets OR the curly braces can be
used to contain the set of dependent variables being
defined. If the "learn" command is used within a
macro then the curly braces MUST be used because
the macro itself uses the square brackets as delimiters
for optional macro arguments.
If "newfiles" or "newfilex" has also been specified
the dependent variables to be defined can have their
names changed. If no name change is specified, the
calculated dependent variable values will overstore
the existing dependent variable values in each of the
respective files being processed. If a dependent
variable is renamed, it is considered a new SIF
variable and is added to each of the SIF records being
processed. Dependent variables can be renamed by the
specification of a left-hand side (LHS) when specifying
the dependent variable name(s). An example follows :
Here, each new file produced will contain the computed
dependent variable "newcl" as well as the original
dependent variable "cl". Similar renaming constructs
can be specified for the bracketed multi-polynomial
definitions :
In the first of these examples two newly-named computed
dependent variables, "newcl" and "newcd", will be added
to each SIF record processed. In the second of these
examples the shorthand for the renaming of a series
of SIF variables has been utilized. The computed
dependent SIF variables "cp1", "cp2", "cp3", ... will be
renamed "newcp1", "newcp2", "newcp3", ..., respectively.
The third example accomplishes exactly the same result
as the second; the implied series of names is, however,
now on the right-hand side.
Up to 100 polynomials can be specified.
The number of data points which will be considered in
the determination of the coefficients of a given
polynomial is a function of the number of polynomial
terms specified. The maximum number of data points
which will be considered is (25000/Nterms), where
"Nterms" is the number of polynomial terms + 1.
ALL of the independent variables in ALL of the
polynomials specified should exist in ALL of the
SIF files specified or should be defined in a "newterms"
argument list. If one or more of the independent
variables does NOT exist in either of these two
locations for a particular SIF file, then this SIF file
is skipped in the current "learn" execution; ie,
its data will NOT be considered when determining
the polynomial coefficients.
Example : ... polyterms cl alpha beta mach ...
... polyterms [ newcp1 = cp1 thru cp20 ] alpha config ...
... polyterms [ newcp1 thru newcp20 = cp1 ] alpha config ...
BEprefix)
(Command :learn) Details for the prefix option.Example : prefix P1 P2
BEreport)
(Command :learn) Details for the report option.The "dci" and "dpi" parameters are the "confidence interval" and the "prediction interval" as described in the "confidence" option discussion.
Example : report 1
BEsetvoid)
(Command :learn) Details for the setvoid option.Example : setvoid 880
BEtags)
(Command :learn) Details for the tags option.Example : tags run alpha
BEvfile)
(Command :learn) Details for the vfile option.
The structure of a valid void file must adhere to the following rules :
name/value logical name/value
where, "name/value" represents either a SIF name OR a constant value, and "logical" represents one of the allowable 9 1- or 2-character logical operators : eq, =, lt. <, le, ge, gt, >, or ne. An illegally formed condition will cause the line containing it to be skipped and cause a message to be issued to this effect.
Before the void file is used, by specifying "vfile" rather than "vfilen", and if the DESL session is purely interactive, the user will have the opportunity to edit the void file.
An EXAMPLE of a void file is the following :The procedural sequence of (1) voiding, then (2) accounting for frequency via "dfreq", and then (3) averaging is always maintained.* * a comment line * * assign "ple" and "re" abbreviations * abbr ple ?point le? re ?run =? run=10 point ge 101 point le 120 re 10 point ge 153 ple 156 un32 * * deassign "ple" abbreviation * abbr ple null re 12 point ge 101 point le 120 * *
An EXAMPLE of a "keep" file is the following :
* * a comment line * keep * * assign "ple" and "re" abbreviations * abbr ple ?point le? re ?run =? run=10 point ge 101 ple 120 re 12 point ge 101 point le 120 * *
Example : vfile void1
BEvfilen)
(Command :learn) Details for the vfilen option.Example : vfilen void1
DESL Manager at ViGYAN, Inc.
30 Research Drive
Hampton, VA 23666
Voice: (757) 865-1400
Toll Free: (800) 288-3998
FAX: (757) 865-8177
