Merge pull request #112 from SNEWS2/JostMigenda/JOSSReview

Update README and documentation

README.md

@@ -4,33 +4,53 @@
 ![tests](https://github.com/SNEWS2/snewpy/actions/workflows/tests.yml/badge.svg)
 [![Documentation Status](https://readthedocs.org/projects/snewpy/badge/?version=latest)](https://snewpy.readthedocs.io/en/latest/?badge=latest)
 
-Collection of models from the community in common format for use by the SNEWS teams
+SNEWPY is a Python package for working with supernova neutrinos. It offers …
+
+* … a simple and unified interface to hundreds of supernova simulations.
+* … a large library of flavor transformations that relate neutrino fluxes produced in the supernova to those reaching a detector on Earth.
+* … and a Python interface to SNOwGLoBES which lets you estimate and plot event rates in many different neutrino detectors.
+
 
 ## Installation
 
+### For Users
 Run `pip install snewpy` to install SNEWPY.
-After installation you can run `python -c 'import snewpy; snewpy.get_models()'` to download supernova models supported by SNEWPY. By default, they will be downloaded to a subdirectory named `SNEWPY-models/<model_name>/` in the current directory.
 
-## Dependencies 
+SNEWPY includes a large number of supernova models from different simulation groups. Since these models have a size of several 100 MB, they are not included in the initial install. Instead, after installing, run the following command to download models you want to use:
+
+`python -c 'import snewpy; snewpy.get_models()'`
+
+By default, they will be downloaded to a subdirectory named `SNEWPY-models/<model_name>/` in the current directory.
+
+### For Developers
 
-To interface with the SNOwGLoBES software the user will need to install the software which can be found at https://github.com/SNOwGLoBES/snowglobes
-SNOwGLoBES requires that the GLoBES libraries to be installed which can be found at https://www.mpi-hd.mpg.de/personalhomes/globes/
+**Your contributions to SNEWPY are welcome!** For minor changes, simply submit a pull request. If you plan larger changes, it’s probably a good idea to open an issue first to coordinate our work.
 
-Here we provide a skeleton outline to install these tools.
+To contribute, first clone the repository (`git clone https://github.com/SNEWS2/snewpy.git`), then make changes and install your modified version locally using `pip install .` from the base directory of the repository.
+Once you’re happy with your changes, please submit a pull request.
+Unit tests will run automatically for every pull request or you can run them locally using `python -m unittest python/snewpy/test/test_*.py`.
 
-This is a walkthrough to install GLoBES and SNOwGLoBES locally in the users home
-(i.e. /path/to/home/ == ~/ particularly this installs in ~/opt/) directory, it is in bash notation
+### Dependencies 
 
-	cd /path/to/home/
+Some functionality of SNEWPY requires that [SNOwGLoBES](https://github.com/SNOwGLoBES/snowglobes) and its dependency, [GLoBES](https://www.mpi-hd.mpg.de/personalhomes/globes/) are installed.
+
+<details>
+<summary>Expand this to view sample instructions for installing SNOwGLoBES and GLoBES</summary>
+
+This is a walkthrough to install GLoBES and SNOwGLoBES locally in the users home directory
+(i.e. `~/opt/`). It uses `bash` syntax.
+
+```bash
+	cd ~
 	mkdir opt
 	cd opt
 	wget https://www.mpi-hd.mpg.de/personalhomes/globes/download/globes-3.2.17.tar.gz
 	tar -zxf globes-3.2.17.tar.gz
 	cd globes-3.2.17/
-	./configure --prefix=/path/to/home/opt/globes-3.2.17-install  --disable-binary
+	./configure --prefix=~/opt/globes-3.2.17-install --disable-binary
 	make
 	make install
-	cd /path/to/home/opt/globes-3.2.16-install
+	cd ~/opt/globes-3.2.17-install
 	export GLB_DIR=${PWD}
 	cd ..
 
@@ -40,9 +60,15 @@ This is a walkthrough to install GLoBES and SNOwGLoBES locally in the users home
 	cd src
 	make
 	make install
+```
+</details> 
 
 
-## Usage
-The core code is found in `python/snewpy/`. Example scripts which show
-how the software can be used are available in the
+## Usage and Documentation
+Example scripts which show how SNEWPY can be used are available in the
 `python/snewpy/scripts/` subfolder as well as notebooks in `doc/nb/`.
+Most downloadable models also include a Jupyter notebook with simple usage examples.
+
+A paper describing SNEWPY and the underlying physics is available at [arXiv:2109.08188](https://arxiv.org/abs/2109.08188).
+
+For more, see the [full documentation on Read the Docs](https://snewpy.rtfd.io/).

doc/paper.bib

@@ -54,7 +54,7 @@ @article{SNEWS:2020tbu
 }
 
 @misc{SNOwGLoBES,
-	author = "Scholberg, Kate and others",
+	author = "Scholberg, Kate and {SNOwGLoBES Contributors}",
 	journal = "GitHub repository",
 	publisher = "GitHub",
 	title = "{SNOwGLoBES code: SuperNova Observatories with GLoBES}",

doc/paper.md

@@ -117,13 +117,13 @@ affiliations:
     index: 20
   - name: Georgia Institute of Technology, Atlanta, GA, USA
     index: 21
-date: 13 September 2021
+date: 1 November 2021
 bibliography: paper.bib
 
 # Optional fields if submitting to a AAS journal too, see this blog post:
 # https://blog.joss.theoj.org/2018/12/a-new-collaboration-with-aas-publishing
-aas-doi: 10.3847/xxxxx # <- update this with the DOI from AAS once you know it.
-aas-journal: The Astrophysical Journal # <- The name of the AAS journal.
+aas-doi: 10.3847/1538-4357/ac350f # <- update this with the DOI from AAS once you know it.
+aas-journal: Astrophysical Journal # <- The name of the AAS journal.
 ---
 
 
@@ -165,9 +165,9 @@ transformation in the mantle of the star and during propagation to Earth.
 The third module, `snewpy.snowglobes`, interfaces with SNOwGLoBES itself:
 First, it can generate either a time series of neutrino spectra at Earth—the
 “neutrinocurve”—or the spectral fluence. The module is then able to
-run the generated data files through all neutrino detector models available in
-SNOwGLoBES to compute the expected event rates before collating the
-output from SNOwGLoBES into a signal data file per detector per interaction channel.
+run the generated data files through SNOwGLoBES, which computes the expected
+event rates in different neutrino detector models, before collating the output
+from SNOwGLoBES into a signal data file per detector per interaction channel.
 
 Instead of using it as a complete simulation pipeline, SNEWPY can also be
 integrated into other software thanks to its modular design.

doc/source/contributing.rst

@@ -18,14 +18,17 @@ Contribute Code or Documentation
 --------------------------------
 
 **Your contributions to SNEWPY are welcome!**
-To contribute, please clone the GitHub repository, make your changes and
-`submit a pull request <https://github.com/SNEWS2/snewpy/pulls>`_.
-If you plan larger changes, it’s probably a good idea to open an issue first
-to coordinate our work.
+For minor changes, simply submit a pull request. If you plan larger changes,
+it’s probably a good idea to open an issue first to coordinate our work.
+
+To contribute, first clone the GitHub repository (``git clone https://github.com/SNEWS2/snewpy.git``),
+then make your changes and install your modified version locally using
+``pip install .`` from the base directory of the repository. Once you’re happy
+with your changes, please `submit a pull request <https://github.com/SNEWS2/snewpy/pulls>`_.
 
 SNEWPY uses the `unittest <https://docs.python.org/3/library/unittest.html>`_
-module for automated testing. Tests will run when you submit a pull request.
-In addition, you can run them manually using ``python -m unittest python/snewpy/test/test_*.py``.
+module for automated testing. Tests will run when you submit a pull request
+or you can run them manually using ``python -m unittest python/snewpy/test/test_*.py``.
 
 
 Contribute Supernova Models