ASMA : All Sky Monitor Assistant

[configure] [summary] [help]

Cleaned "daily-averaged" light curves for the entire ASM catalog are made available with weekly frequency by MIT at URL http://xte.mit.edu/ASM_lc.html .
Users can obtain quick-look curves more rapidly and with their own selection (including start and end times) using a form-driven CGI script at HEASARC URL http://heasarc.gsfc.nasa.gov/docs/xte/SOF/asmlc.html

ASMA does not replace the above but complements them allowing you to

• select a target of interest, and some criteria to receive a trigger notification. Use the following configuration form.
• the HEASARC CGI script will be accessed each night in batch mode, and you will be e-mailed a notification of the trigger condition (or of the entire job)
• you can browse the results via the summary page which provides pointers to individual sources overview pages
• further help information is provided below

In a nutshell, you use ASMA by filling in the configuration form, waiting at least one day, waiting for e-mail notifications, and looking at the results via the summary page. To know more read on.

ASMA components

• a crontab entry (under the name of fictitious user "asma@ifctr.mi.cnr.it") which once every night runs asmmonitor
• software installed under ~lucio/ASM which is described below.
• CGI software installed under virtual directory /lucio-bin which is also described below.
• some HTML files
• configuration and result files located in individual subdirectories of ~lucio/ASM/Sources

• the configuration file config is created by the configuration form and contains the following self-explanatory information :
  • the target catalogue name
  • the "high" threshold for the first trigger (in ASM cts/s)
  • the "low" threshold for the second trigger (in ASM cts/s)
  • the number of days over which to compute an average to determine the "floating" threshold for the third trigger
  • the logging mode. The user will receive a mail according to this, i.e.
    • for all jobs irrespective of their result
    • for jobs terminating in error
    • only when a trigger condition is met
  • the e-mail address(es) to notified
• the last run date contains the date when the monitor job was last run.
• the log file contains the full log of the job (this is what is being e-mailed when requested)
• the query issued to the HEASARC CGI script
• the response obtained from HEASARC. This is either a piece of light curve, or (in case of errors) an otherwise reformatted piece of HTML.
• the trigger file, later appended to the log file, contains the list of intervals where trigger conditions are met
• the history file is the full light curve ("XAS ASCII" format)
• the last time bin contains the date of the last bin of the history file for which the last analysis has been performed
• there are big and small GIF plot files. They are described with the graphical output
• auxiliary files include a script used to set up the "flag files" and three files with the min and max count rate in the interval from the last timebin of the previous run to the present one.

• the log file mailed to the user
• the summary HTML page, which contains the name of all sources being monitored, and for each a small GIF plot, and the 9 "trigger flags". Clicking on the plot one moves to the relevent overview page
• the overview HTML page allows access to the data files listed above, and in particular contains
  • the last run date and last timebin in clear
  • the 9 "trigger flags"
  • two small GIF plots (an expanded version is obtained clicking on them)
  • the min and max rates of the three light curves (raw, smoothed and daily average) in the interval from the last timebin of the previous run to the present one.
• the trigger flag files are shown as little green or red icons, according to the fact the relevant trigger condition is quiescent (green) or active (red)
• the first GIF plot contains the raw and smoothed light curves, plotted respectively in black and green.
  Two magenta horizontal lines indicate the first and second thresholds specified by the user.
  An yellow stripe indicates the time interval over which the floating threshold is computed (i.e. the average value, indicated as a blue horizontal line).
  If the analysis of such threshold is not requested an yellow vertical line indicates the last bin of the previous run.
  The values of the smoothed light curve exceeding the first threshold or below the second are shown in red.
• the second GIF plot contains the daily average light curve, plotted in black, and with the same conventions described above.
  In addition the parts of the light curve above the floating threshold but below the first one appear in cyan.

• asmmonitor is a three-line script which for each source listed in the ~lucio/ASM/Sources directory runs the main script monitor
• monitor is a csh script which processes a single target.
  • it verifies that a subdirectory named after the target exists in ~lucio/ASM/Sources and reads the configuration file from there
  • it verifies that HEASARC is reachable, if not terminates. If the line is noisy, it issues a warning and attempts to continue.
  • it issues a query to the HEASARC CGI script with all default parameters, except the start and end times.
    • normally it attempts to retrieve the most recent ASM data since the last time bin (retrieved in a previous run) till "now"
    • however the first time is run it attempts to retrieve all ASM data since beginning of the mission. To protect against line interruptions, this is done in chunks of 100 days at a time (not all of which may contain data, according to celestial constraints).
  • it verifies the response obtained has the expected format, if not terminates.
  • if the response obtained is valid, but empty (devoid of data) it may terminate (it may be that there are no recent data available) or continue with the next chunk (if retrieving the entire dataset in chunks).
  • at the end the response is reformatted and appended to the "history" file (i.e. the total light curve, which is created the first time)
  • it verifies that the IDL license manager is available, if not terminates
  • it runs the IDL analysis procedure analysis.pro
  • it updates the "trigger flag" files
  • it updates the time of the last bin retrieved in file last.update which will be used as start time of the next retrieval.
  • a log file is generated throughout, and is mailed to the person designated in the configuration file (according to criteria contained therein).
• reformat.awk is an auxiliary awk program used to reformat the ASCII file produced by the HEASARC CGI script (stripping unused comments, and transforming the data quality flag into numeric values).
• analysis.pro is an IDL procedure used for the trigger analysis, as well as to produce summary plots.
  • it reads in the "history" light curve (raw data)
  • it produces a smoothed light curve (smoothing is done with a 11-bin boxcar, or smaller, on each interval not interrupted by 1-day gaps (or larger))
  • it produces a daily averaged light curve (also excluding gaps)
  • the analysis is performed for data points more recent than the last bin retrieved in the previous run (i.e. Tlast)
  • the average of the daily averages over the N days before Tlast is computed, where N is in the configuration file (this can be bypassed if N is 0)
  • the trigger analysis is run three times :
    • on raw data
    • on smoothed data
    • on daily averages
  • each trigger analysis considers three cases
    • count rates going above a fixed user selected threshold
    • count rates going below another fixed user selected threshold
    • count rates going above the mean of the last N days before Tlast
  • for each interval meeting the trigger condition, a message is logged. In addition if any of the 9 trigger conditions is met at least once, a "trigger flag" files is updated (in fact the flag files are just soft links to standard "on" and "off" files, the IDL procedures simply writes a file of commands executed by the calling script monitor
  • the GIF summary plots are produced
  • the number of triggers (if any) is returned

• CGI components

• asmsummary is a CGI script which creates the summary page
• asmoverview is a CGI script (invoked with the target name as argument) which creates a volatile HTML overview page

• s/w history

• 27 Nov 1997 : original version, using mconnect to handle the httpd connection (this is prone to line noise, hence the reason to have retrievals in small chunks)
• 17 Apr 1998 : small change to invocation of HEASARC CGI script propagated
• 18 Aug 1998 : new version, using lynx in "source" mode to handle the httpd connection with full error control. Also adjusted the reformatting awk script to better handling of spurious lines
• 24 Feb 2000 : adjusted X-axis scale in plots produced by IDL
• 18 Aug 2000 to 05 Sep 2000 : IDL procedure now labels X-axis plots in real dates (YY MM DD)
• 17 Aug 2000 : main script changed IDL license server
• 02 Feb 2001 : in main script trapped IDL messages to /dev/null
• 20 Aug 2001 : in main script disabled ping check on reachability of HEASARC since legacy does no longer respond to ping request even when up