Data Finders¶

The classes in gbm.finder are for finding data in the GBM trigger and continuous data FTP databases, and for searching the online GBM catalogs.

Base Classes¶

These base classes define an interface to the HEASARC FTP data server for GBM data and the online Browse catalog.

FtpFinder¶

class gbm.finder.FtpFinder[source]¶

Bases: object

A base class for the interface to the HEASARC FTP archive of GBM data. Specifically, it creates a connection to legacy.gsfc.nasa.gov

Attributes

num_files (int) – Number of files in the current directory
files (list of str) – The list of files in the current directory

Note

This class should not be directly instantiated, but rather inherited.

ls(id)[source]¶

List the directory contents of an FTP directory associated with a trigger or data set.

Parameters: id (str) – The id associated with a trigger or data set
Returns: list of str – Alphabetically ordered file list

HeasarcBrowse¶

class gbm.finder.HeasarcBrowse(table=None, verbose=True)[source]¶

Bases: object

A class that interfaces with the HEASARC Browse API. This can be called directly, but primarily intended as a base class.

The class makes a query to HEASARC’s w3query.pl perl script in BATCHRETRIEVALCATALOG mode. All fields and rows are retrieved so that this class, on instantiation, contains the full set of catalog data. Any queries based on row or columns selections/slices are then done locally, instead of making repeated requests to the HEASARC.

Parameters

table (str, optional) – The name of the table to be passed to the w3query.pl script.
verbose (bool, optional) – Default is True

Attributes

columns (np.array) – The names of the columns available in the table
num_cols (int) – The total number of columns (fields) in the data table
num_rows – (int): The total number of rows in the data table

column_range(column)[source]¶

Return the data range for a given column

Parameters: column (str) – The column name
Returns: tuple – The (lo, hi) range of the data column

get_table(columns=None)[source]¶

Return the table data as a record array with proper type conversions. Missing values are treated as type-converted np.nan.

Parameters: columns (list of str, optional) – The columns to return. If omitted, returns all columns.
Returns: np.recarray – A record array containing the requested data

slice(column, lo=None, hi=None)[source]¶

Perform row slices of the data table based on a conditional of a single column

Parameters

column (str) – The column name
lo (optional) – The minimum (inclusive) value of the slice. If not set, uses the lowest range of the data in the column.
hi (optional) – The maximum (inclusive) value of the slice. If not set, uses the highest range of the data in the column.

Returns

HeasarcBrowse – Returns a new catalog with the sliced rows

slices(columns)[source]¶

Perform row slices of the data table based on a conditional of multiple columns

Parameters: columns (list of tuples) – A list of tuples, where each tuple is (column, lo, hi). The ‘column’ is the column name, ‘lo’ is the lowest bounding value, and ‘hi’ is the highest bouding value. If no low or high bounding is desired, set to None. See slice() for more info.
Returns: HeasarcBrowse – Returns a new catalog with the sliced rows.

FTP Finders¶

Classes to find and download GBM data. Inherits from FtpFinder.

TriggerFtp¶

class gbm.finder.TriggerFtp(tnum=None)[source]¶

Bases: gbm.finder.FtpFinder

A class that interfaces with the HEASARC FTP trigger directories. An instance of this class will represent the available files associated with a single trigger.

An instance can be created without a trigger number, however a trigger number will need to be set by set_trigger(tnum) to query and download files. An instance can also be changed from one trigger number to another without having to create a new instance. If multiple instances are created and exist simultaneously, they will all use a single FTP connection.

Note

Since HEASARC transitioned to FTPS, some have had issues with connecting to the HEASARC FTP site via Python’s ftplib for no obvious reason while it works flawlessy for others (even on the same platform). Currently the thought is that this may be related to the underlying OpenSSL version that is installed. If you have connection problems using this, you may consider upgrading you OpenSSL and see if that solves your problem. A potential solution is to do the following:

$ pip3 install pyopenssl
$ pip3 install requests[security]

Parameters

tnum (str, optional) – A valid trigger number

Attributes

num_files (int) – Number of files in the current directory
files (list of str) – The list of files in the current directory

get_all(download_dir, **kwargs)[source]¶

Download all files associated with the trigger

Parameters

download_dir (str) – The download directory
verbose (bool, optional) – If True, will output the download status. Default is True.

get_cat_files(download_dir, **kwargs)[source]¶

Download all catalog files for the trigger

Parameters

download_dir (str) – The download directory
verbose (bool, optional) – If True, will output the download status. Default is True.

get_cspec(download_dir, dets=None, **kwargs)[source]¶

Download the cspec files for the trigger

Parameters

download_dir (str) – The download directory
dets (list, optional) – The detectors’ data to download. If omitted, will download all.
verbose (bool, optional) – If True, will output the download status. Default is True.

get_ctime(download_dir, dets=None, **kwargs)[source]¶

Download the ctime files for the trigger

Parameters

download_dir (str) – The download directory
dets (list, optional) – The detectors’ data to download. If omitted, will download all.
verbose (bool, optional) – If True, will output the download status. Default is True.

get_healpix(download_dir, **kwargs)[source]¶

Download the healpix localization file for the trigger.

Parameters

download_dir (str) – The download directory
verbose (bool, optional) – If True, will output the download status. Default is True.

get_lightcurve(download_dir, **kwargs)[source]¶

Download the lightcurve plots for the trigger

Parameters

download_dir (str) – The download directory
verbose (bool, optional) – If True, will output the download status. Default is True.

get_localization(download_dir, **kwargs)[source]¶

Download all localization files for the trigger

Parameters

download_dir (str) – The download directory
verbose (bool, optional) – If True, will output the download status. Default is True.

get_rsp(download_dir, ctime=True, cspec=True, dets=None, **kwargs)[source]¶

Download the response Type-I files for the trigger

Parameters

download_dir (str) – The download directory
ctime (bool, optional) – If True, download the ctime responses. Default is True.
cspec (bool, optional) – If True, download the cspec responses. Default is True.
dets (list, optional) – The detectors’ data to download. If omitted, will download all.
verbose (bool, optional) – If True, will output the download status. Default is True.

get_rsp2(download_dir, ctime=True, cspec=True, dets=None, **kwargs)[source]¶

Download the response Type-I files for the trigger

Parameters

download_dir (str) – The download directory
ctime (bool, optional) – If True, download the ctime responses. Default is True.
cspec (bool, optional) – If True, download the cspec responses. Default is True.
dets (list, optional) – The detectors’ data to download. If omitted, will download all.
verbose (bool, optional) – If True, will output the download status. Default is True.

get_trigdat(download_dir, **kwargs)[source]¶

Download the trigger data (trigdat) file for the trigger

Parameters

download_dir (str) – The download directory
verbose (bool, optional) – If True, will output the download status. Default is True.

get_tte(download_dir, dets=None, **kwargs)[source]¶

Download the TTE files for the trigger

Parameters

download_dir (str) – The download directory
dets (list, optional) – The detectors’ data to download. If omitted, will download all.
verbose (bool, optional) – If True, will output the download status. Default is True.

ls(id)¶

List the directory contents of an FTP directory associated with a trigger or data set.

Parameters: id (str) – The id associated with a trigger or data set
Returns: list of str – Alphabetically ordered file list

ls_cat_files()[source]¶

List all catalog files for the trigger

Returns: list of str – The file list

ls_cspec()[source]¶

List all cspec files for the trigger

Returns: list of str – The file list

ls_ctime()[source]¶

List all ctime files for the trigger

Returns: list of str – The file list

ls_lightcurve()[source]¶

List all lightcurve plots for the trigger

Returns: list of str – The file list

ls_localization()[source]¶

List all localization files for the trigger

Returns: list of str – The file list

ls_rsp(ctime=True, cspec=True)[source]¶

List all response Type-I files for the trigger

Parameters

ctime (bool, optional) – If True, list the ctime responses. Default is True.
cspec (bool, optional) – If True, list the cspec responses. Default is True.

Returns

list of str – The file list

ls_rsp2(ctime=True, cspec=True)[source]¶

List all response Type-II files for the trigger

Parameters

ctime (bool, optional) – If True, list the ctime responses. Default is True.
cspec (bool, optional) – If True, list the cspec responses. Default is True.

Returns

list of str – The file list

ls_trigdat()[source]¶

List the trigger data (trigdat) file for the trigger

Returns: list of str – The file list

ls_tte()[source]¶

List all tte files for the trigger

Returns: list of str – The file list

set_trigger(tnum)[source]¶

Set the trigger number. If the object was previously associated with a trigger number, this will effectively change the working directory to that of the new trigger number. If the trigger number is invalid, an exception will be raised, and no directory change will be made.

Parameters: tnum (str) – A valid trigger number

ContinuousFtp¶

class gbm.finder.ContinuousFtp(met=None, utc=None, gps=None)[source]¶

Bases: gbm.finder.FtpFinder

A class that interfaces with the HEASARC FTP continuous daily data directories. An instance of this class will represent the available files associated with a single day.

An instance can be created without a time, however a time will need to be set by set_time() to query and download files. An instance can also be changed from one time to another without having to create a new instance. If multiple instances are created and exist simultaneously, they will all use a single FTP connection.

Note

Since HEASARC transitioned to FTPS, some have had issues with connecting to the HEASARC FTP site via Python’s ftplib for no obvious reason while it works flawlessy for others (even on the same platform). Currently the thought is that this may be related to the underlying OpenSSL version that is installed. If you have connection problems using this, you may consider upgrading you OpenSSL and see if that solves your problem. A potential solution is to do the following:

$ pip3 install pyopenssl
$ pip3 install requests[security]

Parameters

met (float, optional) – A time in MET. Either met, utc, or gps must be set.
utc (str, optional) – A UTC time in ISO format: YYYY-MM-DDTHH:MM:SS
gps (float, optional) – A GPS time

Attributes

num_files (int) – Number of files in the current directory
files (list of str) – The list of files in the current directory

get_all(download_dir, **kwargs)[source]¶

Download all files within a daily directory.

Note

Use at your own risk. Unless you have a high-bandwidth connection and can handle downloading several GBs, this function is not recommended for use.

Parameters

download_dir (str) – The download directory
verbose (bool, optional) – If True, will output the download status. Default is True.

get_cspec(download_dir, dets=None, **kwargs)[source]¶

Download the cspec files

Parameters

download_dir (str) – The download directory
dets (list, optional) – The detectors’ data to download. If omitted, will download all.
verbose (bool, optional) – If True, will output the download status. Default is True.

get_ctime(download_dir, dets=None, **kwargs)[source]¶

Download the ctime files

Parameters

download_dir (str) – The download directory
dets (list, optional) – The detectors’ data to download. If omitted, will download all.
verbose (bool, optional) – If True, will output the download status. Default is True.

get_poshist(download_dir, **kwargs)[source]¶

Download the poshist file

Parameters

download_dir (str) – The download directory
verbose (bool, optional) – If True, will output the download status. Default is True.

get_spechist(download_dir, dets=None, **kwargs)[source]¶

Download the spechist files

Parameters

download_dir (str) – The download directory
dets (list, optional) – The detectors’ data to download. If omitted, will download all.
verbose (bool, optional) – If True, will output the download status. Default is True.

get_tte(download_dir, dets=None, full_day=False, **kwargs)[source]¶

Download all TTE files associated with a time.

Note

Unless you have a high-bandwidth connection and can handle downloading several GBs, it is not recommended to download the full day of TTE data.

Parameters

download_dir (str) – The download directory
dets (list, optional) – The detectors’ data to download. If omitted, will download all.
full_day (bool, optional) – If True, will download the TTE files for the full day. If False, will return the TTE files for the covering the specified time. Default is False.
verbose (bool, optional) – If True, will output the download status. Default is True.

ls(id)¶

List the directory contents of an FTP directory associated with a trigger or data set.

Parameters: id (str) – The id associated with a trigger or data set
Returns: list of str – Alphabetically ordered file list

ls_cspec()[source]¶

List all cspec files

Returns: list of str – The file list

ls_ctime()[source]¶

List all ctime files

Returns: list of str – The file list

ls_poshist()[source]¶

List the poshist file

Returns: list of str – The file list

ls_spechist()[source]¶

List all spechist files

Returns: list of str – The file list

ls_tte(full_day=False)[source]¶

List all TTE files

Parameters: full_day (bool, optional) – If True, will return the TTE files for the full day. If False, will return the TTE files for the hour covering the specified time. Default is False.
Returns: list of str – The file list

set_time(met=None, utc=None, gps=None)[source]¶

Set the time. If the object was previously associated with a different time, this will effectively change the working directory to that of the new time. If the time is invalid, an exception will be raised, and no directory change will be made.

Only one of met, utc, or gps should be defined.

Parameters

met (float, optional) – A time in MET.
utc (str, optional) – A UTC time in ISO format: YYYY-MM-DDTHH:MM:SS
gps (float, optional) – A GPS time

HEASARC Catalogs¶

Classes to download and query the GBM trigger and burst catalogs.

TriggerCatalog¶

class gbm.finder.TriggerCatalog(coord_units_deg=True, **kwargs)[source]¶

Bases: gbm.finder.HeasarcBrowse

Class that interfaces with the GBM Trigger Catalog via HEASARC Browse.

Note

Because this calls HEASARC’s w3query.pl script on initialization, it may take several seconds for the object to load.

Parameters

coord_units_deg (bool, optional) – If True, converts the hms sexigesimal format output by HEASARC to decimal degree. Default is True.
verbose (bool, optional) – Default is True

Attributes

columns (np.array) – The names of the columns available in the table
num_cols (int) – The total number of columns (fields) in the data table
num_rows – (int): The total number of rows in the data table

column_range(column)¶

Return the data range for a given column

Parameters: column (str) – The column name
Returns: tuple – The (lo, hi) range of the data column

get_table(columns=None)¶

Return the table data as a record array with proper type conversions. Missing values are treated as type-converted np.nan.

Parameters: columns (list of str, optional) – The columns to return. If omitted, returns all columns.
Returns: np.recarray – A record array containing the requested data

slice(column, lo=None, hi=None)¶

Perform row slices of the data table based on a conditional of a single column

Parameters

column (str) – The column name
lo (optional) – The minimum (inclusive) value of the slice. If not set, uses the lowest range of the data in the column.
hi (optional) – The maximum (inclusive) value of the slice. If not set, uses the highest range of the data in the column.

Returns

HeasarcBrowse – Returns a new catalog with the sliced rows

slices(columns)¶

Perform row slices of the data table based on a conditional of multiple columns

Parameters: columns (list of tuples) – A list of tuples, where each tuple is (column, lo, hi). The ‘column’ is the column name, ‘lo’ is the lowest bounding value, and ‘hi’ is the highest bouding value. If no low or high bounding is desired, set to None. See slice() for more info.
Returns: HeasarcBrowse – Returns a new catalog with the sliced rows.

BurstCatalog¶

class gbm.finder.BurstCatalog(coord_units_deg=True, **kwargs)[source]¶

Bases: gbm.finder.HeasarcBrowse

Class that interfaces with the GBM Burst Catalog via HEASARC Browse.

Note

Because this calls HEASARC’s w3query.pl script on initialization, it may take several seconds up to a couple of minutes for the object to load.

Parameters

coord_units_deg (bool, optional) – If True, converts the hms sexigesimal format output by HEASARC to decimal degree. Default is True.
verbose (bool, optional) – Default is True

Attributes

columns (np.array) – The names of the columns available in the table
num_cols (int) – The total number of columns (fields) in the data table
num_rows – (int): The total number of rows in the data table

column_range(column)¶

Return the data range for a given column

Parameters: column (str) – The column name
Returns: tuple – The (lo, hi) range of the data column

get_table(columns=None)¶

Return the table data as a record array with proper type conversions. Missing values are treated as type-converted np.nan.

Parameters: columns (list of str, optional) – The columns to return. If omitted, returns all columns.
Returns: np.recarray – A record array containing the requested data

slice(column, lo=None, hi=None)¶

Perform row slices of the data table based on a conditional of a single column

Parameters

column (str) – The column name
lo (optional) – The minimum (inclusive) value of the slice. If not set, uses the lowest range of the data in the column.
hi (optional) – The maximum (inclusive) value of the slice. If not set, uses the highest range of the data in the column.

Returns

HeasarcBrowse – Returns a new catalog with the sliced rows

slices(columns)¶

Perform row slices of the data table based on a conditional of multiple columns

Parameters: columns (list of tuples) – A list of tuples, where each tuple is (column, lo, hi). The ‘column’ is the column name, ‘lo’ is the lowest bounding value, and ‘hi’ is the highest bouding value. If no low or high bounding is desired, set to None. See slice() for more info.
Returns: HeasarcBrowse – Returns a new catalog with the sliced rows.