Table Of Contents

Previous topic

batse5bp

This Page

batse5bp Package

batse5bp Package

Package providing remote access to and local persistant storage of GRB data from the BATSE 5Bp (“Current”) catalog hosted by the Compton Observatory Science Support Center (COSSC) at Goddard Space Flight Center.

Created 2012-05-07 by Tom Loredo

ascii64 Module

Objects providing access to 64 ms count data as compiled in the ASCII data files at the COSSC.

These files compile DISCLA, PREB, and DISCSC data over an interval determined by examination of trigger and pre-trigger data by the BATSE team.

NOTE: The DISCLA data is in 1024 ms bins; the counts are divided by 16 to distribute across the tabulated 64 ms bins. The DISCLA bins can overlap with the 1st PREB bin, in which case the PREB overlap is subtracted and the remaining counts divided among earlier bins.

For full documentation, see:

ftp://legacy.gsfc.nasa.gov/compton/data/batse/ascii_data/64ms/README

Created 2012-10-22 by Tom Loredo

class batse5bp.ascii64.ASCII64(grb)[source]

Provide access to the 64 ms count data compiled in the ASCII data files hosted by the COSSC.

rates()[source]

Return time bin centers & widths (vectors) & count rates (4-row matrix). These values are useful for plotting.

catalog Module

Read data from the “current” BATSE catalog (dubbed 5Bp here, with “p” for “preliminary,” since an official 5B successor to the 4B catalog has not yet been released). Provide access to catalog data and other GRB data via a GRBCollection instance providing access to its individual GRB elements in three ways:

  • as an OrderedDict indexed by BATSE trigger number
  • via attributes of the form .t#, with # = BATSE trigger number
  • via attributes of the form .b#, with # = YYMMDD burst designation; this returns a list of triggers matching the designation (there will be >1 if BATSE detected multiple bursts on the specified date)

Only one function in this module is intended for users: load().

This module was created to access the data as released in Jul-Sep 2000.

Created 2012-05-06 by Tom Loredo

batse5bp.catalog.load_catalog(root_dir='BATSE_5Bp_Data')[source]

Establish access to GRB data from the BATSE ‘5B’ catalog, stored in the root_dir directory. Return a GRBCollection providing burst-by-burst access keyed by trigger number and via trigger and YYMMDD (date) attributes.

If no catalog has yet been established, the directory is created and summary data for all GRBs are fetched from the CGRO SSC and stored locally for future use.

Detailed data for specific bursts is fetched, parsed, and cached lazily as requested.

docn Module

Documentation supporting the 5Bp data.

Created 2012-05-07 by Tom Loredo

batse5bp.docn.show_ssc()[source]

Show the COSSC web site in the user’s default web browser.

batse5bp.docn.show_4B()[source]

Show the 4B catalog web site in the user’s default web browser.

batse5bp.docn.show_5Bp()[source]

Show the 5Bp (“current”) catalog web site in the user’s default web browser.

batse5bp.docn.show_problems()[source]

Show the BATSE data problems archive in the user’s default web browser.

drm Module

Provide access to DRM data stored in FITS files at COSSC.

Documentation of the compressed DRM format from the DRM FITS header (for 1-based array indexing):

The detector response matrix is stored in a compressed format:

Elements are listed in order of row by column (n_e_bin by n_e_chan), with all elements equal to 0 at the top of the column ommited.

The row index of the first non-zero element for each column is given by n_zeros.

Thus, for the ith column: insert n_zeros(i) - 1 0s, followed by the next n_e_bin - n_zeros(i) + 1 elements of the drm (either drm_dir, drm_sct or drm_sum).

The last column should exhaust the elements of the compressed drm.

Created 2012-10-16 by Tom Loredo

class batse5bp.drm.DRM_DISCSC(row_data, n_ch, n_E)[source]

Provide access to the detector response matrix (DRM) for a single BATSE detector’s discriminator science (DISCSC) data.

The DRM units according to the FITS header is area in cm^2.

fields = {0: ('DET_NUM', 'the active detector for one row'), 1: ('MAT_TYPE', '0=Direct,1=Scattered, 2= Both, 3=Summed'), 2: ('TIME', 'time drm is calculated for'), 3: ('NUMEBINS', 'number of rows in PHT_EDGE (N_E_BINS+1)'), 4: ('NUMCHAN', 'number of columns in E_EDGES (N_E_CHAN+1)'), 5: ('NUMZERO', 'number of of zeroes top of each column'), 6: ('DIRDRM', 'number of rows in the DIR drm'), 7: ('SCTDRM', 'number of rows in the SCT drm'), 8: ('SUMDRM', 'number of rows in the SUM drm'), 9: ('PHT_EDGE', 'input bin energy edges'), 10: ('E_EDGES', 'channel energy edges'), 11: ('N_ZEROS', 'list of how many 0 elements in each column'), 12: ('DRM_DIR', 'detector response matrix'), 13: ('DRM_SCT', 'detector response matrix'), 14: ('DRM_SUM', 'detector response matrix'), 15: ('CAL_NAME', 'Name of energy calibration method')}
class batse5bp.drm.DRMs_DISCSC(grb)[source]

Provide access to detector response matrix (DRM) data from a BATSE DISCSC DRM FITS file for all triggered detectors associated with a BATSE trigger; also calculate the summed response.

load_from_fits(fits_path, drm_path, meta_path)[source]

Read DRM data from a FITS file. The path fname may be to a gzipped version. Archive the data at the DRM file paths.

meta_attrs = ['burst_id', 'file_id', 'n_ch', 'n_E', 'alpha', 'n_det']

grb Module

Define a GRB object holding BATSE data associated with a single GRB trigger, and a GRBCollection to hold GRB instances for many GRBs.

Created 2012-05-06 by Tom Loredo (adapted from an earlier version for the 4B catalog)

class batse5bp.grb.GRB(basic_record)[source]

Bases: object

Provide access to BATSE data for a single GRB, both through persistant local storage and via access to the CGRO SSC data archive.

cached_path(fname)[source]

Return the path to a persistant local copy of a remote file.

Point to a local copy of the resource if present; otherwise, fetch it remotely and save a copy locally, then return the local path.

clear_cached(fname)[source]
duration_attributes = ['T50', 'T50_err', 'T50_start', 'T90', 'T90_err', 'T90_start']
file_check(fname)[source]

Check to see if the named file exists in this bursts data directory.

flux_attributes = ['F1', 'F1_err', 'F2', 'F2_err', 'F3', 'F3_err', 'F4', 'F4_err', 'F64ms', 'F64ms_err', 't64ms', 'F256ms', 'F256ms_err', 't256ms', 'F1024ms', 'F1024ms_err', 't1024ms']
load_ascii64()[source]

Load 64 ms count data from COSSC ASCII files.

These files compile DISCLA, PREB, and DISCSC data over an interval determined by examination of trigger and pre-trigger data by the BATSE team.

NOTE: The DISCLA data is in 1024 ms bins; the counts are divided by 16 to distribute across the tabulated 64 ms bins. The DISCLA bins can overlap with the 1st PREB bin, in which case the PREB overlap is subtracted and the remaining counts divided among earlier bins.

For full documentation, see:

ftp://legacy.gsfc.nasa.gov/compton/data/batse/ascii_data/64ms/README

load_discsc_drms()[source]

Load DISCSC DRM data for the triggered detectors.

load_pickle(fname)[source]

Retrive an object associated with this GRB from a pickle in the database.

open_cached(fname)[source]
raw_cached_path(fname)[source]

Return the path to a local copy of a remote file; it is stored in the raw_cache directory for temporary use.

Point to an existing local copy of the resource if present; otherwise, fetch it remotely and save a copy locally, then return the local path.

save_pickle(obj, fname)[source]

Save an object associated with this GRB as a pickle in the database.

set_bright(trigger, cols)[source]

Add peak flux & fluence data from a brightness table record.

set_durn(trigger, cols)[source]

Add duration data from a duration table record.

set_grb_dir()[source]

Set the path to this GRB’s local data directory, creating the directory and its containing group if needed.

This is not done in __init__ so the group and burst directories are created only when detailed data are loaded for a burst.

show_lc()[source]

Show light curve GIF files in the default image browser, merging 4ch and summed light curves.

class batse5bp.grb.GRBCollection(*args, **kwds)[source]

Bases: collections.OrderedDict

Store GRB objects in an ordered dict accessed by BATSE trigger number (with the key being the integer trigger number, not a string).

GRB data may also be accessed as attributes in two ways:

.t# where # is the trigger number; returns a GRB instance

.b# where # is YYMMDD from the traditional GRBYY... designation;
returns a list of GRB instances

Note that multiple bursts may occur on the same day, so the .b# value is a list of GRBs that occurred on that day. The 4B catalog distinguished such bursts with designators that add a letter suffix (B, C, D after the first burst), nominally ordered by intensity. The 5Bp bursts (even those from 4B) are not so labeled.

add(grb)[source]

Add a GRB instance to the collection.

locations Module

Specify locations, locally and the COSSC, for accessing GRB data.

No modules are imported here; ‘from locations import *‘ should be safe.

Created 2012-05-07 by Tom Loredo

batse5bp.locations.ascii64_paths(tnum)[source]

Return components of the path to the data for trigger tnum, both at the COSSC FTP site and locally: (group, fname, remote).

group name of the group directory containing the trigger directory fname name of the ASCII data file, “cat64ms.<tnum>” remote tail of the ftp path @ COSSC, “<group>/<fname>”

batse5bp.locations.trigger_paths(tnum)[source]

Return components of the path to the data for trigger tnum, both at the COSSC FTP site and locally: (group, trigger, remote).

group name of the group directory containing the trigger directory trigger name of the trigger directory, “<tnum>_burst” remote tail of the ftp path @ COSSC, “<group>/<trigger>”

persistant Module

Utility classes for simple object persistance.

More sophisticated alternatives include atpy, h5py, and PyTables. This simple approach is adopted for now to reduce dependencies.

* MODULE NOT YET USED *

Based on ioutils.py from the Inference package.

Created 2012-10-22 by Tom Loredo

class batse5bp.persistant.ArrayStore(fname=None)[source]

Bases: object

A container class that provides lazy persistance of array instance attributes via NumPy’s .npz archives.

This is doubly lazy: arrays are not read into the namespace until actually requested, and they are not saved to the archive until the ArrayStore is explicitly saved.

contents()[source]

List the names of arrays accessible by this store, including both previously archived arrays and newly defined arrays.

save(fname=None)[source]

Save array attributes to a NumPy .npz archive. If a name is provided, it is used (adding ‘.npz’ if needed); otherwise it is presumed this store was created from an existing archive, and that archive’s name is used.

In either case, any existing version is backed up before the new one is created, with up to two levels of backups (with ‘%’ and ‘%%’ suffixes).

class batse5bp.persistant.AttrStore(fname=None, **kwds)[source]

Bases: object

A container class that provides lazy persistance of instance attributes as a Python pickle.

This is doubly lazy: attributes are not placed in the namespace until actually requested (but they are all read from the file), and they are not saved to the archive until the AttrStore is explicitly saved.

If only NumPy arrays are to be stored, ArrayStore may be more efficient.

contents()[source]

List the names of arrays accessible by this store, including both previously archived arrays and newly defined arrays.

save(fname=None)[source]

Save attributes to a high-protocal pickle. If a name is provided, it is used (adding ‘.pkl’ if needed); otherwise it is presumed this store was created from an existing archive, and that archive’s name is used.

In either case, any existing version is backed up before the new one is created, with up to two levels of backups (with ‘%’ and ‘%%’ suffixes).

read_tte Module

A class (TTE) and support functions for reading and writing BATSE TTE data from tte_ibdb FITS files, loosely based on IDL code by Jay Norris.

NOTE: Jay Norris has found that a few tte_ibdb files have corrupt data. There is no simple way to identify these automatically, but they are obvious when one plots a histogram of the TTE data. The problem appears to be due to misidentified triggered detectors. In addition, Adam Kruger has found more complicated corruption in a few files; this is reported in ApJ v. 576, 532 (2002).

FTP users take note! If you are downloading a FITS file by ftp from an archive, make sure you download it in BINARY format. Some ftp programs (e.g. ‘Fetch’ on the Mac) work by default in an ‘automatic’ mode that attempts to distinguish text files from binary files automatically. FITS files mix ASCII and binary data and can confuse these programs. An improperly downloaded file will appear to read correctly, but the data will be corrupted.

Created: 25 May 2000 by Tom Loredo Modified: 01 Jun 2000 TL

14 Dec 2006 TL - Convert to PyFITS 2012-05-09 TJL - Adapt for batse5bp
class batse5bp.read_tte.TTE(fname)[source]

Bases: object

Instances of this class read and store TTE IDBD data from a BATSE tte_ibdb FITS file. TTE.primary stores the primary header data. Each IBDB field value that is constant (from packet to packet) is stored as a TTE attribute (e.g. TTE.BSTNO). Data from ‘good’ events that were detected in a single energy channel in one of the 4 maximum-count-rate detectors are stored as follows:

TTE.nevents # of events (int) TTE.time integer # of us for each event (list of int) TTE.det detector # for each event (list of int) TTE.chan channel # for each event (list of int)

Other events are either ‘bad’ events (multiple channels hit in 2us) or ‘background’ events (detected with detectors other than the ‘good’ ones). These are collected in lists of tuples:

TTE.background (t, det, ch) for each bg event TTE.bad (t, det, ch) for each bad event

In these tuples, ch is a tuple of the channels for that event.

The initializer does a lot of internal consistency checking of the FITS file contents as it reads and parses the data; it takes ~10 s per file on a 2 GHz processor. Store the instance for fast repeated use of the data.

FWIW: I don’t think multi-channel ‘bad’ events should be ignored, unless this is a discriminator error!

const_fields = ['SCHED_PTR', 'LOOP_CTR', 'ITER_NUM', 'BSTST', 'BSTLT', 'BSTNO', 'DSELB', 'NSCALE', 'BERFGS', 'TTRIG', 'SOLFLG', 'TIME', 'DSELH', 'SPARE']
const_sizes = [1, 1, 1, 3, 3, 1, 1, 1, 1, 1, 1, 3, 4, 1]
nconst = 14
write_ASCII(fname=None)[source]

Write the good event data in the ASCII TTE format adopted by the COSSC. This method opens the indicated file for writing, and closes it on completion.

batse5bp.read_tte.byte2bits(d)[source]

Convert a 1-byte datum into a list of 8 bits ordered from lsb to msb.

batse5bp.read_tte.byte2bits_(d)[source]

Convert a 1-byte datum into a list of 8 bits ordered from lsb to msb.

batse5bp.read_tte.bytes2bits(d)[source]

Convert a 2-byte datum into a list of 16 bits ordered from lsb to msb. Uses logical operations. This approach is transparent to whether the datum has been read from a signed or unsigned representation.

batse5bp.read_tte.bytes2bits_(d)[source]

Convert a 2-byte datum into a list of 16 bits ordered from lsb to msb. Uses logical operations. This approach is transparent to whether the datum has been read from a signed or unsigned representation.

batse5bp.read_tte.unpack_TTESD(d)[source]

Unpack a TTE SCIENCE_DATA datum from its 2 byte packed format into (detector #, channel #’s, # of 2us clock cycles), returned as a tuple. Since mutiple channels can be triggered in a 2us interval, the channel value is itself a tuple.

utils Module

Utilities for the batse5bp package.

Created 2012-05-08 by Tom Loredo

batse5bp.utils.retrieve_gzip(url, cache)[source]

Return an open file accessing data from the file at the http URL url that may be persistantly stored as a gzipped file named from the URL tail and stored in the directory cache.

If the cached file exists, simply return an opened file object accessing it.

If it does not exist, retrieve the file using the URL, cache a gzipped version, and return an opened file object accessing it.

batse5bp.utils.write_seq(fob, seq, format, per_line, label=None)[source]

Write the contents of the sequence object seq to the open file object fob, writing each element according to the passed format, with per_line elements per line. label gives an optional label to start each line.