[REVIEW]: Orbital Dynamics in X-ray stellar binary systems

editorialbot commented 1 month ago

Submitting author: !--author-handle-->@xragua@warrickball<!--end-editor-- Reviewers: @matteobachetti, @tddesjardins Archive: Pending

Status

Status badge code:

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

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

@matteobachetti & @tddesjardins, 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 @warrickball 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 @matteobachetti

editorialbot commented 1 month 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 month ago

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

✅ OK DOIs

- 10.1162/EVCO_r_00180 is OK
- 10.1093/mnras/staa3953 is OK
- 10.1117/12.2232432 is OK
- 10.1038/s41592-019-0686-2 is OK
- 10.1086/153315 is OK
- 10.1086/160554 is OK
- 10.1103/PhysRevLett.119.161101 is OK
- 10.1093/mnras/stac352 is OK
- 10.48550/arXiv.2202.05399 is OK

🟡 SKIP DOIs

- No DOI given, and none found for title: PySwarms: A Python-Based Swarm Optimization Librar...
- No DOI given, and none found for title: Accretion Power in Astrophysics
- No DOI given, and none found for title: An introduction to modern astrophysics and cosmolo...
- No DOI given, and none found for title: Accretion Power in Astrophysics

❌ MISSING DOIs

- None

❌ INVALID DOIs

- None

editorialbot commented 1 month ago

Software report:

github.com/AlDanial/cloc v 1.90  T=0.08 s (590.1 files/s, 226513.8 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Python                           6           1965           1516           3635
SVG                              1              0              0           2671
HTML                             7            147             21           1479
Markdown                         3            306              0           1029
JavaScript                      12            138            228            912
CSS                              4            190             35            780
reStructuredText                 5            187             21            535
TeX                              1             21              0            151
Jupyter Notebook                 6              0           2245            136
DOS Batch                        1              8              1             26
YAML                             1              1              4             18
make                             1              4              7              9
-------------------------------------------------------------------------------
SUM:                            48           2967           4078          11381
-------------------------------------------------------------------------------

Commit count by author:

   148  LAEX
     7  GracielaSanjurjoFerrin

editorialbot commented 1 month ago

Paper file info:

📄 Wordcount for paper.md is 1245

✅ The paper includes a Statement of need section

editorialbot commented 1 month ago

License info:

✅ License found: MIT License (Valid open source OSI approved license)

editorialbot commented 1 month ago

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

warrickball commented 1 month ago

Hi @matteobachetti &, @tddesjardins, and thanks again for agreeing to review. This is the review thread for the paper. All of our correspondence will now happen here.

Please read the "Reviewer instructions & questions" in the first comment above, and generate your checklists by commenting @editorialbot generate my checklist on this issue. As you go over the submission, please check off 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. We aim to work with the authors to help them meet our criteria instead of merely passing judgement on the submission. We also encourage reviewers to submit issues and pull requests on the software repository. When doing so, please mention openjournals/joss-reviews#7220 so that the issue/PR is linked to this thread. Please also feel free to comment and ask questions on this thread. JOSS editors have found it 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 weeks but start whenever you can. JOSS reviews are iterative and the authors can start responding while you continue to review other parts of the submission.

If it suits your workflow, you're welcome to assign yourself to this issue in the GitHub UI.

Finally, don't hesitate to ask any questions you might have about the process.

matteobachetti commented 1 month ago

Review checklist for @matteobachetti

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/xragua/xraybinaryorbit?
[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 (@xragua) 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? Online documentation lacks, in my opinion, a good introduction and an overall structure. The README contains a lot of API documentation while it should be more of an introduction to the motivation, the installation and the usage of the code. The docs pages do not seem to render correctly, I don't know if I looked at the wrong address:

[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). There is a notebooks directory containing a number of examples that can be run on a user's computer
[x] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)? The API is documented to a good degree using docstrings
[ ] Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified? There are unit tests running, CI is used, but there is no measurement of test coverage to help understanding to what level. I opened a PR to make tests run during pull requests
[ ] 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 Not that I can see

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? Mostly yes.
[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? Not that I can see
[ ] Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)? The paper has good style and clear language. In my opinion, it spends a little too much time describing the underlying theoretical frameworks, and too little describing why this code is important and useful. Also, a JOSS paper should, in my opinion, be a little more technical on the algorithm and software solutions used in the code.
[ ] 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?

xragua commented 1 month ago

Dear @matteobachetti and @tddesjardins, Thank you so much for agreeing to review our project! I look forward to receiving your comments and corrections.

warrickball commented 1 month ago

Hi @matteobachetti & @tddesjardins, I was wondering if you'd made any progress with your reviews? We encourage reviewers to comment on whichever aspects they have a moment for at any time, rather than waiting to deliver a single, monolithic review. That way authors can start working on changes while the rest of the review proceeds.

You can also raise issues (or pull requests) in the software repo but try to mention openjournals/joss-reviews#7220 so that the activity is linked here.

matteobachetti commented 1 month ago

@warrickball: yes, I'm very sorry for this slow progress but I had a couple of busy weeks coming back from vacation. I'm playing with the software

tddesjardins commented 1 month ago

@warrickball I'm hoping to work on this today! We're hosting a two-day workshop, and today is day 2...so it was crazy in the lead up last week.

warrickball commented 3 weeks ago

Hi @matteobachetti & @tddesjardins, I was wondering if you'd made any progress with your reviews since I last checked in? I see there's been some activity in some issues but @xragua has responded in each case (and some can possibly even be closed).

matteobachetti commented 3 weeks ago

@warrickball @xragua I think I'm done. Sorry for the long wait.

xragua commented 3 weeks ago

Dear @matteobachetti and @tddesjardins, I just wanted to mention that I have added a small function that fits well this package (density_and_ionization_orbital_phase_theoretical), its purpose is to calculate the density and ionization parameter the radiation emitted by the NS finds from the point that is emitted in the orbit in its path to the observer until certain extent (default 10 R*). It has been added in the documentation, in the package of course, added to the CI tests and in the examples section. Thank you!

xragua commented 2 weeks ago

Dear @matteobachetti and @tddesjardins, I added MKdocs gh page describing the package, https://xragua.github.io/xraybinaryorbit/ , Thankyou!

matteobachetti commented 2 weeks ago

@xragua thanks. As I mentioned in my review, I think the docs should do some more than a list of functions with their API documentation. The documentation of a package of this kind, in my opinion, should introduce curious users to the kind of science analysis they can do with it, with a robust introduction (sort of an expanded statement of need!), and then maybe go through a couple of simple examples, the typical "getting started". The API documentation should be for those who are already using the code and want to understand the subtleties of it, at the end. You have good notebooks, so I think it shouldn't be so difficult linking them in the documentation through nbsphinx and form a large section of examples, maybe ordered from the simplest to the most advanced

One of the many examples: https://astropy-regions.readthedocs.io/en/stable/index.html

xragua commented 2 weeks ago

Dear @matteobachetti, I tried to follow your indications both in the documentation pages, the README and in the paper, I hope that now it looks better, let me know what you think, Thanks a lot!

warrickball commented 2 weeks ago

@tddesjardins — Have you had a chance to start a review? I noticed you haven't generated a checklist yet.

@matteobachetti — Thanks for your review. You haven't ticked off all the items so I presume you're waiting for further responses from @xragua. Once your satisfied on any given point, please tick off each item, and I suggest also saying you're happy in this comment thread.

@xragua — Note that @matteobachetti has left comments by editing his review checklist. You should address the comments he's raised there.

matteobachetti commented 2 weeks ago

@xragua the docs look much better now! Great job! Small nitpick: there is a typo in the big all-caps title "GUETTING STARTED"

xragua commented 2 weeks ago

@matteobachetti, @tddesjardins and @warrickball, I have made the following updates to the project: Modified the paper, pages, and README files. Added coverage calculation in the CI test. *Included a few lines in the community guidelines. I look forward to your feedback. Thank you!

matteobachetti commented 2 weeks ago

@editorialbot generate pdf

editorialbot commented 2 weeks ago

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

matteobachetti commented 1 week ago

@xragua: thanks for all the work you are doing to address my comments. Besides all the nitpicks I'm doing through Issues, I do have one general suggestion that I make in this context though: all the testing/coverage apparatus I've been recommending is incredibly useful, but it's just esthetics (cute green ticks in a checklist) if you commit to main without checking them. Developers of robust open source projects work in branches/forks, test locally, and when code is ready, they do a pull request, during which tests are automatically executed by Github Actions or similar systems on multiple python versions and architectures, coverage is updated, and so on. It seems like a needless burden, but it's very effective in finding code breaks before the code goes into production.

xragua commented 1 week ago

@matteobachetti, thanks for the suggestion, I will work like this from now (I did it now when I changed the CI test to use codecov). I really appreciate the guidance, thank you!

openjournals / joss-reviews