Script cal-seis  -  ~/Seismo/gcf/SCG/cal-seis

 USAGE
     cal-seis  directives [-D <yymmdd>] [options] [loop parameters ...]
 
 PURPOSE:
Analyse calibration of seismometer against SCG
 
A successful analysis arrives at a combination of a Bessel-filter and a delay that yields
a flat, near-zero phase spectrum. The anti-causal spectrum and filter coefficients
would be low/small.  

N.B.: "uncompressed" here signifies a signal's dynamics, not a file's zip status.

Observe dependence on some settings in the environment.

 
 DIRECTIVES:
          All directives must be concatenated to one string.
          You can use any unused noblank character as a delimeter.
 
   TST - show definitions: date and subdirectory, and exit
 
   D   - compile new data (for another Bessel filter parameter
         or another all-pass parameter.)
   DS  - also do anew the gcf-to-ts conversion (tedious!)
   DG  - also do anew the SCG-data.
   DGO - Skip the other data compilation steps and exit ...
         unless DSO is given after DGO , in which case processing
         continues but ... 
   DSO - ... the Bessel-filter step is skipped
         (trusting the existing data iff it's there).
 
   X   - Cross-spectrum analysis. Is included with D
         If time-shifting is applied, X suffices to
         prepare the data for plotting.
 
   Z-  - skip the stage where zacc-files are produced.
         Combine with option -z<p><q>  where p and q
         are combinations of + 0 -
 
   P   - plot. Some (+) can be executed in loops
         Specify the kind of plot:
   PP  + Phase plots
   PG  + Gain plots
   PSF + spectral factorisation (PP and PG must appear first)
   PSC + causal and anti-causal spectra and filters (PP and PG ...)
 
   Please don't combine plot directives!
 
   CP  + Collection of plots
 
   L{B|A|T}  - Loops,
         process can loop through a set of either ...
 
   LB  - Bessel filter parameters or ...
 
   LA  - Allpass complex zeros given as  radius,phase 
         where 0 < radius < 1 and phase in degrees.
         (We've given up on this for the time being;
         delays in the complex spectrum are rather more
         convenient.)
         The parameters for the loop are given after the option part
         of the call line.
         Not recommended any more!

   LT  - time-shift parameters

         N.B.: The SCG-data is independent of A and T,
         thus DS+LA would imply redundant operations.
 
 OPTIONS:
   -             - dummy option signals that this is the last one.
                   Must be used if first loop parameter starts with a `-ยด
 
   -D <yymmdd>   - the date of the data. This option must
                   be given first. An alternative is to specify
                   the subdir using
                      setenv CAL_SEIS_SUBDIR <subdir>
                   You can still, optionally, specify a different
                   date with -D <yymmdd>
 
                   generates/uses subdirectories
                   o-<yymmdd>                  for data files
                   plot-<yymmdd>/PS            for plot ps
                   ~/www/4me/seis-cal-<yymmdd> for plot png

   -wf-from <t>    t = unc[ompressed}'  runs sasm06 ... :UWF
                       and names of sp-files end in  -uc.sp
                   t = <trg>[,<wfx>]    runs sasm06 ... :trg
                       and names of sp-files end in wfx.sp
                   The general version must be consistent with
                   the targets and files in sasm06-seis-scg.ins
                   and sasm06-scg-seis.ins .
                   Default: t = WF
 
   -a <param>    - All-pass parameter given as <radius,phase>
                   Default = SKIP
 
   -b <param>    - The Bessel-filter design frequency in Hz
                   Default = 0.01745
  
   -[f]t <param> - Delay, applied on the co-spectrum in units of the
                   sampling interval.
                   Variant -ft can be used to specify a text string
                   that replaces the delay information in the file
                   names produced; a time delay will not be applied.
                   Default = SKIP (to ignore the option in LB-loops)
                   
                   Specify always with a leading + or - !

   -sg-delay <d> - Unlike -f[t], this option samples the 100 Sps seismometer
                   record at a delay of d seconds. Default is 0.
                   A non-zero delay is marked in the file names with
                   +dsd where s is the sign of d. As of yet the delay
                   cannot be applied in a loop. 
                
   -n <basic_filename>
                 - can be repeated. Used in plot. See example
                   cal-seis CP+LT ... below. 

   -z<str>       - by default, seismometer files are named zacc-*
                   Use e.g. -zvel to change to zvel-*        
 

 ENVIRONMENT:
  
   CAL_SEIS_YMD <yymmdd>  - Defines the date. A subdirectory o-yymmdd is needed
                            You are encouraged to specify the -D option and
                            to setenv CAL_SEIS_YMD

   For continued processing with a range of scripts_*) that depend on further
   environment settings, cal-seis produces a file with setenv-commands:
    o-<yymmdd>/curr.env and o-<yymmdd>/curr.env-tmp (condensed version). One of
   them needs to be sourced (after inspection and editing if required). Edited versions
   should be saved under a new name.

*) plot-acaufs plot-besselfratio plot-cepstrum plot-fitpz-disk plot-fitpz-result plot-seis-bessel-deci plot-splist-dbg plot-tsx plot-wfdelays plot-wfrms plot-wfspectra plot-xcorr-sg-s-vs-time plot-zacc-scg-scatter prep-hcoupl wf-ts wiener+fit xcorr-sg-s   


 EXAMPLES:
          
           setenv CAL_SEIS_SUBDIR 160601
           cal-seis DG+DS
to prepare new data. May fail if gcf-files are not found in directory ~/Seismo/gcf/3u93z2
 cal-seis DG+DSO -D 110911 -wf-from uncomp
     renews the SCG-data, leaves the  zacc-(cmpr)  data unchanged, and
     computes Wiener filters from the uncompressed data.

           cal-seis D+LB 0.0173 0.01745 0.0175 0.0176 0.0177
prepares a sequence of data with seis through Bessel-filters of different design frequency.
At least one Bessel filter must be given.
 
           cal-seis LT+X -b 0.0174 - -0.3 -0.2 -0.1 +0.1 +0.2 +0.3
prepares spectra for sequence of small time-shifts.

           cal-seis X -b 0.0174
           cal-seis X -b 0.0174 -t +0.0
prepares the undelayed case, second version with `+t+0.0' in the file name, however.
 
           cd ..
           vary-guralp-roots DS
           cd SCG
           cal-seis DX- -z++ -b 0.01745
 
 
           cal-seis CP+LT -b 0.0174 -n causal_filter -n antcau_filter -t ALL
prepares tmp/collect.files for plot-causal-filters . Follow up with 
           mv tmp/collect.files tmp/actual.files; edit tmp/actual.files
           plot-causal-filters -A tmp/actual.files
 
           cal-seis CP+LT -b 0.0174 -n causal_filter -n antcau_filter +0.1 +0.2 SKIP
prepares tmp/collect.files  for the specified delays and the undelayed+unmarked case too (`SKIP')
 
           cal-seis PSC -b 0.0174 -t +0.3
Plots (!) the causal-anticausal spectra for gain and phase and the filter series.
 
           cal-seis PSC -b 0.0174 -t +0.3      
           cal-seis PSF -b 0.0174 -t +0.3     
Does causality analysis and spectral factorisation
 
Example for curr.env

cat o-110909/curr.env
setenv CAL_SEIS_YMD 110909
setenv SUBDIR -110909
setenv SAS_DATE 2011,09,09
setenv YYMMDD 110909
setenv BSFFC 0.0176833
setenv MARKIN -0.0176833
setenv MARK -0.0176833
setenv MARKIN -0.0176833

 .bye
.bye