Classes and functions

minbar.Minbar is the base class for minbar.Bursts and minbar.Observations, so the functions below are common to both those objects

minbar.Sources is the other main class that is derived from the tables accompanying the paper, but it’s architecture is a bit different, and is based on the FITS table.

class minbar.Minbar(filename=None, IDL=False)

This class is provided to access MINBAR burst or observation data EITHER from the MRT tables (publicly available) or from the original IDL database files. Methods here are common to both minbar.Bursts and minbar.Observations classes

Visibility is controlled by the selection attribute, which indicates which of the table entries are selected for display or data extraction

Ordering is persistent and is controlled by the order attribute, by default time ordering

__getitem__(field)

Originally this routine was just a shorthand for minbar.Minbar.get(), but has been expanded to to also return the item with the entry number; return selected items from the current selection; and return

Note that the ID selections below ignore the data selection, and also return astropy Tables (rather than minbar.Bursts or minbar.Observations objects) so you unfortunately can’t use the minbar.Minbar.show() method after selecting

Usage:

b[‘time’] - return all the times for the current selection

b[2094] - return the entry for ID 2094 (ignores current selection)

b[[2094,2095]] - return the entry for IDs 2094, 2095

b[[‘time’,’tau’,’bpflux’]] - return all the attributes for the current selection

b[b[‘time’] > 54000.] - return only those items with the selected properties

__len__()

Return the number of entries in the current selection.

_pad_name(name)

Source names in records are padded with spaces. This routine pads the given name with spaces for comparison to the records.

attr_like(substring, attribute='name')

Function to find attributes matching a particular string. Output can then be used as input to select.

Parameters:

• substring – string to match (anywhere in the attribute string)

• attribute – attribute to match on

Returns:

list of indices of unique matches

clear()

Clear the current selection. If self.type is not None, only bursts of the given type are selected.

exclude(name)

Removes source with given name from the current selection. Now redundant, since minbar.Minbar.select() has the optional exclude flag.

exclude_flag(flags)

Removes entries with flags matching one or more labels from the current selection.

exclude_like(name)

Like minbar.Minbar.exclude(), but get the name from minbar.Minbar.get_name_like().

If multiple names are found, the first is excluded and the rest are reported.

get(field)

Get the field as a numpy array while applying the current (source) selection and time ordering the result. Modified to allow getting data from an attribute, if it is not available in the standard database. Mainly for use by minbar.Minbar.__getitem__()

Parameters:

field – field name or array of field names

Returns:

astropy MaskedColumn giving the data subject to the current selection

get_default_path(filename)

Return the default path of the minbar data files with prefix filename

get_name_like(name)

Return a list of sources that have ‘name’ in their archive identifier.

get_records()

Get the time ordered records that are currently selected.

get_type()

Return an index array selecting the specified burst type (self.type).

instr(instrument, exclude=False)

More general-purpose routine to allow selections (and exclusions) on instr. Values 'pca', 'wfc' and 'jemx' match on ALL configurations for those instruments (i.e. WFC 1 & 2, PCA for any choice of PCUs on etc.)

Parameters:

• instrument – string or array of strings to match

• exclude – boolean, set to True to instead exclude entries for that instrument

Returns:

class object

instr_exclude(instrument)

Wrapper for minbar.Minbar.instr(), used to exclude entries for the selected instrument

Parameters:

instrument – instrument to exclude

Returns:

class object

instr_like(instrument)

Return an array that selects all entries where the instrument name begins with the given instrument string. E.g., ‘XP’ for PCA. For convenience, the following aliases are provided: ‘pca’, ‘wfc’, ‘jemx’.

name_like(name)

Like select, but get the source name from minbar.Minbar.get_name_like(). If multiple names are found, the first is selected and the rest are reported.

obsid(obsid)

Select observations with a particular obsid

Parameters:

obsid – Observation ID to select

Returns:

class object

select(value, attribute='name', exclude=False)

Define a selection for filtering entries based on the provided value(s) and attribute.

Previously this would reset the previous selection, but now it preserves any prior filter, so as to allows multiple chained selections using implied or; also implements exclusion

Parameters:

• value – single value or array to match

• attribute – attribute to match on values; default is name

• exclude – set to True to instead exclude the selection

Returns:

Minbar object

select_all(names)

Select multiple sources with given names. Now redundant, since minbar.Minbar.select() accepts arrays as well as single strings

show(attributes=None, all=False)

Display the object in a user-friendly way, using pprint

Parameters:

• attributes – list of attributes to display; both minbar.Bursts and minbar.Observations classes have a (short) default list

• all – set to True to display all the attributes

Returns:

nothing

sort(attribute='time', ascending=True, descending=False)

Basic sort functionality; will modify the default ordering of the selection, until another sort parameter is chosen, or a call to minbar.Minbar.clear() is made (which replaces the default sort field as time)

Usage:

b.sort(‘tdel’,descending=True) # sort the selected bursts in descending order

# of the time since the last burst

Parameters:

• attribute – (single) table attribute to sort on

• ascending – set to False to sort descending instead

• descending – set to True to sort descending instead

Returns:

sorted object

class minbar.Bursts(filename=None, type=1, IDL=False)

Class for extracting and anlysing the MINBAR burst data. The class methods operate on the table read in from the MRT file, which should be downloaded as part of the install process.

Example usage:

import minbar

mb = minbar.Bursts()

mb.name_like(‘1636’) # Select a source using part of its name

print mb.field_labels # See which fields are available

time = mb[‘time’] # Get a field as a numpy array (automatically time-ordered)

flux = mb[‘pflux’]*1e-9 # Flux in erg/s/cm2

mb.create_distance_correction() # Include distance information from Sources()

distance = mb[‘dist’]

luminosity = flux*mb[‘distcor’] # Luminosity in erg/s

mb.name_like(‘1826’) # Replace selection by another source

mb.select_all([‘GS 1826-24’, ‘4U 1636-536’]) # Select multiple sources; requires exact names

mb.clear() # Clear the selection so all sources are included

mb.exclude_like(‘1636’) # Exclude source from selection

mb.exclude_like(‘1826’) # Now two sources are excluded

PRE(rexp_thresh=1.629, marginal=False)

Select only photospheric radius-expansion (PRE) bursts, according to the standard threshold Additional marginal flag will optionally include those “marginal” events

Parameters:

rexp_thresh – threshold REXP value to use, if not the default

Returns:

__init__(filename=None, type=1, IDL=False)

Create a new Bursts instance.

Parameters:

• filename – path to the database files, excluding their extension. By default the minbar database in the directory of this script is used.

• type – burst type. The default, 1, selects all vetted Type I bursts. Setting it to None means no type is selected.

__str__()

Return a nice string.

burstplot(entry=None, param='flux', bdata=None, show=True, **kwargs)

General-purpose routine to plot burst data. Would like to be able to call this in a number of ways, both with a burst ID from MINBAR, but also with a pandas table (as read in with get_burst_data, for example). And do a bunch of different plots, including the three-panel “in ‘t Zand” plot (see e.g. Fig 3, in ‘t Zand et al. 2012, A&A 547, A47), as well as the three-panel “HR-diagram” version

TODO add some annotation identifying the burst, somewhere…

Usage:

burstplot(burst,param=’rad’,xlim=[-5,25])

burstplot(burst,param=[‘flux’,’rad’,’kT’,’chisq’])

Parameters:

• entry – MINBAR burst entry # to plot

• param – parameter or list of parameters to plot; special ‘hr’ to plot the three-panel HR-diagram version

• bdata – alternative table of input data, e.g. for bursts not in MINBAR

• show – show the figure immediately if True, otherwise withhold it (e.g. to add further annotation etc.)

create_distance_correction()

Create an array of distance corrections, 4 pi d^2, for each burst. This can be used to easily convert flux to luminosity, assuming isotropic X-ray emission and neglecting the bolometric correction

Returns correction factor (cm^2), error, distance (kpc, from the minbar.Source table), error. Furthermore, these arrays are stored and can be accessed as self['fieldname'], with 'fieldname' one of distcor, distcore, dist, diste.

get_burst_data(id)

Retrieve time-resolved spectroscopy for this burst.

Example usage:

data1 = b.get_burst_data(2380)

data2 = b.get_burst_data(1600)

Parameters:

id – MINBAR burst ID to retrieve data

Returns:

pandas DataFrame with time, kT, rad, flux, & errors, chisq etc.

get_error(field)

Return an array representing the uncertainty in field. minbar.Bursts.has_error() can be used to check whether errors are available. If not available, an array of zeros will be returned.

get_error_name(field)

Return the name of the field containing the error for field.

get_lc(id, pre=16.0, post=None)

Preliminary routine to return the lightcurve corresponding to a burst from the lightcurve for the host observation

Later this should probably be incorporated into a Burst object or similar Usage:

b = minbar.Bursts()

mjd, rate, error = b.get_lc(2257)

Parameters:

• id – Burst ID to retrieve

• pre – pre-burst interval (in seconds) to include

• post – post-burst interval (in seconds) to include

Returns:

has_error(field)

Return True if there exists a field with error data on field.

is_error(field)

Return whether given field represents the uncertainty in another.

unique()

Removes multiply-observed bursts, with a priority for RXTE/PCA. That is, if the current selection includes a burst observed both by PCA and WFC, only the PCA entry will be kept

Returns:

class object

class minbar.Observations(filename=None, type=None, IDL=False, bursts=True, verbose=True)

Class with the MINBAR observations (and also the bursts)

__init__(filename=None, type=None, IDL=False, bursts=True, verbose=True)

Load the database of observations.

__str__()

Return a nice string.

good()

Filter for only the “good” observations, excluding bad flags and non detections

Returns:

class object

plot(bursts=True, entry=None, lightcurve=None, show=True, **kwargs)

Simple plotting interface for MINBAR observations, useful for producing (for example) summary plots of source behaviour over the MINBAR sample

This routine works off the fluxes in the current selection, which could include multiple sources (no current method to plot for >1 sources)

Example usage:

import minbar

o = minbar.Observations()

o.select(‘4U 1636-536’)

o.select(0,’flux’,exclude=True) # don’t plot zero fluxes

o.plot()

# or alternatively, for individual observations

o.plot(entry=[14637,14639])

Parameters:

• bursts – boolean flag to toggle plotting of bursts

• entry – alternative selection method, by just passing an array of the observation ID numbers

• lightcurve – boolean to trigger plotting of the high-time resolution lightcurves. By default, this will plot the lightcurves if there are less than 10 observations or they cover 10d or less

class minbar.Sources(filename=None, X=0.0, Gaia=True)

Contains all information on the sources present in MINBAR, via the file minbar_sources.fits.

Example:

s = Sources()

print s.field_names # Show available data fields

ra = s[‘ra_obj’] # Right ascension for all sources

s.name_like(‘1636’)

ra = s[‘ra_obj’] # Right ascension for selected source only

s.clear() # Clear selection

__getitem__(field)

Return field with given name. See minbar.Sources.get().

__init__(filename=None, X=0.0, Gaia=True)

Load source list from FITS file.

__str__()

Display some information about this object The “local files” option refers to auxiliary information including the list of Eddington fluxes, which is not part of the online dataset :return:

_get_field_labels()

Get the field labels from the comment fields in the fits header

clear()

Clear current source selection

get(field, all=False)

Return value with given field

Parameters:

• field – field name to return

• all – whether to return all values or only the current selection

get_F_Edd()

Read in information from Eddington fluxes file

Returns:

get_default_path()

Return the default path of the source list

get_distances(X=0.0, Gaia=True)

Create an array of distances for all sources in self.name

Distances taken from Table 8 of the MINBAR paper, which includes distances derived from the Eddington flux measured for MINBAR bursts, as well as distances measured from Gaia and other sources

Parameters:

• X – assumed H-fraction for Eddington luminosity calculation (default is 0.0)

• Gaia – boolean, set to True to adopt distances from Gaia parallax over calculated values from PRE bursts

Returns:

arrays dist, diste_hi, diste_lo, dist_method, giving the distances and limits (kpc) and the method

get_name_like(name)

Return a list of source indices that have ‘name’ in their name or name_2 fields. Case insensitive.

name_like(name, verbose=True)

Select the source with given name. Uses first result from minbar.Sources.get_name_like()

type(types)

Select only objects matching a particular type code. As for the minbar.Bursts and minbar.Observations classes the selection is persistent until minbar.Sources.clear() is called

Parameters:

types – one or more letters corresponding to the type code in the Sources table, e.g. ‘A’ for atoll, ‘C’ for ultracompact etc.

Returns:

number of sources matching selection

class minbar.Observation(obs_entry=None, instr=None, name=None, obsid=None)

This object is intended to allow all the possible actions you might have on an observation. You can create it from a minbar entry, or given an instrument, source name and obs ID

__init__(obs_entry=None, instr=None, name=None, obsid=None)

Create an observation instance, either from a MINBAR obs entry, or by-hand Ideally this object should make available every parameter in the MINBAR observation table It’d be nice to be able to create this just given the obs ID (for example), but then we’d need to keep a copy of the Observations object, which seems wasteful

Example usage:

import minbar

o = minbar.Observations()

obs = minbar.Observation(o[14637])

Parameters:

• obs_entry – single entry in the minbar.Observations table, to create the object from (in which case the other parameters are not required)

• instr – minbar.Instrument object corresponding to the source instrument for these data

• source – source name

• obsid – observation ID

analyse_burst(bursts)

Function to analyse the persistent emission (lightcurve and spectrum) for a single observation (not yet implemented)

Parameters:

bursts – start times for burst(s) to analyse

Returns:

analyse_persistent()

Function to analyse the persistent emission (lightcurve and spectrum) for a single observation (not yet implemented)

Returns:

get_lc()

Return the lightcurve for a particular observation; this is a replacement for the IDL routine get_lc.pro This routine also populates the time, mjd_tt, mjd, rate, and error attributes for the observation

get_path(split=False)

Return the path for MINBAR observations, assuming you have them stored locally

Parameters:

split – set to true to deal with RXTE/PCA observations that are divided between multiple directories

Returns:

path string (or array of paths) for observation data, if present

plot(figure=None, show=True, show_bursts=True, sym_burst='^r', **kwargs)

Plot the observation lightcurve, reading it in first if need be. Keyword arguments are passed on to the plot command.

Example usage, showing a combined plot of two subsequent observations from 4U 1254-69:

obs1=mb.Observation(o[17920])

obs2=mb.Observation(o[17921], color=’C0’)

fig = obs1.plot(show=False)

obs2.plot(fig)

Parameters:

• figure – existing figure to add to, if multiple observations are to be plotted on the same axis (for example)

• show – display the figure immediately or not (latter case for multiple observations to be plotted together)

Returns:

plot object

class minbar.Instrument(name, camera=None, path=None, label=None, lightcurve=['lc1_3-25keV_1.0s.fits', 'lc2_3-25keV_1.0s.fits'], source_name=None, spectrum=None, verbose=False, effarea=None)

Here’s a generic instrument class which can be adapted and/or duplicated for different instruments. This class is kept pretty lean to avoid having to replicate lots of code Defines the properties of an instrument with data that we’re going to analyse and add to MINBAR

__init__(name, camera=None, path=None, label=None, lightcurve=['lc1_3-25keV_1.0s.fits', 'lc2_3-25keV_1.0s.fits'], source_name=None, spectrum=None, verbose=False, effarea=None)

Define the instrument

Example usage:

import minbar

jemx = minbar.Instrument(‘JEM-X’, ‘jemx’, ‘IJ’)

Parameters:

• name – string giving instrument name; for the MINBAR instruments, these are defined as MINBAR_INSTR_NAME.keys()

• camera – qualifier for the instrument name; e.g. camera 1 or 2 for WFC or JEM-X. TODO decide how to deal with this for the PCA

• path – local path specifier for observations from this instrument

• label – two-character label code for this instrument

• lightcurve – filename for the lightcurves

• source_name – list of source names for this instrument, defaulting to the names from minbar.Sources

• spectrum – filename for the spectra

• verbose – passed to minbar.Instrument.verify_path()

• effarea – effective area assumed for this instrument [cm^2]

filename_with_obsid(template, obsid, exclude=None)

Function to return a filename (possibly including path) incorporating the observation ID, as used for RXTE and NuSTAR lightcurves. Also have the option of excluding a character from the obsid string See minbar.Instrument.pca_lightcurve_filename() for example usage

Parameters:

• template – template string for converting obsid to filename

• obsid – observation ID (string)

• exclude – character(s) to exclude from the obsid when forming the filename

Returns:

filename

pca_lightcurve_filename(obsid)

Function to return the lightcurve name for PCA observations

Parameters:

obsid – observation ID (string)

Returns:

filename

wfc_lightcurve_filename(name, obsid, camera)

Function to return the lightcurve name for WFC observations. This convention is for the 2013 data, not publicly available

Parameters:

• name – source name following WFC convention (string)

• obsid – observation ID (string)

• camera – WFC camera (1 or 2)

Returns:

string giving data file name