Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fix markdownlint #329

Merged
merged 2 commits into from
Nov 22, 2023
Merged

Fix markdownlint #329

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
79c0153
Fix `markdownlint`
paddyroddy Nov 22, 2023
715d081
Merge branch 'main' into markdownlint
paddyroddy Nov 22, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions CODE_OF_CONDUCT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ representative at an online or offline event.

Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
patrickjamesroddy@gmail.com.
<patrickjamesroddy@gmail.com>.
All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the
Expand Down Expand Up @@ -116,13 +116,13 @@ the community.

This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.0, available at
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
<https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>.

Community Impact Guidelines were inspired by [Mozilla's code of conduct
enforcement ladder](https://github.com/mozilla/diversity).

[homepage]: https://www.contributor-covenant.org

For answers to common questions about this code of conduct, see the FAQ at
https://www.contributor-covenant.org/faq. Translations are available at
https://www.contributor-covenant.org/translations.
<https://www.contributor-covenant.org/faq>. Translations are available at
<https://www.contributor-covenant.org/translations>.
26 changes: 19 additions & 7 deletions documentation/DOCUMENTATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
<!-- markdownlint-disable MD041 -->

Documentation of the `SLEPLET` package. The
[API documentation](#header-submodules) is included at the end of this page. See
[API documentation](#header-submodules) <!-- markdownlint-disable MD051 -->
is included at the end of this page. See
[PyPI](https://pypi.org/project/sleplet) for more details.

## Bandlimit
Expand Down Expand Up @@ -249,7 +252,8 @@ export SLEPIAN_MASK="south_america"
sphere slepian_south_america -L 128 -n -10 -s 2 -u
# b-d
for s in 2 3 5; do
python -m examples.arbitrary.south_america.denoising_slepian_south_america -n -10 -s ${s}
python -m examples.arbitrary.south_america.denoising_slepian_south_america \
-n -10 -s ${s}
done
```

Expand Down Expand Up @@ -821,7 +825,9 @@ sleplet.plotting.PlotSphere(g_sphere, f.L, "fig_3_3_b", annotations=[]).execute(

##### Fig. 3.4

Figs. (c-d) correspond to (a-b) in [Fig. 1 of the Sifting Convolution on the Sphere paper](#sifting-convolution-on-the-sphere-fig-1). The following creates Figs. (a-b).
Figs. (c-d) correspond to (a-b) in
[Fig. 1 of the Sifting Convolution on the Sphere paper](#sifting-convolution-on-the-sphere-fig-1).
The following creates Figs. (a-b).

```sh
for ell in $(seq 2 -1 1); do
Expand All @@ -846,16 +852,22 @@ for ell in range(2, 0, -1):

##### Fig. 3.5

The same as [Fig. 2 of the Sifting Convolution on the Sphere paper](#sifting-convolution-on-the-sphere-fig-2).
The same as
[Fig. 2 of the Sifting Convolution on the Sphere paper](#sifting-convolution-on-the-sphere-fig-2).

##### Fig. 3.6

The same as [Fig. 3 of the Sifting Convolution on the Sphere paper](#sifting-convolution-on-the-sphere-fig-3).
The same as
[Fig. 3 of the Sifting Convolution on the Sphere paper](#sifting-convolution-on-the-sphere-fig-3).

#### Chapter 4

The plots here are the same as the [Slepian Scale-Discretised Wavelets on the Sphere paper](#slepian-scale-discretised-wavelets-on-the-sphere) without the Africa examples, i.e. [Fig. 10 onwards](#slepian-scale-discretised-wavelets-on-the-sphere-fig-10).
The plots here are the same as the
[Slepian Scale-Discretised Wavelets on the Sphere paper](#slepian-scale-discretised-wavelets-on-the-sphere)
without the Africa examples, i.e.
[Fig. 10 onwards](#slepian-scale-discretised-wavelets-on-the-sphere-fig-10).

#### Chapter 5

The plots here are the same as the [Slepian Scale-Discretised Wavelets on Manifolds paper](#slepian-scale-discretised-wavelets-on-manifolds).
The plots here are the same as the
[Slepian Scale-Discretised Wavelets on Manifolds paper](#slepian-scale-discretised-wavelets-on-manifolds).
119 changes: 77 additions & 42 deletions paper/paper.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,54 +17,89 @@ date: "`r format(Sys.time(), '%d %B %Y')`"
bibliography: paper.bib
---

# Summary
# Summary <!-- markdownlint-disable-line MD025 -->

Wavelets are widely used in various disciplines to analyse signals both in space and scale.
Whilst many fields measure data on manifolds (i.e., the sphere), often data are only observed on a partial region of the manifold.
Wavelets are a typical approach to data of this form, but the wavelet coefficients that overlap with the boundary become contaminated and must be removed for accurate analysis.
Another approach is to estimate the region of missing data and to use existing whole-manifold methods for analysis.
However, both approaches introduce uncertainty into any analysis.
Slepian wavelets enable one to work directly with only the data present, thus avoiding the problems discussed above.
Applications of Slepian wavelets to areas of research measuring data on the partial sphere include gravitational/magnetic fields in geodesy, ground-based measurements in astronomy, measurements of whole-planet properties in planetary science, geomagnetism of the Earth, and cosmic microwave background analyses.
Wavelets are widely used in various disciplines to analyse signals both in space
and scale. Whilst many fields measure data on manifolds (i.e., the sphere),
often data are only observed on a partial region of the manifold. Wavelets are a
typical approach to data of this form, but the wavelet coefficients that overlap
with the boundary become contaminated and must be removed for accurate analysis.
Another approach is to estimate the region of missing data and to use existing
whole-manifold methods for analysis. However, both approaches introduce
uncertainty into any analysis. Slepian wavelets enable one to work directly with
only the data present, thus avoiding the problems discussed above. Applications
of Slepian wavelets to areas of research measuring data on the partial sphere
include gravitational/magnetic fields in geodesy, ground-based measurements in
astronomy, measurements of whole-planet properties in planetary science,
geomagnetism of the Earth, and cosmic microwave background analyses.

# Statement of Need
# Statement of Need <!-- markdownlint-disable-line MD025 -->

Many fields in science and engineering measure data that inherently live on non-Euclidean geometries, such as the sphere.
Techniques developed in the Euclidean setting must be extended to other geometries.
Due to recent interest in geometric deep learning, analogues of Euclidean techniques must also handle general manifolds or graphs.
Often, data are only observed over partial regions of manifolds, and thus standard whole-manifold techniques may not yield accurate predictions.
Slepian wavelets are designed for datasets like these.
Slepian wavelets are built upon the eigenfunctions of the Slepian concentration problem of the manifold [@Slepian1961; @Landau1961; @Landau1962]: a set of bandlimited functions that are maximally concentrated within a given region.
Wavelets are constructed through a tiling of the Slepian harmonic line by leveraging the existing scale-discretised framework [@Wiaux2008; @Leistedt2013].
Whilst these wavelets were inspired by spherical datasets, like in cosmology, the wavelet construction may be utilised for manifold or graph data.
Many fields in science and engineering measure data that inherently live on
non-Euclidean geometries, such as the sphere. Techniques developed in the
Euclidean setting must be extended to other geometries. Due to recent interest
in geometric deep learning, analogues of Euclidean techniques must also handle
general manifolds or graphs. Often, data are only observed over partial regions
of manifolds, and thus standard whole-manifold techniques may not yield accurate
predictions. Slepian wavelets are designed for datasets like these. Slepian
wavelets are built upon the eigenfunctions of the Slepian concentration problem
of the manifold [@Slepian1961; @Landau1961; @Landau1962]: a set of bandlimited
functions that are maximally concentrated within a given region. Wavelets are
constructed through a tiling of the Slepian harmonic line by leveraging the
existing scale-discretised framework [@Wiaux2008; @Leistedt2013]. Whilst these
wavelets were inspired by spherical datasets, like in cosmology, the wavelet
construction may be utilised for manifold or graph data.

To the author's knowledge, there is no public software that allows one to compute Slepian wavelets
(or a similar approach) on the sphere or general manifolds/meshes.
`SHTools` [@Wieczorek2018] is a `Python` code used for spherical harmonic transforms, which allows one to compute the Slepian functions of the spherical polar cap [@Simons2006].
A series of `MATLAB` scripts exist in `slepian_alpha` [@Simons2020], which permits the calculation of the Slepian functions on the sphere.
However, these scripts are very specialised and hard to generalise.
To the author's knowledge, there is no public software that allows one to
compute Slepian wavelets (or a similar approach) on the sphere or general
manifolds/meshes. `SHTools` [@Wieczorek2018] is a `Python` code used for
spherical harmonic transforms, which allows one to compute the Slepian functions
of the spherical polar cap [@Simons2006]. A series of `MATLAB` scripts exist in
`slepian_alpha` [@Simons2020], which permits the calculation of the Slepian
functions on the sphere. However, these scripts are very specialised and hard to
generalise.

`SLEPLET` [@Roddy2023a] is a Python package for the construction of Slepian wavelets in the spherical and manifold (via meshes) settings.
In contrast to the aforementioned codes, `SLEPLET` handles any spherical region as well as the general manifold setting.
The API is documented and easily extendible, designed in an object-orientated manner.
Upon installation, `SLEPLET` comes with two command line interfaces - `sphere` and `mesh` - that allow one to easily generate plots on the sphere and a set of meshes using `plotly`.
Whilst these scripts are the primary intended use, `SLEPLET` may be used directly to generate the Slepian coefficients in the spherical/manifold setting and use methods to convert these into real space for visualisation or other intended purposes.
The construction of the sifting convolution [@Roddy2021] was required to create Slepian wavelets.
As a result, there are also many examples of functions on the sphere in harmonic space (rather than Slepian) that were used to demonstrate its effectiveness.
`SLEPLET` has been used in the development of [@Roddy2021; @Roddy2022; @Roddy2022a; @Roddy2023].
`SLEPLET` [@Roddy2023a] is a Python package for the construction of Slepian
wavelets in the spherical and manifold (via meshes) settings. In contrast to the
aforementioned codes, `SLEPLET` handles any spherical region as well as the
general manifold setting. The API is documented and easily extendible, designed
in an object-orientated manner. Upon installation, `SLEPLET` comes with two
command line interfaces - `sphere` and `mesh` - that allow one to easily
generate plots on the sphere and a set of meshes using `plotly`. Whilst these
scripts are the primary intended use, `SLEPLET` may be used directly to generate
the Slepian coefficients in the spherical/manifold setting and use methods to
convert these into real space for visualisation or other intended purposes. The
construction of the sifting convolution [@Roddy2021] was required to create
Slepian wavelets. As a result, there are also many examples of functions on the
sphere in harmonic space (rather than Slepian) that were used to demonstrate its
effectiveness. `SLEPLET` has been used in the development of
[@Roddy2021; @Roddy2022; @Roddy2022a; @Roddy2023].

Whilst Slepian wavelets may be trivially computed from a set of Slepian functions, the computation of the spherical Slepian functions themselves are computationally complex, where the matrix scales as $\mathcal{O}(L^{4})$.
Although symmetries of this matrix and the spherical harmonics have been exploited, filling in this matrix is inherently slow due to the many integrals performed.
The matrix is filled in parallel in `Python` using `concurrent.futures`, and the spherical harmonic transforms are computed in `C` using `SSHT`.
This may be sped up further by utilising the new `ducc0` backend for `SSHT`, which may allow for a multithreaded solution.
Ultimately, the eigenproblem must be solved to compute the Slepian functions, requiring sophisticated algorithms to balance speed and accuracy.
Therefore, to work with high-resolution data such as these, one requires high-performance computing methods on supercomputers with massive memory and storage.
To this end, Slepian wavelets may be exploited at present at low resolutions, but further work is required for them to be fully scalable.
Whilst Slepian wavelets may be trivially computed from a set of Slepian
functions, the computation of the spherical Slepian functions themselves are
computationally complex, where the matrix scales as $\mathcal{O}(L^{4})$.
Although symmetries of this matrix and the spherical harmonics have been
exploited, filling in this matrix is inherently slow due to the many integrals
performed. The matrix is filled in parallel in `Python` using
`concurrent.futures`, and the spherical harmonic transforms are computed in `C`
using `SSHT`. This may be sped up further by utilising the new `ducc0` backend
for `SSHT`, which may allow for a multithreaded solution. Ultimately, the
eigenproblem must be solved to compute the Slepian functions, requiring
sophisticated algorithms to balance speed and accuracy. Therefore, to work with
high-resolution data such as these, one requires high-performance computing
methods on supercomputers with massive memory and storage. To this end, Slepian
wavelets may be exploited at present at low resolutions, but further work is
required for them to be fully scalable.

# Acknowledgements
# Acknowledgements <!-- markdownlint-disable-line MD025 -->

The author would like to thank Jason D. McEwen for his advice and guidance on the mathematics behind `SLEPLET`.
Further, the author would like to thank Zubair Khalid for providing his `MATLAB` implementation to compute the Slepian functions of a polar cap region, as well as the formulation for a limited colatitude-longitude region [@Bates2017].
`SLEPLET` makes use of several libraries the author would like to acknowledge, in particular, `libigl` [@Libigl2017], `NumPy` [@Harris2020], `plotly` [@Plotly2015], `SSHT` [@McEwen2011], `S2LET` [@Leistedt2013].
The author would like to thank Jason D. McEwen for his advice and guidance on
the mathematics behind `SLEPLET`. Further, the author would like to thank Zubair
Khalid for providing his `MATLAB` implementation to compute the Slepian
functions of a polar cap region, as well as the formulation for a limited
colatitude-longitude region [@Bates2017]. `SLEPLET` makes use of several
libraries the author would like to acknowledge, in particular, `libigl`
[@Libigl2017], `NumPy` [@Harris2020], `plotly` [@Plotly2015], `SSHT`
[@McEwen2011], `S2LET` [@Leistedt2013].

# References
# References <!-- markdownlint-disable-line MD025 -->
Loading