Refactoring image deconvolution classes

[hiyoneda]

This PR improves code maintainability through three key refactorings:

1. Centralize magic numbers into constants.py

   Added the new filecosipy/image_deconvolution/constants.py and centralized magic numbers and default values

2. Reduce code duplication in finalization methods

   Added _save_standard_results() method in DeconvolutionAlgorithmBase because the common save logic was used in three classes (RichardsonLucySimple, RichardsonLucy, MAP_RichardsonLucy)

3. Improved Error Messages
   Files modified: image_deconvolution.py

   • model_initialization(): Shows available model classes
   • register_deconvolution_algorithm(): Shows available algorithms

[codecov]

Codecov Report

❌ Patch coverage is 93.68132% with 46 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.91%. Comparing base (cb14438) to head (a2420e2).

Files with missing lines	Patch %	Lines
...e_deconvolution/data_interfaces/dataIF_Parallel.py	25.00%	15 Missing ⚠️
...ution/data_interfaces/data_interface_collection.py	85.96%	8 Missing ⚠️
...deconvolution/algorithms/RichardsonLucyAdvanced.py	94.95%	6 Missing ⚠️
...ge_deconvolution/algorithms/RichardsonLucyBasic.py	94.36%	4 Missing ⚠️
...y/image_deconvolution/algorithms/RichardsonLucy.py	96.72%	2 Missing ⚠️
...lution/algorithms/accelerators/accelerator_base.py	95.45%	2 Missing ⚠️
...ution/algorithms/accelerators/build_accelerator.py	87.50%	2 Missing ⚠️
...onvolution/algorithms/response_weighting_filter.py	88.23%	2 Missing ⚠️
cosipy/image_deconvolution/image_deconvolution.py	91.30%	2 Missing ⚠️
cosipy/image_deconvolution/RLparallelscript.py	0.00%	1 Missing ⚠️
... and 2 more

Files with missing lines	Coverage Δ
cosipy/image_deconvolution/__init__.py	100.00% <100.00%> (ø)
cosipy/image_deconvolution/algorithms/__init__.py	100.00% <100.00%> (ø)
..._deconvolution/algorithms/accelerators/__init__.py	100.00% <100.00%> (ø)
...on/algorithms/accelerators/max_step_accelerator.py	100.00% <100.00%> (ø)
...olution/algorithms/deconvolution_algorithm_base.py	94.11% <100.00%> (ø)
...osipy/image_deconvolution/algorithms/prior_base.py	100.00% <ø> (ø)
...py/image_deconvolution/algorithms/prior_entropy.py	100.00% <100.00%> (ø)
cosipy/image_deconvolution/algorithms/prior_tsv.py	100.00% <100.00%> (ø)
cosipy/image_deconvolution/constants.py	100.00% <100.00%> (ø)
...py/image_deconvolution/data_interfaces/__init__.py	100.00% <100.00%> (ø)
... and 24 more

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[hiyoneda]

#259 (comment)

For the future, I think it would be nice if RichardLucySimple were kept, well, simple 😬. That is, with the minimal set of parameters to make it work. You could add an intermediate class e.g. RLAugmented, deriving from RLSimple and adding these extra parameters, and RL and MAP_RL can derive from RLAugmented. Maybe other naming conventions would be better, but you get the point. This doesn't prevent this from being merged, just something for later, as RichardLucySimple can be the landing point for new students.

I will work on this in this PR. So I changed the status to the draft PR till it is finished.

[hiyoneda]

The structure of the deconvolution classes is modified as follows.

RichardsonLucySimple is renamed to RichardsonLucyBasic to better reflect its role as an educational entry point for understanding the core EM structure of the RL algorithm.

A new class RichardsonLucyAdvanced is introduced between RichardsonLucy and MAP_RichardsonLucy, giving the following 4-level hierarchy:

RichardsonLucyBasic       – core RL (E-step + M-step, minimum flux, masking)
  └─ RichardsonLucy       – + background normalization optimization
       ├─ RichardsonLucyAdvanced  – + response weighting, acceleration, smoothing
       └─ MAP_RichardsonLucy      – + response weighting, prior distributions

Two helper methods are extracted to reduce duplication and improve reuse across subclasses:

• _ensure_model_constraints() defined in RichardsonLucyBasic: enforces minimum flux and masking after each model update
• _ensure_bkg_norm_range() defined in RichardsonLucy: clips background normalization values to their allowed range

A new class ResponseWeightingFilter is introduced to encapsulate the response weighting filter. It takes exposure_map and index at initialization and computes the filter internally, exposing an apply() method.

A bug was fixed where bkg_norm stored in results was showing the same value across iterations during the refactoring. The cause was that astropy.Quantity uses in-place +=, so dict.copy() (shallow copy) was storing references to the same object. This is fixed by converting to float in _ensure_bkg_norm_range() via float(bkg_norm.to('')) when the value is a Quantity. The same pattern is applied to log_likelihood, log_prior, and log_posterior in the relevant methods.

[hiyoneda]

Module reorganization

• Split module into subdirectories: algorithms/, models/, data_interfaces/
• Added DataInterfaceCollection to manage multiple data interfaces
• Added calc_source_expectation and calc_bkg_expectation to DataInterfaceCollection and ImageDeconvolutionDataInterface

Accelerator framework

• Added AcceleratorBase and MaxStepAccelerator
• Added LineSearchAccelerator with 1-D (Brent) and 2-D (gradient/grid) search modes
• Added accel_bkg_norm support to both accelerators
• Added logged_result_fields to AcceleratorBase for structured iteration logging
• Renamed do_* variables to *_enabled for clarity

Parameter and logging

• Added parameter_summary display at algorithm initialization
• Refactored logging across deconvolution modules
• Refactored finalization in deconvolution algorithms

Documentation

• Added docstrings with mathematical definitions for PriorBase, PriorTSV, PriorEntropy, and MAP_RichardsonLucy
• Renamed prior_map to reference_map in entropy prior

[hiyoneda]

@avalluvan This PR includes minor changes to DataIF_COSI_Parallel. The modifications are limited to adding calc_source_expectation and calc_bkg_expectation as a split from calc_expectation, following a small base class interface change. These should be compatible, but please take a look when you have a chance.

[israelmcmc]

Thanks @GallegoSav and @hiyoneda! I'll wait a bit to merge this until we merge the interfaces, in order to avoid possible further conflicts. @GallegoSav mentioned a possible conflict with cosipy.spacecraftfile, but it seems that's only in a docstring whic probably need to be updated anyway, since SpacecraftAttitudeExposureTable was moved to the imaging module. It might be fine and have no conflict. Alternatively, @hiyoneda, if you don't want to wait you can rebase to the interfaces branch and merge it directly there if you see that everything is working.

[hiyoneda]

@israelmcmc Thanks. I will work on the background estimator from now. So I can wait for the interface being merged for a while.

[GallegoSav]

@hiyoneda @israelmcmc is this pr ready to be merged now ?

[israelmcmc]

I think so, it seems that @hiyoneda already fixed the conflict with the interfaces. Does it still work for you @GallegoSav ?

[hiyoneda]

I fixed the conflict. If someone checks that the imaging notebook works correctly (@GallegoSav can I ask you to do that?), it is ready to be merged in my opinion.