Description

The S2LET code provides functionality to compute fast wavelet transforms of signals on the sphere. It uses the SSHT and SO3 codes to compute fast and exact spherical harmonic and Wigner transforms. The resulting wavelet transform is theoretically exact, i.e. wavelet coefficients capture all information of a band-limited signal and the original signal can be recovered exactly from its wavelet coefficients. S2LET also supports the HEALPix sampling scheme, in which case the transforms are not theoretically exact but achieve good numerical accuracy.

This documentation describes installation details and documents the source code. Reference, author and license information is also given. The code itself is hosted on GitHub.

Scale discretised wavelets on the sphere

S2LET supports scale-discretised axisymmetric and directional wavelets (Wiaux et al. 2008, Leisted et al. 2012, McEwen et al. 2018), spin wavelets (McEwen et al. 2015), ridgelets (McEwen & Price 2019), and curvelets (Chan et al. 2017).

Fast and exact algorithms are implemented to compute forward and inverse wavelet transforms by leveraging fast and exact algorithms to compute harmonic transforms on the sphere (McEwen & Wiaux 2011) and rotation group (McEwen et al. 2015), implemented in the SSHT and SO3 codes, respectively.

Scale-discretised wavelets are constructed through an exact tiling of harmonic space. The harmonic line is tiled into wavelet kernels which are localised in both real and frequency spaces, as shown on the image below for a particular set of wavelet parameters (B=2, J_min=2, harmonic space on the left, corresponding kernels on the right).

      

Scale-discretised wavelets on the sphere satisfy excellent spatial localisation and asymptotic correlation properties , as shown in McEwen et al. (2018).

A band-limited signal may be decomposed into a set of wavelet maps that exactly capture all the information content of the original signal. The original signal may then be synthesised exactly from its wavelet coefficients (at machine precision). Due to the nature of the tiling in harmonic space, the individual wavelet maps have different band-limits and hence can be reconstructed at different resolutions, i.e. with the minimal number of samples. The left and right panels below are the wavelet decomposition of Earth tomography data at full (left) and multi-resolution (right). Due to the exactness of all transforms, these two approaches are equivalent and capture all the information contained in the initial band-limited map.

         

When using HEALPix instead of the sampling on the sphere of McEwen & Wiaux (2011), the harmonic transform is not exact and hence the corresponding wavelet transform performed by S2LET is only exact in harmonic space. In other words, a set of spherical harmonic coefficients may be projected onto wavelets exactly in harmonic spaces but the HEALPix maps don't capture all the information contained in these coefficients. However good numerical accuracy is achieved in a wide range of situations.

Spin wavelets

The framework of scale-discretised wavelets was extended in McEwen et al. (2015) to support spin signals. The figure below shows the real, imaginary and absolute part of a spin wavelet.

Ridgelets

S2LET supports the spherical ridgelet transform developed in McEwen & Price (2019). The ridgelet transform is defined natively on the sphere, probes signal content globally along great circles, does not exhibit any blocking artefactes, does not rely on any ad hoc parameters, and permits the exact inversion for antipodal signals. The figure below shows spherical ridgelets, with axis aligned with the North pole, for wavelet scales j=3 and 4, plotted on the sphere and parametrically.

Curvelets

S2LET also supports scale-discretised curvelets, as developed in Chan (2017), which are efficient for representing local linear and curvilinear structure and admit exact inversion for both scalar and spin signals. The figure below shows spherical curvelets, with axis aligned with the North pole, for various wavelet scales j, plotted on the sphere.

Installation

The S2LET package in based on a core C implementation. Python, Matlab and IDL interfaces to the C implementation are provided.

Dependencies

S2LET requires the SSHT, SO3, and FFTW libraries. The IO FITS features require CFITSIO. To support HEALPix, a valid installation of its Fortran implementation must be provided.

Python installation

The python package, pys2let, is available on pypi and can be installed with: 

pip install pys2let

The python package is backed by scikit-build and CMake. It will install a local version of FFTW and will compile its own version of the C package.

Alternatively, the python package can be installed from a local clone of the repository for development purposes by 

pip install -e .[dev]

C installation

The C package can be installed with CMake and conan.

Both can be installed using pip: 

pip install conan cmake

Then S2LET can be compiled with: 

  git clone https://github.com/astro-informatics/s2let.git
  mkdir s2let/build && cd s2let/build
  cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local -Dconan_deps=ON  -Dcfitsio=ON ..
  make
  make install

The above will also download FFTW, SSHT and SO3, if necessary.

Matlab installation

The Matlab interface requires the C version to be installed.

It can be built using make by configuring appropriate compilers and dependencies, and then running: 

make matlab

IDL installation

The IDL interface requires the dynamic C library to first be built using make. The variable S2LET must then be defined in Bash/Shell and point to the root of the S2LET directory so that IDL can find the dynamic library.

Source code documentation

S2LET code is self documented. Source code documentation for each language is available here:

Referencing

If you use S2LET for work that results in publication, please reference https://github.com/astro-informatics/s2let/ and cite the relevant academic paper(s):

Y. Wiaux, J. D. McEwen, P. Vandergheynst, O. Blanc, Exact reconstruction with directional wavelets on the sphere, Mon. Not. Roy. Astron. Soc., 388(2):770-788, 2008. (ArXiv | DOI).
B. Leistedt, J. D. McEwen, P. Vandergheynst and Y. Wiaux, S2LET: A code to perform fast wavelet analysis on the sphere, Astronomy & Astrophysics, 558(A128):1-9, 2013 (ArXiv | DOI).
J. D. McEwen, B. Leistedt, M. Büttner, H. V. Peiris, Y. Wiaux, Directional spin wavelets on the sphere, IEEE Trans. Signal Proc., submitted, 2015 (ArXiv).
J. D. McEwen, M. Price, Ridgelet transform on the sphere, 27th European Signal Processing Conference (EUSIPCO), 2019 (ArXiv | DOI).
J. Y. H. Chan, B. Leistedt, T. D. Kitching, J. D. McEwen, Second-generation curvelets on the sphere, IEEE Trans. Signal Proc., 65(1):5-14, 2017 (ArXiv | DOI).
J. D. McEwen, C. Durastanti, Y. Wiaux, Localisation of directional scale-discretised wavelets on the sphere, Applied Comput. Harm. Anal., 44(1), 59-88, 2018 (ArXiv | DOI).

You may also like to consider citing the following papers on which the fast algorithms of S2LET are based:

J. D. McEwen, M. Büttner, B. Leistedt, H. V. Peiris, Y. Wiaux, A novel sampling theorem on the rotation group, IEEE Sig. Proc. Let., 22(12):2425-2429, 2015 (ArXiv | DOI).
J. D. McEwen and Y. Wiaux, A novel sampling theorem on the sphere, IEEE Trans. Signal Proc., 59, 5876-5887, 2011 (ArXiv | DOI).

License

S2LET package to perform fast wavelet transform on the sphere
Copyright (C) 2012- Boris Leistedt, Jason McEwen, Martin Büttner and contributors

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

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. See the GNU General Public License for more details (License.txt).

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.


Authors

S2LET was initially developed by Boris Leistedt, Martin Büttner, and Jason McEwen but significant contributors have since been made by a number of others.