TimeChannelBins

class gdt.core.data_primitives.TimeChannelBins(counts, tstart, tstop, exposure, chan_nums, quality=None, count_uncerts=None, precalc_good_segments=True)

Bases: object

A class defining a set of 2D Time/Energy-Channel 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

• chan_nums (np.array) – The channel numbers in ascending order

• 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 channel segments on initialization.

Attributes Summary

chan_nums	The channel numbers
channel_range	The channel number range
count_uncertainty	The counts uncertainty in each bin
counts	The array of counts in each bin
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
rates	The rates in each Time-Channel Bin
size	The number of bins along both axes (num_times, 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

apply_ebounds(ebounds)	Apply an energy bounds calibration and return a TimeEnergyBins object.
closest_time_edge(val[, which])	Return the closest time bin edge
contiguous_channel_bins()	Return a list of TimeChannelBins, each one containing a contiguous channel segment of data.
contiguous_time_bins()	Return a list of TimeChannelBins, each one containing a contiguous time segment of data.
from_rates(rates, rate_uncerts, tstart, ...)	Create an TimeChannelBins 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_channels([chan_min, chan_max])	Integrate the histogram over the channel axis (producing a lightcurve).
integrate_time([tstart, tstop])	Integrate the histogram over the time axis (producing an energy channel spectrum).
merge_channels(histos, **kwargs)	Merge multiple TimeChannelBins together along the channel axis.
merge_time(histos, **kwargs)	Merge multiple TimeChannelBins together along the time axis.
rebin_channels(method, *args[, chan_min, ...])	Rebin the TimeChannelBins object along the energy axis given a binning function and return a new TimeChannelBins object.
rebin_time(method, *args[, tstart, tstop])	Rebin the TimeChannelBins object along the time axis given a binning function and return a new TimeChannelBins object.
slice_channels(chan_min, chan_max)	Perform a slice over an energy range and return a new TimeChannelBins object.
slice_time(tstart, tstop)	Perform a slice over a time range and return a new TimeChannelBins object.

Attributes Documentation

chan_nums

The channel numbers

Type:

(np.array)

channel_range

The channel number range

Type:

(int, int)

count_uncertainty

The counts uncertainty in each bin

Type:

(np.array)

counts

The array of counts in each bin

Type:

(np.array)

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)

rates

The rates in each Time-Channel Bin

Type:

(np.array)

size

The number of bins along both axes (num_times, 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

apply_ebounds(ebounds)

Apply an energy bounds calibration and return a TimeEnergyBins object.

Parameters:

ebounds (Ebounds) – The energy bounds. Must match the number of channels as this object.

Returns:

(TimeEnergyBins)

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

Return a list of TimeChannelBins, each one containing a contiguous channel segment of data. This is done by comparing adjacent channel numbers, and if there is a gap between channels, the data is split into separate TimeChannelBins objects, each containing a channel-contiguous set of data.

Returns:

(list of TimeChannelBins)

contiguous_time_bins()

Return a list of TimeChannelBins, 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 TimeChannelBins objects, each containing a time-contiguous set of data.

Returns:

(list of TimeChannelBins)

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

Create an TimeChannelBins 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

• chan_nums (np.array) – The channel numbers in ascending order

• 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:

(TimeChannelBins)

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_channels(chan_min=None, chan_max=None)

Integrate the histogram over the channel axis (producing a lightcurve). Limits on the integration smaller than the full range can be set.

Parameters:

• chan_min (int, optional) – The low end of the integration range. If not set, uses the lowest energy channel of the histogram

• chan_max (int, optional) – The high end of the integration range. If not set, uses the highest energy channel of the histogram

Returns:

(TimeBins)

integrate_time(tstart=None, tstop=None)

Integrate the histogram over the time axis (producing an energy channel 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:

(ChannelBins)

classmethod merge_channels(histos, **kwargs)

Merge multiple TimeChannelBins together along the channel axis.

Parameters:

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

Returns:

(TimeChannelBins)

classmethod merge_time(histos, **kwargs)

Merge multiple TimeChannelBins together along the time axis.

Parameters:

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

Returns:

(TimeChannelBins)

rebin_channels(method, *args, chan_min=None, chan_max=None)

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

• chan_min (int, optional) – If set, defines the starting channel of the TimeChannelBins to be binned, otherwise binning will begin at the the first channel.

• chan_max (int, optional) – If set, defines the ending channel of the TimeChannelBins to be binned, otherwise binning will end at the last channel.

Returns:

(TimeChannelBins)

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

Rebin the TimeChannelBins object along the time axis given a binning function and return a new TimeChannelBins 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 TimeChannelBins 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 TimeChannelBins to be binned, otherwise binning will end at the time of the last bin edge.

Returns:

(TimeChannelBins)

slice_channels(chan_min, chan_max)

Perform a slice over an energy range and return a new TimeChannelBins object. Note that chan_min and chan_max 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:

(TimeChannelBins)

slice_time(tstart, tstop)

Perform a slice over a time range and return a new TimeChannelBins 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:

(TimeChannelBins)