Add algorithm-level citations for spherical geometry implementations - #1635
Add algorithm-level citations for spherical geometry implementations#1635hongyuchen1030 wants to merge 30 commits into
Conversation
This reverts commit 99573b8.
This reverts commit 1ba6880.
Adds a docs/references.bib with full BibTeX entries for the two Chen et al. UXarray papers plus the supporting numerical-methods references (Shewchuk, Knuth, Dekker, Higham, Jeannerod et al., Rump), extends citation.rst with an algorithm-to-publication mapping table alongside the existing Zenodo citation, and adds References sections to the docstrings of the specific APIs called out in the mapping: Grid.bounds and face_bounds_lon/lat, zonal_mean, the intersection APIs, the arcs predicates, and the compensated-arithmetic primitives in utils/computing.py. Resolves UXARRAY#1631 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- Demote "Algorithm-Level Citations" from a page-title-weight heading to
a proper second-level section, and wrap the call-to-action intro in a
note admonition instead of plain body text.
- Replace short in-text citations ("Chen et al. (2026), GMD") in the
mapping table with the full citation (title, journal, DOI) so readers
don't have to cross-reference elsewhere to know what they're citing.
- Drop the single hand-maintained docs/references.bib (and its now-dead
link to a file that doesn't exist on main yet) in favor of one small
.bib file per publication under docs/_static/citations/, downloadable
directly from next to each citation via Sphinx's :download: role.
- Fix "Documentation section" links: every row pointed at api.html#remapping
regardless of section; now each points at its real anchor (descriptors,
zonal-average, intersections, arcs, compensated-arithmetic), verified
against the built HTML.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Replace the generic "please also cite the corresponding publication(s)" note with more precise guidance on when citation is expected: results reported in an academic work that depend on one of these algorithms (e.g. computed face areas or regridding weights used as analysis input), as opposed to incidental use in tutorials/internal tools/other software that merely depends on UXarray. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Replace em dash punctuation with parentheses (no em dashes unless explicitly requested), swap the citation-trigger examples for concrete UXarray operations (latlon bounds, zonal-mean, conservative remapping, computed face area), and correct "intersection and remapping algorithms" to "intersection and geometry operators" in the SIAM paper's intro sentence.
Merge table rows that share the same documentation section and required citation (Descriptors bounds/face_bounds_lon/face_bounds_lat; Arcs orient3d_on_sphere/on_minor_arc; Arcs in_between/point_within_gca; Compensated Arithmetic accucross/accucross_pair) into single rows listing each API on its own line, instead of repeating the citation per row. Also reorder the Arcs rows to match the order APIs actually appear in api.rst (in_between, point_within_gca, extreme_gca_latitude, orient3d_on_sphere, on_minor_arc); the other sections already matched.
Independent citation audit against the DOI landing page found the published title uses the multiplication sign (2 × 2), not the letter x, in citation.rst, the jeannerod2013.bib entry, and the diff_of_products docstring. The .bib uses the LaTeX $\times$ form for portability across BibTeX toolchains; the RST/docstring prose uses the Unicode × character directly.
erogluorhan
left a comment
erogluorhan
left a comment
There was a problem hiding this comment.
Overall this looks great; please address only one comment below:
Per review feedback, move everything from the Algorithm-Level Citations heading onward out of citation.rst into a new docs/citations-for-algorithms.rst page, added to the "For users" toctree in index.rst. citation.rst now ends with a brief note pointing readers to the new page, keeping the main "How to Cite UXarray" page focused on the Zenodo software citation.
erogluorhan
left a comment
erogluorhan
left a comment
There was a problem hiding this comment.
Almost there, the newer links, pages, display clean! Just a final iteration hopefully. See comments below
| API Reference <api> | ||
| Tutorials and Videos <tutorials> | ||
| Cite UXarray <citation> | ||
| Algorithm-Level Citations <citations-for-algorithms> |
There was a problem hiding this comment.
Let's remove this from the index as it will show up under "Cite UXarray" page.
Only one "Cite..." entry in this index should be clearer and enough I think:
There was a problem hiding this comment.
Good catch, done — removed it from the toctree in index.rst. It turns out a hidden toctree still surfaces in sphinx_book_theme's sidebar (as a nested item under "Cite UXarray"), so I marked citations-for-algorithms.rst :orphan: instead. It's now reachable only through the link in the note, no separate nav entry at all — just the one "Cite UXarray" entry as you suggested.
There was a problem hiding this comment.
To close the loop on this: right now the page is essentially an orphan — it's not in any toctree, so it's only reachable through the link in the note on "How to Cite UXarray" (or a direct/search-engine link). It doesn't show up anywhere in the sidebar nav at all.
That satisfies "only one Cite... entry," but it also means there's no breadcrumb/Prev-Next trail back into the docs if someone lands there directly, and no other discovery path.
Is that acceptable as-is, or would you prefer it nested as a collapsed sub-item under "Cite UXarray" instead (still just one top-level entry, but with a small expandable arrow revealing the sub-page in the sidebar, plus proper Prev/Next navigation)? Happy to switch to that if you'd rather.
There was a problem hiding this comment.
Hmm, yeah, I don't know what's the best. @rajeeja , @rljacob, @Sevans711 thoughts? Two ways:
- How it currently shows up, i.e. only through Cite UXarray page as @hongyuchen1030 describes
- On left sidebar, we'd have something like this:
- Cite UXarray
- Software package
- Algorithm publications
- Cite UXarray
@hongyuchen1030 what'd be your preference?
There was a problem hiding this comment.
I think most natural would be to change to having a collapsed sub-item, as @hongyuchen1030 suggested. All other docs pages are reachable with Prev/Next navigation, so this would follow that pattern. So, something like this:
- Cite UXarray
- Algorithm-Level Citations
The one downside is that users might not realize "Cite UXarray" is itself a clickable page… but it does get highlighted like a link when you mouse over it, so I think it's fine? Also, my guess is that clicking through the docs isn't the primary way to get to the main "how do I cite this package" page, anyway. I always landed on pages like that by looking at the github README, searching "cite" in the docs, or googling.
There was a problem hiding this comment.
Yeah, my concern with it was that users might not realize "Cite UXarray" is itself a clickable page; hence, offered,
- Cite UXarray
- Software package
- Algorithm publications
where both "Cite UXarray" and "Software package" can link to the Cite UXarray page. This can feel duplicative though.
There was a problem hiding this comment.
How about this
- Cite UXarray Package
- Detailed Algorithm-Level References
The sidebar sub-item provides discoverability: it gives users a direct path from a UXarray function to the peer-reviewed method behind it. It also signals that our results rest on validated, peer-reviewed methods, giving users and reviewers confidence in the package's output.
There was a problem hiding this comment.
I think it makes a lot of sense to have a drop down now, especially with all the content on the new page. It will make it easier to navigate for both humans and machines. I notice AI tools or SEO referencing the docs quite frequently, and it depends heavily on how well the site is structured and how easy it is to find the structure when the machines read the content of the home page.
Having the nested structure will likely also help if someone googles "uxarray algorithm citation", putting them directly to the desired page, rather than making them go to the home page and find it themselves (a lot of friction), because SEO relies on these nested pages being clearly defined and named in ways that people actually search. I worry something specific like: "Detailed Algorithm-Level References" may not be served to someone who just googles "uxarray citation guide" or something similar.
- Cite UXarray (Short and simple with references and brief explanations/demo of the nested pages)
- Package-Level Citation (depends on what this page has on it)
- Algorithm-Level Citations (matches the current title of the page)
This makes the most sense to me, assuming you have enough content for the 1st page, if not, maybe just make it a single nested page and add the 2nd later. It's easy to read, and allows you to assume what the page will be about without reading much into it
There was a problem hiding this comment.
Thanks @dylannelson ! The content of the "Package-Level Citation" wouldn't be any different than what's currently present under the "Cite UXarray" page. That said, I don't know if we need a separate page for that one.
- Remove the toctree entry for citations-for-algorithms from index.rst; a hidden toctree in citation.rst still surfaced it as a nested sidebar item under "Cite UXarray" (sphinx_book_theme includes hidden toctrees in the nav structure, it only suppresses the inline body listing). Mark citations-for-algorithms.rst :orphan: instead so it's reachable only via the :doc: link, with no separate nav entry at all. - Switch the pointer in citation.rst from a plain .. note:: to .. admonition:: Algorithm-Level Citations so the block shows that title instead of the generic "Note".
4 participants
Closes #1631
Overview
docs/references.bibwith full BibTeX entries for the two Chen et al. UXarray papers (GMD 2026, SIAM J. Sci. Comput. 2026) plus the supporting numerical-methods references (Shewchuk 1997, Knuth 1997, Dekker 1971, Higham 2002, Jeannerod et al. 2013, Rump 2023)docs/citation.rstwith an "Algorithm-Level Citations" section: the general node/edge/face statement, human-readable citations for both papers, and the full algorithm-to-publication mapping table from the issue, alongside the existing package-level Zenodo citationReferencessections to the docstrings of the specific APIs listed in the issue's mapping table:Grid.bounds,Grid.face_bounds_lon,Grid.face_bounds_latUxDataArray.zonal_mean(withzonal_average/zonal_anomalycross-referencing it)grid.intersections.gca_gca_intersection,gca_const_lat_intersection,get_number_of_intersectionsgrid.arcs.extreme_gca_latitude,orient3d_on_sphere,on_minor_arcutils.computing.two_sum,two_prod,diff_of_products,accucross,accucross_pair,acc_sqrt_regrid.arcs.in_betweenandpoint_within_gcaintentionally left uncited per the issue (pending removal in a future release)PR Checklist
General
Testing & Benchmarking
N/A — documentation/docstring-only change, no functional or performance impact. Full test suite (815 passed, 1 pre-existing skip) and pre-commit hooks pass locally.
Documentation
docs/api.rst(N/A — no new public API surface)_)Examples
N/A — no notebook examples affected.