ResponseMatrix

class gdt.core.data_primitives.ResponseMatrix(matrix, emin, emax, chanlo, chanhi)[source]

Bases: object

A class defining a 2D detector response matrix, with an (input) photon axis and (output) channel axis.

Parameters:

  • matrix (np.array) – The 2D matrix, of shape (num_photon_bins, num_channels)

  • emin (np.array) – The low edges of the (input) photon bins

  • emax (np.array) – The high edges of the (input) photon bins

  • chanlo (np.array) – The low edges of the (output) energy channels

  • chanhi (np.array) – The high edges of the (output) energy channels

Attributes Summary

channel_centroids

The geometric mean of the energy channels

channel_widths

The energy channel widths

ebounds

The energy bounds

matrix

The raw matrix

num_chans

The number of energy channels

num_ebins

The number of photon bins

photon_bin_centroids

The geometric mean of the photon bins

photon_bin_widths

The photon bin widths

photon_bins

The photon bins

Methods Summary

channel_effective_area()

Returns the effective area as a function of recorded channel energy (integrated over incident photon bins).

effective_area(energy[, interp_kind])

Calculate the effective area at a given energy or an array of energies.

fold_spectrum(function, params[, channel_mask])

Fold a photon spectrum through a DRM to get a count spectrum

photon_effective_area()

Returns the effective area as a function of incident photon energy (integrated over recorded energy channels).

rebin([factor, edge_indices])

Rebins the channel energy axis of a DRM and returns a new response object.

resample([num_photon_bins, ...])

Resamples the incident photon axis of a DRM and returns a new ResponseMatrix object.

Attributes Documentation

channel_centroids

The geometric mean of the energy channels

Type:

(np.array)

channel_widths

The energy channel widths

Type:

(np.array)

ebounds

The energy bounds

Type:

(Ebounds)

matrix

The raw matrix

Type:

(np.array)

num_chans

The number of energy channels

Type:

(int)

num_ebins

The number of photon bins

Type:

(int)

photon_bin_centroids

The geometric mean of the photon bins

Type:

(np.array)

photon_bin_widths

The photon bin widths

Type:

(np.array)

photon_bins

The photon bins

Type:

(Ebounds)

Methods Documentation

channel_effective_area()[source]

Returns the effective area as a function of recorded channel energy (integrated over incident photon bins).

Returns:

(Bins)

effective_area(energy, interp_kind='linear')[source]

Calculate the effective area at a given energy or an array of energies. This function interpolates the DRM (in log10(cm^2)) to provide the effective area for any energy within the photon energy bounds of the DRM.

Parameters:

  • energy (float or np.array) – The photon energy or energies at which to calculate the effective area.

  • interp_kind (str, optional) – The kind of interpolation to be passed to scipy.interp1d. Default is ‘linear’.

Returns:

(np.array)

fold_spectrum(function, params, channel_mask=None)[source]

Fold a photon spectrum through a DRM to get a count spectrum

Parameters:

  • function (<function>) – A photon spectrum function. The function must accept a list of function parameters as its first argument and an array of photon energies as its second argument. The function must return the evaluation of the photon model in units of ph/s-cm^2-keV.

  • params (list of float) – A list of parameter values to be passed to the photon spectrum function

  • channel_mask (np.array, optional) – A boolean mask where True indicates the channel is to be used for folding and False indicates the channel is to not be used for folding. If omitted, all channels are used.

Returns:

(np.array)

photon_effective_area()[source]

Returns the effective area as a function of incident photon energy (integrated over recorded energy channels).

Returns:

(Bins)

rebin(factor=None, edge_indices=None)[source]

Rebins the channel energy axis of a DRM and returns a new response object. Rebinning can only be used to downgrade the channel resolution and is constrained to the channel edges of the current DRM.

Rebinning can be performed by either defining an integral factor of the number of current energy channels to combine (e.g. factor=4 for 128 energy channels would result in 32 energy channels), or by defining an index array into the current channel edges that will define the new set of edges.

Parameters:

  • factor (int, optional) – The rebinning factor. Must set either this or edge_indices

  • edge_indices (np.array, optional) – The index array that represents which energy edges should remain in the rebinned DRM.

Returns:

(ResponseMatrix)

resample(num_photon_bins=None, photon_bin_edges=None, num_interp_points=20, interp_kind='linear')[source]

Resamples the incident photon axis of a DRM and returns a new ResponseMatrix object. Resampling can be used to downgrade the photon energy resolution, upgrade the resolution, and/or redefine the edges of the incident photon bins. By definition, the resampling can only be performed within the photon energy range of the current object.

The process for resampling is to create a high-resolution grid for each new photon bin, interpolate the differential effective area onto that grid (interpolation is performed on log10(effective area)), and then integrate the differential effective area over the grid points in each bin. The final effective area is then scaled by the ratio of the initial number of photon bins to the requested number of photon bins.

Parameters:

  • num_photon_bins (int, optional) – The number of photon bins in the new DRM. The bin edges will be generated logarithmically. Only set this or photon_bin_edges.

  • photon_bin_edges (np.array, optional) – The array of photon bin edges. Only set this or num_photon_bins

  • num_interp_points (int, optional) – The number of interpolation points used to integrate over for each new photon bin. Default is 20.

  • interp_kind (str, optional) – The kind of interpolation to be passed to scipy.interp1d. Default is ‘linear’.

Returns:

(ResponseMatrix)