parse_xml Module
parsed_VOEvent Class
- class tracet.parse_xml.parsed_VOEvent(xml, packet=None, trig_pairs=None)[source]
Parses a VOEvent XML file or packet and extracts the useful information from most telescope formats.
- Parameters:
- xmlstr
The location of an XML file you wish to parse
- packetstr, optional
The contents of an XML file you wish to parse (instead of the file).
- trig_pairslist, optional
A list of strings in the format “{telescope}_{event_type}” that you consider interesting.
- Attributes:
- xmlstr
The location of an XML file you wish to parse.
- packetstr
The contents of an XML file you wish to parse (instead of the file).
- trig_pairslist
A list of strings in the format “{telescope}_{event_type}” that you consider interesting.
- event_durationfloat
The duration of the event in seconds.
- event_observedDateTime
The date and time that event was observed.
- telescopestr
The name of the telescope that observed this event.
- event_typestr
The type of the event that is extracted from the ivorn (e.g. BAT_GRB_Pos).
- rafloat
The right ascension in degrees.
- ra_hmsstr
The right ascension in the format “HH:MM:SS.SS”.
- decfloat
The declination in degrees.
- dec_dmsstr
The declination in the format “DD:MM:SS.SS”.
- errfloat
The uncertainty in the event position in degrees.
- ignorebool
If the event should be ignored (e.g. test or unknown events).
- source_typestr
The predicted source type (GRB, FS, NU or GW).
- trig_idstr
The ID the telescope has given the event.
- sequence_numint
What number/sequence this event is for the trig_id group.
- source_namestr
The name of the source from the telescope.
- grb_identbool
If the telescope has identified it as a GRB.
- rolestr
The role of the observation (eg. test or observation).
- ntares_ranking1
The rating (1 is best) for Antares sources.
- fermi_detection_probfloat
The probability the source is real the Fermi provides (it appears to be a percentage).
- fermi_most_likely_indexint
An index that Fermi uses to describe what sort of source the Event is. GRBs are four, so this is what we check for.
- swift_rate_signiffloat
The “RATE_SIGNIF” (appears to be a signal-to-noise ratio) to observe for SWIFT sources (in sigma).
- lvc_false_alarm_ratestr
False alarm rate, a statistic that is used to describe the significance of a gravitational-wave event.
- lvc_binary_neutron_star_probabilityfloat
Likelyhood of the event being a BNS (0-1 range)
- lvc_neutron_star_black_hole_probabilityfloat
Likelyhood of the event being a NSBH (0-1 range)
- lvc_binary_black_hole_probabilityfloat
Likelyhood of the event being a BBH (0-1 range)
- lvc_terrestial_probabilityfloat
Likelyhood of the event being terrestrial (noise) (0-1 range)
- lvc_includes_neutron_star_probabilityfloat
Likelyhood of the event including a neutron star (0-1 range)
- lvc_retraction_messagestring
Message for why observation has been retracted
- lvc_skymap_fitsstring
The contents of a sky map (shows GW probability) in a multi-order FITS format as a Base64-encoded string.
- lvc_prob_density_tilefloat
Shows GW probability of the hights prob tile in the skymap
- lvc_skymap_filebinary
Skymap file from url
get_telescope Function
get_event_type Function
load_swift_source_database Function
get_source_types Function
- tracet.parse_xml.get_source_types(telescope, event_type, source_name, v)[source]
Predict what the source type of the event.
- Parameters:
- telescopestr
The name of the telescope that observed this event.
- event_typestr
The type of the event that is extracted from the ivorn (e.g. BAT_GRB_Pos).
- source_namestr
The name of the source from the telescope.
- vobject
The xml loaded into the voeventparse class.
- Returns:
- source_typestr
Source typre of the event (GRB, FS, NU or GW).
get_position_info Function
trigger_logic Module
worth_observing_grb Function
- tracet.trigger_logic.worth_observing_grb(event_duration=None, fermi_most_likely_index=None, fermi_detection_prob=None, swift_rate_signif=None, hess_significance=None, pos_error=None, dec=None, event_any_duration=False, event_min_duration=0.256, event_max_duration=1.023, pending_min_duration_1=0.124, pending_max_duration_1=0.255, pending_min_duration_2=1.024, pending_max_duration_2=2.048, fermi_min_detection_prob=50, swift_min_rate_signif=0.0, minimum_hess_significance=0.0, maximum_hess_significance=1.0, maximum_position_uncertainty=None, atca_dec_min_1=None, atca_dec_max_1=None, atca_dec_min_2=None, atca_dec_max_2=None, proposal_telescope_id=None, decision_reason_log='', event_id=None)[source]
Decide if a GRB Event is worth observing.
- Parameters:
- event_durationfloat, optional
The duration of the VOevent in seconds.
- fermi_most_likely_indexint, optional
An index that Fermi uses to describe what sort of source the Event. GRBs are 4 so this is what we check for.
- fermi_detection_probint, optional
A GRB detection probabilty that Fermi produces as a percentage.
- swift_rate_signiffloat, optional
A rate signigicance that SWIFT produces in sigma.
- event_any_duration: `Bool`, optional
If True will trigger on an event with any duration including None. Default False.
- event_min_duration, event_max_durationfloat, optional
A event duration between event_min_duration and event_max_duration will trigger an observation. Default 0.256, 1.023.
- pending_min_duration_1, pending_max_duration_1float, optional
A event duration between pending_min_duration_1 and pending_max_duration_1 will create a pending observation. Default 0.124, 0.255.
- pending_min_duration_2, pending_max_duration_2float, optional
A event duration between pending_min_duration_2 and pending_max_duration_2 will create a pending observation. Default 1.024, 2.048.
- fermi_min_detection_probfloat, optional
The minimum fermi_detection_prob to trigger or create a pending observation. Default: 50.
- swift_min_rate_signiffloat, optional
The minimum swift_rate_signif to trigger or create a pending observation. Default: 0.0.
- decision_reason_logstr, optional
A log of all the decisions made so far so a user can understand why the source was(n’t) observed. Default: “”.
- event_idint, optional
An Event ID that will be recorded in the decision_reason_log. Default: None.
- Returns:
- trigger_boolboolean
If True an observations should be triggered.
- debug_boolboolean
If True a debug alert should be sent out.
- pending_boolboolean
If True will create a pending observation and wait for human intervention.
- decision_reason_logstr
A log of all the decisions made so far so a user can understand why the source was(n’t) observed.
triggerservice Module
web_api Function
- tracet.triggerservice.web_api(url='', urldict=None, postdict=None, username=None, password=None, logger=<RootLogger root (DEBUG)>)[source]
Given a url, an optional dictionary for URL arguments, and an optional dictionary containing data to POST, open the appropriate URL, POST data if supplied, and return the result of the call converted from JSON format to a Python dictionary.
- Parameters:
url – The full URL to open, minus any trailing ?name=value&name2=value2… arguments
urldict – Optional Python dictionary to be URL-encoded and appended as …?name=value&name2=value2&… data in the URL itself
postdict – Python dictionary to be converted to JSON format and POSTed with the request.
logger – If a logger object is passed, log activity to it, otherwise use the default logger which will suppress all output.
username – Optional BASIC auth username
password – Optional BASIC auth password
- Returns:
A tuple of (result, header) where result is a Python dict (un-jsoned from the text), the text itself, or None, and ‘header’ is the HTTP header object (use .get_param() to extract values) or None.
busy Function
- tracet.triggerservice.busy(project_id=None, obstime=None, logger=<RootLogger root (DEBUG)>)[source]
Call with a project_id and a desired observing time. This function will return False if the given project_id is allowed to override current observations from now for the given length of time, or True if not.
Note that a False result doesn’t guarantee a later call to trigger() will succeed, as new observations may have been added to the schedule in the meantime.
- Parameters:
project_id – eg ‘C001’
obstime – eg 1800
logger – optional logging.logger object
- Returns:
boolean
vcsfree Function
- tracet.triggerservice.vcsfree(logger=<RootLogger root (DEBUG)>)[source]
This function will return the maximum number of seconds that a VCS trigger will be allowed to request, given the current free space, and upcoming VCS observations in the schedule.
Note that this doesn’t guarantee a later call to trigger() will succeed, as new VCS observations may have been added to the schedule in the meantime.
- Parameters:
logger – optional logging.logger object
- Returns:
int
obslist Function
- tracet.triggerservice.obslist(obstime=None, logger=<RootLogger root (DEBUG)>)[source]
Call with a desired observing time. This function will return a list of tuples containing (starttime, obsname, creator, projectid, mode) for each observation between ‘now’ and the given number of seconds in the future.
- Parameters:
obstime – eg 1800
logger – optional logging.logger object
- Returns:
list of (starttime, obsname, creator, projectid, mode) tuples
trigger Function
- tracet.triggerservice.trigger(project_id=None, secure_key=None, group_id=None, ra=None, dec=None, alt=None, az=None, source=None, subarray_list=None, freqspecs=None, creator=None, obsname=None, nobs=None, exptime=None, calexptime=None, calibrator=None, freqres=None, inttime=None, avoidsun=None, vcsmode=None, buffered=None, pretend=None, logger=<RootLogger root (DEBUG)>)[source]
Call with the parameters that describe the observation/s to schedule, and those observations will be added to the schedule immediately, starting ‘now’.
You can pass more than one position, in any combination of:
one or more RA/Dec pairs
one or more alt/az pairs
one of more source names
Observations will be generated for each position given, in turn (all RA/Dec first, then all Alt/Az, then all source names) unless the ‘subarrays’ list of subarray names is provided, in which case each position will be allocated to one subarray, and observed simultaneously.
You can also pass, for example, one Alt value and a list of Az values, in which case the one Alt value will be propagated to the other Az’s. For example, alt=70.0, az=[0,90,180] will give [(70,0), (70,90), (70,180)]. The same is true for RA/Dec.
You can also pass more than one frequency specifier, in which case observations will be generated for each choice of frequency, AT each position.
If the ‘avoidsum’ parameter is True, then the coordinates of the target and calibrator are shifted slightly to put the Sun in a beam null. For this to work, the target coordinates must be RA/Dec values, not Alt/Az.
If ‘buffered’ is specified, and True, then instead of scheduling new observations, a voltage buffer dump of all available past data will be triggered, and voltage capture will continue from ‘now’ until (nobs * exptime) seconds into the future. Existing observations in the schedule, from ‘now’ until that time, will be truncated or deleted.
The structure returned is a dictionary, containing the following:
result[‘success’] - a boolean, True if the observations were scheduled successfully, False if there was an error.
result[‘errors’] - a dictionary, containing integer keys from 0-N, where each value is an error message. Normally empty.
result[‘params’] - a dictionary containing all parameters passed to the web service, after parsing, and some extra parameters calculated by the web service (the name of the automatically chosen calibrator, etc).
result[‘clear’] - the commands used to clear the schedule. It contains the keys/values:
‘command’: The full clear_schedule.py command line
‘retcode’: The integer return code from that command
‘stderr’: The output to STDERR from that command
‘stdout’: The output to STDOUT from that command
result[‘schedule’] - the commands used to schedule the triggered observations. It contains the keys/values:
‘command’: A string containing all of the single_observation.py command lines
‘retcode’:The integer return code from the shell spawned to run those commands
‘stderr’: The output to STDERR from those commands
‘stdout’: The output to STDOUT from those commands
result[‘obsid_list’] - (only if buffered is True) The observation IDs of all MWA observations covered by the buffer dump and subsequent voltage capture. Use these observation IDs to download the voltage capture files, and to determine the telescope setting/s during the time span including the captured data.
- Parameters:
project_id – eg ‘C001’ - project ID for the triggered observations
secure_key – password associated with that project_id
group_id – optional group ID - the start time of a previously triggered observation of the same event
ra – Either one RA (float, in hours), or a list of RA floats. Eg 12.234, or [11.0, 12.0]
dec – Either one Dec (float, in degrees), or a list of Dec floats. Eg -12.234, or [-26.0, -36.0]
alt – Either one Alt (float, in degrees), or a list of Alt floats. Eg 80.0, or [70.0, 90.0]
az – Either one Az (float, in degrees), or a list of Az floats. Eg 250.3, or [90.0, 270.0]
source – Either one source name string, or a list of source name strings. Eg ‘Sun’, or [‘Sun’, ‘Moon’]
subarray_list – An optional list of subarray names, the same length as the total number of points (ra/decs, alt/azs, etc)
freqspecs – Either one frequency specifier string, or a list of frequency specifier strings. Eg ‘145,24’, or [‘121,24’, ‘145,24’]
creator – Creator string, eg ‘Andrew’
obsname – Observation name string, eg ‘Fermi Trigger 20180211.1234’
nobs – Number of observations to schedule for each position/frequency combination
exptime – Exposure time of each observation scheduled, in seconds (must be modulo-8 seconds)
calexptime – Exposure time of the trailing calibrator observation, if applicable, in seconds
calibrator – None or False for no calibrator observation, a source name to specify one, or True to have one chosen for you.
freqres – Correlator frequency resolution for observations. None to use whatever the current mode is, for lower latency. Eg 40
inttime – Correlator integration time for observations. None to use whatever the current mode is, for lower latency. Eg 0.5
avoidsun – boolean or integer. If True, the coordinates of the target and calibrator are shifted slightly to put the Sun in a null.
vcsmode – boolean. If True, the observations are made in ‘Voltage Capture’ mode instead of normal (HW_LFILES) mode.
buffered – boolean. If True and vcsmode, trigger a Voltage capture using the ring buffer.
pretend – boolean or integer. If True, the clear_schedule.py and single_observation.py commands will be generated but NOT run.
logger – optional logging.logger object
- Returns:
dictionary structure describing the processing (see above for more information).
triggerbuffer Function
- tracet.triggerservice.triggerbuffer(project_id=None, secure_key=None, pretend=None, start_time=None, end_time=None, obstime=None, logger=<RootLogger root (DEBUG)>)[source]
Trigger an immediate dump of the memory buffers to disk, using ‘start_time’ as the earliest time to capture (zero, or any time earlier than the oldest time in the buffer, means ‘save as much as possible’. If ‘end_time’ is specified, save data only up to (but not necessarily including) that time, or if ‘obs_time’ is specified, then keep capturing voltages until that many seconds from ‘now’. Existing observations in the schedule, from ‘now’ until that time, will be truncated or deleted.
For triggers requiring continued capturing after the trigger, you would normally pass zero to start_time, and a duration to obstime as a capture duration, counted from the time that the trigger takes place.
For captures requiring only one or two subfiles at a specific time in the past, you would pass specific GPS times to start_time and stop_time, and not use obstime.
Note that if start_time and end_time are both specified, and both zero, no subfiles are captured, but otherwise the full end-to-end process takes place as a null operation, including calls to all 24 MWAX servers.
The structure returned is a dictionary, containing the following:
result[‘success’] - a boolean, True if the observations were scheduled successfully, False if there was an error.
result[‘errors’] - a dictionary, containing integer keys from 0-N, where each value is an error message. Normally empty.
result[‘params’] - a dictionary containing all parameters passed to the web service, after parsing, and some extra parameters calculated by the web service (the name of the automatically chosen calibrator, etc).
result[‘clear’] - the commands used to clear the schedule. It contains the keys/values:
‘command’: The full clear_schedule.py command line
‘retcode’: The integer return code from that command
‘stderr’: The output to STDERR from that command
‘stdout’: The output to STDOUT from that command
result[‘schedule’] - the commands used to trigger the buffer dump and add a VOLTAGE_STOP observation. It contains the keys/values:
‘command’: A string containing all of the single_observation.py command lines
‘retcode’: The integer return code from the shell spawned to run those commands
‘stderr’: The output to STDERR from those commands
‘stdout’: The output to STDOUT from those commands
result[‘obsid_list’] - The observation IDs of all MWA observations covered by the buffer dump and subsequent voltage capture. Use these observation IDs to download the voltage capture files, and to determine the telescope setting/s during the time span including the captured data.
- Parameters:
project_id – eg ‘C001’ - project ID for the triggered observations
secure_key – password associated with that project_id
pretend – boolean or integer. If True, the triggervcs command will NOT be run.
logger – optional logging.logger object
start_time – Optional earliest time to capture - defaults to zero, for ‘as early as possible’.
end_time – Optional end time, in GPS seconds, to capture (can also be in the past).
obstime – Duration of data capture, in seconds, if end_time is not specified. Counts from ‘now’, not the time in the past when data capture started.
- Returns:
dictionary structure describing the processing (see above for more information).