Merge branch 'main' into joss_to_tex

.gitattributes

@@ -0,0 +1 @@
+src/ananke/_version.py export-subst

.github/workflows/draft-pdf.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: TeX and PDF  # Build draft PDF
         uses: docker://openjournals/paperdraft:latest  # openjournals/openjournals-draft-action@master
         with:
@@ -24,7 +24,7 @@ jobs:
           GIT_SHA: $GITHUB_SHA
           JOURNAL: joss
       - name: Upload
-        uses: actions/upload-artifact@v1
+        uses: actions/upload-artifact@v4
         with:
           name: paper
           # This is the output path where Pandoc will write the compiled

.github/workflows/main.yml

@@ -40,10 +40,10 @@ jobs:
         flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
         # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
         flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
-    # - name: Test with pytest
-    #   run: |
-    #     conda install pytest
-    #     pytest
+    - name: Test with pytest
+      run: |
+        conda install pytest
+        pytest src
   
   develop-post-install:
     runs-on: ubuntu-latest

.gitignore

@@ -69,6 +69,12 @@ instance/
 .scrapy
 
 # Sphinx documentation
+docs/source/*
+!docs/source/*.*
+docs/source/*.ebf
+docs/source/*.h5
+!docs/source/_templates
+!docs/source/_static
 docs/_build/
 
 # PyBuilder

.readthedocs.yaml

@@ -0,0 +1,37 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.9"
+    # You can also specify other tool versions:
+    # nodejs: "20"
+    # rust: "1.70"
+    # golang: "1.20"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
+  builder: "dirhtml"
+  # Fail on all warnings to avoid broken references
+  # fail_on_warning: true
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#   - pdf
+#   - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: docs/source/requirements.txt
+    - method: pip
+      path: .

.zenodo.json

@@ -0,0 +1,22 @@
+{
+    "access_right": "open",
+    "title": "py-ananke: a Python pipeline to generate synthetic star catalogs from cosmological simulations",
+    "creators": [
+        {
+            "affiliation": "University of Pennsylvania",
+            "name": "Thob, Adrien C. R.",
+            "orcid": "0000-0001-7928-1973"
+        }
+    ],
+    "contributors": [
+        {
+            "affiliation": "University of Pennsylvania",
+            "name": "Sanderson, Robyn E.",
+            "orcid": "0000-0003-3939-3297",
+            "type": "Supervisor"
+        }
+    ],
+    "license": "GPL-3.0-or-later",
+    "upload_type": "software",
+    "description": "Python package that offers a comprehensive pipeline designed to generate mock astrometric and photometric catalogs of synthetic stars derived from particle-based simulated star populations"
+}

CITATION.cff

@@ -0,0 +1,68 @@
+cff-version: "1.2.0"
+authors:
+- family-names: Thob
+  given-names: Adrien C. R.
+  orcid: "https://orcid.org/0000-0001-7928-1973"
+- family-names: Sanderson
+  given-names: Robyn E.
+  orcid: "https://orcid.org/0000-0003-3939-3297"
+- family-names: Eden
+  given-names: Andrew P.
+  orcid: "https://orcid.org/0009-0004-2146-4856"
+- family-names: Nikakhtar
+  given-names: Farnik
+  orcid: "https://orcid.org/0000-0002-3641-4366"
+- family-names: Panithanpaisal
+  given-names: Nondh
+  orcid: "https://orcid.org/0000-0001-5214-8822"
+- family-names: Garavito-Camargo
+  given-names: Nicolás
+  orcid: "https://orcid.org/0000-0001-7107-1744"
+- family-names: Sharma
+  given-names: Sanjib
+  orcid: "https://orcid.org/0000-0002-0920-809X"
+contact:
+- family-names: Thob
+  given-names: Adrien C. R.
+  orcid: "https://orcid.org/0000-0001-7928-1973"
+doi: 10.5281/zenodo.13942954
+message: If you use this software, please cite our article in the
+  Journal of Open Source Software.
+preferred-citation:
+  authors:
+  - family-names: Thob
+    given-names: Adrien C. R.
+    orcid: "https://orcid.org/0000-0001-7928-1973"
+  - family-names: Sanderson
+    given-names: Robyn E.
+    orcid: "https://orcid.org/0000-0003-3939-3297"
+  - family-names: Eden
+    given-names: Andrew P.
+    orcid: "https://orcid.org/0009-0004-2146-4856"
+  - family-names: Nikakhtar
+    given-names: Farnik
+    orcid: "https://orcid.org/0000-0002-3641-4366"
+  - family-names: Panithanpaisal
+    given-names: Nondh
+    orcid: "https://orcid.org/0000-0001-5214-8822"
+  - family-names: Garavito-Camargo
+    given-names: Nicolás
+    orcid: "https://orcid.org/0000-0001-7107-1744"
+  - family-names: Sharma
+    given-names: Sanjib
+    orcid: "https://orcid.org/0000-0002-0920-809X"
+  date-published: 2024-10-23
+  doi: 10.21105/joss.06234
+  issn: 2475-9066
+  issue: 102
+  journal: Journal of Open Source Software
+  publisher:
+    name: Open Journals
+  start: 6234
+  title: Generating synthetic star catalogs from simulated data for
+    next-gen observatories with py-ananke
+  type: article
+  url: "https://joss.theoj.org/papers/10.21105/joss.06234"
+  volume: 9
+title: Generating synthetic star catalogs from simulated data for
+  next-gen observatories with py-ananke

README.md

@@ -1,6 +1,10 @@
-# `py-ananke` 
+# `py-ananke`
 
+[![Documentation Status](https://readthedocs.org/projects/py-ananke/badge/?version=latest)](https://py-ananke.readthedocs.io/en/latest/?badge=latest)
 [![Python package](https://github.com/athob/py-ananke/actions/workflows/main.yml/badge.svg)](https://github.com/athob/py-ananke/actions/workflows/main.yml)
+[![status](https://joss.theoj.org/papers/357c0445d891fc10e1b0ca4dba1e3cc0/status.svg)](https://joss.theoj.org/papers/357c0445d891fc10e1b0ca4dba1e3cc0)
+[![arXiv](https://img.shields.io/badge/arXiv-2312.02268-b31b1b.svg?style=flat)](https://arxiv.org/abs/2312.02268)
+[![DOI](https://zenodo.org/badge/498927304.svg)](https://zenodo.org/badge/latestdoi/498927304)
 
 Welcome to `py-ananke`, a Python package that offers `ananke` which is a comprehensive pipeline designed to generate mock astrometric and photometric catalogs of synthetic stars derived from particle-based simulated star populations.
 
@@ -43,15 +47,17 @@ After installation, the module can be imported in Python under the name `ananke`
 
 ### Simplified use case
 
-The repository includes a Jupyter notebook that demonstrates a simplified use case utilizing a dummy set of randomly generated particle data. You can access the notebook directly at [jupyter/testing_ananke.ipynb](jupyter/testing_ananke.ipynb). This notebook provides a step-by-step example to help you understand the functionality and usage of `py-ananke` in a straightforward manner.
+The repository includes a Jupyter notebook that demonstrates a simplified use case utilizing a dummy set of randomly generated particle data. You can access the notebook directly at [jupyter/example_notebook.ipynb](jupyter/example_notebook.ipynb). This notebook provides a step-by-step example to help you understand the functionality and usage of `py-ananke` in a straightforward manner.
+
+Note that you will need Jupyter installed on the machine where you intend to test this notebook, which will not be automatically installed by the `py-ananke`'s installation as it is not required to run its modules. Please follow the [Project Jupyter dedicated instructions](https://jupyter.org/install) for installing its tools such as [JupyterLab](https://jupyter.org/install#jupyterlab) or [Jupyter Notebook](https://jupyter.org/install#jupyter-notebook).
 
 ## What's under the hood
 
 Work in progress...
 
 ## On-going development
 
-`py-ananke` has recently entered its beta phase, and we are diligently working towards its submission to the [Journal of Open Source Software](https://joss.theoj.org).
+Currently in beta, `py-ananke` has been [submitted for publication to The Journal of Open Source Software](https://joss.theoj.org/papers/357c0445d891fc10e1b0ca4dba1e3cc0) and is presently [under peer review](https://github.com/openjournals/joss-reviews/issues/6234). Simultaneously, an early version has been deposited on arXiv, an open-access repository for electronic preprints and postprints. You can access the arXiv submission [here](https://arxiv.org/abs/2312.02268).
 
 ### Upcoming updates
 
@@ -67,29 +73,58 @@ These upcoming updates signify our commitment to continuously improve `py-ananke
 
 ### Contributing
 
-You can readily access the code in this main GitHub repository, as well as its submodules repositories. We encourage users to utilize the [Github issues](https://github.com/athob/py-ananke/issues) feature to report any bugs encountered or suggest new ideas for improvement. Contributions to the project are highly valued and greatly appreciated. To contribute, we kindly request that you make your changes in a separate branch or fork of the repository. Once your contributions are ready, you can submit a [pull request](https://github.com/athob/py-ananke/pulls) to merge them into the [develop](https://github.com/athob/py-ananke/tree/develop) branch. If you choose to make your contributions in a branch, please make sure to base those changes from the develop branch in that fork, and have your pull requests originate from your forked develop branch and target this repository's develop branch. Additionally, you may need to confirm that the Workflow permissions in your fork settings are set to Read and write (Settings > Actions > General > Workflow permissions) in case the [CI/CD GitHub Action](https://github.com/athob/py-ananke/actions/workflows/main.yml) does't complete.
+You can readily access the code in the [main GitHub repository](https://github.com/athob/py-ananke), as well as its submodules repositories. We encourage users to utilize the [Github issues](https://github.com/athob/py-ananke/issues) feature to report any bugs encountered or suggest new ideas for improvement. Contributions to the project are highly valued and greatly appreciated. To contribute, we kindly request that you make your changes in a separate branch or fork of the repository. Once your contributions are ready, you can submit a [pull request](https://github.com/athob/py-ananke/pulls) to merge them into the [develop](https://github.com/athob/py-ananke/tree/develop) branch. If you choose to make your contributions in a fork, please make sure to base those changes from the develop branch in that fork, and have your pull requests originate from your forked develop branch and target this repository's develop branch. Additionally, you may need to confirm that the Workflow permissions in your fork settings are set to Read and write (Settings > Actions > General > Workflow permissions) in case the [CI/CD GitHub Action](https://github.com/athob/py-ananke/actions/workflows/main.yml) doesn't complete.
 
 ## `py-ananke` & the community
 
 ### License
 
-`py-ananke` is distributed under the [GNU General Public License (GPL) version 3](LICENCE), offering you the freedom to utilize, modify, and distribute the software. The GPL v3 ensures that you have the flexibility to adapt py-ananke to suit your specific needs, while also contributing to the open-source community. We encourage you to read the full license text to understand your rights and responsibilities when using py-ananke. 
+`py-ananke` is distributed under the [GNU General Public License (GPL) version 3](LICENSE), offering you the freedom to utilize, modify, and distribute the software. The GPL v3 ensures that you have the flexibility to adapt py-ananke to suit your specific needs, while also contributing to the open-source community. We encourage you to read the full license text to understand your rights and responsibilities when using py-ananke.
 
-<!-- ### Citing `py-ananke`
+### Citing `py-ananke`
 
 If py-ananke has played a role in your research project or software development, we kindly request that you acknowledge and cite the project. Citing py-ananke not only gives credit to the dedicated efforts of its creators but also helps others discover and benefit from this software.
 
-To cite py-ananke, please use the following DOI as a reference in your publications:
-
-[DOI reference to be inserted] -->
+To cite `py-ananke`, please use DOI `10.48550/arXiv.2312.02268` as a reference in your publications, or cite as the following:
+
+```text
+Thob, Adrien C. R. et al. 2023, “Generating synthetic star catalogs from simulated data for next-gen observatories with py-ananke”, arXiv e-prints, doi:10.48550/arXiv.2312.02268.
+```
+
+Alternatively, you may use [one of the entries associated with `py-ananke` as listed by The SAO/NASA Astrophysics Data System](https://ui.adsabs.harvard.edu/abs/2023arXiv231202268T/exportcitation), such as the following BibTeX entry:
+
+```text
+@ARTICLE{2023arXiv231202268T,
+       author = {{Thob}, Adrien C.~R. and {Sanderson}, Robyn E. and {Eden}, Andrew P. and {Nikakhtar}, Farnik and {Panithanpaisal}, Nondh and {Garavito-Camargo}, Nicol{\'a}s and {Sharma}, Sanjib},
+        title = "{Generating synthetic star catalogs from simulated data for next-gen observatories with py-ananke}",
+      journal = {arXiv e-prints},
+     keywords = {Astrophysics - Astrophysics of Galaxies, Astrophysics - Instrumentation and Methods for Astrophysics},
+         year = 2023,
+        month = dec,
+          eid = {arXiv:2312.02268},
+        pages = {arXiv:2312.02268},
+          doi = {10.48550/arXiv.2312.02268},
+archivePrefix = {arXiv},
+       eprint = {2312.02268},
+ primaryClass = {astro-ph.GA},
+       adsurl = {https://ui.adsabs.harvard.edu/abs/2023arXiv231202268T},
+      adsnote = {Provided by the SAO/NASA Astrophysics Data System},
+         note = {Submitted to The Journal of Open Source Software, in review}
+}
+```
 
 ### Dissemination
 
 <!-- Below, you will find a selection of scientific papers that showcase the potential and capabilities of py-ananke. These papers serve as valuable resources for understanding the practical implementation and impact of py-ananke in various domains. -->
 
-
-`py-ananke` was featured at [EAS 2023 in Krakow](https://eas2023programme.kuoni-congress.info/presentation/generating-mock-euclid-and-roman-surveys-of-stellar-halos-of-simulated-nearby-galaxies-using-the-py-ananke-pipeline) as an e-poster, check it at [this URL](https://k-poster.kuoni-congress.info/eas-2023/poster/5bf40113-efa9-4bfc-89a5-b67ebd81f7dd).
+- [`py-ananke_v0.0.2-beta2`](https://github.com/athob/py-ananke/releases/tag/v0.0.2-beta2) was featured at [EAS 2023 in Krakow](https://eas2023programme.kuoni-congress.info/presentation/generating-mock-euclid-and-roman-surveys-of-stellar-halos-of-simulated-nearby-galaxies-using-the-py-ananke-pipeline) as an e-poster, check it at [this URL](https://k-poster.kuoni-congress.info/eas-2023/poster/5bf40113-efa9-4bfc-89a5-b67ebd81f7dd).
+- [`py-ananke_v0.1.0-beta2`](https://github.com/athob/py-ananke/releases/tag/v0.1.0-beta2) was featured at the 243rd AAS meeting in New Orleans.
+- a Galactic Plane survey application of `py-ananke` was featured at:
+    1. the [Roman@Yerkes workshop on Galactic Science with the Nancy Grace Roman Space Telescope](https://sites.google.com/cfa.harvard.edu/romanyerkes/home),
+    2. [EAS 2024 in Padova](https://eas2024programme.kuoni-congress.info/presentation/synthetic-survey-catalogs-for-the-galactic-roman-infrared-plane-survey-grips-using-py-ananke) as an e-poster (available [here](https://k-poster.kuoni-congress.info/eas-2024/poster/749fd8f1-ec4c-4167-911f-914e2215eeab)),
+    3. the [Challenging Theory with Roman meeting at Caltech](https://conference.ipac.caltech.edu/roman2024/) (recording available [here](https://youtu.be/93hF1ZCDzw8)),
+    4. the [2024 IAU GA in Cape Town](https://astronomy2024.org/) (live streamed [here](https://m.youtube.com/watch?v=8R-Wc9tGWcg&t=7218s)).
 
 ## Acknowledgements
 
-We extend our sincere gratitude to [Robyn Sanderson (UPenn)](https://live-sas-physics.pantheon.sas.upenn.edu/people/standing-faculty/robyn-sanderson), [Andrew Eden (FloridaTech)](mailto:Andrew%20Eden%20<aeden2019@my.fit.edu>), [Farnik Nikakhtar (Yale)](https://physics.yale.edu/people/farnik-nikakhtar), [Nondh Panithanpaisal (UPenn/CarnegieObs)](https://nonsk131.github.io), and [Nicolas Garavito-Camargo (FlatironCCA)](https://jngaravitoc.github.io/Garavito-Camargo/) for their invaluable contributions and support during the development of this package. Their expertise, guidance, and collaboration have been instrumental in shaping the vision and advancement of this project. We also appreciate the valuable feedback and suggestions provided by the wider community, including the extended [Galaxy Dynamics @ UPenn group](web.sas.upenn.edu/dynamics/) and the participants of the "anankethon" workshop, which have significantly contributed to the refinement and enhancement of the package.
+We extend our sincere gratitude to [Robyn Sanderson (UPenn)](https://live-sas-physics.pantheon.sas.upenn.edu/people/standing-faculty/robyn-sanderson), [Andrew Eden (FloridaTech)](mailto:Andrew%20Eden%20<aeden2019@my.fit.edu>), [Farnik Nikakhtar (Yale)](https://physics.yale.edu/people/farnik-nikakhtar), [Nondh Panithanpaisal (UPenn/CarnegieObs)](https://nonsk131.github.io), and [Nicolas Garavito-Camargo (FlatironCCA)](https://jngaravitoc.github.io/Garavito-Camargo/) for their invaluable contributions and support during the development of this package. Their expertise, guidance, and collaboration have been instrumental in shaping the vision and advancement of this project. We also appreciate the valuable feedback and suggestions provided by the wider community, including the extended [Galaxy Dynamics @ UPenn group](https://web.sas.upenn.edu/dynamics/) and the participants of the "anankethon" workshop, which have significantly contributed to the refinement and enhancement of the package.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd