TimeEnergyBins

class gdt.core.data_primitives.TimeEnergyBins(counts, tstart, tstop, exposure, emin, emax, count_uncerts=None, quality=None, precalc_good_segments=True)

Bases: object

A class defining a set of 2D Time-Energy bins.

Parameters:

• counts (np.array) – The array of counts 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

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

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

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

• count_uncerts (np.array, optional) – An array the same length as counts if the uncertainty is not Poisson.

• quality (np.array, optional) – The spectrum quality flag

• precalc_good_segments (bool, optional) – If True, calculates the good time and energy segments on initialization.

Attributes Summary

chan_widths	The bin widths along the energy axis
count_uncertainty	The counts uncertainty in each bin
counts	The array of counts in each bin
emax	The high-value edges of the energy bins
emin	The low-value edges of the energy bins
energy_centroids	The bin centroids along the energy axis
energy_range	The range of the data along the energy axis
exposure	The exposure of each bin
num_chans	The number of energy channels along the energy axis
num_times	The number of bins along the time axis
quality	The spectrum quality flag
rate_uncertainty	The rate uncertainty in each bin
rate_uncertainty_per_kev	The differential rate uncertainty in units of counts/s/keV
rates	The rates in each Time-Energy Bin
rates_per_kev	The differential rates in units of counts/s/keV
size	The number of bins along both axes (numtimes, num_chans)
time_centroids	The bin centroids along the time axis
time_range	The range of the data along the time axis
time_widths	The bin widths along the time axis
tstart	The low-value edges of the time bins
tstop	The high-value edges of the time bins

Methods Summary

closest_energy_edge(val[, which])	Return the closest energy bin edge
closest_time_edge(val[, which])	Return the closest time bin edge
contiguous_energy_bins()	Return a list of TimeEnergyBins, each one containing a contiguous energy segment of data.
contiguous_time_bins()	Return a list of TimeEnergyBins, each one containing a contiguous time segment of data.
from_rates(rates, rate_uncerts, tstart, ...)	Create an TimeEnergyBins object from count rates and uncertainties.
get_exposure([time_ranges, scale])	Calculate the total exposure of a time range or time ranges of data
integrate_energy([emin, emax])	Integrate the histogram over the energy axis (producing a lightcurve).
integrate_time([tstart, tstop])	Integrate the histogram over the time axis (producing a count rate spectrum).
merge_energy(histos, **kwargs)	Merge multiple TimeEnergyBins together along the energy axis.
merge_time(histos, **kwargs)	Merge multiple TimeEnergyBins together along the time axis.
rebin_energy(method, *args[, emin, emax])	Rebin the TimeEnergyBins object along the energy axis given a binning function and return a new TimeEnergyBins object.
rebin_time(method, *args[, tstart, tstop])	Rebin the TimeEnergyBins object along the time axis given a binning function and return a new TimeEnergyBins object
slice_energy(emin, emax)	Perform a slice over an energy range and return a new TimeEnergyBins object.
slice_time(tstart, tstop)	Perform a slice over a time range and return a new TimeEnergyBins object.

Attributes Documentation

chan_widths

The bin widths along the energy axis

Type:

(np.array)

count_uncertainty

The counts uncertainty in each bin

Type:

(np.array)

counts

The array of counts in each bin

Type:

(np.array)

emax

The high-value edges of the energy bins

Type:

(np.array)

emin

The low-value edges of the energy bins

Type:

(np.array)

energy_centroids

The bin centroids along the energy axis

Type:

(np.array)

energy_range

The range of the data along the energy axis

Type:

(float, float)

exposure

The exposure of each bin

Type:

(np.array)

num_chans

The number of energy channels along the energy axis

Type:

(int)

num_times

The number of bins along the time axis

Type:

(int)

quality

The spectrum quality flag

Type:

(np.array)

rate_uncertainty

The rate uncertainty in each bin

Type:

(np.array)

rate_uncertainty_per_kev

The differential rate uncertainty in units of counts/s/keV

rates

The rates in each Time-Energy Bin

Type:

(np.array)

rates_per_kev

The differential rates in units of counts/s/keV

Type:

(np.array)

size

The number of bins along both axes (numtimes, num_chans)

Type:

(int, int)

time_centroids

The bin centroids along the time axis

Type:

(np.array)

time_range

The range of the data along the time axis

Type:

(float, float)

time_widths

The bin widths along the time axis

Type:

(np.array)

tstart

The low-value edges of the time bins

Type:

(np.array)

tstop

The high-value edges of the time bins

Type:

(np.array)

Methods Documentation

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)

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)

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)

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)

classmethod from_rates(rates, rate_uncerts, tstart, tstop, exposure, emin, emax, **kwargs)

Create an TimeEnergyBins object from count rates and uncertainties.

Parameters:

• rates (np.array) – The count rates

• rate_uncerts (np.array) – The count rate uncertainties

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

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

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

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

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

• quality (np.array, optional) – The spectrum quality flag

• precalc_good_segments (bool, optional) – If True, calculates the good time and energy segments on initialization.

Returns:

(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)

integrate_energy(emin=None, emax=None)

Integrate the histogram over the energy axis (producing a lightcurve). 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:

(TimeBins)

integrate_time(tstart=None, tstop=None)

Integrate the histogram 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:

(EnergyBins)

classmethod merge_energy(histos, **kwargs)

Merge multiple TimeEnergyBins together along the energy axis.

Parameters:

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

Returns:

(TimeEnergyBins)

classmethod merge_time(histos, **kwargs)

Merge multiple TimeEnergyBins together along the time axis.

Parameters:

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

Returns:

(TimeEnergyBins)

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

Rebin the TimeEnergyBins object along the energy axis given a binning function and return a new TimeEnergyBins 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 edge of the TimeEnergyBins to be binned, otherwise binning will begin at the the first bin edge.

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

Returns:

(TimeEnergyBins)

rebin_time(method, *args, tstart=None, tstop=None)

Rebin the TimeEnergyBins object along the time axis given a binning function and return a new TimeEnergyBins 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

• tstart (float, optional) – If set, defines the start time of the TimeEnergyBins to be binned, otherwise binning will begin at the time of the first bin edge.

• tstop (float, optional) – If set, defines the end time of the TimeEnergyBins to be binned, otherwise binning will end at the time of the last bin edge.

Returns:

(TimeEnergyBins)

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)

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)