A Useful Example Of Using XED

Let's say there is some interesting class of event that I wish to tag by hand, like a flasher. (There are, of course, much better ways to do this than hand-viewing, but this kind of first-pass analysis is a very good way to get a feel for your data.) You wish to get a list of all these events in a given zdab file, or perhaps make a zdab containing only those events.

First, create an empty DARN cache with some bank number, say 100, and save it as darn_100.dat in your cache directory:

*LOG
*---  Titles File: darn_100.dat     19991209
*---                 Banks: DARN
*LOG OFF
*DO   DARN        100 -i(30I -I) -n100            #.  DAMN/DARN: Event Mask.
#.
#.    My custom DARN bank for tagging flashers
#.
#.       Standard Database Header
#.
19750101        0 20380517 03331900  #.  1..4   Intrinsic validity
       0        0        0           #.  5..7   Data type, Task type, Format no.
19991209 15540000        0           #.  8..10  Creation Date, Time, Source Id.
19750101        0 20380517 03331900  #. 11..14  Effective validity
       0        0                    #. 15..16  Entry Date Time
4*0                                  #. 17..20  Spare
10*0                                 #. 21..30  Temporary data (not in database)
#.
#.    End of Standard Database Header
#.
#.
         0          #. Version number
         0          #. Compression algorithm
8*0                 #. Spare
#.

Now, run a command file like so:

file inp 1 input_data.zdab

define event_loop
	call inp
	call upk
	call cal
	call ftt   ! or whatever
	call dmm(100,1,102)  * test to see if bit 0 has already been defined
	if_not_ok quit_event 

	call dmm(100,1,200)  * set the bit to be 0 by default: i.e. we 
                             * have applied our test
	call xed             * Let the user set the bit manually
end_def

And run SNOMAN with this command file. Whenever you see an event that is a flasher, press the 0 bit-button in the 'Result' row to be in the ON position, then press 'Set Masks' before advancing to the next event.

Now, let's say you make a mistake. For instance, you realize that three events ago you tagged a clipping-muon as a flasher. No problem. Simply use the +- 1/10 buttons to scan backward through the XED event buffer to find your mistake. Then click the bit-buttons to the correct values, and press 'Set Masks' to re-define the correct values for the event in question. XED tells DMM to modify the bits for the correct event (even though it isn't the current event for SNOMAN). This is the major advantage to using DARN bits instead of simply using XED as a filter.

To stop half-way through, select 'Quit Snoman' from the File menu, and the cache file will be saved. Later, you can resume your hand-scanning by simply running the job again: the event loop will skip all the events that you have already looked at, and display the next event after you left off. (This is handy for those all-night scanning sessions, or if you want to scan the output of another job as it comes out.) This works because of the wonderful persistency of the DARN cache files.

To see a list of events that passed your test, just look at the darn_100.dat file. At it's simplest, it's simply a list of runs, sub-runs, and GTIDs of events that match your criteria. (This file is something much easier to send to a friend by email than an entire ZDAB file.)

To generate a summary ZDAB file, consisting of only those events that passed your test, you can simply run another SNOMAN job:

file inp 1 input_data.zdab

$multi_output_sel $pel_args
file out 1 my_summary_file.zdab format=$zdab_only

define event_loop
	call inp
	call dmm(100,1)  * test to see if bit 0 has been set
	if_not_ok quit_event 
	call out(1)
end_def

'my_summary_file.zdab' will now contain only those events you had flagged as flashers.

Tip: Here is an even faster way to scan data. The command file for doing the hand scanning can be:

file inp 1 input_data.zdab

define event_loop
	call inp
	call upk
	call cal
	call ftt   ! or whatever
	call dmm(100,1,102)  * test to see if bit 0 has already been defined
	if_not_ok quit_event 

	call dmm(100,1,200)  * set the bit to be 0 by default: i.e. we 
                             * have applied our test
	call xed             * Let the user set the bit manually
	if_not_ok quit_event
	call dmm(100,1,201)  * set the bit to 1
end_def

Now, if you advance by pressing 'Next/Pass', bit 0 gets set to 1 by DMM automatically, and pressing 'Next/Fail' advances without setting the bit. You can still go back and make changes by manually adjusting the mask values in the event history.