|
| 1 | +--- |
| 2 | +layout: single |
| 3 | +title: "SLEPLET: Slepian Scale-Discretised Wavelets in Python" |
| 4 | +excerpt: SLEPLET is a tool to create Slepian scale-discretised wavelets that has recently passed the PyOpenSci review. |
| 5 | +author: Patrick J. Roddy |
| 6 | +permalink: /blog/sleplet-slepian-wavelets |
| 7 | +header: |
| 8 | + overlay_image: /images/sleplet/planck_2018_temp_mask.jpg |
| 9 | + overlay_filter: 0.5 |
| 10 | + caption: "Figure credit: [**The Planck Collaboration 2018**](https://www.aanda.org/articles/aa/full_html/2020/09/aa33881-18/F38.html)" |
| 11 | +categories: |
| 12 | + - blog-post |
| 13 | + - manifolds |
| 14 | + - signal-processing |
| 15 | + - wavelets |
| 16 | +comments: true |
| 17 | +--- |
| 18 | + |
| 19 | +[SLEPLET](https://github.com/astro-informatics/sleplet) is a Python package for |
| 20 | +the construction of Slepian wavelets in the spherical and manifold (via meshes) |
| 21 | +settings. In contrast to other codes, `SLEPLET` handles any spherical region as |
| 22 | +well as the general manifold setting. The API is documented and easily |
| 23 | +extendible, designed in an object-orientated manner. Upon installation, |
| 24 | +`SLEPLET` comes with two command line interfaces - `sphere` and `mesh` - that |
| 25 | +allow one to easily generate plots on the sphere and a set of meshes using |
| 26 | +[plotly](https://github.com/plotly/plotly.py). Whilst these scripts are the |
| 27 | +primary intended use, `SLEPLET` may be used directly to generate the Slepian |
| 28 | +coefficients in the spherical/manifold setting and use methods to convert these |
| 29 | +into real space for visualisation or other intended purposes. The construction |
| 30 | +of the sifting convolution was required to create Slepian wavelets. As a result, |
| 31 | +there are also many examples of functions on the sphere in harmonic space |
| 32 | +(rather than Slepian) that were used to demonstrate its effectiveness. `SLEPLET` |
| 33 | +has been used in the development of several papers. |
| 34 | + |
| 35 | +## Background |
| 36 | + |
| 37 | +Wavelets are widely used in various disciplines to analyse signals both in space |
| 38 | +and scale. Whilst many fields measure data on manifolds (i.e. the sphere), |
| 39 | +often data are only observed on a partial region of the manifold. Wavelets are a |
| 40 | +typical approach to data of this form, but the wavelet coefficients that overlap |
| 41 | +with the boundary become contaminated and must be removed for accurate analysis. |
| 42 | +Another approach is to estimate the region of missing data and to use existing |
| 43 | +whole-manifold methods for analysis. However, both approaches introduce |
| 44 | +uncertainty into any analysis. Slepian wavelets enable one to work directly with |
| 45 | +only the data present, thus avoiding the problems discussed above. Applications |
| 46 | +of Slepian wavelets to areas of research measuring data on the partial sphere |
| 47 | +include gravitational/magnetic fields in geodesy, ground-based measurements in |
| 48 | +astronomy, measurements of whole-planet properties in planetary science, |
| 49 | +geomagnetism of the Earth, and cosmic microwave background analyses. |
| 50 | + |
| 51 | +## Statement of Need |
| 52 | + |
| 53 | +Many fields in science and engineering measure data that inherently live on |
| 54 | +non-Euclidean geometries, such as the sphere. Techniques developed in the |
| 55 | +Euclidean setting must be extended to other geometries. Due to recent interest |
| 56 | +in geometric deep learning, analogues of Euclidean techniques must also handle |
| 57 | +general manifolds or graphs. Often, data are only observed over partial regions |
| 58 | +of manifolds, and thus standard whole-manifold techniques may not yield accurate |
| 59 | +predictions. Slepian wavelets are designed for datasets like these. Slepian |
| 60 | +wavelets are built upon the eigenfunctions of the Slepian concentration problem |
| 61 | +of the manifold: a set of bandlimited functions that are maximally concentrated |
| 62 | +within a given region. Wavelets are constructed through a tiling of the Slepian |
| 63 | +harmonic line by leveraging the existing scale-discretised framework. Whilst |
| 64 | +these wavelets were inspired by spherical datasets, like in cosmology, the |
| 65 | +wavelet construction may be utilised for manifold or graph data. |
| 66 | + |
| 67 | +To the author's knowledge, there is no public software that allows one to |
| 68 | +compute Slepian wavelets (or a similar approach) on the sphere or general |
| 69 | +manifolds/meshes. [SHTools](https://github.com/SHTOOLS/SHTOOLS) is a `Python` |
| 70 | +code used for spherical harmonic transforms, which allows one to compute the |
| 71 | +Slepian functions of the spherical polar cap. A series of `MATLAB` scripts exist |
| 72 | +in [slepian_alpha](https://github.com/csdms-contrib/slepian_alpha), which |
| 73 | +permits the calculation of the Slepian functions on the sphere. However, these |
| 74 | +scripts are very specialised and hard to generalise. |
| 75 | + |
| 76 | +Whilst Slepian wavelets may be trivially computed from a set of Slepian |
| 77 | +functions, the computation of the spherical Slepian functions themselves are |
| 78 | +computationally complex, where the matrix scales as 𝒪(𝐿⁴). Although symmetries |
| 79 | +of this matrix and the spherical harmonics have been exploited, filling in this |
| 80 | +matrix is inherently slow due to the many integrals performed. The matrix is |
| 81 | +filled in parallel in `Python` using |
| 82 | +[concurrent.futures](https://docs.python.org/3/library/concurrent.futures.html), |
| 83 | +and the spherical harmonic transforms are computed in `C` using |
| 84 | +[SSHT](https://github.com/astro-informatics/ssht). This may be sped up further |
| 85 | +by utilising the new [ducc0](https://github.com/mreineck/ducc) backend for |
| 86 | +`SSHT`, which may allow for a multithreaded solution. Ultimately, the |
| 87 | +eigenproblem must be solved to compute the Slepian functions, requiring |
| 88 | +sophisticated algorithms to balance speed and accuracy. Therefore, to work with |
| 89 | +high-resolution data such as these, one requires high-performance computing |
| 90 | +methods on supercomputers with massive memory and storage. To this end, Slepian |
| 91 | +wavelets may be exploited at present at low resolutions, but further work is |
| 92 | +required for them to be fully scalable. |
| 93 | + |
| 94 | +## Example Usage |
| 95 | + |
| 96 | +`SLEPLET` may be interacted with via the API or the CLIs. |
| 97 | + |
| 98 | +### API Usage |
| 99 | + |
| 100 | +The following demonstrates the first wavelet (ignoring the scaling function) of |
| 101 | +the South America region on the sphere. |
| 102 | + |
| 103 | +```python |
| 104 | +import sleplet |
| 105 | + |
| 106 | +B, J, J_MIN, L = 3, 0, 2, 128 |
| 107 | + |
| 108 | +region = sleplet.slepian.Region(mask_name="south_america") |
| 109 | +f = sleplet.functions.SlepianWavelets(L, region=region, B=B, j_min=J_MIN, j=J) |
| 110 | +f_sphere = sleplet.slepian_methods.slepian_inverse(f.coefficients, f.L, f.slepian) |
| 111 | +sleplet.plotting.PlotSphere( |
| 112 | + f_sphere, |
| 113 | + f.L, |
| 114 | + f"slepian_wavelets_south_america_{B}B_{J_MIN}jmin_{J_MIN+J}j_L{L}", |
| 115 | + normalise=False, |
| 116 | + region=f.region, |
| 117 | +).execute() |
| 118 | +``` |
| 119 | + |
| 120 | + |
| 121 | + |
| 122 | +### CLI Usage |
| 123 | + |
| 124 | +The demonstrates the first wavelet (ignoring the scaling function) of the head |
| 125 | +region of a Homer Simpson mesh for a per-vertex normals field. |
| 126 | + |
| 127 | +```sh |
| 128 | +mesh homer -e 3 2 0 -m slepian_wavelet_coefficients -u -z |
| 129 | +``` |
| 130 | + |
| 131 | + |
| 132 | + |
| 133 | +## Citing |
| 134 | + |
| 135 | +If you use `SLEPLET` in your research, please cite the paper. |
| 136 | + |
| 137 | +```bibtex |
| 138 | +@article{Roddy2023, |
| 139 | + title = {%raw%}{{SLEPLET: Slepian Scale-Discretised Wavelets in Python}}{%endraw%}, |
| 140 | + author = {Roddy, Patrick J.}, |
| 141 | + year = 2023, |
| 142 | + journal = {Journal of Open Source Software}, |
| 143 | + volume = 8, |
| 144 | + number = 84, |
| 145 | + pages = 5221, |
| 146 | + doi = {10.21105/joss.05221}, |
| 147 | +} |
| 148 | +``` |
| 149 | + |
| 150 | +Please also cite [S2LET](https://doi.org/10.1051/0004-6361/201220729) upon which |
| 151 | +`SLEPLET` is built, along with [SSHT](https://doi.org/10.1109/TSP.2011.2166394) |
| 152 | +in the spherical setting or [libigl](https://doi.org/10.1145/3134472.3134497) in |
| 153 | +the mesh setting. |
| 154 | + |
| 155 | +## Acknowledgements |
| 156 | + |
| 157 | +The author would like to thank Jason D. McEwen for his advice and guidance on |
| 158 | +the mathematics behind `SLEPLET`. Further, the author would like to thank Zubair |
| 159 | +Khalid for providing his `MATLAB` implementation to compute the Slepian |
| 160 | +functions of a polar cap region, as well as the formulation for a limited |
| 161 | +colatitude-longitude region. `SLEPLET` makes use of several libraries the author |
| 162 | +would like to acknowledge, in particular, |
| 163 | +[libigl](https://github.com/libigl/libigl-python-bindings), |
| 164 | +[NumPy](https://github.com/numpy/numpy), `plotly`, `SSHT`, |
| 165 | +[S2LET](https://github.com/astro-informatics/s2let). |
0 commit comments