instruction_manual

A Guide to Using PYGCN
Sergiy Vasylyev 

1) Installing the package

    -Create and activate a conda environment with the necessary modules:
        conda create -p /path/to/pygcn python=2.7 numpy matplotlib mysql-python astropy scipy requests astroquery healpy -c openastronomy
        source activate /path/to/pygcn
        pip install voevent-parse cosmolopy
    -Then install lcogtsnpipe (https://github.com/svalenti/lcogtsnpipe.git) and pygcn (https://github.com/svasyly/pygcn.git)
     by cloning them from github and running 'python setup.py install' for each of them

2) How to use the voevent listener (with pygcn-listen)

    -The listener stores XML files in the current working directory, so run it somewhere that you don't mind cluttering up
    -In order to listen for public GCN voevents, simply run 'pygcn-listen' (this will choose a default host and port 8099)
    -To connect to a specific server, input the following: pygcn-listen theHOSTnumber:thePORTnumber (example: pygcn-listen 68.169.57.253:8099)

3) Receiving private voevents

    -First thing to do is to give your IP address permission to receive these private events by adding or modifying a GCN configuration at this url: http://gcn.gsfc.nasa.gov/config_builder.html
    -Here, make sure to check mark all of the voevents you want to receive (they are automatically filtered). Click submit at bottom of page (MAKE SURE to include your ip address)
    -I can take some time to authorize your computer
    -Some available GCN servers can be found at https://github.com/svasyly/pygcn/blob/master/gcn/GCN_server_list

4) Accessing Gracedb (remote authorization to access LIGO fits files)

    -Make .netrc file that has your generated user and password stored: For information go to http://nbviewer.jupyter.org/github/lpsinger/ligo-virgo-emfollowup-tutorial/blob/master/ligo-virgo-
     emfollowup-tutorial.ipynb and look under "2.Sign up for a GraceDb robot password".

5) Use gcn/lvc_ingest.py to make changes to what voevents are received (filtered) and how to act on them.

6) Changing number of galaxies to pick from glade catalog

    -Go to gcn/galaxy_list.py and change the global variable ngalaxtoshow (near top) to the desired value.

7) Serving voevents

    -Example: pygcn-serve filename1 filename2 filenameN (you can send multiple events)
    -To receive these events run: pygcn-listen 127.0.0.1

8) FITS file storage

    -Currently files are stored in the directory: /supernova/ligoevent_fits
    -To change: Go to gcn/lvc_ingest.py and change this directory to /yourhome/ligoevent_fits. BE SURE to change this for all instances of this directory in this .py file.

9) Creating SQL tables

    -Tables and example sql code provided in the gcn folder of the github: https://github.com/svasyly/pygcn/gcn
    -If you want to remove everything in table then run the following in mysql: DELETE FROM tablename
    -If you want to reset the id auto increment for tables, run the following in mysql: ALTER TABLE tablename AUTO_INCREMENT = 1 
    
10) Connecting to a database 

    -See lcogtsnpipe on github for instructions on making a configure file: https://github.com/svalenti/lcogtsnpipe

Additional comments: 
*If any changes are made to pygcn, then make sure to run the command 'python setup.py install' in terminal.
*If test events are dumping too many voevents in your working directory, then go to gcn/lvc_ingest.py and uncomment the os.system("rm " +filename) line. 
*NOTE: this is a fork of pygcn 
----------------------------------------------------------------------------------- 
If you have questions, contact me at svasylyev@umail.ucsb.edu or sergiyjr@yahoo.com
Acknowledgements: Leo P. Singer, Scott Barthelmy, David Guevel, Michael Zalzman