astro-informatics / darkmappy

Scalable mapping of the dark universe

DarkMappy: mapping the dark universe

darkmappy is a lightweight python package which implements the hybrid Bayesian dark-matter reconstruction techniques outlined on the plane in Price et al. 2019, and on the celestial sphere in Price et al. 2021. For comparison (and as initilaisiation for our iterations) the spherical Kaiser-Squires estimator of the convergence is implemented (see Wallis et al. 2021). These techniques are based on maximum a posteriori estimation which, by construction, support principled uncertainty quantification, see Pereyra 2016. Further examples of such uncertainty quantification techniques developed for the weak lensing setting can be found in related articles Price et al. 2019a and Price et al. 2019b.

INSTALLATION

darkmappy can be installed through PyPi by running

pip install darkmappy 

or alternatively from source by running the following

git clone https://github.com/astro-informatics/DarkMappy.git
cd DarkMappy 
bash build_darkmappy.sh 

following which the test suite can be executed by running

pytest --black darkmappy/tests

BASIC USAGE

For planar reconstructions across the flat-sky the estimator can be run by the following, note that images must be square.

import numpy as np
import darkmappy.estimators as dm

# LOAD YOUR DATA
data = np.load(<path_to_shear_data>)
ngal = np.load(<path_to_ngal_per_pixel_map>)
mask = np.load(<path_to_observation_mask>)

# BUILD THE ESTIMATOR 
dm_estimator = dm.DarkMappyPlane(
           n = n,                   # Dimension of image
        data = data,                # Observed shear field
        mask = mask,                # Observational mask
        ngal = ngal,                # Map of number density of observations per pixel
         wav = [<select_wavelets>], # see https://tinyurl.com/mrxeat3t
      levels = level,               # Wavelet levels
 supersample = supersample)         # Super-resolution factor (typically <~2)

# RUN THE ESTIMATOR
convergence, diagnostics = dm_estimator.run_estimator()

For spherical reconstructions across the full-sky the estimator can be run by the following, note images must be of dimension L by 2L-1, see McEwen & Wiaux 2011.

import numpy as np
import darkmappy.estimators as dm

# LOAD YOUR DATA
data = np.load(<path_to_shear_data>)
ngal = np.load(<path_to_ngal_per_pixel_map>)
mask = np.load(<path_to_observation_mask>)

# BUILD THE ESTIMATOR
dm_estimator = dm.DarkMapperSphere(
           L = L,             # Angular Bandlimit    
           N = N,             # Azimuthal Bandlimit (wavelet directionality)
        data = data,          # Observational shear data
        mask = mask,          # Observation mask
        ngal = ngal)          # Map of number density of observations per pixel

# RUN THE ESTIMATOR 
convergence, diagnostics = dm_estimator.run_estimator()

CONTRIBUTORS

Matthew A. Price, Jason D. McEwen & Contributors

ATTRIBUTION

A BibTeX entry for darkmappy is:

@article{price:2021:spherical,
        title = {Sparse Bayesian mass-mapping with uncertainties: Full sky observations on the celestial sphere},
       author = {M.~A.~Price and J.~D.~McEwen and L.~Pratley and T.~D.~Kitching},
      journal = {Monthly Notices of the Royal Astronomical Society},
         year = 2021,
        month = jan,
       volume = {500},
       number = {4},
        pages = {5436-5452},
          doi = {10.1093/mnras/staa3563},
    publisher = {Oxford University Press}
}

@article{price:2021:hypothesis,
        title = {Sparse Bayesian mass mapping with uncertainties: hypothesis testing of structure},
       author = {M.~A.~Price and J.~D.~McEwen and X.~Cai and T.~D.~Kitching and C.~G.~R.~Wallis and {LSST Dark Energy Science Collaboration}},
      journal = {Monthly Notices of the Royal Astronomical Society},
         year = 2021,
        month = jul,
       volume = {506},
       number = {3},
        pages = {3678--3690},
          doi = {10.1093/mnras/stab1983},
    publisher = {Oxford University Press}
}

If, at any point, the direction inverse functionality (i.e. spherical Kaiser-Squires) please cite

@article{wallis:2021:massmappy,
        title = {Mapping dark matter on the celestial sphere with weak gravitational lensing},
       author = {C.~G.~R.~Wallis and M.~A.~Price and J.~D.~McEwen and T.~D.~Kitching and B.~Leistedt and A.~Plouviez},
      journal = {Monthly Notices of the Royal Astronomical Society},
         year = 2021,
        month = Nov,
       volume = {509},
       number = {3},
        pages = {4480-4497},
          doi = {10.1093/mnras/stab3235},
    publisher = {Oxford University Press}
}

Finally, if uncertainty quantification techniques which rely on the approximate level-set threshold (derived by Pereyra 2016) are performed please consider citing relating articles appropriately.

LICENSE

darkmappy is released under the GPL-3 license (see LICENSE.txt).

DarkMappy
Copyright (C) 2022 Matthew A. Price, Jason D. McEwen & contributors

This program is released under the GPL-3 license (see LICENSE.txt).

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

darkmappy's Issues

SNR calculation

In darkmappy.validation the snr is calculated as

return 10.0 * np.log(l2_true / l2_diff)

but it should use
return 20.0 * np.log10(l2_true / l2_diff)

Need to be careful with the np.linalg.norm(x, ord=2) calls to calculate L2 norms as this behaves slightly differently for arrays (images) or flattened vectors. Also it doesn't return the squared norm, hence the new factor of 2.