JOSS Paper

.github/workflows/joss-pdf.yml

@@ -0,0 +1,34 @@
+name: Generate JOSS PDF
+on: 
+  push:
+    paths:
+      - paper2026/**
+      - .github/workflows/joss-pdf.yml
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: JOSS Paper Draft PDF
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          # This should be the path to the paper within your repo.
+          paper-path: paper2026/paper.md
+      - name: Upload PDF
+        uses: actions/upload-artifact@v7
+        with:
+          name: paper
+          # This is the output path where Pandoc will write the compiled
+          # PDF. Note, this should be the same directory as the input
+          # paper.md
+          path: paper2026/paper.pdf
+      - name: Commit PDF to repository
+        uses: EndBug/add-and-commit@v10
+        with:
+          message: '(auto) Paper PDF Draft'
+          # This should be the path to the paper within your repo.
+          add: 'paper2026/paper.pdf' # 'paper2026/*.pdf' to commit all PDFs in the paper directory

paper2026/paper.bib

@@ -0,0 +1,103 @@
+@article{akeson:2013,
+  author  = {Akeson, R. L. and Chen, X. and Ciardi, D. and Crane, M. and Good, J. and Harbut, M. and Jackson, E. and Kane, S. R. and Laity, A. C. and Leifer, S. and Lynn, M. and McElroy, D. L. and Papin, M. and Plavchan, P. and Ram{\'i}rez, S. V. and Rey, R. and von Braun, K. and Wittman, M. and Abajian, M. and Ali, B. and Beichman, C. and Bryden, G. and Chance, L. and Christiansen, J. L. and Clark, E. and Eastman, J. D. and Gagn{\'e}, N. and Haas, E. and Heraldo, L. and Ho, C. and Hogerhijde, B. and Martin, D. and Riddle, R. and Shofer, F. and Still, M. and Tanner, A. and Walp, B. and Zhang, S.},
+  title   = {The {NASA} Exoplanet Archive: Data and Tools for Exoplanet Research},
+  journal = {Publications of the Astronomical Society of the Pacific},
+  year    = {2013},
+  volume  = {125},
+  number  = {930},
+  pages   = {989--999},
+  doi     = {10.1086/672273}
+}
+
+@article{gordon:2022,
+  author  = {Gordon, I. E. and Rothman, L. S. and Hargreaves, R. J. and Hashemi, R. and Karlovets, E. V. and Skinner, F. M. and Conway, E. K. and Hill, C. and Kochanov, R. V. and Tan, Y. and Wcis{\l}o, P. and Finenko, A. A. and Nelson, K. and Bernath, P. F. and Birk, M. and Boudon, V. and Campargue, A. and Chance, K. V. and Coustenis, A. and Drouin, B. J. and Flaud, J.-M. and Gamache, R. R. and Hodges, J. T. and Jacquemart, D. and Mlawer, E. J. and Nikitin, A. V. and Perevalov, V. I. and Rotger, M. and Tennyson, J. and Toon, G. C. and Tran, H. and Tyuterev, V. G. and Adkins, E. M. and Baker, A. and Barbe, A. and Can{\'e}, E. and Csász{\'a}r, A. G. and Dudaryonok, A. and Egorov, O. and Fleisher, A. J. and Fleurbaey, H. and Foltynowicz, A. and Furtenbacher, T. and Harrison, J. J. and Hartmann, J.-M. and Horneman, V.-M. and Huang, X. and Karman, T. and Karns, J. and Kassi, S. and Kleiner, I. and Kofman, V. and Kwabia-Tchana, F. and Lavrentieva, N. N. and Lee, T. J. and Long, D. A. and Lukashevskaya, A. A. and Lyulin, O. M. and Makhnev, V. Yu. and Matt, W. and Massie, S. T. and Melosso, M. and Mikhailenko, S. N. and Mondelain, D. and M{\"u}ller, H. S. P. and Naumenko, O. V. and Perrin, A. and Polyansky, O. L. and Raddaoui, E. and Raston, P. L. and Reed, Z. D. and Rey, M. and Richard, C. and T{\'o}bi{\'a}s, R. and Sadiek, I. and Schwenke, D. W. and Starikova, E. and Sung, K. and Tamassia, F. and Tashkun, S. A. and Vander Auwera, J. and Vasilenko, I. A. and Vigasin, A. A. and Villanueva, G. L. and Vispoel, B. and Wagner, G. and Yachmenev, A. and Yurchenko, S. N.},
+  title   = {The {HITRAN2020} molecular spectroscopic database},
+  journal = {Journal of Quantitative Spectroscopy and Radiative Transfer},
+  year    = {2022},
+  volume  = {277},
+  pages   = {107949},
+  doi     = {10.1016/j.jqsrt.2021.107949}
+}
+
+@article{yaron:2012,
+  author  = {Yaron, O. and Gal-Yam, A.},
+  title   = {{WISeREP} --- An Interactive Supernova Data Repository},
+  journal = {Publications of the Astronomical Society of the Pacific},
+  year    = {2012},
+  volume  = {124},
+  number  = {917},
+  pages   = {668--681},
+  doi     = {10.1086/666656}
+}
+
+@article{guillochon:2017,
+  author  = {Guillochon, J. and Parrent, J. and Kelley, L. Z. and Margutti, R.},
+  title   = {An Open Catalog for Supernova Data},
+  journal = {The Astrophysical Journal},
+  year    = {2017},
+  volume  = {835},
+  number  = {1},
+  pages   = {64},
+  doi     = {10.3847/1538-4357/835/1/64}
+}
+
+@article{malo:2021,
+  author  = {Malo, L. and Gagn{\'e}, J.},
+  title   = {{MOCA}: The Montreal Open Clusters and Associations Catalog},
+  journal = {Research Notes of the American Astronomical Society},
+  year    = {2021},
+  volume  = {5},
+  number  = {9},
+  pages   = {221},
+  doi     = {10.3847/2515-5172/ac2440}
+}
+
+@article{stolker:2020,
+  author  = {Stolker, T. and Quanz, S. P. and Todorov, K. O. and Kühn, J. and Mollière, P. and Meyer, M. R. and Lew, B. and Lacour, S.},
+  title   = {{MIRACLES}: atmospheric characterization of directly imaged planets and substellar companions at 4--5 $\mu$m. {I}. Youngwide-orbit exoplanets},
+  journal = {Astronomy \& Astrophysics},
+  year    = {2020},
+  volume  = {635},
+  pages   = {A182},
+  doi     = {10.1051/0004-6361/201937159}
+}
+
+@article{price-whelan:2021,
+  author  = {{Price-Whelan}, A. M. and {Bonaca}, A. and {Caldwell}, N. and {Cerny}, W. and {Conroy}, C. and {Cunningham}, E. C. and {Hernquist}, L. and {Koposov}, S. E. and {Naidu}, R. P. and {Nidever}, D. L. and {Oh}, S. and {Speagle}, J. S. and {Vivas}, A. K.},
+  title   = {Off the Beaten Track: A New Catalog of Stellar Streams in the Milky Way},
+  journal = {The Astrophysical Journal},
+  year    = {2021},
+  volume  = {910},
+  number  = {1},
+  pages   = {17},
+  doi     = {10.3847/1538-4357/abcb8d}
+}
+
+@article{hinkel:2014,
+  author  = {Hinkel, N. R. and Timmes, F. X. and Young, P. A. and Pagano, M. D. and Turnbull, M. C.},
+  title   = {Stellar Abundances in the Solar Neighborhood: The {Hypatia} Catalog},
+  journal = {The Astronomical Journal},
+  year    = {2014},
+  volume  = {148},
+  number  = {3},
+  pages   = {54},
+  doi     = {10.1088/0004-6256/148/3/54}
+}
+@dataset{ucsheet,
+  author       = {Best, William M. J. and
+                  Dupuy, Trent J. and
+                  Liu, Michael C. and
+                  Sanghi, Aniket and
+                  Siverd, Robert J. and
+                  Zhang, Zhoujian},
+  title        = {The UltracoolSheet: Photometry, Astrometry,
+                   Spectroscopy, and Multiplicity for 4000+ Ultracool
+                   Dwarfs and Imaged Exoplanets
+                  },
+  month        = jul,
+  year         = 2025,
+  publisher    = {Zenodo},
+  version      = {2.1.0},
+  doi          = {10.5281/zenodo.15802304},
+  url          = {https://doi.org/10.5281/zenodo.15802304},
+}

paper2026/paper.md

@@ -0,0 +1,123 @@
+---
+title: 'AstroDB Toolkit: A toolkit for creating and maintaining small, collaborative astronomical databases'
+tags:
+  - Python
+  - astronomy
+  - databases
+  - data management
+authors:
+  - name: Kelle L. Cruz
+    orcid: 0000-0000-0000-0000
+    equal-contrib: true
+    affiliation: "1, 2, 3" 
+  - name: David Rodriguez
+    orcid: 0000-0000-0000-0000
+    equal-contrib: true 
+    affiliation: 4
+affiliations:
+ - name: Hunter College, City University of New York, United States
+   index: 1
+ - name: Graduate Center, City University of New York, United States
+   index: 2
+ - name: Astrophysics, American Museum of Natural History, United States
+   index: 3
+ - name: STScI, USA
+   index: 4
+date: 1 April 2026
+bibliography: paper.bib
+
+---
+## Summary
+
+We introduce the AstroDB Toolkit to fill a gap in the data management/sharing ecosystem for astronomers working on catalogs of astronomical sources. The AstroDB Toolkit is an open-source, openly developed tool that lowers the technology burden on astronomers and empowers them to make databases of astronomical sources using a common, interoperable framework. The Toolkit uses GitHub’s features and its collaborative workflow.
+
+## Statement of need
+
+In the “big data” era of large datasets and archive science, astronomers find themselves managing increasingly large and unwieldy collections of astrophysical parameters, both observed and derived.
+Currently, astronomers reinvent the wheel, spending time making technology choices, database design decisions, and web applications as opposed to focusing on the analysis and physical interpretation of actual data.
+The AstroDB Toolkit greatly lowers the technology burden on the astronomers and empowers them to make databases of astronomical sources using a common, interoperable framework.
+
+The AstroDB Toolkit aims to serve the needs of individual astronomers and small-to-medium sized collaborations who need a data management system for hundreds to thousands of sources. The Toolkit bridges the divide where a shared spreadsheet is insufficient, but the dataset is either still living (e.g., follow-up observations are underway, new parameters being derived) or otherwise not appropriate for an institutional archive.
+
+## State of the field
+
+The astronomical community has produced numerous data compilations, but they fall into two broad categories: large institutional archives and small grassroots efforts — and neither category offers a reusable framework for building new compilations.
+
+**Institutional archives** such as the NASA Exoplanet Archive [@akeson:2013], HITRAN [@gordon:2022], and WISeREP [@yaron:2012] provide excellent data access and, in the case of the Exoplanet Archive, gold-standard interoperability via the IVOA Table Access Protocol (TAP) and ADQL. However, their backends are undisclosed, they are operated by dedicated engineering teams, and they cannot be deployed by individual researchers or small collaborations. Contributing data requires submission through web forms or bulk upload APIs. These platforms are powerful for data consumers but offer no path for an astronomer to build their own analogous database.
+
+**Grassroots compilations** span a wide range of technology choices with little interoperability between them. The Open Astronomy Catalogs (AstroCats; @guillochon:2017) represent the most mature open-source effort: each transient source is stored as a richly annotated JSON file in a Git repository, with a documented schema that mandates source attribution for every data point. The framework was explicitly designed to be reusable, and four separate catalogs (supernovae, tidal disruption events, novae, black holes) were built on it. However, AstroCats supports only JSON — there is no relational query layer — and the codebase targets Python 2/3.4–3.6, limiting its continued maintainability. The MOCA database of open clusters [@malo:2021] uses a hosted MySQL backend with a companion Python package (`mocapy`) for querying, but the database schema is not designed to be forked and repopulated for a new science case. The Community Atlas of Tidal Streams [@price-whelan:2021] encapsulates its science logic in Jupyter notebooks with no persistent database backend, making it difficult to query programmatically or extend to new data types. At the lightest end of the spectrum, compilations such as the Ultracool Sheet [@ucsheet] and the Hypatia Catalog [@hinkel:2014] rely on Google Sheets or web-only interfaces — convenient for human browsing but lacking version control, contribution workflows, or machine-readable schemas.
+
+Across this landscape, several gaps are consistent. Schema documentation is rare. Contribution workflows are ad hoc (CSV uploads, pull requests against JSON files, or web forms), with no shared tooling. Most critically, none of these projects offer a general-purpose, deployable framework: an astronomer who wants to build their own compilation of, say, low-mass stars or high-redshift galaxies cannot fork any of these projects and adapt the infrastructure to their science case without essentially starting from scratch.
+
+## Software design
+
+The technical choices that were made in the development of the AstroDB Toolkit followed several design requirements:
+
+- Ability to represent complex data models in a simple, intuitive fashion,
+- Support for datasets up to tens of thousands of astrophysical sources,
+- Collaborative editing that enables community members to modify and maintain data holdings,
+- Be usable privately for managing not-yet-public data,
+- Interactively explore and visualize holdings via a website,
+- Queryable locally via scripting without the need for an internet connection.
+
+As described below, the AstroDB Toolkit meets all of these requirements.
+
+The AstroDB Toolkit consists of:
+
+- a template schema ([`astrodb-template-db`](https://github.com/astrodbtoolkit/astrodb-template-db)),
+- Python packages ([`AstrodbKit`](https://github.com/astrodbtoolkit/AstrodbKit), [`astrodb_utils`](https://github.com/astrodbtoolkit/astrodb_utils)), and
+- [documentation and suggested workflows](https://astrodb-utils.readthedocs.io/en/stable/)
+
+The AstroDB Toolkit facilitates the creation of intermediate-scale databases focused on typical astronomy use-cases. The Toolkit's template schema (\autoref{fig:schema}) relies on an object-model that naturally translates to astronomical sources, that is to say, the core table in the database can represent objects such as brown dwarfs or galaxies, while supporting tables represent properties of that object. Because the AstroDB Toolkit’s core Python package, `AstrodbKit`, is a wrapper around the database package `SQLAlchemy`, it supports a large range of database architectures, including SQLite, PostgreSQL, MySQL, etc, while using language that is familiar to astronomers. `AstrodbKit` also supports cone searches and can output results as `astropy.table` objects.
+
+Uses Felis.
+![Template Schema.\label{fig:schema}](schema_erd.png){ width=20% }
+
+### Collaborative Workflow and Testing with GitHub
+
+One of the key design requirements for an AstroDB Toolkit-powered database is support for collaborative editing of the holdings using a GitHub workflow. As a result, the Toolkit creates databases that are fundamentally a set of plain text JSON files that describe each object. When users make changes to the properties of an object, such as adding a new spectrum or updating a value for a radial velocity, these changes are human-readable as a simple diff between two JSON files and can be reviewed via pull requests. This JSON document store architecture allows for a community to maintain a database, review changes as they come in, and use automated tools to validate the database. The `AstrodbKit` package has tools to readily transform data between the document store and relational database to facilitate managing local, private data as well as external applications, such as a hosted website.
+
+An individual user may deploy their own copy of any AstroDB database. They may make changes in their local branch and push to their copy on GitHub. By issuing a pull request, they request their changes be adopted into the main branch of the database. Because the database is stored as individual JSON documents, reviewers can see exactly which objects have been updated and can comment on the changes if needed.
+
+As part of the pull request process, automatic tests implemented via GitHub Actions can be run to verify the integrity of the database. This ensures no changes took place that break the functionality of the database and also include verification for the data that has been added.
+
+Finally, when the pull request is accepted, additional automated tasks can be performed to regenerate the database and push it to external users of the database, such as a hosted website.
+
+<!-- Figures can be included like this:
+![Caption for example figure.\label{fig:example}](figure.png)
+and referenced from text using \autoref{fig:example}.
+
+Figure sizes can be customized by adding an optional second parameter:
+![Caption for example figure.](figure.png){ width=20% } -->
+
+![Toolkit design.\label{fig:design}](astrodbkit_v2.png)
+
+### Spectra and non-tabular data
+
+Spectra, images, and other non-tabular data are stored as pointers to cloud-hosted files. The files are hosted in a variety of places, including institutional repositories. However, we have found the easiest and most reliable host to be Amazon Simple Storage Service (Amazon S3). Amazon S3 provides individual links to each file and since they are infrequently accessed, the cost is minimal.
+In order to enable the database to fully function without an internet connection and/or to point to files not hosted in the cloud, we allow pointers to local files using an environment variable to indicate a local path.
+AstrodbKit contains logic to understand which columns contain pointers to spectra and translates them into `specutils.Spectrum` objects.
+
+## Research impact statement
+
+*Evidence of realized impact (publications, external use, integrations) or credible near-term significance (benchmarks, reproducible materials, community-readiness signals). The evidence should be compelling and specific, not aspirational.*
+
+The current poster-child of the AstroDB Toolkit is SIMPLE, the Substellar and IMaged PLanet Explorer Archive of Complex Objects [https://simple-bd-archive.org/](https://simple-bd-archive.org/).
+
+The newest useage of the Toolkit is focused on Dwarf Galaxies. There are tens if not hundreds of galaxies in the Local Group, with a diverse range of applicable science problems. Many of these scientific applications depend on having as complete as possible a list of properties for these galaxies including total luminosity, half-light radius, and redshift/systemic velocity.
+
+## AI usage disclosure
+
+Generative AI tools were used at several stages of this work.
+
+**GitHub Copilot** was used to assist in writing small portions of code and inline documentation throughout the development of the AstroDB Toolkit. Its assistance was limited to code completion and documentation suggestions.
+
+**Claude Sonnet 4.6** (Anthropic, accessed via Claude Code CLI) was used to assist in drafting the "State of the field" section of this manuscript, including researching and summarizing the technology stacks and schemas of related astronomical data compilations, and constructing initial BibTeX bibliography entries for cited works.
+
+All AI-generated text and code was thoroughly reviewed, revised, and validated by the human authors. The authors made all primary architectural and design decisions for the AstroDB Toolkit. The authors take full responsibility for the accuracy of all content in this manuscript, including citations and bibliographic details.
+
+## Acknowledgements
+
+We acknowledge contributions from Arjun, HS students, etc.
+
+## References

pyproject.toml

@@ -111,6 +111,9 @@ max-complexity = 20
 
 [tool.coverage.run]
 branch = true
+omit = [
+    "paper2026/**"
+]
 
 [tool.coverage.report]
 # Relaxed coverage requirements