astro-informatics / sleplet

Slepian Scale-Discretised Wavelets in Python

SLEPLET

SLEPLET is a Python package for the construction of Slepian wavelets in the spherical and manifold (via meshes) settings. The API of SLEPLET has been designed in an object-orientated manner and is easily extendible. Upon installation, SLEPLET comes with two command line interfaces - sphere and mesh - which allows one to easily generate plots on the sphere and a set of meshes using plotly.

To read more about Slepian wavelets please see the following publications

Installation

The recommended way to install SLEPLET is via pip

pip install sleplet

To install the latest development version of SLEPLET clone this repository and run

pip install -e .

This will install two scripts sphere and mesh which can be used to generate the figures in the associated papers.

Supported Platforms

SLEPLET has been tested with . Windows is not currently supported as SLEPLET relies on pyssht and pys2let which do not work on Windows. These can hopefully be replaced with s2fft and s2wav in the future when they are available on PyPI.

Example Usage

SLEPLET may be interacted with via the API or the CLIs.

API Usage

The following demonstrates the first wavelet (ignoring the scaling function) of the South America region on the sphere.

import sleplet

B, J, J_MIN, L = 3, 0, 2, 128

region = sleplet.slepian.Region(mask_name="south_america")
f = sleplet.functions.SlepianWavelets(L, region=region, B=B, j_min=J_MIN, j=J)
f_sphere = sleplet.slepian_methods.slepian_inverse(f.coefficients, f.L, f.slepian)
sleplet.plotting.PlotSphere(
    f_sphere,
    f.L,
    f"slepian_wavelets_south_america_{B}B_{J_MIN}jmin_{J_MIN+J}j_L{L}",
    normalise=False,
    region=f.region,
).execute()

CLI Usage

The demonstrates the first wavelet (ignoring the scaling function) of the head region of a Homer Simpson mesh for a per-vertex normals field.

mesh homer -e 3 2 0 -m slepian_wavelet_coefficients -u -z

Documentation

See here for the documentation. This includes demonstrations of the figures from the associated papers along with the API documentation. Further examples are included in the examples folder.

Community Guidelines

We'd love any contributions you may have, please see the contributing guidelines.

Citing

If you use SLEPLET in your research, please cite the paper.

@article{Roddy2023,
  title   = {{SLEPLET: Slepian Scale-Discretised Wavelets in Python}},
  author  = {Roddy, Patrick J.},
  year    = 2023,
  journal = {Journal of Open Source Software},
  volume  = 8,
  number  = 84,
  pages   = 5221,
  doi     = {10.21105/joss.05221},
}

Please also cite S2LET upon which SLEPLET is built, along with SSHT in the spherical setting or libigl in the mesh setting.

sleplet's Issues

Add test coverage

Replace the extra args hack?

Unknown mat file type in earth example

When trying to run the command sphere earth -L 128 to reproduce Fig. 2 in the "Sifting Convolution on the Sphere" section, I get the following error message:

Traceback (most recent call last):
  File "/home/karl/Documents/review/sleplet/venv/bin/sphere", line 8, in <module>
    sys.exit(main())
  File "/home/karl/Documents/review/sleplet/src/sleplet/scripts/plotting_on_sphere.py", line 350, in main
    f = COEFFICIENTS[
  File "pydantic/dataclasses.py", line 341, in pydantic.dataclasses._add_pydantic_validation_attributes.new_init
    'unsafe_hash',
  File "/home/karl/Documents/review/sleplet/src/sleplet/functions/flm/earth.py", line 14, in __post_init_post_parse__
    super().__post_init_post_parse__()
  File "/home/karl/Documents/review/sleplet/src/sleplet/functions/f_lm.py", line 16, in __post_init_post_parse__
    super().__post_init_post_parse__()
  File "/home/karl/Documents/review/sleplet/src/sleplet/functions/coefficients.py", line 32, in __post_init_post_parse__
    self.coefficients = self._create_coefficients()
  File "/home/karl/Documents/review/sleplet/src/sleplet/functions/flm/earth.py", line 17, in _create_coefficients
    return create_flm(self.L, smoothing=self.smoothing)
  File "/home/karl/Documents/review/sleplet/src/sleplet/data/other/earth/create_earth_flm.py", line 19, in create_flm
    flm = _load_flm()
  File "/home/karl/Documents/review/sleplet/src/sleplet/data/other/earth/create_earth_flm.py", line 43, in _load_flm
    mat_contents = sio.loadmat(str(_matfile))
  File "/home/karl/Documents/review/sleplet/venv/lib/python3.10/site-packages/scipy/io/matlab/_mio.py", line 226, in loadmat
    MR, _ = mat_reader_factory(f, **kwargs)
  File "/home/karl/Documents/review/sleplet/venv/lib/python3.10/site-packages/scipy/io/matlab/_mio.py", line 74, in mat_reader_factory
    mjv, mnv = _get_matfile_version(byte_stream)
  File "/home/karl/Documents/review/sleplet/venv/lib/python3.10/site-packages/scipy/io/matlab/_miobase.py", line 251, in _get_matfile_version
    raise ValueError('Unknown mat file type, version %s, %s' % ret)
ValueError: Unknown mat file type, version 55, 54

Eq 54 -> yes

Use `numpy.typing`

[C] Compare sparsity in wavelet basis vs Slepian space

• historgram of wavelet coefficients
• decay faster in Slepian basis than normal
• ringing will give us more coefficients => less sparsity

Fig 12, Slepian on ball w/ Zubair

• red spherical harmonics
• blue Slepian functions
• decay faster = more sparse!

Create API documentation

Action Required: Fix Renovate Configuration

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Error type: Cannot find preset's package (github>paddyroddy/.github//renovate/default-config.json)

[D] Fig 4: another region

Compute i.e. Africa

Investigate beamer

[B] Sparsity

• compare to other wavelets
• S2LET with standard wavelets and without
• thresholding in SLepian basis i.e. S2LET paper

Fix `cmocean` warnings

a

Apologies if this is obvious, but I can't find anything in the docs/tutorial.

I've transferring methods in the spherical setting to general manifolds. Say I had some function f defined on the sphere and I wanted to compute it's integral

Fix `tox`: `Failed to generate report: No data to report` in CI

Doesn't happen locally.

Improve `pydantic` `validators`

Discretise eq 11

Using weights over sphere

[BUG] Zenodo downloads are flaky following the recent Zenodo upgrade

Describe the Bug
Occasionally Zenodo will fail to download the data, simply run again if that is the case

Add documentation

[A] Eq 17, test leakage?

Numerically calculate it. Proportion of energy inside vs outside

Switch to `concurrent.futures`?

Use `tox`

Negative tests should check error message

Fix `pyproject.toml`

Currently getting module not found errors

Missing community/contribution guidelines

This project is lacking guidelines for other people who wish to contribute, e.g,. through bug reports or pull requests.

The JOSS review checklist specifies this as

Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

I think this should be clarified in a CONTRIBUTING.md file and Github issue templates should be added.

[BUG] `pooch.registry[filedata["key"]] = filedata["checksum"]` `KeyError: 'key'`

Zenodo has changed its API, without documenting. See fatiando/pooch#371.

[REVIEW]: SLEPLET: Slepian scale-discretised wavelets in Python

Hi, I have few suggestions / requests. Let me know if you disagree with any of these:

Installation Instructions

• On Windows, pip install sleplet fails openjournals/joss-reviews#5221 (comment). Additionally, it appears that sleplet is only compatible with python >=3.10 (i see badge). The installation instructions should be updated to reflect the supported operating systems and compatible python versions. Did you tried previous stable versions of pys2let>=2.2.5, pyssht>=1.5.2 ?

Usage/Examples

• When using sleplet, generated images and PDFs are saved in the package root directory in conda. Is it possible for users to define or change the save path? Imagine, only my admin has the right to access conda directory.
• sleplet saves generated figures in both PDF and PNG formats, which may be redundant. Can users choose the file type to be saved?
• sleplet does not report or plot the generated figures. When testing the examples in the notebook, it was somewhat inconvenient to search for the generated images.
• Also, it download the cache/save sample analysis data in conda root directory. I recommend it to be at pwd.

Documentation

• The README file seems to include almost all example codes, which should be moved to the documentation. I recommend keeping only one or two sample codes with generated images in the README file and directing users to the documentation for further information, including the Bandlimit and Environment Variables. It would be best to host those examples at https://astro-informatics.github.io/sleplet/index.html. Otherwise, a separate .md file for documentation in the package itself could be created, and the path could be hyperlinked in the README file.

• Here's what I suggest adding to the README file:
  About sleplet
  Installation instructions
  Usage with a few example code runs and images/results with explanations instead of links to paper figures.
  Documentation, hyperlink (to doc) for further information
  Community guidelines

Thanks

Fig 2: read again

Cannot load file containing pickled data in south_america example

When running the command python -m sleplet.plotting.arbitrary.south_america.tiling_south_america to reproduce Fig. 2 from the "Slepian Scale-Discretised Wavelets on the Sphere" section, I get the following error:

Traceback (most recent call last):
  File "/usr/lib/python3.10/runpy.py", line 196, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "/usr/lib/python3.10/runpy.py", line 86, in _run_code
    exec(code, run_globals)
  File "/home/karl/Documents/review/sleplet/src/sleplet/plotting/arbitrary/south_america/tiling_south_america.py", line 54, in <module>
    main()
  File "/home/karl/Documents/review/sleplet/src/sleplet/plotting/arbitrary/south_america/tiling_south_america.py", line 35, in main
    slepian = SlepianArbitrary(L, "south_america")
  File "pydantic/dataclasses.py", line 341, in pydantic.dataclasses._add_pydantic_validation_attributes.new_init
    'unsafe_hash',
  File "/home/karl/Documents/review/sleplet/src/sleplet/slepian/slepian_region/slepian_arbitrary.py", line 47, in __post_init_post_parse__
    super().__post_init_post_parse__()
  File "/home/karl/Documents/review/sleplet/src/sleplet/slepian/slepian_functions.py", line 19, in __post_init_post_parse__
    self.mask = self._create_mask()
  File "/home/karl/Documents/review/sleplet/src/sleplet/slepian/slepian_region/slepian_arbitrary.py", line 56, in _create_mask
    return create_mask_region(self.resolution, self.region)
  File "/home/karl/Documents/review/sleplet/src/sleplet/utils/mask_methods.py", line 32, in create_mask_region
    mask = _load_mask(name)
  File "/home/karl/Documents/review/sleplet/src/sleplet/utils/mask_methods.py", line 62, in _load_mask
    mask = np.load(location)
  File "/home/karl/Documents/review/sleplet/venv/lib/python3.10/site-packages/numpy/lib/npyio.py", line 438, in load
    raise ValueError("Cannot load file containing pickled data "
ValueError: Cannot load file containing pickled data when allow_pickle=False

Submit to JOSS

Make into PyPI package

Move check manifest to CI

Too slow

Switch from IGL