Comprehensive List of Features - JOSS Review

[rmorgan10]

After some time digging through the code and documentation, I was able to piece together that SkyPy is useful for quickly obtaining realistic distributions of galaxy shapes, redshifts, luminosities, photometry, and masses (perhaps there are more physical quantities that I missed). If that list of features / use cases were clearly presented, it would eliminate the need for interested astronomers to dig through all the code / examples / documentation to determine whether SkyPy will be useful in their analysis.

I recommend 2 ways of conveying all of SkyPy's uses to potential users:

1. In the software paper, include the physical quantities related to SkyPy in the high-level description of the package's functionality

and

2. In the documentation, create a new page titled "Main Functionalities" or something to that extent. In your main README, link to this specific page in the sentence "The full list of features ...". In the new page, link to the location in the documentation for each feature you list.

Examples:
Galaxy Morphology Distributions
Galaxy Redshift Distributions

The page https://skypy.readthedocs.io/en/latest/galaxies.html almost accomplishes this goal for the skypy.galaxies package, but the only descriptions included are "The following modules are found in the skypy.galaxies.* package." I think a potential user may want some expanded descriptions of how a particular module will be relevant to their analysis.

The page I think would be useful would contain all packages in SkyPy (at present galaxies, utils, and pipeline) and use "astronomer-friendly" language (not function names) to describe the feature, and then link to the page in the documentation. All the features are documented thoroughly, but it would be nice to have some sort of reference page for all the things SkyPy can do.

After seeing some of the other issues in this repo, it's clear that the main functionalities of SkyPy will be expanding, so that is even stronger motivation to have a page like this.

[rmorgan10]

Linking openjournals/joss-reviews#3056

[cescalara]

Hi, I agree with @rmorgan10. For me, there is a gap between the high-level software description in the docs/paper and the examples which jump into to specific applications. I think the suggested text in the docs/paper could also benefit form a discussion of the following points:

• What are some example scientific questions that SkyPy tools can help address with its current tools?
• As noted above, it looks as though the developers plan to add more functionality. What is the scope of the package? Is the focus on simulation of observed galaxy populations, or populations of other astrophysical objects too? It seems SkyPy is already popular and such a statement could help potential contributors understand what you could be looking for in the future and where the project is going.

[rrjbca]

Resolved by #456 and #460. Closing