U.S. Geological Survey       National Strong-Motion Program

Software Change History for BAP and Related AGRAM Programs


This documentation describes the changes from version 1.0 to version 1.1 of the National Strong-Motion Program's Basic Strong-Motion Accelerogram Processing (BAP) computer program and related AGRAM computer programs.  A text version of this documentation can be obtained here (whatsnew.txt).   This documentation was last updated on November 16, 1999.   Questions regarding the BAP or the AGRAM computer programs should be directed to:
Kent Fogleman:   (650) 329-4745, fogleman@usgs.gov
or
Chris Stephens:  (650) 329-4752, cdstephens@usgs.gov

U.S. Geological Survey, MS 977
345 Middlefield Road
Menlo Park, CA 94025
 

Table of Contents

  1.0  Changes from BAP version 1.0 to version 1.1

     1.1  BAP version 1.1 files available via NMSP WWW and FTP sites.

     1.2  Upgraded SMC-format and online documentation

     1.3  New programs

     1.4  Removed programs

     1.5  New examples and documentation

     1.6  BAP changes

                Input/output files

                 Modified processing steps

                 Better top-of-plot titles

                 New run parameters

     1.7  Warnings

     1.8  Bug fixes

     1.9  New programming conventions

  2.0  About the Response Spectra calculating subroutine


1.0  Changes From BAP Version 1.0 to Version 1.1

1.1  BAP  Version 1.1 Files Available via NSMP WWW and FTP Sites.

The same files that are provided on the PC/BAP distribution diskettes are also available via the NSMP WWW site at the URL: "/processing.html" and the NSMP anonymous FTP  server "https://ca.water.usgs.gov/nsmp" in the directory at "/software/bap/4pc/".

Back to Top of Page


1.2  Upgraded SMC-format:

The SMC-format used for data has evolved somewhat.  The main changes are:

  • First line indicates the type of data in the file.
  • Time series can be unevenly sampled.
  • File can contain response spectra values rather than time-series values.
  • The comments section of the file can contain plot label information.   The plot labels are used in BAP output plots, but they are not yet used by the TSPLOT program (because TSPLOT cannot read SMC files yet).

BAP can still read the version 1 SMC-format files.

The latest version of the SMC documentation is available via the NSMP WWW site at the URL:"/smcfmt.html" and via the NSMP anonymous FTP server "https://ca.water.usgs.gov/nsmp" in the directory at "/software/bap/docs/".

Back to Top of Page


1.3  New Programs

  • V2S will translate a "volume 1" or "volume 2" time series data file  from CalTech, CSMIP, USC, USGS, Kinemetrics, etc. into one or more SMC-format time series files.   For more information, just type V2S at the DOS command line.
  • SMCHDR allows the user to insert header information into SMC-format data files in situations where it would be cumbersome to make the changes with a text editor.  For brief information, just type SMCHDR at the DOS command line.  For a complete user's guide, refer to the first set of comment lines in the file at \agram\exes\smchdr.prl.
  • PERL16 and PERL32 are now redistributed along with the BAP/AGRAM software.  They are used to implement the SMCHDR program, but they might be useful for user-written script files too.  For more info about these versions of PERL and about PERL in general, refer to the file at \agram\docs\perlinfo.txt.
  • BOOT.BAT was renamed to REBOOT.BAT and it flushes the smartdrv cache if c:\windows\smartdrv.exe is on the PC.  (Users on PCs using different caching technique may want to change or comment out that line in REBOOT.BAT.)

Back to Top of Page


1.4  Removed Programs

  • LOWBAP  (This took more space on the distribution diskettes than it was worth.)
  • SFAS, PFAS  (the FASPLT program doesn't offer much more than the Fourier amplitude plots from BAP do, and these two .EXE files took more space on the distribution diskettes than they were worth.  The Fortran code for the FASPLT program is still distributed, however, in the \agram\gats\ood\ directory (gats= gathered source files; ood= out-of-date).  The more important things FASPLT offered over BAP's FAS step were the ability to:
        = generate plots of spectral ratios from two inpu time series,
        = learn user-specified axes ranges and whether each axis should be log or linear,
        = generate plots of the Fourier phase spectra as well as amplitude spectra.  Integrated or differentiated
            amplitude spectra too.)
  • WHATMEM  (this program was provided with the Ergo DOS-extendingsoftware used with BAP version 1.0.  BAP version 1.1 uses a different DOS-extender (PharLap) so the Ergo WHATMEM command is no longer provided with BAP.
  • HELP   (this was a do-nothing command among the BAP .exes/.bats in the version 1.0 distribution files.  All it ever did was get in the way of the DOS help command.)

Back to Top of Page


1.5  New Examples and Documentation

  • \agram\examples\rdbbf.for = example of how to read a BBF file.
  • The following documentation files (all in \agram\docs) are new:
         WHATS.NEW    (=this file),
         PERLINFO.TXT (info about the Perl interpreters include among the BAP distribution files).
  • The following documentation files (all in \agram\docs) have been updated: 
        SMCFMT.DOC   (completely rewritten), 
        BBFFMT.DOC  (minor changes),
        BAPINFO.TXT   (how to get the software via FTP, ++),
        ALTBOOTS.NTS (BOOT.BAT was renamed to REBOOT.BAT, ++),
        PROGBAP.NTS   (new call tree diagram, ++).

Back to Top of Page


1.6  BAP Changes

=    BAP can read the expanded-format SMC time-series files as well as the older SMC-format files.  BAP output time-series files are now in the newer format.  The output response spectra files are by default consistent with the new SMC format too.  The older, BAP-version-1.0, response spectra format can be requested via the new RSFMT run parameter.  Fourier amplitude output file format has not changed.
 
=    SMC-format output time-series files will by default include the leading and trailing pads.  In BAP version 1.0, only the BBF output files contained the pads.  User can request that no pads be output with the time series via the new PADSOUT run parameter.
 
=    The extension on the response spectra output file name has changed from '.TXT', as it was in BAP version 1.0, to '.RS1' or '.RS2', depending on which response spectra output format was requested.  Note that we are using '.RS2' rather than '.SMC' even though the new response spectra format is included in the new SMC file-format specification.  BAP reserves the '.SMC' file extension for time series files so users can distiguish between time-series files and response spectra files just by noting the file name.
 
=    The extension on the Fourier amplitude output file name has changed also, to be consistent with the response spectra naming convention.  The extension has changed from '.TXT' to '.FS1'.  The format of the file has not changed.
 
=    BAP version 1.0 truncated comments it transfered from an input to an output SMC file at 40 lines.  BAP version 1.1 will transfer any number of SMC comments from the input to the SMC-format output files.
 
=    BAP will now transfer SMC text header values and SMC comments to an output BBF-format file and vice-versa.   The comments will be truncated to whatever will fit into BAP's in-memory character working area.  (There's room for about 1000 characters there, more or less, depending on other character info stored there, like input/output file names.)
=    RESPONse spectra:
The default period list for use in response spectra calculations now begins at .04 rather than at the .05 used in BAP version 1.0.  The addition makes the new list the same as that used in the older PHASE3 program.  The line drawn on the plot when CLIPRS=OFF moved from 10/sps, as it was in BAP version 1.0, to 8/sps.
 
=    DECIMate:
BAP version 1.0 reduced the sampling rate in this step by removing the 2 samples between every 3rd sample (or removing the NDENSE-1 samples between every NDENSE-th sample).  We found that we needed to reduce the sampling rate of the time-series output from the new USGS digitizer from 500 to 200, however, and to do so we need to interpolate rather than discard points.  So a new run parameter was added: SPSLAST.  When SPSLAST is given and it is not evenly divisable into the undecimated sampling rate, the new DECIMation step will interpolate rather than discard samples.
 
=    INTERPolate:
The interpolation step was modified so its resulting time series will always contain a sample at time=0.0.  BAP version 1.0 always began interpolating with the first sample given in the input time series.  The first sample in an input time series would normally be at time= 0.0 except in the unusual situation where one wished to pass a padded BAP output time series to a second BAP run in which the time series was reinterpolated (not recommended!).  When the input file was padded, the version 1.0 interpolating algorithm could end up with a time series with samples that bracket 0.0 rather than with a sample right at 0.0.  This became a problem when we used the same interpolating subroutine in the new DECIMate step as we use in the INTERPolate step.
 
=    LINear CORrection: 
A new "skew" option was added to the LINCOR step via the new TSKEW, YO, and SLOPE parameters.  This option may be used in an attempt to eliminate the transients that result if the time series is so distorted that the values near the beginning and/or end are significantly different than zero, even after the mean has been removed.  An example would be a time series with a bow-shaped distortion.  Padding such a time series with zeros produces step changes at the beginning and/or end; filtering will produce transients associated with these steps.
Version 1.1 BAP will get top-of-plot labeling lines from the new PLTLBL run parameter (see below) and/or from the input SMC-format time-series file.
 
Top-of-plot labels are given in the comments section of SMC-format data files.   They are indicated by a leading   "<pltlbl=>"  or "<loclbl=>" and a trailing "<end>".  (Note that  the <pltlbl=>, <loclbl=> and <end> must all be in lower case.)     Both types of top-of-plot label can be more than one line long.  Some sample comment lines that include top-of-plot labels:
 
| This time series was digitized at the USGS on 12dec97
|   by Sam Spade.  
|   <pltlbl=> blah blah blah  
|              any number of lines here
|              ending with:   <end>  
|   <loclbl=> roof, north-west corner <end>
| More general comments here.
 
The <pltlbl=> top-of-plot label is usually just one line that indicates the address or name of the recording station, if sufficient station identification would not fit on line 6  (colums 11-40).  The <loclbl=> label gives information about the location of the recording transducer.  It is usually quite short, and in the case of tri-axial recordings it is usually absent because all three transducers are in the same location.   The <loclbl=> information is provided separately from <pltlbl=> info so the info unique to each transducer is separate from the info several transducers share. (Makes construction the plot labels more convenient for the TSPLOT program.)  
=    input/output parameters = PADSOUT, RSFMT, FASFMT
  PADSOUT = ON or OFF to indicated whether or not the output time-series files should include the leading and trailing pads.  By default, PADSOUT=ON.  (In BAP version 1, the user had no control over whether or not the pads were written to the output files, other than in deciding which type of output file to request.  Pads were written to output BBF files, but were *not* written to output SMC files.)
   
  RSFMT = 'RS1' or 'RS2' to indicate which of the two available formats the response spectra output file should be in.  The RS1 format is that which was used for output response spectra files in BAP version1;  the RS2 format is that specified for SMC-stlyle response spectra files in the \agram\docs\smcfmt.doc file.   By default, RSFMT=RS2.
    
  FASFMT = 'FS1'.  There is only one format available for the Fourier amplitude output files so far, so this parameter doesn't make much sense.  It was introduced for consistency with the RSFMT parameter and to allow us to add alternative formats in the future.
   
=    plot parameters = PLTLBL, PLTTOP, PLTTYPE, PLTDPI
PLTLBL = top-of-plot label lines.   Example:
                  pltlbl = "blah blah blah"; "another line"; "third line"
   
PLTTOP = location for the top of the plot frame, given as a fraction of the page height.  BAP version 1.1 will by default place the top of the plot frame just below all the top-of-plot label lines.  But if one wanted to compare plots generated in different BAP runs having different numbers of top-of-plot lines, one should specify the same PLTTOP value for each run.  And if one wanted to compare a BAP version 1.1 plot  to a corresponding plot from BAP version 1.0,  PLTTOP=0.85 should be used.
   
PLTTYPE = type of plot indicator.  *** this isn't used yet, but allowable values will be something like: aps, meta, 8ps, ... to indicate which plotting medium should be used. *** 
   
PLTDPI = resolution to be used in postscript plots, given as dots per inch.  *** isn't used yet. ***
   
=    DECIMation parameters = SPSLAST
SPSLAST = the target sampling rate for the decimation step when we really want to interpolate rather than remove NDENSE -1 samples between every NDENSE-th sample.
   
=    LINear CORrection parameters = TSKEW, Y0, SLOPE
 
TSKEW  = one to four numbers that indicate how BAP should determine a trend line to be removed from the time series.  "TSKEW=0.0" is the most commonly-used version of this option; in this case, the line determined by the first and last points of the time series is subtracted from the time series.  By default, TSKEW=* (meaning do not use the TSKEW option.)
   
The first two TSKEW values indicate a time interval at the beginning of the time series, the second two values indicate a time interval at the end of the time series.  If the user provides these in the run parameters list, BAP will determine the trend line as the line passing through the following two points:
  1. the FIRST zero-crossing of the time series with the mean value of the time series between TSKEW(1) and TSKEW(2) seconds, and
  2. the LAST zero-crossing of the time series with the mean value of the time series between TSKEW(3) and TSKEW(4) seconds.
   
Or, if MLLSQF=ON, the two points will be deterimined from the first or last zero-crossings of the time series with the linear least squares fit (rather than the mean) of the time series in the two intervals specified in TSKEW.
   
If just one number is indicated for TSKEW, it represents the time interval to be used at both ends of the time series.  If that one number is 0.0, then  the trend line will be determined from the two end-points of the time series.  If two numbers are indicated, they represent the time interval to be used at the beginning of the time series and the end of the time series, respectively.  If four numbers are given, the  first two indicate the times that bracket the first interval and the second two indicate the times that bracket the second interval.
   
Warning: one should probably use the ZCROSS padding option when using the skew option.  Fortunately, ZCROSS is the default.
Y0  = y-intercept of a line to be subtracted from the time series.  The slope of the line is indicated in the parameter named SLOPE.  (The YO parameter was named VLINE in version 1.0 BAP.  Either name may be used.)
SLOPE  = slope of a line to be subtracted from the time series.  The y-intercept of the line is indicated in the parameter named Y0.
Only one linear correction option will be performed even if more than one is requested.  TSKEW takes precedence over MLLSF=ON, which takes precedence over MMEAN=ON, which takes precedence over Y0 & SLOPE (and over VLINE, which is a synonym for Y0).
By default, TSKEW=* (=undefined), MLLSQF=OFF, MMEAN=OFF, Y0=0.0, and SLOPE=0.0;  this is equivalent to NOlincor.

Back to Top of Page


1.7  Warnings

The 32-bit programs (BAP, HDRSET, & Perl32) run in extended memory with the help of "DOS-extending" software.  Attempts to run these programs can hang one's computer (it will just sit there doing nothing, even in response to control-C) when the computer is configured to use the same extended memory for another purpose (like a RAM disk).  Refer to the file at \agram\docs\atboots.doc for information about setting up alternative configurations.

Back to Top of Page


1.8  Bug Fixes and Trivia

Back to Top of Page


1.9  New Programming Conventions

The following changes affect the information given in the "Programming" appendix in the BAP version 1.0 users manual.

Back to Top of Page


2.0  About the Response Spectra Calculating Subroutine

April Converse was under the impression, when she wrote the BAP user's manual and when she added the comments to subroutine CMPMAX.FOR, that the author of CMPMAX, I.M. Idriss, had written it according to the technique presented by Nigam and Jennings in a 1969 paper published in BSSA.  Not true!  Dr. Idriss developed his essentially identical technique independently of Nigam and Jennings, and at about the same time.


Back to Top of Page
Back to NSMP Home Page