Background Estimation Module

The classes in gbm.background are standard background estimation classes available to fit time history background for pre-binned and unbinned data.

Fitter Interface

These fitting classes are plugins for BackgroundFitter, which outputs a BackgroundRates object that can be integrated in time to produce a BackgroundSpectrum, which is a background spectrum.

BackgroundFitter

class gbm.background.BackgroundFitter[source]

Bases: object

Class for fitting a background, given a fitting algorithm, to time-energy data (e.g. PHAII, TTE).

When a BackgroundFitter is created, an algorithm must be specified. In particular, the algorithm must be a class that has two public methods: fit() and interpolate().

For PHAII data, the class, upon initialization, must take the following as arguments:

  1. a 2D array of counts with shape (numtimes, numchans);

  2. a 1D array of time bin start times, shape (numtimes,);

  3. a 1D array of time bin end times, shape (numtimes,);

  4. a 1D array of exposures for each time bin, shape (numtimes,).

While for TTE data, the class, upon initialization, must take the following as an argument:

  1. a list, of length numchans, where each item is a np.array of event times.

The fit() method takes no arguments, hoewever, parameters that are required for the algorithm may be specified as keywords.

The interpolate() method must take in the following as arguments:

  1. a 1D array of time bin start times, shape (numtimes,);

  2. a 1D array of time bin end times, shape (numtimes,).

Any additional parameters required can be specified as keywords. The interpolate() method must return:

  1. a 2D rates array, shape (numtimes, numchans);

  2. a 2D rate uncertainty array, shape (numtimes, numchans).

Additionally, the class can provide the following public attributes that will be exposed by BackgroundFitter:

  • dof: The degrees of freedom of the fits, array shape (numchans,)

  • statistic: The fit statistic for each fit, array shape (numchans,)

  • statistic_name: A string of the fit statistic used

Attributes

  • dof (np.array) – If available, the degrees-of-freedom of the fit for each energy channel

  • livetime (float) – The total livetime of the data used for the background

  • method (str) – The name of the fitting algorithm class

  • parameters (dict) – All parameters passed to the fitting algorithm

  • statistic (np.array) – If available, the fit statistic for each energy channel

  • statistic_name (str) – If available, the name of the fit statistic

  • type (str) – The type of background algorithm, either ‘binned’ or ‘unbinned’

fit(**kwargs)[source]

Perform a background fit of the data

Parameters

**kwargs – Options to be passed as parameters to the fitting class

classmethod from_phaii(phaii, method, time_ranges=None)[source]

Create a background fitter from a PHAII object

Parameters

  • phaii (PHAII) – A PHAII data object

  • method (<class>) – A background fitting/estimation class for binned data

  • time_ranges ([(float, float), ...]) – The time range or time ranges over which to fit the background. If omitted, uses the full time range of the data

Returns

BackgroundFitter – The initialized background fitting object

classmethod from_tte(tte, method, time_ranges=None)[source]

Create a background fitter from a TTE object

Parameters

  • tte (TTE) – A TTE data object

  • method (<class>) – A background fitting/estimation class for unbinned data

  • time_ranges ([(float, float), ...]) – The time range or time ranges over which to fit the background. If omitted, uses the full time range of the data

Returns

BackgroundFitter – The initialized background fitting object

interpolate_bins(tstart, tstop, **kwargs)[source]

Interpolate the fitted background model over a set of bins. The exposure is calculated for each bin of the background model in case the background model counts is needed.

Parameters

  • tstart (np.array) – The starting times

  • tstop (np.array) – The ending times

  • **kwargs – Options to be passed as parameters to the interpolation method

Returns

BackgroundRates – The background rates/uncertainty object

interpolate_times(times, **kwargs)[source]

Interpolate the fitted background model over a set of times. Does not calculate an exposure since this returns a set of point estimates of the background rates.

Parameters

  • tstart (np.array) – The sampling times

  • **kwargs – Options to be passed as parameters to the interpolation method

Returns

BackgroundRates – The background rates/uncertainty object

BackgroundRates

class gbm.background.BackgroundRates(rates, rate_uncertainty, tstart, tstop, emin, emax, exposure=None, detector=None, datatype=None, trigtime=None)[source]

Bases: gbm.data.primitives.TimeEnergyBins

Class containing the background rate data.

Parameters

  • rates (np.array) – The array of background rates in each bin

  • rate_uncertainty (np.array) – The array of background rate uncertainties in each bin

  • tstart (np.array) – The low-value edges of the time bins

  • tstop (np.array) – The high-value edges of the time bins

  • emin (np.array) – The low-value edges of the energy bins

  • emax (np.array) – The high-value edges of the energy bins

  • exposure (np.array, optional) – The exposure of each bin

  • detector (str, optional) – The associated detector

  • datatype (str, optional) – The datatype associated with the background

  • trigtime (float, optional) – The trigger time

Attributes

  • chanwidths (np.array) – The bin widths along the energy axis

  • count_uncertainty (np.array) – The counts uncertainty in each bin

  • energy_centroids (np.array) – The bin centroids along the energy axis

  • energy_range (float, float) – The range of the data along the energy axis

  • numchans (int) – The number of energy channels along the energy axis

  • numtimes (int) – The number of bins along the time axis

  • rates (np.array) – The rates in each Time-Energy Bin

  • rates_per_kev (np.array) – The differential rates in units of counts/s/keV

  • rate_uncertainty (np.array) – The rate uncertainty in each bin

  • rate_uncertainty_per_kev (np.array) – The differential rate uncertainty in units of counts/s/keV

  • size (int, int) – The number of bins along both axes (numtimes, numchans)

  • time_centroids (np.array) – The bin centroids along the time axis

  • time_range (float, float) – The range of the data along the time axis

  • time_widths (np.array) – The bin widths along the time axis

closest_energy_edge(val, which='either')

Return the closest energy bin edge

Parameters

  • val (float) – Input value

  • which (str, optional) –

    Options are:

    • ’either’ - closest edge to val;

    • ’low’ - closest edge lower than val;

    • ’high’ - closest edge higher than val. Default is ‘either’

Returns

float – The closest energy bin edge to the input value

closest_time_edge(val, which='either')

Return the closest time bin edge

Parameters

  • val (float) – Input value

  • which (str, optional) –

    Options are:

    • ’either’ - closest edge to val;

    • ’low’ - closest edge lower than val;

    • ’high’ - closest edge higher than val. Default is ‘either’

Returns

float – The closest time bin edge to the input value

contiguous_energy_bins()

Return a list of TimeEnergyBins, each one containing a contiguous energy segment of data. This is done by comparing the edges of each energy bin, and if thereis a gap between edges, the data is split into separate TimeEnergyBin objects, each containing an energy-contiguous set of data.

Returns

list of TimeEnergyBins – A list of TimeEnergyBins

contiguous_time_bins()

Return a list of TimeEnergyBins, each one containing a contiguous time segment of data. This is done by comparing the edges of each time bin, and if thereis a gap between edges, the data is split into separate TimeEnergyBin objects, each containing a time-contiguous set of data.

Returns

list of TimeEnergyBins – A list of TimeEnergyBins

get_exposure(time_ranges=None, scale=False)

Calculate the total exposure of a time range or time ranges of data

Parameters

  • time_ranges ([(float, float), ...], optional) – The time range or time ranges over which to calculate the exposure. If omitted, calculates the total exposure of the data

  • scale (bool, optional) – If True and the time ranges don’t match up with the data binning, will scale the exposure based on the requested time range. Default is False.

Returns

float – The exposure of the time selections

integrate_energy(emin=None, emax=None)[source]

Integrate the over the energy axis. Limits on the integration smaller than the full range can be set.

Parameters

  • emin (float, optional) – The low end of the integration range. If not set, uses the lowest energy edge of the histogram

  • emax (float, optional) – The high end of the integration range. If not set, uses the highest energy edge of the histogram

Returns

gbm.data.primitives.TimeBins – A TimeBins object containing the lightcurve histogram

integrate_time(tstart=None, tstop=None)[source]

Integrate the background over the time axis (producing a count rate spectrum). Limits on the integration smaller than the full range can be set.

Parameters

  • tstart (float, optional) – The low end of the integration range. If not set, uses the lowest time edge of the histogram

  • tstop (float, optional) – The high end of the integration range. If not set, uses the highest time edge of the histogram

Returns

BackgroundSpectrum – A BackgroundSpectrum object containing the count rate spectrum

classmethod merge_energy(histos)

Merge multiple TimeEnergyBins together along the energy axis.

Parameters

histos (list of TimeEnergyBins) – A list containing the TimeEnergyBins to be merged

Returns

TimeEnergyBins – A new TimEnergyBins object containing the merged TimeEnergyBins

classmethod merge_time(histos)[source]

Merge multiple BackroundRates together along the time axis.

Parameters

histos (list of BackgroundRates) – A list containing the BackgroundRates to be merged

Returns

BackgroundRates – A new BackgroundRates object containing the merged BackgroundRates

rebin_energy(method, *args, emin=None, emax=None)[source]

Not Implemented

rebin_time(method, *args, tstart=None, tstop=None)[source]

Not Implemented

slice_energy(emin, emax)

Perform a slice over an energy range and return a new TimeEnergyBins object. Note that emin and emax values that fall inside a bin will result in that bin being included.

Parameters

  • emin (float) – The start of the slice

  • emax (float) – The end of the slice

Returns

TimeEnergyBins – A new TimeEnergyBins object containing the energy slice

slice_time(tstart, tstop)

Perform a slice over a time range and return a new TimeEnergyBins object. Note that tstart and tstop values that fall inside a bin will result in that bin being included.

Parameters

  • tstart (float) – The start of the slice

  • tstop (float) – The end of the slice

Returns

TimeEnergyBins – A new TimeEnergyBins object containing the time slice

classmethod sum_time(bkgds)[source]

Sum multiple TimeBins together if they have the same time range. Example use would be summing two backgrounds from two detectors.

Parameters

of (bkgds (list) – class:`BackgroundRates): A list containing the BackgroundRates to be summed

Returns

BackgroundRates – A new BackgroundRates object containing the summed BackgroundRates

to_bak(time_range=None, **kwargs)[source]

Integrate over the time axis and produce a BAK object

Parameters

  • time_range ((float, float), optional) – The time range to integrate over

  • **kwargs – Options to pass to BAK.from_data()

Returns

gbm.data.BAK – The background BAK object

BackgroundSpectrum

class gbm.background.BackgroundSpectrum(rates, rate_uncertainty, lo_edges, hi_edges, exposure)[source]

Bases: gbm.data.primitives.EnergyBins

A class defining a Background Spectrum.

Parameters

  • rates (np.array) – The array of background rates in each bin

  • rate_uncertainty (np.array) – The array of background rate uncertainties in each bin

  • lo_edges (np.array) – The low-value edges of the bins

  • hi_edges (np.array) – The high-value edges of the bins

  • exposure (np.array) – The exposure of each bin

Attributes

  • centroids (np.array) – The geometric centroids of the bins

  • counts (np.array) – The counts in each bin

  • count_uncertainty (np.array) – The count uncertainty in each bin

  • exposure (np.array) – The exposure of each bin

  • hi_edges (np.array) – The high-value edges of the bins

  • lo_edges (np.array) – The low-value edges of the bins

  • range (float, float) – The range of the bin edges

  • rates (np.array) – count rate of each bin

  • rate_uncertainty (np.array) – The count rate uncertainty of each bin

  • size (int) – Number of bins

  • widths (np.array) – The widths of the bins

closest_edge(val, which='either')

Return the closest bin edge

Parameters

  • val (float) – Input value

  • which (str, optional) –

    Options are:

    • ’either’ - closest edge to val;

    • ’low’ - closest edge lower than val; or

    • ’high’ - closest edge higher than val. Default is ‘either’

Returns

float – The closest bin edge to the input value

contiguous_bins()

Return a list of Bins, each one containing a continuous segment of data. This is done by comparing the edges of each bin, and if there is a gap between edges, the data is split into separate Bin objects, each containing a contiguous set of data.

Returns

list of Bins: A list of Bins

classmethod from_fits_array(arr, ebounds)

Create an EnergyBins object from a FITS counts array

Parameters

  • arr (np.recarray or astropy.io.fits.fitsrec.FITS_rec) – The FITS counts array

  • ebounds (np.recarray or astropy.io.fits.fitsrec.FITS_rec) – The ebounds array, mapping channel numbers to energy bins

Returns

EnergyBins – The new EnergyBins object

classmethod merge(histos)

Merge multiple TimeBins together.

Parameters

histos (list of TimeBins) – A list containing the TimeBins to be merged

Returns

TimeBins – A new TimeBins object containing the merged TimeBins

rebin(method, *args, emin=None, emax=None)

Rebin the EnergyBins object in given a binning function and return a a new EnergyBins object

The binning function should take as input an array of counts, array of exposures, and an array of bin edges. Additional arguments specific to the function are allowed. The function should return an array of the new counts, new exposure, and new edges.

Parameters

  • method (<function>) – A binning function

  • *args – Arguments to be passed to the binning function

  • emin (float, optional) – If set, defines the starting energy of the EnergyBins to be binned, otherwise binning will begin at the first bin edge.

  • emax (float, optional) – If set, defines the ending energy of the EnergyBins to be binned, otherwise binning will end at the last bin edge.

Returns

EnergyBins – The rebinned EnergyBins object

slice(emin, emax)[source]

Perform a slice over an energy range and return a new BackgroundSpectrum object. Note that the emin and emax values that fall inside a bin will result in that bin being included.

Parameters

  • emin (float) – The low energy edge of the slice

  • emax (float) – The high energy of the slice

Returns

BackgroundSpectrum – A new object containing the energy slice

classmethod sum(histos)[source]

Sum multiple BackgroundSpectrums together if they have the same energy range (support).

Parameters

histos (list of BackgroundSpectrum) – A list containing the background spectra to be summed

Returns

BackgroundSpectrum – A new object containing the summed BackgroundSpectrum

For Pre-Binned Data

To be used for fitting the background of pre-binned data.

Polynomial

class gbm.background.binned.Polynomial(counts, tstart, tstop, exposure)[source]

Bases: object

Class for performing a polynomial fit on Time-Energy data. The fit is performed over the time axis, treating each energy channel separately, although performing the fits simultaneously.

Parameters

  • counts (np.array) – The array of counts in each bin, shape (numtimes, numchans)

  • tstart (np.array) – The low-value edges of the time bins, shape (numtimes,)

  • tstop (np.array) – The high-value edges of the time bins, shape (numtimes,)

  • exposure (np.array) – The exposure of each bin, shape (numtimes,)

Attributes

  • dof (np.array) – The degrees-of-freedom for each channel

  • statistic (np.array) – The fit chi-squared statistic for each channel

  • statistic_name (str) – ‘chisq’

fit(order=0)[source]
Fit the data with a polynomial. Model variances are used for

chi-squared via two fitting passes. Adapted from RMfit polynomial fitter.

Parameters

order (int) – The order of the polynomial

Returns

(np.array, np.array) – The fitted model value and model uncertainty at each input bin

interpolate(tstart, tstop)[source]

Interpolation of the fitted polynomial

Parameters

  • tstart (np.array) – The starting edge of each bin

  • tstop (np.array) – The ending edge of each bin

Returns

(np.array, np.array) – The interpolated model value and model uncertainty in each bin

For Unbinned Data

To be used for fitting the background of unbinned data.

NaivePoisson

class gbm.background.unbinned.NaivePoisson(times)[source]

Bases: object

A class to estimate the background of un-binned data using the naive Poisson maximum likelihood.

This method is approximately equivalent to sliding a window of fixed length through un-binned data and calculating the Poisson maximum likelihood for the rate. The rate estimate is applied to the center of the sliding window, therefore, the amount of data equivalent to half of the sliding window at the beginning and half of the window at the end of the data is a constant.

Note

This naive approach assumes there is either no ‘strong’ signal in the data, or the presence of a ‘weaker’ signal has a duration much less than the window width of the sliding window.

Parameters

counts (list of np.array) – A list of length numchans, and each element of the list is an array of event times in that channel.

fit(window_width=100.0, fast=True)[source]

Fit the data via Naive Poisson Maximum Likelihood

Parameters

  • window_width (float) –

    The width of the sliding window in seconds.

    Note

    If the range of the data is shorter than window_width, the window_width will automatically be shortened to the range of the data.

  • fast (bool) – If True, then will use the fast approximation of the algorithm that allows the window_width to change throughout the data (the number of counts in the window is constant). If False, uses the exact algorithm with a fixed window, but is much slower.

interpolate(tstart, tstop)[source]

Interpolate the background at the given times

Parameters

  • tstart (np.array) – The start times of the bins to interpolate

  • tstop (np.array) – The end times of the bins to interpolate

Returns

(np.array, np.array) – The interpolated model value and model uncertainty in each bin