# 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.

# 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), subject to
the non-commercial use condition (see LICENSE_EXT.txt)

```
DarkMappy
Copyright (C) 2022 Matthew A. Price, Jason D. McEwen & contributors
This program is released under the GPL-3 license (see LICENSE.txt),
subject to a non-commercial use condition (see LICENSE_EXT.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.
```