DOCUMENTATION

SYNOPSIS

PERL PROGRAM NAME:  SUWIND - window traces by key word					
AUTHOR: Juan Lorenzo (Perl module only)
DATE:  Nov 1 2012  
DESCRIPTION: suwind a lists of header words
or an single value

Version:  0.0.3

SEISMIC UNIX NOTES

 SUWIND - window traces by key word					

  suwind <stdin >stdout [options]					

 Required Parameters:							
  none 								

 Optional Parameters:							
 verbose=0		=1 for verbose					
 key=tracl		Key header word to window on (see segy.h)	
 min=LONG_MIN		min value of key header word to pass		
 max=LONG_MAX		max value of key header word to pass		

 abs=0			=1 to take absolute value of key header word	
 j=1			Pass every j-th trace ...			
 s=0			... based at s  (if ((key - s)%j) == 0)		
 skip=0		skip the initial N traces                       
 count=ULONG_MAX	... up to count traces				
 reject=none		Skip traces with specified key values		
 accept=none		Pass traces with specified key values(see notes)
			processing, but do no window the data		
 ordered=0		=1 if traces sorted in increasing keyword value 
			=-1  if traces are sorted in a decreasing order 

 Options for vertical windowing (time gating):				
 dt=tr.dt (from header) time sampling interval (sec)	(seismic data)	
 			 =tr.d1  (nonseismic)				
 f1=tr.delrt (from header) first sample		(seismic data)	
 			 =tr.f1  (nonseismic)				

 tmin=0.0		min time to pass				
 tmax=(from header)	max time to pass				
 itmin=0		min time sample to pass				
 itmax=(from header)   max time sample to pass				
 nt=itmax-itmin+1	number of time samples to pass			

 Notes:								
 On large data sets, the count parameter should be set if		
 possible.  Otherwise, every trace in the data set will be		
 examined.  However, the count parameter overrides the accept		
 parameter, so you can't specify count if you want true		
 unconditional acceptance.						

 The skip= option allows the user to skip over traces, which helps	
 for selecting traces far from the beginning of the dataset.		
 Caveat: skip only works with disk input.                        	

 The ordered= option will speed up the process if the data are   	
 sorted in according to the key.                                 	

 The accept option is a bit strange--it does NOT mean accept ONLY	
 the traces on the accept list!  It means accept these traces,   	
 even if they would otherwise be rejected (except as noted in the	
 previous paragraph).  To implement accept-only, you can use the 	
 max=0 option (rejecting everything).  For example, to accept    	
 only the tracl values 4, 5 and 6:					
	... | suwind max=0 accept=4,5,6 | ...		   		

 Another example is the case of suppressing nonseismic traces in 	
 a seismic data set. By the SEGY standard header field trace id, 	
 trid=1 designates traces as being seismic traces. Other traces, 	
 such as calibration traces may be designated by another value.  	

 Example:  trid=1 seismic and trid=0 is nonseismic. To reject    	
       nonseismic traces						
       ... | suwind key=trid reject=0 | ...				

 On most 32 bit machines, LONG_MIN, LONG_MAX and ULONG_MAX are   	
 about -2E9,+2E9 and 4E9, they are defined in limits.h.		

 Selecting times beyond the maximum in the data induces		
 zero padding (up to SU_NFLTS).					

 The time gating here is to the nearest neighboring sample or    	
 time value. Gating to the exact temporal value requires	 	
 resampling if the selected times fall between samples on the    	
 trace. Use suresamp to perform the time gating in this case.    	

 It doesn't really make sense to specify both itmin and tmin,		
 but specifying itmin takes precedence over specifying tmin.		
 Similarly, itmax takes precedence over tmax and tmax over nt.		
 If dt in header is not set, then dt is mandatory			


 Credits:
	SEP: Einar Kjartansson
	CWP: Shuki Ronen, Jack Cohen, Chris Liner
	Warnemuende: Toralf Foerster
	CENPET: Werner M. Heigl (modified to include well log data)

 Trace header fields accessed: ns, dt, delrt, keyword
 Trace header fields modified: ns, delrt, ntr
 
 =head2 USE

NOTES

Example: If skip is used, s is ignored e.g. s=2 skip=1 key=tracl j=2

Example:

accept=4,9,11 max=0 (max=0 is needed)

Example: where in data, tracl=1,2,3, etc.

j=3 key=tracl,s=0, tracl's are 3, 6, 9 etc., j=2 key=tracl s=0, tracl's are 2, 4, 6 etc. j=2 key=tracl s=1, tracl's are 1, 3, 5,7 j=2 key=tracl s=2, tracl's are 2, 4, 6,8 etc.,

New list option:

Include a file name conatining a single-column list of numbers which represent trace header values. Make sure to set the header as well.

CHANGES and their DATES

V 0.0.3 May 2023 Include a file name conatining a single-column list of numbers which represent trace header values. Make sure to set the header as well.

sub Step

collects switches and assembles bash instructions by adding the program name

sub note

collects switches and assembles bash instructions by adding the program name

sub clear

sub abs

sub accept

sub accept_only_list: when selecting multiple traces
    all at once.
    Should be used with list, setheaderword.

sub accept_only_tracl

when selecting multiple traces
all at once
use a list

sub count

sub dt

sub f1

sub itmax

sub itmin

sub j

sub key

set which header word to use as the x-coordinate for plotting

sub list

input a list of trace numbers as a referenced array

Example 1: $value[0] = 2; suwind->list(\@value); suwind->setheaderword('tracf'); $suwind[1] = suwind->Step();

sub max

sub min

sub nt

sub ordered

sub reject

sub setheaderword