------------------------------------------------------------------------
Extracting GCNs for a given GRB
------------------------------------------------------------------------

BACKGROUND: The gamma-ray burst coordinates network (GCN)  distributes
the essentials of a GRB (coordinates, time, flux) to users. GCN
also distributes to the users follow-up information sent by users.
The creator and PI of GCN is Dr. Scott Barthelmy of GSFC.

GCN has its origin in the Burst and Transient Source Experiment
(BATSE) detector aboard the Compton Gamma-ray Observatory (CGRO
which operated during 1991-2000).  BATSE had large collecting area
but very poor localization. This led to "BATSE coordinates distribution
network" or BACODNE to relay, in real time, error circle of BATSE
for wide field telescopes (with the hope that the prompt emission
would be detected at other wavelengths).

BACODINE was reborn as GCN (circa summer 1997) when the afterglow
phenomenon was discovered by BeppoSAX mission. GCN was the backbone
of GRB in the afterglow era.

Ref: Wikipedia

I first got interested in GRBs, following a sabbatical to ISAS,
Japan in 1992.  Along with Dale Frail I earnestly entered the GRB
field in 1995. I stopped work one year after Swift was launched
(2004) since the field had become main stream at this point and
extremely crowded.

Recently, ZTF discovered an afterglow in a FERMI GBM error circle
and that piqued my interest in GRBs again. I wanted to look at GCNs
related to a given GRB and so I set to write a Unix tool to do so
[only to discover that such a tool already was already developed
by GCN].  I pressed on and will shortly ask for a competition between
my version and GSFC version and the one with the fewest key strokes
is the winner!

------------------------------------------------------------------------
getGRB
------------------------------------------------------------------------

The goal is "give me all GCNs which mention a given GRB name". 
We will build an index table to speed up past the first inquiry.
We also will construct a "Update" the index table program (as new
GCNs roll in).

The index file is simple. It has two columns:
(1)		(2)
GCN_number	GRB_name (mentioned in the body of the file)

To this end, I downloaded the tar file of past GCNs from
https://gcn.gsfc.nasa.gov/gcn3/all_gcn_circulars.tar.gz
and unpacked the files *.gcn3 into "gcn3" diretory.  Each GCN is a
text file with name "nnn.gcn3" where nnn is the GCN number.

$ export dirGCN=gcn3        #bash variable for sub-directory hosting *.gcn3
$ export tableGCN=tableGCN  #bash variable for name of GCN table file

$ ./buildMaster $tableGCN   #Master list (takes tens of minutes to run)
$ cat $masterGCN
gcn3/29045.gcn3   GRB201214B
gcn3/29044.gcn3   GRB201214B
...
gcn3/009.gcn3	  GRB970508
...
gcn3/neg3.gcn3	  GRB970828
gcn3/neg4.gcn3	  GRB970228

An efficient search for GRB names is essenial for building the
master table. This trick is explained  below.

Now let us query this table for all GCNs issued. I will chose 020410
which has some value given it resulted in a Nature paper, commemorates
the launch of Sputnik (and another world shaking event which modesty
prevents me from disclosing).

$ getGRB 020410        (output in GRB020410.txt0

------------------------------------------------------------------------
Updating the Master Table
------------------------------------------------------------------------

You may wish to update your master list.  Fortunately, the architects
of GCN were Zen scientists (as opposed to XML gooks). The URL for
GCN #NNNN is
	https://gcn.gsfc.nasa.gov/gcn3/NNNN.gcn3
So "updateTable" reads off the top GCN entry in the Table and
fetches new GCNs, copying them to $dirGCN and updates the Table.

$ updateTable     
top GCN in GCN Table is # 29093
29094.gcn3 -> gcn3/
29095.gcn3 -> gcn3/
Table is now up to date

The four programs are attached to this example file.

------------------------------------------------------------------------
README 
------------------------------------------------------------------------

[1] Create a directory holding the following programs. 
[2] In this directory there should be a sub-directory named "gcn3".
[3] Download and unpack tar file of old GCNs in gnc3/.
	https://gcn.gsfc.nasa.gov/gcn3/all_gcn_circulars.tar.gz

There are three principal programs: 
	buildTable*
	getGRB*
	updateTable*
and one supporting program (extractGRB*)

$ export dirGCN="gcn3"
$ export tableGCN="tableGCN"

$ buildTable
  The ouput, "$tableGCN", has two columns
    column 1 ... name of GCN file 
    column 2 ... GRB name mentioned in the body of the GCN file
  As many entries, per GCN, are generated as the number of distinct
  GRB names. This program, at the first instantiation, can take up
  to half an hour. 
$ tail -f ${tableGCN}.tmp    #to keep you busy

The search for GRB names is complicated by (1) the GRB name could be
split on two lines (GRB\n 970508), the GRB name could be a part of a
word complex: GRB98045/SN1998bw or XRF/GRB 061022, (GRB 970222),
GR170817A:GW and so on. "grep" has a unique feature: "-o" which
prints the matched portion of the string. I ended up using this
feature.


$ getGRB nameGRB 
  The output is "nameGRB.dat" and is the concatenation of all GCNs
  which mention "nameGRB" in their body

$ updateTable 
  This downloads *.gcn3 to $dirGCN of GCNs issued since the
  "buildTable" or last call to "updateTable". Results are
  appended to $tableGCN.