Data Binning Module

The functions in gbm.binning are standard functions available to rebin pre-binned data and to bin unbinned data.

For Pre-Binned Data

The following functions in gbm.binning.binned can be used to rebin pre-binned data.

User-defined algorithms can be used as long as the function has the following inputs:

  1. old_counts: The current array of counts in each bin

  2. old_exposure: The current array of exposure for each bin

  3. old_edges: The current array of bin edges

Additionally, you can define any algorithm-specific positional arguments after the required inputs.

The required outputs are:

  1. new_counts: The new array of counts in the rebinned data

  2. new_exposure: The new array of exposure for the rebinned data

  3. new_edges: The new array of bin edges for the binned data

Essentially, the function should read in the old histogram data and provide updated values for the new histogram. As long as you design your function like this, you can use it to bin PHAII data.

combine_by_factor

gbm.binning.binned.combine_by_factor(counts, exposure, old_edges, bin_factor)[source]

Rebins binned data to a multiple factor

Parameters

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

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

  • old_edges (np.array) – The time edges of each bin

  • bin_factor (int) – The number of consecutive bins to be combined

Returns

(np.array, np.array, np.array) – The counts and exposure in each bin and the new bin edges

combine_into_one

gbm.binning.binned.combine_into_one(counts, exposure, old_edges)[source]

Combines binned data into a single bin

Parameters

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

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

  • old_edges (np.array) – The time edges of each bin

Returns

(np.array, np.array, np.array) – The counts and exposure in each bin and the new bin edges

rebin_by_edge

gbm.binning.binned.rebin_by_edge(counts, exposure, old_edges, new_edges)[source]

Rebins binned data based on an array of bin edge indices

Parameters

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

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

  • old_edges (np.array) – The time edges of each bin

  • new_edges (np.array) – The new edges of the binned data

Returns

(np.array, np.array, np.array) – The counts and exposure in each bin and the new bin edges

rebin_by_edge_index

gbm.binning.binned.rebin_by_edge_index(counts, exposure, old_edges, new_edge_index)[source]

Rebins binned data based on an array of bin edge indices

Parameters

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

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

  • old_edges (np.array) – The time edges of each bin

  • new_edge_index (np.array) – The edge indices for the new binned data

Returns

(np.array, np.array, np.array) – The counts and exposure in each bin and the new bin edges

rebin_by_snr

gbm.binning.binned.rebin_by_snr(counts, exposure, old_edges, background_counts, snr)[source]

Rebins binned data such that each bin is above a minimum signal-to-noise ratio

Parameters

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

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

  • old_edges (np.array) – The time edges of each bin

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

  • snr (float) – The minimum signal-to-ratio threshold

Returns

(np.array, np.array, np.array) – The counts and exposure in each bin and the new bin edges

rebin_by_time

gbm.binning.binned.rebin_by_time(counts, exposure, old_edges, dt)[source]

Rebins binned data to a specified temporal bin width.

If the requested bin width is smaller than some of the original bin widths, those bins will be left as is.

If the requested bin width is an exact factor of all the current bin widths, the resulting bin width will be exactly as requested. If the requested bin width is not an exact factor, then the resulting bin width will be approximately the requested bin width without exceeding the requested bin width.

Parameters

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

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

  • old_edges (np.array) – The time edges of each bin

  • dt (float) – The requested temporal bin width in seconds

Returns

(np.array, np.array, np.array) – The counts and exposure in each bin and the new bin edges

For Unbinned Data

The following functions in gbm.binning.unbinned can be used to bin unbinned data

User-defined algorithms can be used as long as the function has the following required input:

  1. times: The array of event times

Additionally, you can define any algorithm-specific positional or keyword arguments after the required inputs.

The required output is:

  1. bin_edges: The bin edges

The algorithm should read in the event times and return the bin edges. A function designed like this can be used to bin event data.

bin_by_edges

gbm.binning.unbinned.bin_by_edges(times, time_edges)[source]

Bins unbinned data by pre-defined edges. A rather trivial function :)

Parameters

  • times (np.array) – The time of each event

  • time_edges (np.array) – The pre-defined time edges

Returns

np.array – The edges of the binned data

bin_by_snr

gbm.binning.unbinned.bin_by_snr(times, back_rates, snr)[source]

Bins unbinned data by SNR

Parameters

  • times (np.array) – The time of each event

  • back_rates (np.array) – The background rate at the time of each event

  • snr (float) – The signal-to-noise ratio

Returns

np.array – The edges of the binned data

bin_by_time

gbm.binning.unbinned.bin_by_time(times, dt, tstart=None, tstop=None, time_ref=None)[source]

Bins unbinned data to a specified temporal bin width.

Parameters

  • times (np.array) – The time of each event

  • dt (float) – The requested temporal bin width in seconds

  • tstart (float, optional) – The first bin edge time. Will use the first event time if omitted.

  • tstop – (float, optional): The last bin edge time. Will use the last event time if omitted.

  • time_ref (float, optional) – The reference time at which the binning will be based. If the set, the binning will proceed starting at time_ref and moving forward in time as well as starting at time_ref and moving backward in time. If not set, the binning will start at the beginning of the data.

Returns

np.array – The edges of the binned data

combine_by_factor

gbm.binning.unbinned.combine_by_factor(times, old_edges, bin_factor, tstart=None, tstop=None)[source]

Bins individual events to a multiple factor of bins given a set of bin edges

Parameters

  • times (np.array) – The time of each event

  • old_edges (np.array) – The edges to be combined

  • bin_factor (int) – The number of bins to be combined

  • tstart (float, optional) – The first bin edge time. Will use the first event time if omitted.

  • tstop – (float, optional): The last bin edge time. Will use the last event time if omitted.

Returns

np.array – The edges of the binned data

combine_into_one

gbm.binning.unbinned.combine_into_one(times, tstart, tstop)[source]

Bins unbinned data to a single bin.

Parameters

  • times (np.array) – The time of each event

  • tstart (float) – The first bin edge time. Will use the first event time if omitted.

  • tstop – (float): The last bin edge time. Will use the last event time if omitted.

Returns

np.array – The edges of the binned data

time_to_spill

gbm.binning.unbinned.time_to_spill(times, threshold)[source]

Time-to-Spill Binning for an event list Bins an event list by accumulating counts until the set threshold is reached, and then creating a new bin.

Parameters

  • times (np.array) – The time of each event

  • threshold (int) – The count threshold for the histogram

Returns

np.array – The edges of the binned data