[REVIEW]: ScatteringOptics.jl: An Interstellar Scattering Framework in the Julia Programming Language

[editorialbot]

Submitting author: !--author-handle-->@annatartaglia<!--end-author-handle-- (Anna Tartaglia) Repository: https://github.com/EHTJulia/ScatteringOptics.jl Branch with paper.md (empty if default branch): Version: v0.1.2 Editor: !--editor-->@dfm<!--end-editor-- Reviewers: @Edenhofer, @tomkimpson Archive: Pending

Status

Status badge code:

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

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

@Edenhofer & @tomkimpson, 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 @dfm 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 @Edenhofer

📝 Checklist for @tomkimpson

[editorialbot]

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]

Software report:

github.com/AlDanial/cloc v 1.88  T=0.02 s (1283.4 files/s, 130584.5 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
TOML                             3            283              1           1300
Julia                           18            181             76            734
TeX                              1             17              0            245
Markdown                         6             68              0            214
YAML                             4              3              6            128
-------------------------------------------------------------------------------
SUM:                            32            552             83           2621
-------------------------------------------------------------------------------

gitinspector failed to run statistical information for the repository

[editorialbot]

Wordcount for paper.md is 1264

[editorialbot]

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

OK DOIs

- 10.1088/0004-637X/805/2/180 is OK
- 10.3847/1538-4357/833/1/74 is OK
- 10.3847/2041-8205/820/1/L10 is OK
- 10.3847/0004-637X/826/2/170 is OK
- 10.3847/1538-4357/aadcff is OK
- 10.3847/2041-8213/ac6674 is OK
- 10.3847/2041-8213/ac6675 is OK
- 10.3847/2041-8213/ac6429 is OK
- 10.3847/2041-8213/ac6736 is OK
- 10.21105/joss.04457 is OK
- 10.48550/arXiv.1209.5145 is OK
- 10.1146/annurev.aa.28.090190.003021 is OK
- 10.1098/rsta.1992.0090 is OK
- 10.1093/mnras/238.3.963 is OK
- 10.1093/mnras/238.3.995 is OK
- 10.1017/S1743921314000775 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[dfm]

@Edenhofer, @tomkimpson — This is the review thread for the paper. All of our correspondence will happen here from now on. Thanks again for agreeing to participate!

👉 Please read the "Reviewer instructions & questions" in the first comment above, and generate your checklists by commenting @editorialbot generate my checklist on this issue ASAP. As you go over the submission, please check any items that you feel have been satisfied. There are also links to the JOSS reviewer guidelines.

The JOSS review is different from most other journals. Our goal is to work with the authors to help them meet our criteria instead of merely passing judgment on the submission. As such, the reviewers are encouraged to submit issues and pull requests on the software repository. When doing so, please mention openjournals/joss-reviews#6354 so that a link is created to this thread (and I can keep an eye on what is happening). Please also feel free to comment and ask questions on this thread. In my experience, it is better to post comments/questions/suggestions as you come across them instead of waiting until you've reviewed the entire package.

We aim for the review process to be completed within about 4-6 weeks but please try to make a start ahead of this as JOSS reviews are by their nature iterative and any early feedback you may be able to provide to the author will be very helpful in meeting this schedule. Please get your review started as soon as possible!

[editorialbot]

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

[Edenhofer]

Review checklist for @Edenhofer

Conflict of interest

• [ ] 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/EHTJulia/ScatteringOptics.jl?
• [x] License: Does the repository contain a plain-text LICENSE or COPYING file with the contents of an OSI approved software license?
• [x] Contribution and authorship: Has the submitting author (@annatartaglia) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• [ ] 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.
• [ ] 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

• [ ] Installation: Does installation proceed as outlined in the documentation?
• [ ] Functionality: Have the functional claims of the software been confirmed?
• [ ] 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.
• [ ] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• [ ] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• [ ] Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• [ ] 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?
• [ ] State of the field: Do the authors describe how this software compares to other commonly-used packages?
• [ ] 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?

[Edenhofer]

I would like to request a COI waiver for my review of ScatteringOptics.jl (#6354) regarding Paul Tiede, who is a co-author of said paper. I've been at the Center for Astrophysics | Harvard & Smithsonian, Paul's employer, for about half a year in 2023 and have had two extended conversations with Paul about Gaussian processes, a subject unrelated to the submission. Since we work on very different topics in astrophysics, have never collaborated, and haven't interacted regularly, I believe I can evaluate the submission impartially.

[Edenhofer]

Paper

The paper is well written, summarizes the need for the software well, and focuses on the essential mathematics. However, as a non-expert in the field of radio astronomy, I think that the mathematics discussed should be more closely tied to what ScatteringOptics.jl provides. In particular, it is not clear to me how the equation after l70 and the equation after l74 are related. I probably am missing something, but I thought the scattering is performed in image space and only $G$ and $\phi$ are relevant for ScatteringOptics.jl. If ScatteringOptics.jl only returns the effective scattering in visibility space, please state this more clearly, e.g. in l82ff.

Minor notes

• l65 Why does $\phi$ depend twice on $r$?

• l65-l67 What is the difference between the phase screen $\phir$ and the spatial structure function of the phase screen $D\phi(r)$?

• l70 How is $G$ related to $\phi$?

• r$ is defined in l71 and again in l65; please merge the definitions.

• l76 It is not clear to me what "earth-screen distance D" refers to; please rephrase.

• Is eq. following l74 an alternative formulation of l70 in visibility space?

• l97 It would be great if the authors could provide an example that is reproducible from scratch, e.g., by providing "jason_mad_eofn.fits".

• l102 Wrap line.

• Figure 1 and Figure 2: Increase DPI for publication?

[dfm]

I would like to request a COI waiver for my review of ScatteringOptics.jl (https://github.com/openjournals/joss-reviews/issues/6354) regarding Paul Tiede, who is a co-author of said paper. I've been at the Center for Astrophysics | Harvard & Smithsonian, Paul's employer, for about half a year in 2023 and have had two extended conversations with Paul about Gaussian processes, a subject unrelated to the submission. Since we work on very different topics in astrophysics, have never collaborated, and haven't interacted regularly, I believe I can evaluate the submission impartially.

@Edenhofer — Thanks for bringing this up! Given the weak nature of this potential COI, I'm happy for you to continue with the review, having noted this context.

@annatartaglia — If you or any of your co-authors have any concerns about this at all please reach out to me here or over email (my address should be easy to find!). Thanks all!!

[tomkimpson]

Review checklist for @tomkimpson

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/EHTJulia/ScatteringOptics.jl?
• [x] License: Does the repository contain a plain-text LICENSE or COPYING file with the contents of an OSI approved software license?
• [x] Contribution and authorship: Has the submitting author (@annatartaglia) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• [ ] 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.
• [ ] 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?
• [ ] Functionality: Have the functional claims of the software been confirmed?
• [ ] 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.
• [ ] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• [ ] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• [ ] Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• [ ] 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

• [ ] Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• [ ] 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?
• [ ] 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)?
• [ ] 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?

[tomkimpson]

The package is useful and the accompanying paper is well-written. It was nice to learn about the use of Julia by the EHT collaboration. I have some general comments below. I will review the code itself separately and open any issues as needed.

• In the manuscript, is it really true that current scattering models are written in Python? If so, then it is fine to refer to the speed of Julia as the motivation. If not (I always thought these things were done in C++, but I could just be ignorant), then perhaps the composability with the wider EHTJulia organisation is a more accurate justification.
• In the manuscript, it claims that ScatteringOptics.jl includes a set of abstract types that enable users to define other phase screen models. It is not obvious to me how a user would define some other phase screen model - perhaps a MWE would be useful.
• The MWE in the tutorial is difficult for a user to reproduce without the accompanying .fits file. If sufficiently small, it could be worth including jason_mad_eofn.fits in a data/ directory.
• I would really really like to see some unit tests. I see that @Edenhofer has already opened an issue about this. This would make is easier to verify the functionality of the software, and have confidence that everything is working as expected.
• Some community guidelines should be included for third parties who want to contribute or raise issues

[annatartaglia]

Apologies for the delay in my response–I have been busy with graduate admissions visits the past few weeks.

We would like to thank the referees (@Edenhofer @tomkimpson) for their constructive comments. We are in the process of carefully going through each review and revising the paper and repository accordingly. I will respond to individual comments as we revise. Thanks for your patience!

[dfm]

@annatartaglia — Thanks for your previous update! I wanted to check in here to make sure that this is still on your radar. Let us know how things are going. Thanks!

[dfm]

@annatartaglia — Any updates here? Please let us know what your timeline looks like for the next steps. If I don't hear from you in the next 2 weeks, I'll assume that this review has been abandoned, and reject the submission, so just let me know how things are going ASAP!

[kazuakiyama]

@dfm

We are very sorry for the delay in revising the submission. As @annatartaglia already wrote, we found the referee's suggestions constructive, and have been revising the repository and its documentation. As I wrote to you separately, the revision has been unexpectedly taking longer because the process collides with on-going Anna's career transition. I would appreciate if you can provide us with a few months of an extension to complete the revision.

Also, as an author, I'm very sorry that I didn't respond --- I didn't receive a notification and I should have answered promptly if I did. Please include me when you reach out to us for the next time.

[dfm]

@kazuakiyama, @annatartaglia — Thanks for the update! I can "pause" this submission if it will be a few months before you can return to the review. Otherwise, please update here even with small changes - unlike other journals, we don't require a serial review process where you respond to all comments in one go. Please feel free to iterate interactively! Let me know what your realistic timeline looks like and we'll work with that. Thanks!