------------------------------------------------------------------------
Querying the Transient Name Server (TNS)
------------------------------------------------------------------------
Below find a program that queries TNS and returns a file of transients
(classified or unclassified) for every requested month-year.
Considerable effort was put to ensure that requested month-year are
valid. Notice the curious construct on line 35. Apparently the
last entry provided by TNS does not have a "\nl". This is rectified
on this line.
1 #!/bin/zsh
2 # query TNS for each of requested months [scale: 1-12] in a given year (YYYY)
3 # output: one line per event, tsv format
4 #
5 # qTNS [-t type] [-s] YYYY [START_MONTH [END_MONTH]]]
6 # -t type where type=unclassified (u), classified [c]
7 # -s display header
8 # output(s) are tsv with names: TNS_YEAR_MONTH.tsv
9 #
10 # usage:
11 # qTNS 2021 1 % classified events for Jan, 2021 without header
12 # qTNS 2020 1 2 % classified for Jan & Feb 2020 without header
13 # qTNS 2020 % classified for all of 2020 without header
14 # qTNS -s 2021 1 % classified for Jan,2021 with header
15 # qTNS -s -t u 2021 1 % unclassified for Jan,2021 with header
16 #
17 #YETI: FRB option not implemented (not even sure if this option
18 # works correctly on TNS)
19 #YETI=yet to be implemented
20 #
21 # S.R.Kulkarni, 3-January-2021
22 #=======================================================================
23 # internal function: gets TNS events for a given month-year
24 get1month () {
25 #-----------------------------------------------------------------------
26 PAGENO=0; N=1
27 printf "%d %d- " $YEAR $MONTH
28 while [ $N -ne 0 ]
29 do
30 s0="https://www.wis-tns.org/search?&"
31 s2="date_start%5Bdate%5D=$YEAR-$MONTH-01&date_end%5Bdate%5D=$YEAR-$MONTH-31&"
32 s3="num_page=$NMAX&page=$PAGENO&format=tsv"
33 printf "%d:" $PAGENO
34 curl -s -o $TFILE "${s0}${s1}${s2}${s3}"
35 echo "" >> $TFILE #supplying \n for last record
36 N=$(($(wc -l < $TFILE)-1))
37 [ $HEADR -eq 0 ] && sed -it 1d $TFILE
38 if [ $HEADR -eq 1 ]; then
39 [ $PAGENO -gt 0 ] && sed -it 1d $TFILE
40 fi
41 cat $TFILE >> $OFILE
42
43 printf "%d " $N
44 PAGENO=$((PAGENO+1))
45 done
46 return $?
47 }
48 #-----------------------------------------------------------------------
49 #set defaults
50 #-----------------------------------------------------------------------
51 NMAX=500; TYPE=c; HEADR=0; INVALID=;
52 FNAME="TNS"
53 #-----------------------------------------------------------------------
54 TFILE="z_$$.tsv"; touch $TFILE ${TFILE}t
55 trap "rm $TFILE ${TFILE}t" EXIT
56 #-----------------------------------------------------------------------
57 #decode options
58 #-----------------------------------------------------------------------
59 while getopts t:s OPTION
60 do
61 case $OPTION in
62 t) TYPE=$OPTARG;; #classified (c) or unclassified (u)
63 s) HEADR=1;; #HEADR=1 means that HEADER is requested
64 *) INVALID=1;;
65 esac
66 done
67 [ $INVALID ] && exit -1
68 shift $(($OPTIND-1))
69
70 #the choice of events changes the call to TNS
71 #here is where FRBs (in future) will be considered
72 case $TYPE in
73 [cC]) s1="unclassified_at=0&classified_sne=1&include_frb=0&";;
74 [uU]) s1="unclassified_at=1&classified_sne=0&include_frb=0&";;
75 *) echo "quit - invalid choice of type " $TYPE; exit -1;
76 esac
77 #-----------------------------------------------------------------------
78 # decode & verify: year (YEAR), start-month (MSTART) & end-month (MEND)
79 #-----------------------------------------------------------------------
80 # at the very least, the YEAR has to be specified
81 # note: TNS started in YEAR=2016
82 [ $# -lt 1 ] && {echo "quit - year not specified"; exit -1}
83 [ $1 -lt 2016 ] && {echo "quit - TNS started in 2016"; exit -1}
84 YEAR=$1; shift
85 #Decode the months
86 case $# in
87 0) MSTART=01; MEND=12;;
88 1) MSTART=$1; MEND=$1;;
89 2) MSTART=$1; MEND=$2;;
90 *) echo "quit - parameters exceed pair for month start and end"; exit -1;;
91 esac
92 MSTART=$(printf "%02d" $MSTART); MEND=$(printf "%02d" $MEND); # "0"prefix
93 if [ $MSTART -gt $MEND ]; then
94 echo "quit - start month $MSTART > end month $MEND"; exit -1
95 fi
96 if [ $MSTART -gt 12 ] || [ $MSTART -lt 1 ] || [ $MEND -gt 12 ] || [ $MEND -lt 1 ]
97 then
98 echo "quit - invalid month values $MSTART, $MEND"; exit -1
99 fi
100
101 #-----------------------------------------------------------------------
102 # Loop through the months
103 # quit if year-month is in the future
104 #-----------------------------------------------------------------------
105 for MONTH in {$MSTART..$MEND}
106 do
107 YR=$(date "+%Y"); M=$(date "+%m");
108 if [ $YEAR -gt $YR ] || ([ $YEAR -eq $(date "+%Y") ] && [ $MONTH -gt $(date "+%m") ]); then
109 echo "quit - unable to access the future"; exit
110 fi
111 OFILE="${FNAME}_${YEAR}_$MONTH.tsv"; :>$OFILE
112 get1month
113 n=$(sed '/^"ID/d' $OFILE | wc -l | sed 's/ *//')
114 print " $OFILE ($n events)"
115 done