o paper: add data flow figure, expand case studies scope, add sections_todo plan

Rajeev Jain · Rajeev Jain · commit 78e401a36da7 · 2025-08-18T16:48:47.000-05:00
diff --git a/paper/images/data_flow.svg b/paper/images/data_flow.svg
@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="540" viewBox="0 0 960 540">
+  <rect width="100%" height="100%" fill="#0b1220"/>
+  <defs>
+    <style>.t{fill:#e5e7eb;font:14px sans-serif;text-anchor:middle}.b{fill:#1f2937;stroke:#93c5fd;stroke-width:2;rx:8}.a{stroke:#9ca3af;stroke-width:2;fill:none;marker-end:url(#ah)}</style>
+    <marker id="ah" markerWidth="10" markerHeight="7" refX="10" refY="3.5" orient="auto"><polygon points="0 0, 10 3.5, 0 7" fill="#9ca3af"/></marker>
+  </defs>
+  <text x="480" y="36" class="t" style="font-weight:bold">UXarray Data Flow</text>
+  <rect x="40" y="80" width="180" height="90" class="b"/><text x="130" y="115" class="t">Inputs</text><text x="130" y="135" class="t">UGRID/MPAS/Exodus/…</text>
+  <rect x="260" y="80" width="180" height="90" class="b"/><text x="350" y="115" class="t">open_grid/open_dataset</text><text x="350" y="135" class="t">Normalization</text>
+  <rect x="480" y="80" width="180" height="90" class="b"/><text x="570" y="115" class="t">Grid</text><text x="570" y="135" class="t">Topology/Geometry</text>
+  <rect x="700" y="80" width="220" height="90" class="b"/><text x="810" y="115" class="t">UxDataArray/UxDataset</text><text x="810" y="135" class="t">Xarray-backed</text>
+  <path d="M220,125 L260,125" class="a"/><path d="M440,125 L480,125" class="a"/><path d="M660,125 L700,125" class="a"/>
+
+  <rect x="80" y="220" width="160" height="80" class="b"/><text x="160" y="255" class="t">subset</text>
+  <rect x="260" y="220" width="160" height="80" class="b"/><text x="340" y="255" class="t">remap</text>
+  <rect x="440" y="220" width="160" height="80" class="b"/><text x="520" y="255" class="t">cross_section</text>
+  <rect x="620" y="220" width="160" height="80" class="b"/><text x="700" y="255" class="t">plot</text>
+  <rect x="800" y="220" width="160" height="80" class="b"/><text x="880" y="255" class="t">analysis</text>
+
+  <path d="M810,170 L880,220" class="a"/><path d="M810,170 L700,220" class="a"/><path d="M810,170 L520,220" class="a"/><path d="M810,170 L340,220" class="a"/><path d="M810,170 L160,220" class="a"/>
+
+  <rect x="360" y="360" width="240" height="110" class="b"/>
+  <text x="480" y="395" class="t">Outputs</text>
+  <text x="480" y="415" class="t">GeoDataFrame • rasters • plots</text>
+  <text x="480" y="435" class="t">netCDF (UGRID) • CSV/Parquet</text>
+
+  <path d="M160,300 L480,360" class="a"/><path d="M340,300 L480,360" class="a"/><path d="M520,300 L480,360" class="a"/><path d="M700,300 L480,360" class="a"/><path d="M880,300 L480,360" class="a"/>
+</svg>
diff --git a/paper/paper.md b/paper/paper.md
@@ -83,13 +83,15 @@ cs = uxds["psi"].cross_section(start=(-45, -45), end=(45, 45), steps=200)
 
 ![Cross-section sampling](images/fig2.svg)
 
+![End-to-end data flow](images/data_flow.svg)
+
 # Use cases
 
 - Cross-section analysis along great-circle arcs and along constant parallels/meridians.
 - Zonal statistics for climate diagnostics.
 - Format-agnostic ingestion and analysis across UGRID/MPAS/Exodus/ICON/SCRIP/ESMF/FESOM/HEALPix.
 - Integration with visualization stacks (Cartopy, HoloViz) for interactive exploration.
-- Project Pythia examples of UXarray usage (to be summarized and cited here).
+- Project Pythia examples of UXarray usage (to be summarized and cited with attribution).
 
 # Quality control
 
diff --git a/paper/sections_todo.md b/paper/sections_todo.md
@@ -0,0 +1,36 @@
+Planned expansions for ~20-page draft
+
+1. Introduction (2–3 pages)
+- Background on unstructured meshes in climate/ocean/atmospheric modeling
+- Limitations of structured-grid tooling for unstructured data
+- UXarray goals and scope; novelty vs adjacent tools
+
+2. Architecture & Design (4–5 pages)
+- Grid model (topology, geometry, UGRID)
+- UxDataArray/UxDataset and accessors (subset/remap/cross_section/plot)
+- Data flow and lazy workflows
+- Extensibility and format normalization
+
+3. Cross-Sections (2–3 pages)
+- Great-circle sampling (pyproj.Geod), constant lat/lon
+- Face selection via get_faces_containing_point
+- Nearest-neighbor semantics and implications
+- Validation rules; examples and pitfalls
+
+4. Case Studies (5–6 pages)
+- Climate diagnostic with zonal means and cross-sections
+- Mesh-agnostic workflow across UGRID/MPAS/ICON
+- Remap pipeline for intercomparison
+- (If available) Project Pythia examples summarized and cited
+
+5. Performance & Quality (2–3 pages)
+- Numba acceleration; dask notes
+- Pre-commit, CI, tests
+- Portability and dependencies
+
+6. Related Work & Discussion (2 pages)
+- Comparison to alternatives; tradeoffs
+- Limitations and roadmap
+
+7. Conclusions (1 page)
+- Contributions recap and future work
diff --git a/paper/uxarray_joss_paper.doc b/paper/uxarray_joss_paper.doc
@@ -87,13 +87,18 @@ cs = uxds["psi"].cross_section(start=(-45, -45), end=(45, 45), steps=200)
 <h3>Case Studies / Example Applications</h3>
 <p>
 We demonstrate: (1) cross-section sampling along geodesics and constant
-parallels/meridians; (2) zonal means; (3) remapping workflows. Figure 2 shows a
-schematic cross-section sampling trajectory.
+parallels/meridians; (2) zonal means; (3) remapping workflows; (4) mesh-agnostic
+comparisons across formats. We will also summarize selected Project Pythia
+examples of UXarray usage (with attribution) once gathered.
 </p>
 <figure>
   <img src="images/fig2.svg" alt="Cross-section sampling" width="640" />
   <figcaption>Figure 2: Sampling a field along a geodesic arc (steps shown along the path).</figcaption>
 </figure>
+<figure>
+  <img src="images/data_flow.svg" alt="Data flow" width="800" />
+  <figcaption>Figure 3: End-to-end data flow: inputs → normalization → grid → accessors → outputs.</figcaption>
+</figure>
 
 <h3>Conclusions</h3>
 <p>
