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 histogrambkg_binned_data (
histpy.Histogram
) – Background modelrsp (
histpy.Histogram
orcosipy.response.FullDetectorResponse
) – Responsecoordsys_conv_matrix (
cosipy.image_deconvolution.CoordsysConversionMatrix
) – Coordsys conversion matrixis_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:
- 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:
- set_rsp_from_filepath(filepath)[source]
Load response matrix from file pathes
- Parameters:
filepath (str) – File path of the response matrix.
- class cosipy.image_deconvolution.ModelMap(*args: Any, **kwargs: Any)[source]
Photon flux maps in given energy bands. 2-dimensional histogram.
- energy_edges
Bin edges for energies. We recommend to use a Quantity array with the unit of keV.
- Type:
np.array
- coordsys
Instrinsic coordinates of the map. The default is ‘galactic’.
- Type:
str or
astropy.coordinates.BaseRepresentation
, default is ‘galactic’
- 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, …]}.
- 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.
- 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
- 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
) – Orientationnside (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 orientationstop (
astropy.time.Time
or None, default None) – Stop time to analyze the orientationmin_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
) – Orientationnside (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 orientationstop (
astropy.time.Time
or None, default None) – Stop time to analyze the orientationmin_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:
- 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
) – Responseorientation (
cosipy.spacecraftfile.SpacecraftFile
) – Orientationtime_intervals (
np.array
) – The same format of binned_data.axes[‘Time’].edgesnside_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:
- 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
) – Responseexposure_table (
cosipy.image_deconvolution.SpacecraftAttitudeExposureTable
) – Scatt exposure tablenside_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’