Detector response

Different matrices that charaterize the response of the instrument. These encode the effective area and the various detector effects seens in the data, and allow to compute the expected counts given a source hypothesis.

Classes

class cosipy.response.PointSourceResponse(*args: Any, **kwargs: Any)

Handles the multi-dimensional matrix that describes the expected response of the instrument for a particular point in the sky.

Parameters:

• axes (histpy.Axes) –

  Binning information for each variable. The following labels are expected:

  • Ei: Real energy

  • Em: Measured energy. Optional

  • Phi: Compton angle. Optional.

  • PsiChi: Location in the Compton Data Space (HEALPix pixel). Optional.

  • SigmaTau: Electron recoil angle (HEALPix pixel). Optional.

  • Dist: Distance from first interaction. Optional.

• contents (array, astropy.units.Quantity or sparse.SparseArray) – Array containing the differential effective area convolved with wht source exposure.

• unit (astropy.units.Unit, optional) – Physical units, if not specified as part of contents. Units of area*time are expected.

property photon_energy_axis

Real energy bins (Ei).

Return type:

histpy.Axes

get_expectation(spectrum)

Convolve the response with a spectral hypothesis to obtain the expected excess counts from the source.

Parameters:

spectrum (threeML.Model) – Spectral hypothesis.

Returns:

Histogram with the expected counts on each analysis bin

Return type:

histpy.Histogram

class cosipy.response.DetectorResponse(*args: Any, **kwargs: Any)

Handles the multi-dimensional matrix that describes the response of the instrument for a particular SpacecraftFrame coordinate location.

Parameters:

• axes (histpy.Axes) –

  Binning information for each variable. The following labels are expected:

  • Ei: Real energy

  • Em: Measured energy

  • Phi: Compton angle. Optional.

  • PsiChi: Location in the Compton Data Space (HEALPix pixel). Optional.

  • SigmaTau: Electron recoil angle (HEALPix pixel). Optional.

  • Dist: Distance from first interaction. Optional.

• contents (array, astropy.units.Quantity or sparse.SparseArray) – Array containing the differential effective area.

• unit (astropy.units.Unit, optional) – Physical area units, if not specified as part of contents

get_spectral_response(copy=True)

Reduced detector response, projected along the real and measured energy axes only. The Compton Data Space axes are not included.

Parameters:

copy (bool) – If true, a copy of the cached spectral response will be returned.

Return type:

DetectorResponse

get_effective_area(energy=None, copy=True)

Compute the effective area at a given energy. If no energy is specified, the output is a histogram for the effective area at each energy bin.

Parameters:

• energy (optional, astropy.units.Quantity) – Energy/energies at which to interpolate the linearly effective area

• copy (bool) – If true, a copy of the cached effective will be returned.

Return type:

astropy.units.Quantity or histpy.Histogram

get_dispersion_matrix()

Compute the energy dispersion matrix, also known as migration matrix. This holds the probability of an event with real energy Ei to be reconstructed with an measured energy Em.

Return type:

histpy.Histogram

property photon_energy_axis

Real energy bins (Ei).

Return type:

histpy.Axes

property measured_energy_axis

Measured energy bins (Em).

Return type:

histpy.Axes

class cosipy.response.FullDetectorResponse(*args: Any, **kwargs: Any)

Handles the multi-dimensional matrix that describes the full all-sky response of the instrument.

You can access the DetectorResponse at a given pixel using the [] operator. Alternatively you can obtain the interpolated reponse using get_interp_response().

classmethod open(filename, Spectrumfile=None, norm='Linear', single_pixel=False, alpha=0, emin=90, emax=10000, polarization=False)

Open a detector response file.

Parameters:

• filename (str, Path)

• .rsp) (Path to the response file (.h5 or)

• Spectrumfile (str,) –

  path to the input spectrum file used

  for the simulation (optional).

  normstr,

  type of normalisation : file (then specify also SpectrumFile) ,powerlaw, Mono or Linear

  alphaint,

  if the normalisation is “powerlaw”, value of the spectral index.

  single_pixelbool,

  True if there is only one pixel and not full-sky.

  emin,emaxfloat

  emin/emax used in the simulation source file.

property is_sparse

property ndim

Dimensionality of detector response matrix.

Return type:

int

property axes

List of axes.

Return type:

histpy.Axes

property unit

Physical unit of the contents of the detector reponse.

Return type:

astropy.units.Unit

close()

Close the HDF5 file containing the response

property filename

Path to on-disk file containing DetectorResponse

Return type:

Path

get_interp_response(coord)

Get the bilinearly interpolated response at a given coordinate location.

Parameters:

coord (astropy.coordinates.SkyCoord) – Coordinate in the SpacecraftFrame

Return type:

DetectorResponse

get_point_source_response(exposure_map=None, coord=None, scatt_map=None, Earth_occ=True)

Convolve the all-sky detector response with exposure for a source at a given sky location.

Provide either a exposure map (aka dweel time map) or a combination of a sky coordinate and a spacecraft attitude map.

Parameters:

• exposure_map (mhealpy.HealpixMap) – Effective time spent by the source at each pixel location in spacecraft coordinates

• coord (astropy.coordinates.SkyCoord) – Source coordinate

• scatt_map (SpacecraftAttitudeMap) – Spacecraft attitude map

• Earth_occ (bool, optional) – Option to include Earth occultation in the respeonce. Default is True, in which case you can only pass one coord, which must be the same as was used for the scatt map.

Return type:

PointSourceResponse

get_point_source_response_per_image_pixel(ipix_image, orientation, coordsys='galactic', nside_image=None, nside_scatt_map=None, Earth_occ=True)

Generate point source response for a specific HEALPix pixel by convolving the all-sky detector response with exposure.

Parameters:

• ipix_image (int) – HEALPix pixel index

• orientation (cosipy.spacecraftfile.SpacecraftFile) – Spacecraft attitude information

• coordsys (str, default 'galactic') – Coordinate system (currently only ‘galactic’ is supported)

• nside_image (int, optional) – NSIDE parameter for image reconstruction. If None, uses the detector response’s NSIDE.

• nside_scatt_map (int, optional) – NSIDE parameter for scatt map generation. If None, uses the detector response’s NSIDE.

• Earth_occ (bool, default True) – Whether to include Earth occultation in the response

Returns:

Point source response for the specified pixel

Return type:

PointSourceResponse

get_extended_source_response(orientation, coordsys='galactic', nside_image=None, nside_scatt_map=None, Earth_occ=True)

Generate extended source response by convolving the all-sky detector response with exposure over the entire sky.

Parameters:

• orientation (cosipy.spacecraftfile.SpacecraftFile) – Spacecraft attitude information

• coordsys (str, default 'galactic') – Coordinate system (currently only ‘galactic’ is supported)

• nside_image (int, optional) – NSIDE parameter for image reconstruction. If None, uses the detector response’s NSIDE.

• nside_scatt_map (int, optional) – NSIDE parameter for scatt map generation. If None, uses the detector response’s NSIDE.

• Earth_occ (bool, default True) – Whether to include Earth occultation in the response

Returns:

Extended source response covering the entire sky

Return type:

ExtendedSourceResponse

merge_psr_to_extended_source_response(basename, coordsys='galactic', nside_image=None)

Create extended source response by merging multiple point source responses.

Reads point source response files matching the pattern basename + index + file_extension. For example, with basename=’histograms/hist_’, filenames are expected to be like ‘histograms/hist_00001.hdf5’.

Parameters:

• basename (str) – Base filename pattern for point source response files

• coordsys (str, default 'galactic') – Coordinate system (currently only ‘galactic’ is supported)

• nside_image (int, optional) – NSIDE parameter for image reconstruction. If None, uses the detector response’s NSIDE.

Returns:

Combined extended source response

Return type:

ExtendedSourceResponse

class cosipy.response.ExtendedSourceResponse(*args: Any, **kwargs: Any)

A class to represent and manipulate extended source response data.

This class provides methods to load data from HDF5 files, access contents, units, and axes information, and calculate expectations based on sky models.

get_expectation(allsky_image_model)

Calculate expectation based on an all-sky image model.

get_expectation_from_astromodel(source)

Calculate expectation from an astronomical model source.

Notes

Currently, the axes of the response must be [‘NuLambda’, ‘Ei’, ‘Em’, ‘Phi’, ‘PsiChi’].

classmethod open(filename, name='hist')

Load data from an HDF5 file.

Parameters:

• filename (str) – The path to the HDF5 file.

• name (str, optional) – The name of the histogram group in the HDF5 file (default is ‘hist’).

Returns:

A new instance of ExtendedSourceResponse with loaded data.

Return type:

ExtendedSourceResponse

Raises:

ValueError – If the shape of the contents does not match the axes.

get_expectation(allsky_image_model)

Calculate expectation based on an all-sky image model.

Parameters:

allsky_image_model (Histogram) – The all-sky image model to use for calculation.

Returns:

A histogram representing the calculated expectation.

Return type:

Histogram

get_expectation_from_astromodel(source)

Calculate expectation from an astromodels extended source model.

This method creates an AllSkyImageModel based on the current axes configuration, sets its values from the provided astromodels extended source model, and then calculates the expectation using the get_expectation method.

Parameters:

source (astromodels.ExtendedSource) – An astromodels extended source model object. This model represents the spatial and spectral distribution of an extended astronomical source.

Returns:

A histogram representing the calculated expectation based on the provided extended source model.

Return type:

Histogram