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

editorialbot commented 1 year ago

Submitting author: !--author-handle-->@paddyroddy@vissarion<!--end-editor-- Reviewers: @Saran-nns, @klb2 Archive: 10.5281/zenodo.7835860

Status

Status badge code:

HTML: <a href="https://joss.theoj.org/papers/55d9cf16a27bf2d3141f0f66c676b7f2"><img src="https://joss.theoj.org/papers/55d9cf16a27bf2d3141f0f66c676b7f2/status.svg"></a>
Markdown: [![status](https://joss.theoj.org/papers/55d9cf16a27bf2d3141f0f66c676b7f2/status.svg)](https://joss.theoj.org/papers/55d9cf16a27bf2d3141f0f66c676b7f2)

Reviewers and authors:

Please avoid lengthy details of difficulties in the review thread. Instead, please create a new issue in the target repository and link to those issues (especially acceptance-blockers) by leaving comments in the review thread below. (For completists: if the target issue tracker is also on GitHub, linking the review thread in the issue or vice versa will create corresponding breadcrumb trails in the link target.)

Reviewer instructions & questions

@Saran-nns & @klb2, your review will be checklist based. Each of you will have a separate checklist that you should update when carrying out your review. First of all you need to run this command in a separate comment to create the checklist:

@editorialbot generate my checklist

The reviewer guidelines are available here: https://joss.readthedocs.io/en/latest/reviewer_guidelines.html. Any questions/concerns please let @vissarion know.

✨ Please start on your review when you are able, and be sure to complete your review in the next six weeks, at the very latest ✨

Checklists

📝 Checklist for @klb2

📝 Checklist for @Saran-nns

editorialbot commented 1 year ago

Hello humans, I'm @editorialbot, a robot that can help you with some common editorial tasks.

For a list of things I can do to help you, just type:

@editorialbot commands

For example, to regenerate the paper pdf after making changes in the paper's md or bib files, type:

@editorialbot generate pdf

editorialbot commented 1 year ago

Software report:

github.com/AlDanial/cloc v 1.88  T=0.18 s (918.4 files/s, 65529.7 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Python                         140           1613           1363           7221
Markdown                         3            134              0            571
TOML                             8             10              0            265
YAML                             5             21              0            158
TeX                              1              0              0            120
Unity-Prefab                     4              0              0             12
-------------------------------------------------------------------------------
SUM:                           161           1778           1363           8347
-------------------------------------------------------------------------------

gitinspector failed to run statistical information for the repository

editorialbot commented 1 year ago

Wordcount for paper.md is 968

editorialbot commented 1 year ago

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1002/j.1538-7305.1961.tb03977.x is OK
- 10.1002/j.1538-7305.1962.tb03279.x is OK
- 10.1051/0004-6361/201220729 is OK
- 10.1145/3134472.3134497 is OK
- 10.1109/TSP.2011.2166394 is OK
- 10.5281/zenodo.7268074 is OK
- 10.1109/LSP.2021.3050961 is OK
- 10.1109/TSP.2022.3233309 is OK
- 10.5281/zenodo.4085210 is OK
- 10.1002/j.1538-7305.1961.tb03976.x is OK
- 10.1111/j.1365-2966.2008.13448.x is OK
- 10.1029/2018GC007529 is OK

MISSING DOIs

- None

INVALID DOIs

- None

editorialbot commented 1 year ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

klb2 commented 1 year ago

Review checklist for @klb2

Conflict of interest

[x] I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

[x] I confirm that I read and will adhere to the JOSS code of conduct.

General checks

[x] Repository: Is the source code for this software available at the https://github.com/astro-informatics/sleplet?
[x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
[x] Contribution and authorship: Has the submitting author (@paddyroddy) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
[x] Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines
[x] Data sharing: If the paper contains original data, data are accessible to the reviewers. If the paper contains no original data, please check this item.
[x] Reproducibility: If the paper contains original results, results are entirely reproducible by reviewers. If the paper contains no original results, please check this item.
[x] Human and animal research: If the paper contains original data research on humans subjects or animals, does it comply with JOSS's human participants research policy and/or animal research policy? If the paper contains no such data, please check this item.

Functionality

[x] Installation: Does installation proceed as outlined in the documentation?
[x] Functionality: Have the functional claims of the software been confirmed?
[x] Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

[x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
[x] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
[x] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
[x] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
[x] Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
[x] 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

Software paper

[x] Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
[x] A statement of need: Does the paper have a section titled 'Statement of need' that clearly states what problems the software is designed to solve, who the target audience is, and its relation to other work?
[x] State of the field: Do the authors describe how this software compares to other commonly-used packages?
[x] Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
[x] References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

Saran-nns commented 1 year ago

Review checklist for @Saran-nns

Conflict of interest

[x] I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

[x] I confirm that I read and will adhere to the JOSS code of conduct.

General checks

[x] Repository: Is the source code for this software available at the https://github.com/astro-informatics/sleplet?
[x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
[x] Contribution and authorship: Has the submitting author (@paddyroddy) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
[x] Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines
[x] Data sharing: If the paper contains original data, data are accessible to the reviewers. If the paper contains no original data, please check this item.
[x] Reproducibility: If the paper contains original results, results are entirely reproducible by reviewers. If the paper contains no original results, please check this item.
[x] Human and animal research: If the paper contains original data research on humans subjects or animals, does it comply with JOSS's human participants research policy and/or animal research policy? If the paper contains no such data, please check this item.

Functionality

[x] Installation: Does installation proceed as outlined in the documentation?
[x] Functionality: Have the functional claims of the software been confirmed?
[x] Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

[x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
[x] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
[x] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
[x] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
[x] Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
[x] 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

Software paper

[x] Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
[x] A statement of need: Does the paper have a section titled 'Statement of need' that clearly states what problems the software is designed to solve, who the target audience is, and its relation to other work?
[x] State of the field: Do the authors describe how this software compares to other commonly-used packages?
[x] Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
[x] References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

klb2 commented 1 year ago

I currently have issues installing the required packages pyssht and pys2let on my machine. I have opened a bug report in their projects.

After I am able to resolve these issues, I will continue my review of the submitted sleplet package.

klb2 commented 1 year ago

The developers of the pyssht and pys2let packages fixed the issue and I was now able to install the sleplet package.

I will continue my review this week.

klb2 commented 1 year ago

From the JOSS guidelines (https://joss.readthedocs.io/en/latest/submitting.html#what-should-my-paper-contain):

As this short list shows, JOSS papers are only expected to contain a limited set of metadata (see example below), a Statement of need, Summary, Acknowledgements, and References sections. You can look at an example accepted paper. Given this format, a “full length” paper is not permitted, and software documentation such as API (Application Programming Interface) functionality should not be in the paper and instead should be outlined in the software documentation.

Based on this, I think that the "Demonstration" section should be completely removed from the paper and the "Conclusions" section should be merged into the "Summary" and "Statement of Needs" sections.

paddyroddy commented 1 year ago

From the JOSS guidelines (https://joss.readthedocs.io/en/latest/submitting.html#what-should-my-paper-contain):

As this short list shows, JOSS papers are only expected to contain a limited set of metadata (see example below), a Statement of need, Summary, Acknowledgements, and References sections. You can look at an example accepted paper. Given this format, a “full length” paper is not permitted, and software documentation such as API (Application Programming Interface) functionality should not be in the paper and instead should be outlined in the software documentation.

Based on this, I think that the "Demonstration" section should be completely removed from the paper and the "Conclusions" section should be merged into the "Summary" and "Statement of Needs" sections.

Have done

klb2 commented 1 year ago

@editorialbot generate pdf

editorialbot commented 1 year ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

klb2 commented 1 year ago

Is there any documentation besides the examples in the README? I could not find an API documentation that documents all of the individual functions of the package.

klb2 commented 1 year ago

In the paper, it is stated that

To the author’s knowledge, there is no public software which allows one to compute Slepian wavelets (or similar approach) on the sphere or general manifolds/meshes. SHTools (Wieczorek & Meschede, 2018) and slepian_alpha (Simons et al., n.d.) are examples of codes which allow one to compute Slepian functions on the sphere. In conjunction with SSHT (McEwen & Wiaux, 2011), S2LET (Leistedt, B. et al., 2013) may be used to develop scale-discretised wavelets on the whole sphere.

and later

Whilst Slepian wavelets may be trivially computed from a set of Slepian functions, the computation of the spherical Slepian functions themselves are computationally complex

Based on this, it is unclear for me what the advantages of the sleplet package are over the existing ones like SHTools and slepian_alpha. It is said in the paper that these two packages allow computing the Slepian functions and that it is trivial to compute the Slepian wavelets from the Slepian functions.

vissarion commented 1 year ago

Good point @klb2. @paddyroddy could you please clarify?

paddyroddy commented 1 year ago

On closer inspection ShTools only computes the Slepian functions of a polar cap https://shtools.github.io/SHTOOLS/pysphericalcapcoef.html which is much easier to compute. Whereas SLEPLET handles any arbitrary mask. Further, it works for mesh data rather than just the sphere.

slepian_alpha is a huge set of MATLAB code with no documentation or anything. I believe it's largely used to create the various plots on this paper, https://arxiv.org/pdf/math/0408424.pdf. Again, it is defined only for the sphere.

In an ideal world, SLEPLET would have relied on another library to generate the Slepian functions and the build the wavelets from them. However, this proved non-trivial to use and, as such, it was necessary to compute them myself. My wording should have been clearer.

paddyroddy commented 1 year ago

Is there any documentation besides the examples in the README? I could not find an API documentation that documents all of the individual functions of the package.

I hadn't realised full API documentation was required. I can look into this.

paddyroddy commented 1 year ago

Is there any documentation besides the examples in the README? I could not find an API documentation that documents all of the individual functions of the package.

I hadn't realised full API documentation was required. I can look into this.

I've made some: https://astro-informatics.github.io/sleplet/

klb2 commented 1 year ago

On closer inspection ShTools only computes the Slepian functions of a polar cap https://shtools.github.io/SHTOOLS/pysphericalcapcoef.html which is much easier to compute. Whereas SLEPLET handles any arbitrary mask. Further, it works for mesh data rather than just the sphere.

slepian_alpha is a huge set of MATLAB code with no documentation or anything. I believe it's largely used to create the various plots on this paper, https://arxiv.org/pdf/math/0408424.pdf. Again, it is defined only for the sphere.

In an ideal world, SLEPLET would have relied on another library to generate the Slepian functions and the build the wavelets from them. However, this proved non-trivial to use and, as such, it was necessary to compute them myself. My wording should have been clearer.

Thank you for clarifying. I guess it would be good, if some of these details could also be added to the paper in order to make the differences to the sleplet package clear.

klb2 commented 1 year ago

With the latest version of the software, I was able to run all provided examples without any errors. The unit tests also all pass on my machine. Thank you for adding pooch for the data management/downloads @paddyroddy.

klb2 commented 1 year ago

From my side as a reviewer, only the following points are open:

[x] Community guidelines (CONTRIBUTING.md and issue templates)
[x] Argument/function documentation. I appreciate the API documentation, however, it does not contain any explanations of the individual functions and their arguments.

paddyroddy commented 1 year ago

I've added argument/function level description of the API https://astro-informatics.github.io/sleplet/index.html

paddyroddy commented 1 year ago

Have addressed the community guidelines

paddyroddy commented 1 year ago

On closer inspection ShTools only computes the Slepian functions of a polar cap https://shtools.github.io/SHTOOLS/pysphericalcapcoef.html which is much easier to compute. Whereas SLEPLET handles any arbitrary mask. Further, it works for mesh data rather than just the sphere. slepian_alpha is a huge set of MATLAB code with no documentation or anything. I believe it's largely used to create the various plots on this paper, https://arxiv.org/pdf/math/0408424.pdf. Again, it is defined only for the sphere. In an ideal world, SLEPLET would have relied on another library to generate the Slepian functions and the build the wavelets from them. However, this proved non-trivial to use and, as such, it was necessary to compute them myself. My wording should have been clearer.

Thank you for clarifying. I guess it would be good, if some of these details could also be added to the paper in order to make the differences to the sleplet package clear.

I've added some comments to explain this.

klb2 commented 1 year ago

@editorialbot generate pdf

editorialbot commented 1 year ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

klb2 commented 1 year ago

On closer inspection ShTools only computes the Slepian functions of a polar cap https://shtools.github.io/SHTOOLS/pysphericalcapcoef.html which is much easier to compute. Whereas SLEPLET handles any arbitrary mask. Further, it works for mesh data rather than just the sphere. slepian_alpha is a huge set of MATLAB code with no documentation or anything. I believe it's largely used to create the various plots on this paper, https://arxiv.org/pdf/math/0408424.pdf. Again, it is defined only for the sphere. In an ideal world, SLEPLET would have relied on another library to generate the Slepian functions and the build the wavelets from them. However, this proved non-trivial to use and, as such, it was necessary to compute them myself. My wording should have been clearer.

Thank you for clarifying. I guess it would be good, if some of these details could also be added to the paper in order to make the differences to the sleplet package clear.

I've added some comments to explain this.

Thank you @paddyroddy for adding this part to the paper. It all looks good for me now. The only minor comment: The dates/years for two references are missing in the paper, for the SLEPLET package on Zenodo (2023) and for the slepian_alpha package on Zenodo (2020).

klb2 commented 1 year ago

@vissarion: I have completed my review and after @paddyroddy has added the missing years to the references in the paper, I recommend the paper for acceptance.

paddyroddy commented 1 year ago

Years added!

paddyroddy commented 1 year ago

@editorialbot generate preprint

editorialbot commented 1 year ago

:page_facing_up: Preprint file created: Find it here in the Artifacts list :page_facing_up:

Saran-nns commented 1 year ago

@paddyroddy I started my review and created an issue in the repo with few suggestions and requests

klb2 commented 1 year ago

Years added!

Thank you @paddyroddy

That completes my review @vissarion

Saran-nns commented 1 year ago

@vissarion @paddyroddy Couple of steps to go. Will be happy to flag accept then

Saran-nns commented 1 year ago

@paddyroddy thank you, great work @vissarion my checklist is complete and I am happy to recommend accept

paddyroddy commented 1 year ago

@editorialbot generate preprint

paddyroddy commented 1 year ago

Thank you, @klb2 and @Saran-nns for your guidance.

editorialbot commented 1 year ago

:page_facing_up: Preprint file created: Find it here in the Artifacts list :page_facing_up:

paddyroddy commented 1 year ago

Sorry just have just capitalised the title

paddyroddy commented 1 year ago

@editorialbot generate preprint

vissarion commented 1 year ago

Many thanks to both reviewers @Saran-nns and @klb2 !

@paddyroddy could you please create a tagged release and an archive with the code (e.g. in zenodo) and share the link and the release version here? Please use the same title and authors while creating the zenodo archive.

paddyroddy commented 1 year ago

@vissarion here is the archive link https://zenodo.org/record/7802428, current version v1.3.4

vissarion commented 1 year ago

Thanks! Please use the full title in the archive i.e. "SLEPLET: Slepian scale-discretised wavelets in Python" which is the same as the paper.

vissarion commented 1 year ago

@editorialbot generate pdf

vissarion commented 1 year ago

@editorialbot check references

editorialbot commented 1 year ago

Couldn't check the bibtex because branch name is incorrect: joss-paper

editorialbot commented 1 year ago

:warning: An error happened when generating the pdf.

vissarion commented 1 year ago

@editorialbot generate pdf

editorialbot commented 1 year ago

:warning: An error happened when generating the pdf.

openjournals / joss-reviews