JOSS Paper by kelle · Pull Request #238 · astrodbtoolkit/astrodb_utils

kelle · 2026-03-25T20:50:20Z

Let's write a short JOSS paper!

codecov · 2026-03-25T20:52:27Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 72.38%. Comparing base (0b8e36b) to head (5e503c6).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #238      +/-   ##
==========================================
- Coverage   72.62%   72.38%   -0.24%     
==========================================
  Files          19       19              
  Lines        1673     1673              
  Branches      211      211              
==========================================
- Hits         1215     1211       -4     
- Misses        376      380       +4     
  Partials       82       82

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

kelle · 2026-04-01T18:01:49Z

The NASA proposal has the best text to pull from: https://docs.google.com/document/d/13I8EMbolHw1F4P7-QRJ6x_wYdZOFLhHw-pEaOB4BZvQ/edit?tab=t.0#heading=h.jfxzkej6mv63

…-paper

…noreply@anthropic.com>

- Draft State of the field section comparing tech stacks of existing astronomical compilations (AstroCats, MOCA, species, CATS, Hypatia, Ultracool Sheet, NASA Exoplanet Archive, WISeREP, HITRAN) - Add paper.bib with citations for all referenced works - Add @ucsheet Zenodo dataset entry for the Ultracool Sheet - Expand AI usage disclosure to meet required disclosure standards Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…-paper

kelle · 2026-04-01T21:07:32Z

Solid first draft. @dr-rodriguez , take a look!

dr-rodriguez · 2026-04-03T14:18:18Z

paper2026/paper.md

+---
+## Summary
+
+We introduce the AstroDB Toolkit to fill a gap in the data management/sharing ecosystem for astronomers by providing a robust toolkit to empower astronomers to build databases of astronomical sources. The AstroDB Toolkit is an open-source, openly developed tool that greatly lowers the technology burden on the 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.


Suggested change

We introduce the AstroDB Toolkit to fill a gap in the data management/sharing ecosystem for astronomers by providing a robust toolkit to empower astronomers to build databases of astronomical sources. The AstroDB Toolkit is an open-source, openly developed tool that greatly lowers the technology burden on the 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.

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.

dr-rodriguez · 2026-04-03T14:19:50Z

paper2026/paper.md

+## Statement of need
+
+The purpose of the AstroDB Toolkit is to fill a gap in the data management/sharing ecosystem for astronomers by providing a robust toolkit to empower astronomers to build databases of astronomical sources.
+In the “big data” era of large, long-standing missions such as TESS, Kepler, and JWST, astronomers find themselves managing increasingly large and unwieldy collections of target parameters, both observed and modeled.


Suggested change

In the “big data” era of large, long-standing missions such as TESS, Kepler, and JWST, astronomers find themselves managing increasingly large and unwieldy collections of target parameters, both observed and modeled.

In the “big data” era of large, long-standing missions such as TESS, Kepler, and JWST, astronomers find themselves managing increasingly large and unwieldy collections of astrophysical parameters, both observed and derived.

dr-rodriguez · 2026-04-03T14:20:31Z

paper2026/paper.md

+
+## Statement of need
+
+The purpose of the AstroDB Toolkit is to fill a gap in the data management/sharing ecosystem for astronomers by providing a robust toolkit to empower astronomers to build databases of astronomical sources.


This entire sentence feels like a repetition of the summary, I think we can start with "In the big data era" and remove this sentence

dr-rodriguez · 2026-04-03T14:20:56Z

paper2026/paper.md

+
+The purpose of the AstroDB Toolkit is to fill a gap in the data management/sharing ecosystem for astronomers by providing a robust toolkit to empower astronomers to build databases of astronomical sources.
+In the “big data” era of large, long-standing missions such as TESS, Kepler, and JWST, astronomers find themselves managing increasingly large and unwieldy collections of target parameters, both observed and modeled.
+Currently, astronomers reinvent the wheel, spending time making technology choices, database design decisions, and web applications as opposed to being able to focus on the analysis and physical interpretation of the actual data.


Suggested change

Currently, astronomers reinvent the wheel, spending time making technology choices, database design decisions, and web applications as opposed to being able to focus on the analysis and physical interpretation of the actual data.

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.

dr-rodriguez · 2026-04-03T14:21:48Z

paper2026/paper.md

+Currently, astronomers reinvent the wheel, spending time making technology choices, database design decisions, and web applications as opposed to being able to focus on the analysis and physical interpretation of the 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 Google sheet 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.


Suggested change

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 Google sheet 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.

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.

dr-rodriguez · 2026-04-03T14:30:57Z

paper2026/paper.md

+
+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.
+
+By exporting a database to a JSON document store, we can use git and GitHub to handle version control for our database as well as curate commits via pull requests.


Suggested change

By exporting a database to a JSON document store, we can use git and GitHub to handle version control for our database as well as curate commits via pull requests.

dr-rodriguez · 2026-04-03T14:31:44Z

paper2026/paper.md

+
+By exporting a database to a JSON document store, we can use git and GitHub to handle version control for our database as well as curate commits via pull requests.
+
+An individual user may contain their own copy of any 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.


Suggested change

An individual user may contain their own copy of any 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.

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.

dr-rodriguez · 2026-04-03T14:32:17Z

paper2026/paper.md

+
+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 graphical user interface.


Suggested change

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 graphical user interface.

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.

dr-rodriguez · 2026-04-03T14:33:27Z

paper2026/paper.md

+
+### 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 best host to be Amazon Simple Storage Service (Amazon S3). 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.


We don't really explain why the best host is Amazon S3, we may be asked to justify that or list what else we tested.

dr-rodriguez · 2026-04-03T14:34:15Z

paper2026/paper.md

+
+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 such as: total luminosity, half-light radius, and redshift/systemic velocity.


Suggested change

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 such as: total luminosity, half-light radius, and redshift/systemic velocity.

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.

start of paper

981c9ab

kelle added 4 commits March 25, 2026 16:57

paper guidance

95a3528

add action to build PDF

ed40c31

update path

da2cdfb

add some text

8e81172

dr-rodriguez self-requested a review April 1, 2026 17:53

kelle and others added 20 commits April 1, 2026 14:23

add text from NASA proposal

701402a

try to turn off codecov

103274a

yaml lint

23eb4a2

fix path in PDF workflow

5e503c6

removed unused citations

abafb5a

(auto) Paper PDF Draft

24317e7

bump action versions

5e893f9

Merge branch 'joss-paper' of github.com:kelle/astrodb-utils into joss…

7008c79

…-paper

(auto) Paper PDF Draft

19bceb1

another version bump

f972272

Merge branch 'joss-paper' of github.com:kelle/astrodb-utils into joss…

8f98252

…-paper

(auto) Paper PDF Draft

04c2b62

State of the field text and refs. Co-Authored-By: Claude Sonnet 4.6 <…

d922605

…noreply@anthropic.com>

(auto) Paper PDF Draft

fd8bf2f

Merge branch 'joss-paper' of github.com:kelle/astrodb-utils into joss…

4593865

…-paper

(auto) Paper PDF Draft

2ba83d9

reduce paper length

21e8699

add figure

ad39a6c

(auto) Paper PDF Draft

28ca754

dr-rodriguez reviewed Apr 3, 2026

View reviewed changes

	In the “big data” era of large, long-standing missions such as TESS, Kepler, and JWST, astronomers find themselves managing increasingly large and unwieldy collections of target parameters, both observed and modeled.
	In the “big data” era of large, long-standing missions such as TESS, Kepler, and JWST, astronomers find themselves managing increasingly large and unwieldy collections of astrophysical parameters, both observed and derived.


		## Statement of need

		The purpose of the AstroDB Toolkit is to fill a gap in the data management/sharing ecosystem for astronomers by providing a robust toolkit to empower astronomers to build databases of astronomical sources.

	Currently, astronomers reinvent the wheel, spending time making technology choices, database design decisions, and web applications as opposed to being able to focus on the analysis and physical interpretation of the actual data.
	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.


		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.

		By exporting a database to a JSON document store, we can use git and GitHub to handle version control for our database as well as curate commits via pull requests.


		By exporting a database to a JSON document store, we can use git and GitHub to handle version control for our database as well as curate commits via pull requests.

		An individual user may contain their own copy of any 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 graphical user interface.


		### 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 best host to be Amazon Simple Storage Service (Amazon S3). 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.


		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 such as: total luminosity, half-light radius, and redshift/systemic velocity.

Conversation

kelle commented Mar 25, 2026

Uh oh!

codecov bot commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

kelle commented Apr 1, 2026

Uh oh!

kelle commented Apr 1, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codecov bot commented Mar 25, 2026 •

edited

Loading