Image deconvolution

class cosipy.image_deconvolution.DataLoader[source]

A class to manage data for image analysis, namely event data, background model, response, coordsys conversion matrix. Ideally, these data should be input directly to ImageDeconvolution class, but considering their data formats are not fixed, this class is introduced. The purpose of this class is to check the consistency between input data and calculate intermediate files etc. In the future, this class may be removed or hidden in ImageDeconvolution class.

classmethod load(event_binned_data, bkg_binned_data, rsp, coordsys_conv_matrix, is_miniDC2_format=False)[source]

Load data

Parameters:

event_binned_data (histpy.Histogram) – Event histogram
bkg_binned_data (histpy.Histogram) – Background model
rsp (histpy.Histogram or cosipy.response.FullDetectorResponse) – Response
coordsys_conv_matrix (cosipy.image_deconvolution.CoordsysConversionMatrix) – Coordsys conversion matrix
is_miniDC2_format (bool, default False) – Whether the file format is for mini-DC2. It will be removed in the future.

Returns:

DataLoader instance containing the input data set

Return type:

cosipy.image_deconvolution.DataLoader

classmethod load_from_filepath(event_hdf5_filepath=None, event_yaml_filepath=None, bkg_hdf5_filepath=None, bkg_yaml_filepath=None, rsp_filepath=None, ccm_filepath=None, is_miniDC2_format=False)[source]

Load data from file pathes

Parameters:

event_hdf5_filepath (str or None, default None) – File path of HDF5 file for event histogram.
event_yaml_filepath (str or None, default None) – File path of yaml file to read the HDF5 file.
bkg_hdf5_filepath (str or None, default None) – File path of HDF5 file for background model.
bkg_yaml_filepath (str or None, default None) – File path of yaml file to read the HDF5 file.
rsp_filepath (str or None, default None) – File path of the response matrix.
ccm_filepath (str or None, default None) – File path of the coordsys conversion matrix.
is_miniDC2_format (bool, default False) – Whether the file format is for mini-DC2. should be removed in the future.

Returns:

DataLoader instance containing the input data set

Return type:

cosipy.image_deconvolution.DataLoader

set_event_from_filepath(hdf5_filepath, yaml_filepath)[source]

Load event data from file pathes

Parameters:

hdf5_filepath (str) – File path of HDF5 file for event histogram.
yaml_filepath (str) – File path of yaml file to read the HDF5 file.

set_bkg_from_filepath(hdf5_filepath, yaml_filepath)[source]

Load background model from file pathes

Parameters:

hdf5_filepath (str) – File path of HDF5 file for background model.
yaml_filepath (str) – File path of yaml file to read the HDF5 file.

set_rsp_from_filepath(filepath)[source]

Load response matrix from file pathes

Parameters:: filepath (str) – File path of the response matrix.

set_ccm_from_filepath(filepath)[source]

Load coordsys conversion matrix from file pathes

Parameters:: filepath (str) – File path of the coordsys conversion matrix.

load_full_detector_response_on_memory()[source]: Load a response file on the computer memory.

calc_image_response_projected()[source]: Calculate image_response_dense_projected, which is an intermidiate matrix used in RL algorithm.

class cosipy.image_deconvolution.ModelMap(*args: Any, **kwargs: Any)[source]

Photon flux maps in given energy bands. 2-dimensional histogram.

nside

Healpix NSIDE parameter.

Type:: int

energy_edges

Bin edges for energies. We recommend to use a Quantity array with the unit of keV.

Type:: np.array

scheme

Healpix scheme. Either ‘ring’, ‘nested’.

Type:: str, default ‘ring’

coordsys

Instrinsic coordinates of the map. The default is ‘galactic’.

Type:: str or astropy.coordinates.BaseRepresentation, default is ‘galactic’

label_image

The label name of the healpix axis.

Type:: str, default ‘lb’

label_energy

The label name of the energy axis. The default is ‘Ei’.

Type:: str, default ‘Ei’

set_values_from_parameters(algorithm_name, parameter)[source]

Set the values of this model map accordinng to the specified algorithm.

Parameters:

algorithm_name (str) – Algorithm name to fill the values.
parameter (py:class:cosipy.config.Configurator) – Parameters for the specified algorithm.

Notes

Currently algorithm_name can be only ‘flat’. All of the pixel values in each energy bins will set to the given value. parameter should be {‘values’: [ flux value at 1st energy bin (without unit), flux value at 2nd energy bin, …]}.

set_values_from_extendedmodel(extendedmodel)[source]

Set the values of this model map accordinng to the given astromodels.ExtendedSource.

Parameters:: extendedmodel (astromodels.ExtendedSource) – Extended source model

class cosipy.image_deconvolution.ImageDeconvolution[source]

A class to reconstruct all-sky images from COSI data based on image deconvolution methods.

set_data(data)[source]

Set COSI dataset

Parameters:: data (cosipy.image_deconvolution.DataLoader) – Data loader contaning an event histogram, a background model, a response matrix, and a coordsys_conversion_matrix.

Notes

cosipy.image_deconvolution.DataLoader may be removed in the future once the formats of event/background/response are fixed. In this case, this method will be also modified in the future.

read_parameterfile(parameter_filepath)[source]

Read parameters from a yaml file.

Parameters:: parameter_filepath (str or pathlib.Path) – Path of parameter file.

property data: Return the set data.

property parameter: Return the set parameter.

override_parameter(*args)[source]

Override parameter

Parameters:: *args – new parameter

Examples

>>> image_deconvolution.override_parameter("deconvolution:parameter_RL:iteration = 30")

property initial_model_map: Return the initial model map.

initialize()[source]

Initialize an image_deconvolution instance. It is mandatory to execute this method before running the image deconvolution.

This method has three steps: 1. generate a model map with properties (nside, energy bins, etc.) given in the parameter file. 2. initialize a model map following an initial condition given in the parameter file 3. load parameters for the image deconvolution

register_deconvolution_algorithm(parameter_deconvolution)[source]

Register parameters for image deconvolution on a deconvolution instance.

Parameters:: parameter_deconvolution (cosipy.config.Configurator) – Parameters for the image deconvolution methods.

Notes

Currently only RichardsonLucy algorithm is implemented.

*An example of parameters for RL algorithm* algorithm: “RL” parameter_RL:

iteration: 10 # number of iterations acceleration: True # whether the accelerated ML-EM algorithm (Knoedlseder+99) is used alpha_max: 10.0 # the maximum value for the acceleration alpha parameter save_results_each_iteration: False # whether a updated model map, detal map, likelihood etc. are save at the end of each iteration response_weighting: True # whether a factor $w_j = (sum_{i} R_{ij})^{eta}$ for weighting the delta image is introduced # see Knoedlseder+05, Siegert+20 response_weighting_index: 0.5 # $eta$ in the above equation smoothing: True # whether a Gaussian filter is used (see Knoedlseder+05, Siegert+20) smoothing_FWHM: 2.0 #deg # the FWHM of the Gaussian in the filter background_normalization_fitting: False # whether the background normalization is optimized at each iteration. # As for now, the same single background normalization factor is used in all of the time bins background_normalization_range: [0.01, 10.0] # the range of the normalization factor. it should be positive.

run_deconvolution()[source]

Perform the image deconvolution. Make sure that the initialize method has been conducted.

Returns:: List containing results (reconstructed image, likelihood etc) at each iteration.
Return type:: list

class cosipy.image_deconvolution.SpacecraftAttitudeExposureTable(*args: Any, **kwargs: Any)[source]

A class to analyze exposure time per each spacecraft attitude

Table columns are: - scatt_binning_index: int - healpix_index: list of tuple. Each tuple is (healpix_index_zpointing, healpix_index_xpointing). - zpointing: np.array of [l, b] in degrees. Array of z-pointings assigned to each scatt bin. - xpointing: np.array of [l, b] in degrees. Array of x-pointings assigned to each scatt bin. - zpointing_averaged: [l, b] in degrees. Averaged z-pointing in each scatt bin. - xpointing_averaged: [l, b] in degrees. Averaged x-pointing in each scatt bin. - delta_time: np.array of float in second. Exposure times for pointings assigned to each scatt bin. - exposure: float in second. total exposure for each scatt bin. - num_pointings: number of pointings assigned to each scatt bin. - bkg_group: index of the backgroud group. will be used in the data analysis.

df

pandas dataframe with the above columns

Type:: pd.DataFrame

nside

Healpix NSIDE parameter.

Type:: int

scheme

Healpix scheme. Either ‘ring’, ‘nested’.

Type:: str, default ‘ring’

classmethod from_pickle(filename, nside, scheme='ring')[source]

Read exposure table from pickle.

Parameters:

filename (str) – Path to file
nside (int) – Healpix NSIDE parameter.
scheme (str, default 'ring') – Healpix scheme. Either ‘ring’, ‘nested’.

Return type:

cosipy.spacecraftfile.SpacecraftAttitudeExposureTable

classmethod from_orientation(orientation, nside, scheme='ring', start=None, stop=None, min_exposure=None, min_num_pointings=None)[source]

Produce exposure table from orientation.

Parameters:

orientation (cosipy.spacecraftfile.SpacecraftFile) – Orientation
nside (int) – Healpix NSIDE parameter.
scheme (str, default 'ring') – Healpix scheme. Either ‘ring’, ‘nested’.
start (astropy.time.Time or None, default None) – Start time to analyze the orientation
stop (astropy.time.Time or None, default None) – Stop time to analyze the orientation
min_exposure (float or None, default None) – Minimum exposure time required for each scatt bin
min_num_pointings (int or None, default None) – Minimum number of pointings required for each scatt bin

Return type:

cosipy.spacecraftfile.SpacecraftAttitudeExposureTable

classmethod analyze_orientation(orientation, nside, scheme='ring', start=None, stop=None, min_exposure=None, min_num_pointings=None)[source]

Produce pd.DataFrame from orientation.

Parameters:

orientation (cosipy.spacecraftfile.SpacecraftFile) – Orientation
nside (int) – Healpix NSIDE parameter.
scheme (str, default 'ring') – Healpix scheme. Either ‘ring’, ‘nested’.
start (astropy.time.Time or None, default None) – Start time to analyze the orientation
stop (astropy.time.Time or None, default None) – Stop time to analyze the orientation
min_exposure (float or None, default None) – Minimum exposure time required for each scatt bin
min_num_pointings (int or None, default None) – Minimum number of pointings required for each scatt bin

Return type:

pd.DataFrame

classmethod from_fits(filename)[source]

Read exposure table from a fits file.

Parameters:: filename (str) – Path to file
Return type:: cosipy.image_deconvolution.SpacecraftAttitudeExposureTable

save_as_fits(filename, overwrite=False)[source]

Save exposure table as a fits file.

Parameters:

filename (str) – Path to file
overwrite (bool, default False)

calc_pointing_trajectory_map()[source]

Calculate a 2-dimensional map showing exposure time for each spacecraft attitude.

Return type:: cosipy.spacecraft.SpacecraftAttitudeMap

Notes

The default axes in SpacecraftAttitudeMap is x- and y-pointings, but here the spacecraft attitude is described with z- and x-pointings.

class cosipy.image_deconvolution.CoordsysConversionMatrix(*args: Any, **kwargs: Any)[source]

A class for coordinate conversion matrix (ccm).

classmethod time_binning_ccm(full_detector_response, orientation, time_intervals, nside_model=None, is_nest_model=False)[source]

Calculate a ccm from a given orientation.

Parameters:

full_detector_response (cosipy.response.FullDetectorResponse) – Response
orientation (cosipy.spacecraftfile.SpacecraftFile) – Orientation
time_intervals (np.array) – The same format of binned_data.axes[‘Time’].edges
nside_model (int or None, default None) – If it is None, it will be the same as the NSIDE in the response.
is_nest_model (bool, default False) – If scheme of the model map is nested, it should be False while it is rare.

Returns:

Its axes are [ “Time”, “lb”, “NuLambda” ].

Return type:

cosipy.image_deconvolution.CoordsysConversionMatrix

classmethod spacecraft_attitude_binning_ccm(full_detector_response, exposure_table, nside_model=None, use_averaged_pointing=False)[source]

Calculate a ccm from a given exposure_table.

Parameters:

full_detector_response (cosipy.response.FullDetectorResponse) – Response
exposure_table (cosipy.image_deconvolution.SpacecraftAttitudeExposureTable) – Scatt exposure table
nside_model (int or None, default None) – If it is None, it will be the same as the NSIDE in the response.
use_averaged_pointing (bool, default False) – If it is True, first the averaged Z- and X-pointings are calculated. Then the dwell time map is calculated once for ach model pixel and each scatt_binning_index. If it is False, the dwell time map is calculated for each attitude in zpointing and xpointing in the exposure table. Then the calculated dwell time maps are summed up. In the former case, the computation is fast but may lose the angular resolution. In the latter case, the conversion matrix is more accurate but it takes a long time to calculate it.

Returns:

Its axes are [ “ScAtt”, “lb”, “NuLambda” ].

Return type:

py:class:`cosipy.image_deconvolution.CoordsysConversionMatrix’

classmethod open(filename, name='hist')[source]

Open a ccm from a file.

Parameters:

filename (str) – Path to file.
name (str, default 'hist') – Name of group where the histogram was saved.

Returns:

Its axes are [ “lb”, “Time” or “ScAtt”, “NuLambda” ].

Return type:

py:class:`cosipy.image_deconvolution.CoordsysConversionMatrix’