Specreduce Glossary by hpparvi · Pull Request #304 · astropy/specreduce

hpparvi · 2026-03-27T20:09:29Z

This PR addresses #285 by replacing the old terms.rst document with a full glossary. Please go through it and let me know if you disagree with any of the definitions or if you think anything is missing. You can find a rendered version of the glossary at https://specreduce--304.org.readthedocs.build/en/304/glossary.html.

LLM disclaimer: This PR includes rather (very) heavy use of LLMs, and I'd like to hear comments from people who might not be comfortable with this (comments from people who are comfortable with this are, of course, also welcome ;) ). My workflow was:

I started with the original terminology document terms.rst
I added terms I thought should be included, with basic definitions.
I tasked Claude Code (Opus 4.6) to rewrite the document into a proper, sorted, Sphinx glossary, and to include terms that are used in the specreduce package and documentation that were not included in the original terminology document.
I went through the glossary created by Claude code and revised it based on my own opinions and knowledge.
I fed the glossary to ChatGPT (5.4) and asked its opinion about the definitions, and whether there were any important terms missing.
I revised the document based on the ChatGPT output (and my own judgement).
I fed the revised glossary to Gemini (3.1 Pro) and asked it to review the definitions in a similar fashion to ChatGPT.
I revised the document based on Gemini output (and my own judgement).
I went through the definitions manually (with some minor tweaks, adding some hyperlinks, etc.).
I tasked Claude Code to again check the terms and definitions against the specreduce codebase.

So, the glossary is based on the existing terminology document, my own knowledge, and three (paid) LLMs. The input from the LLMs is substantial, but I have gone through the final set of definitions several times to ensure that there is nothing I would consider wrong (and likely added some typos along the way).

…the Sphinx configuration files. Added a new glossary section to replace the removed content.

codecov · 2026-03-27T20:11:39Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.45%. Comparing base (b0f657c) to head (6ff5c73).
⚠️ Report is 10 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #304   +/-   ##
=======================================
  Coverage   90.45%   90.45%           
=======================================
  Files          16       16           
  Lines        1855     1855           
=======================================
  Hits         1678     1678           
  Misses        177      177

☔ 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

Some minor comments, but overall looks extremely useful!!!

docs/glossary.rst

weaverba137

This is a great document, and most of my comments are minor. However, I have one major concern: I don't think the Terminology document (terms.rst) should be eliminated unless we are completely satisfied that:

All information contained in terms.rst has been migrated to glossary.rst.
terms.rst also functioned as a thesaurus to some degree, so we should double-check that all items in glossary.rst include synonyms and antonyms. Some entries already do, but this should be verified systematically.

Finally, if we do eliminate terms.rst can we provide a redirect to glossary.rst? Alternatively, keep the existing terms.rst, mark it as deprecated, and link to glossary.rst.

docs/glossary.rst

weaverba137 · 2026-03-27T21:46:02Z

docs/glossary.rst

+      light from one or more sources. One axis corresponds to wavelength (the
+      :term:`dispersion axis`) and the other to spatial position along the slit
+      (the :term:`cross-dispersion axis`). Also called a spectral image. This is
+      the input to the extraction process that produces a :term:`1D spectrum`.


I would add a qualifier here that 2D Spectra are not unique to slit spectroscopy, fiber spectrographs start with 2d images as well.

You could also reference MOS (multi-object spectroscopy) here.

I've revised the 2D Spectrum definition to include the qualifier, added a link to MOS, and also added a definition for "Fiber-fed spectroscopy".

weaverba137 · 2026-03-27T21:52:49Z

docs/glossary.rst

+      A three-dimensional data structure with two spatial dimensions and one
+      spectral dimension. Data cubes are the standard output format for
+      :term:`IFU` observations, where each spatial pixel contains a complete
+      spectrum. Also called a spectral data cube or hyperspectral cube.


You might also want to include the term "spaxel".

weaverba137 · 2026-03-27T21:57:30Z

docs/glossary.rst

+      different wavelengths falls on different positions along this axis.
+
+   Emission Line
+      A bright, narrow feature in a spectrum at a specific wavelength,


I wouldn't use the term "narrow" without some qualification. For example, QSO emission lines can be very broad. In fact, "bright" could also be a bit vague. Maybe "An excess flux feature in a spectrum at a specific wavelength, ...". I'd be open to any alternate wording here.

Thanks, I've revised this now.

weaverba137 · 2026-03-27T22:01:32Z

docs/glossary.rst

+   FWHM
+      Full Width at Half Maximum. A measure of the width of a peak or line
+      profile, defined as the width at which the intensity drops to half its
+      maximum value. FWHM is commonly used to characterize :term:`spectral


Absorption lines also have a FWHM, so "drops to half" isn't quite right here. You could do something simple like "width at which the intensity drops (rises) to half its maximum (minimum) value.

Take a look at the revised version. I've also added a definition for "Absorption line".

weaverba137 · 2026-03-27T22:08:34Z

docs/glossary.rst

+      A spectrum that has been resampled so that the :term:`dispersion axis`
+      is aligned with image rows or columns, with constant wavelength spacing.
+      Rectification involves :term:`resampling`. A rectified
+      ND spectrum has one axis that is purely spectral.


Is "ND" meant to be "2D"?

I used ND originally to include 3D data cubes, etc. I've changed this now to 2D for simplicity.

docs/glossary.rst

hpparvi · 2026-03-30T15:48:55Z

This is a great document, and most of my comments are minor. However, I have one major concern: I don't think the Terminology document (terms.rst) should be eliminated unless we are completely satisfied that:
* All information contained in `terms.rst` has been migrated to `glossary.rst`.

* `terms.rst` also functioned as a _thesaurus_ to some degree, so we should double-check that all items in `glossary.rst` include synonyms and antonyms. Some entries already do, but this should be verified systematically.
Finally, if we do eliminate terms.rst can we provide a redirect to glossary.rst? Alternatively, keep the existing terms.rst, mark it as deprecated, and link to glossary.rst.

I chose the third option. The original terms.rst document is now back as it was (and where it was), but with a deprecation warning and a link to the glossary document. A compiled version of the terms doc can be found at https://specreduce--304.org.readthedocs.build/en/304/terms.html and the glossary at https://specreduce--304.org.readthedocs.build/en/304/glossary.html.

weaverba137

I had two minor comments on this round. Looking good overall.

weaverba137 · 2026-03-30T18:39:07Z

docs/glossary.rst

+      :term:`barycentric correction`, which provides higher precision.
+
+   IFU
+      `Integral Field Unit <https://en.wikipedia.org/wiki/Integral_field_spectrograph>`__.


This might not make any practical difference, but this external hyperlink is terminated with two underscores, while other external hyperlinks have one underscore.

Thanks for catching this; it was a typo.

weaverba137 · 2026-03-30T21:15:55Z

docs/glossary.rst

+
+   Spectrum
+      The distribution of light intensity as a function of wavelength or
+      frequency. In specreduce and specutils, ``Spectrum`` specifically


I would make this a link to specutils.Spectrum.

hpparvi added 4 commits February 16, 2026 18:39

Removed outdated terminology documentation and updated references in …

5593ed5

…the Sphinx configuration files. Added a new glossary section to replace the removed content.

Added the first version of glossary.

6c34952

Revised the glossary.

19b17c7

Minor glossary cleanup.

49d777b

hpparvi linked an issue Mar 27, 2026 that may be closed by this pull request

Consider expanding definitions of unfamiliar terms in the Terminology page. #285

Open

hpparvi requested review from cshanahan1, kecnry and tepickering March 27, 2026 20:14

hpparvi added the enhancement label Mar 27, 2026

hpparvi added this to the v1.9 milestone Mar 27, 2026

kelle approved these changes Mar 27, 2026

View reviewed changes

docs/glossary.rst Outdated Show resolved Hide resolved

docs/glossary.rst Show resolved Hide resolved

hpparvi requested a review from weaverba137 March 27, 2026 21:19

weaverba137 suggested changes Mar 27, 2026

View reviewed changes

hpparvi added 3 commits March 28, 2026 18:03

Glossary revisions based on comments by Kelle Cruz and B. A. Weaver.

8a4784f

Brought back the original terms.rst terminology document.

3235730

Added a deprecation warning to the terms.rst terminology doc.

9ec102f

hpparvi requested a review from weaverba137 March 30, 2026 15:56

weaverba137 approved these changes Mar 30, 2026

View reviewed changes

hpparvi requested a review from kbwestfall April 5, 2026 18:23

Glossary cleanup.

6ff5c73

Uh oh!

Conversation

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

Uh oh!

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

kelle left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

weaverba137 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

weaverba137 left a comment

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!

3 participants

hpparvi commented Mar 27, 2026 •

edited

Loading

codecov bot commented Mar 27, 2026 •

edited

Loading

hpparvi commented Mar 30, 2026 •

edited

Loading