software-submission icon indicating copy to clipboard operation
software-submission copied to clipboard
verified publisher icon pyOpenSci

swiftgalaxy

Open kyleaoman opened this issue 7 months ago • 44 comments

Submitting Author: @kyleaoman All current maintainers: @kyleaoman Package Name: swiftgalaxy One-Line Description of Package: Load in particles of a simulated galaxy, rotate coordinates, easy spherical/cylindrical coordinates, access integrated properties, and more. Repository Link: https://github.com/SWIFTSIM/swiftgalaxy Version submitted: 2.1.1 EiC: @coatless Editor: @crhea93
Reviewer 1: @blakeaw
Reviewer 2: @cmillion
Archive: 10.5281/zenodo.17382007 JOSS DOI: 10.21105/joss.09278 Version accepted: v2.2.1 Date accepted (month/day/year): TBD

Code of Conduct & Commitment to Maintain Package

Description

  • Include a brief paragraph describing what your package does:

SWIFTGalaxy is a module that extends SWIFTSimIO tailored to analyses of particles belonging to individual simulated galaxies. It inherits from and extends the functionality of the SWIFTDataset. It understands the content of halo catalogues (supported: Velociraptor, Caesar, SOAP) and therefore which particles belong to a galaxy or other group of particles, and its integrated properties. The particles occupy a coordinate frame that is enforced to be consistent, such that particles loaded on-the-fly will match e.g. rotations and translations of particles already in memory. Intuitive masking of particle datasets is also enabled. Finally, some utilities to make working in cylindrical and spherical coordinate systems more convenient are also provided.

Scope

  • Please indicate which category or categories. Check out our package scope page to learn more about our scope. (If you are unsure of which category you fit, we suggest you make a pre-submission inquiry):

    • [ ] Data retrieval
    • [x] Data extraction
    • [x] Data processing/munging
    • [ ] Data deposition
    • [ ] Data validation and testing
    • [ ] Data visualization[^1]
    • [ ] Workflow automation
    • [ ] Citation management and bibliometrics
    • [ ] Scientific software wrappers
    • [ ] Database interoperability

Domain Specific

  • [ ] Geospatial
  • [ ] Education

Community Partnerships

If your package is associated with an existing community please check below:

[^1]: Please fill out a pre-submission inquiry before submitting a data visualization package.

  • For all submissions, explain how and why the package falls under the categories you indicated above. In your explanation, please address the following points (briefly, 1-2 sentences for each):

    • Who is the target audience and what are scientific applications of this package? The package is for scientists analysing SWIFT simulations of galaxies. It facilitates extracting a subset of a simulation containing many galaxies that corresponds to a single galaxy and manipulating the data.

    • Are there other Python packages that accomplish the same thing? If so, how does yours differ? pynbody has some points in common, but swiftgalaxy is specifically designed for SWIFT simulations by (i) using swiftsimio as a backend and (ii) having features that leverage the particular data layout and metadata annotations of SWIFT outputs.

    • If you made a pre-submission enquiry, please paste the link to the corresponding issue, forum post, or other discussion, or @tag the editor you contacted:

Technical checks

For details about the pyOpenSci packaging requirements, see our packaging guide. Confirm each of the following by checking the box. This package:

  • [x] does not violate the Terms of Service of any service it interacts with.
  • [x] uses an OSI approved license.
  • [x] contains a README with instructions for installing the development version.
  • [x] includes documentation with examples for all functions.
  • [x] contains a tutorial with examples of its essential functions and uses.
  • [x] has a test suite.
  • [x] has continuous integration setup, such as GitHub Actions CircleCI, and/or others.

Publication Options

JOSS Checks
  • [x] The package has an obvious research application according to JOSS's definition in their submission requirements. Be aware that completing the pyOpenSci review process does not guarantee acceptance to JOSS. Be sure to read their submission requirements (linked above) if you are interested in submitting to JOSS.
  • [x] The package is not a "minor utility" as defined by JOSS's submission requirements: "Minor ‘utility’ packages, including ‘thin’ API clients, are not acceptable." pyOpenSci welcomes these packages under "Data Retrieval", but JOSS has slightly different criteria.
  • [x] The package contains a paper.md matching JOSS's requirements with a high-level description in the package root or in inst/. The paper is now available in the joss-paper branch.
  • [x] The package is deposited in a long-term repository with the DOI: 10.5281/zenodo.15502355

Note: JOSS accepts our review as theirs. You will NOT need to go through another full review. JOSS will only review your paper.md file. Be sure to link to this pyOpenSci issue when a JOSS issue is opened for your package. Also be sure to tell the JOSS editor that this is a pyOpenSci reviewed package once you reach this step.

Are you OK with Reviewers Submitting Issues and/or pull requests to your Repo Directly?

This option will allow reviewers to open smaller issues that can then be linked to PR's rather than submitting a more dense text based review. It will also allow you to demonstrate addressing the issue via PR links.

  • [x] Yes I am OK with reviewers submitting requested changes as issues to my repo. Reviewers will then link to the issues in their submitted review.

Confirm each of the following by checking the box.

  • [x] I have read the author guide.
  • [x] I expect to maintain this package for at least 2 years and can help find a replacement for the maintainer (team) if needed.

Please fill out our survey

P.S. Have feedback/comments about our review process? Leave a comment here

Editor and Review Templates

The editor template can be found here.

The review template can be found here.

kyleaoman avatar May 24 '25 11:05 kyleaoman

Editor in Chief checks

Hi there! Thank you for submitting your package for pyOpenSci review. Below are the basic checks that your package needs to pass to begin our review. If some of these are missing, we will ask you to work on them before the review process begins.

Please check our Python packaging guide for more information on the elements below.

  • [x] Installation The package can be installed from a community repository such as PyPI (preferred), and/or a community channel on conda (e.g. conda-forge, bioconda).
    • [x] The package imports properly into a standard Python environment import package.
  • [x] Fit The package meets criteria for fit and overlap.
  • [] Documentation The package has sufficient online documentation to allow us to evaluate package function and scope without installing the package. This includes:
    • [x] User-facing documentation that overviews how to install and start using the package.
    • [ ] Short tutorials that help a user understand how to use the package and what it can do for them.
    • [x] API documentation (documentation for your code's functions, classes, methods and attributes): this includes clearly written docstrings with variables defined using a standard docstring format.
  • [ ] Core GitHub repository Files
    • [ ] README The package has a README.md file with clear explanation of what the package does, instructions on how to install it, and a link to development instructions.
    • [x] Contributing File The package has a CONTRIBUTING.md file that details how to install and contribute to the package.
    • [x] Code of Conduct The package has a CODE_OF_CONDUCT.md file.
    • [x] License The package has an OSI approved license. NOTE: We prefer that you have development instructions in your documentation too.
  • [x] Issue Submission Documentation All of the information is filled out in the YAML header of the issue (located at the top of the issue template).
  • [x] Automated tests Package has a testing suite and is tested via a Continuous Integration service.
  • [x] Repository The repository link resolves correctly.
  • [x] Package overlap The package doesn't entirely overlap with the functionality of other packages that have already been submitted to pyOpenSci.
  • [ ] Archive (JOSS only, may be post-review): The repository DOI resolves correctly.
  • [ ] Version (JOSS only, may be post-review): Does the release version given match the GitHub release (v1.0.0)?
  • [x] Initial onboarding survey was filled out We appreciate each maintainer of the package filling out this survey individually. :raised_hands: Thank you authors in advance for setting aside five to ten minutes to do this. It truly helps our organization. :raised_hands:

Editor comments

Given the astronomy nature of this package, would you like to also pursue Astropy as well?

Please address the following:

Package Dependency

Please emphasize the requirement for NumPy >= 2.0

https://github.com/SWIFTSIM/swiftgalaxy/blob/c79cd0f190f052f021313000c56c432f3d4740a5/pyproject.toml#L20

README

Please add installation instructions:

https://www.pyopensci.org/python-package-guide/documentation/repository-files/readme-file-best-practices.html#installation-instructions

Please show a brief example of the package in action:

https://www.pyopensci.org/python-package-guide/documentation/repository-files/readme-file-best-practices.html#brief-demonstration-of-how-to-use-the-package

Please add a community section:

https://www.pyopensci.org/python-package-guide/documentation/repository-files/readme-file-best-practices.html#a-community-section-with-links-to-contributing-guide-code-of-conduct

Please add a section that links to the gallery/alternative tutorials.

https://www.pyopensci.org/python-package-guide/documentation/repository-files/readme-file-best-practices.html#descriptive-links-to-package-documentation-short-tutorials

Please update the repository information to add the readthedocs webpage.

https://swiftgalaxy.readthedocs.io/en/latest/

Should be here:

https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics#adding-topics-to-your-repository

(Sorry, there's only a "topics" help page for showing this... But, it's in the same location!)

Package website

Please try to organize the landing page with:

https://www.pyopensci.org/python-package-guide/documentation/write-user-documentation/get-started.html#four-elements-of-a-good-open-source-documentation-landing-page

Example: https://www.fatiando.org/verde/latest/

Please consider placing tutorials under a clear website section, c.f.

https://www.pyopensci.org/python-package-guide/documentation/write-user-documentation/create-package-tutorials.html#sphinx-gallery

Example: https://www.fatiando.org/verde/latest/gallery/index.html#

Or, see the "User Guide" portion on the left hand side bar.

Please make available a way to obtain example data, e.g. snap.hdf5. This could be through a function or a simple bash script that could be run by a user to download and setup the data in an expected format.

https://swiftgalaxy.readthedocs.io/en/latest/getting_started/index.html#quick-start

Action

Please take the necessary steps to address the README file and website requirements. We cannot send the package onto a later stage until these issues are addressed as our reviewers and your future users will need to be able to more easily navigate the documentation.

coatless avatar May 26 '25 23:05 coatless

This package seems to be astronomy-focussed and the source code does have astropy as a dependency. So, I wonder if it makes sense to treat this as an astropy/astronomy related package; to me it looks like that would make sense, but the authors have not set the tick-box for "astropy community".

@kyleaoman: Just checking if that's intentional or should we add it?

hamogu avatar May 27 '25 13:05 hamogu

@hamogu As far as I understand the astropy community packages look for use of astropy features where this is relevant, which is not really the case for this package. For example, astropy.units enables attaching physical units to arrays, so I think that it would be expected that a community package uses this. However, swiftgalaxy uses the unyt package from the yt project for physical units, so doesn't really fit into the astropy ecosystem in this sense. There are options to convert to astropy Quantity arrays if a user wants to pass output to an astropy-affiliated package (this is part of where the dependency comes in), but the connection feels weak so I left the box un-ticked. It's a similar story for other aspects such as coordinate arrays.

kyleaoman avatar May 27 '25 13:05 kyleaoman

Great, thanks for the fast reply; I agree. I just wanted to check to make sure we don't overlook it!

hamogu avatar May 27 '25 13:05 hamogu

@kyleaoman thank you for the clarifications!

coatless avatar May 27 '25 20:05 coatless

Just so I can keep track:

  • [x] Please emphasize the requirement for NumPy >= 2.0
  • [x] Please add installation instructions
  • [x] Please show a brief example of the package in action
  • [x] Please add a community section
  • [x] Please add a section that links to the gallery/alternative tutorials
  • [x] Please update the repository information to add the readthedocs webpage
  • [x] Please try to organize the landing page following best practice
  • [x] Please consider placing tutorials under a clear website section, c.f.
  • [x] Or, see the "User Guide" portion on the left hand side bar.
  • [x] Please make available a way to obtain example data, e.g. snap.hdf5. This could be through a function or a simple bash script that could be run by a user to download and setup the data in an expected format.

kyleaoman avatar May 27 '25 22:05 kyleaoman

@coatless I think that I've addressed all of your requested changes now! I edited the submitted version to 2.1.1, just made a release including the updates.

kyleaoman avatar Jun 08 '25 14:06 kyleaoman

@kyleaoman thanks for the follow-up. I'm now off to working on finding an editor to handle the review!

coatless avatar Jun 09 '25 16:06 coatless

I'm happy to share that we have an editor for the review: @crhea93

I'll let him introduce himself.

coatless avatar Jun 09 '25 17:06 coatless

@kyleaoman My name is Carter Rhea -- I'll be the editor guiding you through this process :) Let me start off by saying that I am very excited about this package! I've used tools like yt and pyxsim for galaxy clusters.

A bit about this process: The first thing I'll be doing is running through some basic checks. Once complete, I'll proceed with finding 2 reviewers. I'll keep you posted!

crhea93 avatar Jun 10 '25 00:06 crhea93

@crhea93 pleased to meet you! (A fellow Canadian, perhaps? I'm from Ottawa.) This is my second pyopensci submission so I have some idea of the lay of the land, although it's changed a bit in the meantime. Looking forward to getting some feedback through the reviews 🙂

kyleaoman avatar Jun 10 '25 05:06 kyleaoman

Editor comments

:wave: Hi @blakeaw and @steventgk! Thank you for volunteering to review for pyOpenSci! <Add any additional banter here that you wish..>

Please fill out our pre-review survey

Before beginning your review, please fill out our pre-review survey. This helps us improve all aspects of our review and better understand our community. No personal data will be shared from this survey - it will only be used in an aggregated format by our Executive Director to improve our processes and programs.

  • [x] reviewer 1 survey completed.
  • [ ] reviewer 2 survey completed.

The following resources will help you complete your review:

  1. Here is the reviewers guide. This guide contains all of the steps and information needed to complete your review.
  2. Here is the review template that you will need to fill out and submit here as a comment, once your review is complete.

Please get in touch with any questions or concerns! Your review is due: July 11, 2025

Reviewers: @blakeaw @steventgk Due date: July 11, 2025

crhea93 avatar Jun 18 '25 17:06 crhea93

Hi @crhea93, I completed the pre-review survey.

blakeaw avatar Jun 26 '25 23:06 blakeaw

@blakeaw Excellent thank you!! You're all set to begin the review in that case :D

crhea93 avatar Jun 27 '25 13:06 crhea93

Package Review - Reviewer 1 (@blakeaw )

Please check off boxes as applicable, and elaborate in comments below. Your review is not limited to these topics, as described in the reviewer guide

  • [x] As the reviewer I confirm that there are no conflicts of interest for me to review this work (If you are unsure whether you are in conflict, please speak to your editor before starting your review).

Documentation

The package includes all the following forms of documentation:

  • [x] A statement of need clearly stating problems the software is designed to solve and its target audience in README.
  • [x] Installation instructions: for the development version of the package and any non-standard dependencies in README.
  • [x] Vignette(s) demonstrating major functionality that runs successfully locally.
  • [x] Function Documentation: for all user-facing functions.
  • [x] Examples for all user-facing functions.
  • [x] Community guidelines including contribution guidelines in the README or CONTRIBUTING.
  • [x] Metadata including author(s), author e-mail(s), a url, and any other relevant metadata e.g., in a pyproject.toml file or elsewhere.

Readme file requirements The package meets the readme requirements below:

  • [x] Package has a README.md file in the root directory.

The README should include, from top to bottom:

  • [x] The package name
  • [x] Badges for:
    • [x] Continuous integration and test coverage,
    • [x] Docs building (if you have a documentation website),
    • [x] A repostatus.org badge,
    • [x] Python versions supported,
    • [x] Current package version (on PyPI / Conda).

NOTE: If the README has many more badges, you might want to consider using a table for badges: see this example. Such a table should be more wide than high. (Note that the a badge for pyOpenSci peer-review will be provided upon acceptance.)

  • [x] Short description of package goals.
  • [x] Package installation instructions
  • [x] Any additional setup required to use the package (authentication tokens, etc.)
  • [x] Descriptive links to all vignettes. If the package is small, there may only be a need for one vignette which could be placed in the README.md file.
    • [x] Brief demonstration of package usage (as it makes sense - links to vignettes could also suffice here if package description is clear)
  • [x] Link to your documentation website.
  • [x] If applicable, how the package compares to other similar packages and/or how it relates to other packages in the scientific ecosystem.
  • [x] Citation information

Usability

Reviewers are encouraged to submit suggestions (or pull requests) that will improve the usability of the package as a whole. Package structure should follow general community best-practices. In general please consider whether:

  • [x] Package documentation is clear and easy to find and use.
  • [x] The need for the package is clear
  • [x] All functions have documentation and associated examples for use
  • [x] The package is easy to install

Functionality

  • [x] Installation: Installation succeeds as documented.
  • [x] Functionality: Any functional claims of the software been confirmed.
  • [x] Performance: Any performance claims of the software been confirmed.
  • [x] Automated tests:
    • [x] All tests pass on the reviewer's local machine for the package version submitted by the author. Ideally this should be a tagged version making it easy for reviewers to install.
    • [x] Tests cover essential functions of the package and a reasonable range of inputs and conditions.
  • [x] Continuous Integration: Has continuous integration setup (We suggest using Github actions but any CI platform is acceptable for review)
  • [x] Packaging guidelines: The package conforms to the pyOpenSci packaging guidelines. A few notable highlights to look at:
    • [x] Package supports modern versions of Python and not End of life versions.
    • [x] Code format is standard throughout package and follows PEP 8 guidelines (CI tests for linting pass)

For packages also submitting to JOSS

  • [x] The package has an obvious research application according to JOSS's definition in their submission requirements.

Note: Be sure to check this carefully, as JOSS's submission requirements and scope differ from pyOpenSci's in terms of what types of packages are accepted.

The package contains a paper.md matching JOSS's requirements with:

  • [x] A short summary describing the high-level functionality of the software
  • [x] Authors: A list of authors with their affiliations
  • [x] A statement of need clearly stating problems the software is designed to solve and its target audience.
  • [x] References: With DOIs for all those that have one (e.g. papers, datasets, software).

Final approval (post-review)

  • [x] The author has responded to my review and made changes to my satisfaction. I recommend approving this package.

Estimated hours spent reviewing: 10 to 12

Review Comments

Associated Issues

  • https://github.com/SWIFTSIM/swiftgalaxy/issues/50
  • https://github.com/SWIFTSIM/swiftgalaxy/issues/51
  • https://github.com/SWIFTSIM/swiftgalaxy/issues/53
  • https://github.com/SWIFTSIM/swiftgalaxy/issues/54
  • https://github.com/SWIFTSIM/swiftgalaxy/issues/55
  • https://github.com/SWIFTSIM/swiftgalaxy/issues/56
  • https://github.com/SWIFTSIM/swiftgalaxy/issues/57
  • https://github.com/SWIFTSIM/swiftgalaxy/issues/64

blakeaw avatar Jun 27 '25 19:06 blakeaw

@blakeaw I think that I've now addressed all of the issues that you've raised so far.

SWIFTSIM/swiftgalaxy#53 is still open but it seems like the caesar maintainers have picked it up and fixed it (https://github.com/dnarayanan/caesar/pull/104). Would be good to know if this has actually fixed the issue (for me caesar installed cleanly both before and after their fix...), before I close the issue.

SWIFTSIM/swiftgalaxy#55 was primarily a symptom of how I was handling temporary file creation/destruction (i.e. very badly). That's now much improved, but would be good to know if the test suite now passes on your system or if there are any remaining issues, so have also left that open for the time being.

Not sure if your review was otherwise complete or if there may be more coming?

@crhea93 I think that the second review is now nearly a month overdue? It's the time of year when people leave on holiday so I'm not trying to put a big rush on things, but don't want this to sit in limbo for ever, either.

kyleaoman avatar Aug 04 '25 17:08 kyleaoman

@kyleaoman Thank you for pointing this out! I'll go ahead and ping @steventgk offline.

crhea93 avatar Aug 04 '25 17:08 crhea93

@crhea93 I'm just back from some holiday and wanted to bump this again, not sure what you want to do about the pending second review at this stage.

kyleaoman avatar Sep 11 '25 10:09 kyleaoman

@kyleaoman Thank you for bringing this to my attention. I have not received any reply from @stevengtk. At this point, I will pursue finding another reviewer.

crhea93 avatar Sep 12 '25 15:09 crhea93

@blakeaw I think that I've now addressed all of the issues that you've raised so far.

SWIFTSIM/swiftgalaxy#53 is still open but it seems like the caesar maintainers have picked it up and fixed it (dnarayanan/caesar#104). Would be good to know if this has actually fixed the issue (for me caesar installed cleanly both before and after their fix...), before I close the issue.

SWIFTSIM/swiftgalaxy#55 was primarily a symptom of how I was handling temporary file creation/destruction (i.e. very badly). That's now much improved, but would be good to know if the test suite now passes on your system or if there are any remaining issues, so have also left that open for the time being.

Not sure if your review was otherwise complete or if there may be more coming?

Hi @kyleaoman, thanks for addressing the various issues.

I've confirmed that Caesar installs cleanly now for me as well, so I went ahead and closed that issue.

Unfortunately, I'm still having issues on my Windows system with the temporary file handling when running the test suite - commented in the appropriate issue.

Otherwise, I think I just need to look over the JOSS paper to complete my review. I'll try to take care of that in the next few days.

blakeaw avatar Sep 12 '25 21:09 blakeaw

@kyleaoman I've found another reviewer @cmillion

crhea93 avatar Sep 16 '25 12:09 crhea93

@kyleaoman Would you consider a modification to the data retrieval method in demo_data.py to use something more cross-platform like requests instead of wget? The issue being that the demos don't run on systems that don't have wget, like OSX. If I hack around it, then the code otherwise works on OSX (afaict). Alternatively, specify in the Quickstart or elsewhere that the demos won't work on systems that don't have wget... but it seems like running through the demos is really important for understanding what this library does and how, so that one hiccup just seems to create an unnecessary barrier to use.

cmillion avatar Sep 23 '25 01:09 cmillion

Would you consider a modification to the data retrieval method in demo_data.py to use something more cross-platform like requests instead of wget?

This is a good suggestion - could you open an issue?

kyleaoman avatar Sep 23 '25 07:09 kyleaoman

The last of the issues raised so far is now basically solved (pending some code reviews, merges and publishing releases). @cmillion @blakeaw it would be appreciated if we could bring the review to a conclusion in the next couple of weeks, if possible.

kyleaoman avatar Oct 09 '25 08:10 kyleaoman

Yes. I will finish my review in the next week.

cmillion avatar Oct 09 '25 16:10 cmillion

Hi @crhea93, @kyleaoman has addressed all the issues I've raised and my review is complete.

blakeaw avatar Oct 16 '25 01:10 blakeaw

@blakeaw Excellent! Thank you very much!

crhea93 avatar Oct 16 '25 14:10 crhea93

The notebook examples/SWIFTGalaxy_Colibre_QuickStart.ipynb appears to be pointing toward simulation files that are supposed to be obtained or produced externally to the notebook file itself. The way in which one goes about producing those files is not clear to me. Could you please help me understand how to be able to run this example?

I think that I would need to run COLIBRE / cosma in order to generate example files in order to run this notebook. Per the statement "This guide is for users working with Colibre simulation outputs on the cosma system." If that is the case, could small example files be included or made available for download? Or can the notebook be updated to clearly indicated that it cannot be run without such files.

The document states

HBT-Herons records which particles belong to each individual halo in a set of "membership" files, usually found alongside the halo catalogue in a subdirectory, in this case membership_0127/membership_0127.X.hdf5 (where X is replaced by integers, each corresponding to one part of the "raw" snapshot). swiftgalaxy expects to find the information contained in these files directly in the (single, monolithic) simulation snapshot file. Such a snapshot file exists alongside the SOAP catalogue as colibre_with_SOAP_membership_0127.hdf5.

and then assembles a path with

colibre_base_path = "/cosma8/data/dp004/colibre/Runs/"
simulation_dir = "L0025N0752/THERMAL_AGN_m5"
soap_catalogue_file = os.path.join(
    colibre_base_path,
    simulation_dir,
    "SOAP/halo_properties_0127.hdf5",
)

virtual_snapshot_file = os.path.join(
    colibre_base_path, simulation_dir, "SOAP/colibre_with_SOAP_membership_0127.hdf5"
)

cmillion avatar Oct 16 '25 22:10 cmillion

My final review is below. The issues I found are, IMO, minor documentation issues at worst. -CM

Package Review

Please check off boxes as applicable, and elaborate in comments below. Your review is not limited to these topics, as described in the reviewer guide

  • ✅ As the reviewer, I confirm that there are no conflicts of interest for me to review this work (If you are unsure whether you are in conflict, please speak to your editor before starting your review).

Documentation

The package includes all the following forms of documentation:

  • ✅ A statement of need clearly stating problems the software is designed to solve and its target audience in the README file.
  • ✅ Installation instructions: for the development version of the package and any non-standard dependencies in README.
  • ✅ Short quickstart tutorials demonstrating significant functionality that successfully runs locally.
  • ✅ Function Documentation: for all user-facing functions.
  • ✅ Examples for all user-facing functions.
  • ✅ Community guidelines including contribution guidelines in the README or CONTRIBUTING.
  • ✅ Metadata including author(s), author e-mail(s), a URL, and any other relevant metadata, for example, in a pyproject.toml file or elsewhere.

Readme file requirements The package meets the readme requirements below:

  • ✅ Package has a README.md file in the root directory.

Reviewer note: It is a README.rst

The README should include, from top to bottom:

  • ✅ The package name
  • [ ] Badges for:
    • ✅ Continuous integration and test coverage,
    • ✅ Docs building (if you have a documentation website),
    • ✅ Python versions supported,
    • ✅ Current package version (on PyPI / Conda).

NOTE: If the README has many more badges, you might want to consider using a table for badges: see this example. Such a table should be wider than high. A badge for pyOpenSci peer review will be provided when the package is accepted.

  • ✅ Short description of package goals.
  • ✅ Package installation instructions
  • ✅ Any additional setup required to use the package (authentication tokens, etc.)
  • ✅ Descriptive links to all vignettes. If the package is small, there may only be a need for one vignette which could be placed in the README.md file.
    • ✅ Brief demonstration of package usage (as it makes sense - links to vignettes could also suffice here if package description is clear)
  • ✅ Link to your documentation website.
  • ✅ If applicable, how the package compares to other similar packages and/or how it relates to other packages in the scientific ecosystem.
  • ✅ Citation information

Usability

Reviewers are encouraged to submit suggestions (or pull requests) that will improve the usability of the package as a whole. The package structure should follow the general community best practices. In general, please consider whether:

  • ✅ Package documentation is clear and easy to find and use.
  • ✅ The need for the package is clear
  • ✅ All functions have documentation and associated examples for use
  • ✅ The package is easy to install

Functionality

  • ✅ Installation: Installation succeeds as documented.
  • ✅ Functionality: Any functional claims of the software been confirmed.
  • ✅ Performance: Any performance claims of the software been confirmed.
  • ✅ Automated tests:
    • ✅ All tests pass on the reviewer's local machine for the package version submitted by the author. Ideally this should be a tagged version making it easy for reviewers to install.
    • ✅ Tests cover essential functions of the package and a reasonable range of inputs and conditions.
  • ✅ Continuous Integration: Has continuous integration setup (We suggest using Github actions but any CI platform is acceptable for review)
  • ✅ Packaging guidelines: The package conforms to the pyOpenSci packaging guidelines. A few notable highlights to look at:
    • ✅ Package supports modern versions of Python and not End of life versions.
    • ✅ Code format is standard throughout package and follows PEP 8 guidelines (CI tests for linting pass)

For packages also submitting to JOSS

  • ✅ The package has an obvious research application according to JOSS's definition in their submission requirements.

Note: Be sure to check this carefully, as JOSS's submission requirements and scope differ from pyOpenSci's in terms of what types of packages are accepted.

The package contains a paper.md matching JOSS's requirements with:

  • ✅ A short summary describing the high-level functionality of the software
  • ✅ Authors: A list of authors with their affiliations
  • ✅ A statement of need clearly stating problems the software is designed to solve and its target audience.
  • ✅ References: With DOIs for all those that have one (e.g. papers, datasets, software).

Final approval (post-review)

  • ✅ The author has responded to my review and made changes to my satisfaction. I recommend approving this package.

Estimated hours spent reviewing: 3.5

Review Comments

  • The software appears to not support the (very new) Python 3.14, and the documentation and badge should be updated to reflect that.
  • The examples/SWIFTGalaxy_Colibre_QuickStart.ipynb example requires external data files to run which are not provided, and it is not entirely clear how to obtain them. Further documentation of this would probably be a good idea.
  • In order for all of the tests to pass, it appears to be the case that every optional dependency must be installed. This is fine (and makes sense, because functionality requiring those dependencies should also have test coverage), but maybe a note in the dependency section of the docs would be helpful to clarity.

cmillion avatar Oct 16 '25 23:10 cmillion

Thank you at @cmillion!

crhea93 avatar Oct 16 '25 23:10 crhea93