Adding beginner friendly explanations on the Docs

[dylannelson]

Closes#1582

Overview

While reading through the docs, there was a few ideas I reviewed that could be useful to new users. I was able to implement a few and test the changes

1) More examples/distinctions between unstructured vs structured grids

• Created a whole new page, now in uxarray\docs\user-guide\unstructured-grids.rst
• Created or located 5 new images
• Added connections so this page appears in other lists and taskbars

2) Updating Tutorials and Videos Page

• Added content to docs/tutorials.rst
• Added 2 new links to 2 videos from 2024
• Added brief context for each of the 3 links now on the page

3) More distinct defintions for UxDataAray vs UxDataset

• Defined here: user-guide/data-structures
• Changed slightly after gathering feedback from team

PR Checklist

Documentation

• New images for various pages
• Created a new page for defining unstructured vs structured grids
• Minor tweaks to styling across a few pages
• Added videos to the Tutorials and Videos page with added context

[review-notebook-app]

Check out this pull request on

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[github-actions]

ASV Benchmarking

Benchmark Comparison Results

Benchmarks that have improved:

Change	Before [852a0c0]	After [526ba94]	Ratio	Benchmark (Parameter)
-	522M	336M	0.64	face_bounds.FaceBounds.peakmem_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/ugrid/geoflow-small/grid.nc'))
-	631M	335M	0.53	face_bounds.FaceBounds.peakmem_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/ugrid/quad-hexagon/grid.nc'))
-	451M	330M	0.73	mpas_ocean.Gradient.peakmem_gradient('480km')

Benchmarks that have stayed the same:

Change	Before [852a0c0]	After [526ba94]	Ratio	Benchmark (Parameter)
	10.3±0.2μs	10.4±0.09μs	1.01	bench_connectivity.Connectivity.time_edge_face('120km')
	10.6±0.04μs	10.8±0.07μs	1.02	bench_connectivity.Connectivity.time_edge_face('480km')
	10.6±0.2μs	10.3±0.1μs	0.98	bench_connectivity.Connectivity.time_edge_node('120km')
	10.9±0.2μs	11.2±0.07μs	1.02	bench_connectivity.Connectivity.time_edge_node('480km')
	10.4±0.1μs	10.5±0.09μs	1.01	bench_connectivity.Connectivity.time_face_edge('120km')
	11.0±0.3μs	11.1±0.2μs	1.01	bench_connectivity.Connectivity.time_face_edge('480km')
	10.4±0.1μs	10.7±0.07μs	1.03	bench_connectivity.Connectivity.time_face_face('120km')
	10.8±0.2μs	11.1±0.1μs	1.03	bench_connectivity.Connectivity.time_face_face('480km')
	21.1±0.3μs	20.9±0.2μs	0.99	bench_connectivity.Connectivity.time_face_node('120km')
	22.0±0.3μs	22.3±0.2μs	1.01	bench_connectivity.Connectivity.time_face_node('480km')
	10.4±0.1μs	10.6±0.05μs	1.02	bench_connectivity.Connectivity.time_node_edge('120km')
	10.9±0.1μs	11.1±0.07μs	1.01	bench_connectivity.Connectivity.time_node_edge('480km')
	10.5±0.1μs	10.6±0.2μs	1.01	bench_connectivity.Connectivity.time_node_face('120km')
	10.8±0.2μs	11.1±0.1μs	1.03	bench_connectivity.Connectivity.time_node_face('480km')
	335M	334M	1	face_bounds.FaceBounds.peakmem_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/mpas/QU/oQU480.231010.nc'))
	365M	363M	0.99	face_bounds.FaceBounds.peakmem_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/scrip/outCSne8/outCSne8.nc'))
	22.7±0.1μs	22.9±0.1μs	1.01	face_bounds.FaceBounds.time_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/mpas/QU/oQU480.231010.nc'))
	10.1±0.05μs	10.2±0.06μs	1	face_bounds.FaceBounds.time_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/scrip/outCSne8/outCSne8.nc'))
	10.2±0.02ms	10.2±0.05ms	1	face_bounds.FaceBounds.time_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/ugrid/geoflow-small/grid.nc'))
	2.14±0.02ms	2.14±0.01ms	1	face_bounds.FaceBounds.time_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/ugrid/quad-hexagon/grid.nc'))
	936±0.8ns	957±20ns	1.02	geometry_kernels.AccucrossKernels.time_accucross
	2.46±0.03μs	2.45±0.02μs	0.99	geometry_kernels.AccucrossKernels.time_accucross_pair
	291±3ns	304±10ns	1.04	geometry_kernels.EFTPrimitives.time_acc_sqrt_re
	281±1ns	278±0.4ns	0.99	geometry_kernels.EFTPrimitives.time_diff_of_products
	234±0.4ns	234±0.3ns	1	geometry_kernels.EFTPrimitives.time_two_prod
	237±0.5ns	236±0.3ns	0.99	geometry_kernels.EFTPrimitives.time_two_sum
	1.21±0.02μs	1.23±0.01μs	1.02	geometry_kernels.GCAConstLatIntersection.time_accux_constlat_kernel
	898±3ns	883±10ns	0.98	geometry_kernels.GCAConstLatIntersection.time_gca_const_lat_intersection
	1.65±0.01μs	1.61±0.01μs	0.98	geometry_kernels.GCAConstLatIntersection.time_try_gca_const_lat_intersection
	1.33±0μs	1.32±0.02μs	0.99	geometry_kernels.GCAGCAIntersection.time_accux_gca_kernel
	1.11±0.01μs	1.10±0.01μs	0.98	geometry_kernels.GCAGCAIntersection.time_gca_gca_intersection
	1.87±0μs	1.84±0.01μs	0.98	geometry_kernels.GCAGCAIntersection.time_try_gca_gca_intersection
	49.8±0.5μs	49.2±2μs	0.99	geometry_kernels.OrientPredicates.time_on_minor_arc
	504±2ns	507±0.4ns	1.01	geometry_kernels.OrientPredicates.time_orient3d_on_sphere
	2.70±0.1ms	2.59±0ms	0.96	geometry_samebody.SameBodyConstLat.time_accux_dispatch
	1.17±0ms	1.17±0ms	1	geometry_samebody.SameBodyConstLat.time_accux_kernel
	1.72±0.01ms	1.72±0.01ms	1	geometry_samebody.SameBodyConstLat.time_fp64_dispatch
	146±0.3μs	145±0.3μs	1	geometry_samebody.SameBodyConstLat.time_fp64_kernel
	33.0±0.06ms	32.3±0.8ms	0.98	geometry_samebody_gcagca.SameBodyGcaGca.time_accux_dispatch
	10.2±0.06ms	10.2±0.05ms	1	geometry_samebody_gcagca.SameBodyGcaGca.time_accux_kernel
	26.4±0.04ms	26.4±0.02ms	1	geometry_samebody_gcagca.SameBodyGcaGca.time_fp64_dispatch
	4.86±0.01ms	4.92±0.06ms	1.01	geometry_samebody_gcagca.SameBodyGcaGca.time_fp64_kernel
	818±6ms	815±3ms	1	import.Imports.timeraw_import_uxarray
	936±5ns	915±7ns	0.98	mpas_ocean.CheckNorm.time_check_norm('120km')
	902±8ns	960±30ns	1.06	mpas_ocean.CheckNorm.time_check_norm('480km')
	816±9ms	826±9ms	1.01	mpas_ocean.ConnectivityConstruction.time_face_face_connectivity('120km')
	52.9±0.8ms	53.4±0.6ms	1.01	mpas_ocean.ConnectivityConstruction.time_face_face_connectivity('480km')
	14.6±0.4μs	14.5±0.09μs	0.99	mpas_ocean.ConnectivityConstruction.time_n_nodes_per_face('120km')
	14.8±0.05μs	14.8±0.1μs	1	mpas_ocean.ConnectivityConstruction.time_n_nodes_per_face('480km')
	4.88±0.02ms	4.90±0.04ms	1	mpas_ocean.ConstructFaceLatLon.time_cartesian_averaging('120km')
	3.37±0.03ms	3.38±0.01ms	1	mpas_ocean.ConstructFaceLatLon.time_cartesian_averaging('480km')
	3.56±0.06s	3.45±0s	0.97	mpas_ocean.ConstructFaceLatLon.time_welzl('120km')
	222±0.9ms	222±1ms	1	mpas_ocean.ConstructFaceLatLon.time_welzl('480km')
	18.2±0.03ms	18.2±0.03ms	1	mpas_ocean.ConstructTreeStructures.time_ball_tree('120km')
	1.05±0.01ms	1.03±0.02ms	0.98	mpas_ocean.ConstructTreeStructures.time_ball_tree('480km')
	10.6±0.03ms	10.6±0.01ms	1	mpas_ocean.ConstructTreeStructures.time_kd_tree('120km')
	729±10μs	775±50μs	1.06	mpas_ocean.ConstructTreeStructures.time_kd_tree('480km')
	702±0.9ms	703±4ms	1	mpas_ocean.CrossSections.time_const_lat('120km', 1)
	353±7ms	352±2ms	1	mpas_ocean.CrossSections.time_const_lat('120km', 2)
	183±1ms	183±1ms	1	mpas_ocean.CrossSections.time_const_lat('120km', 4)
	544±2ms	546±2ms	1	mpas_ocean.CrossSections.time_const_lat('480km', 1)
	273±0.3ms	275±0.3ms	1.01	mpas_ocean.CrossSections.time_const_lat('480km', 2)
	141±0.4ms	141±0.9ms	0.99	mpas_ocean.CrossSections.time_const_lat('480km', 4)
	24.7±0.4ms	24.7±0.2ms	1	mpas_ocean.DualMesh.time_dual_mesh_construction('120km')
	3.18±0.09ms	3.13±0.05ms	0.99	mpas_ocean.DualMesh.time_dual_mesh_construction('480km')
	956±3ms	949±9ms	0.99	mpas_ocean.GeoDataFrame.time_to_geodataframe('120km', False)
	51.2±0.6ms	55.2±0.5ms	1.08	mpas_ocean.GeoDataFrame.time_to_geodataframe('120km', True)
	85.4±0.8ms	84.8±0.3ms	0.99	mpas_ocean.GeoDataFrame.time_to_geodataframe('480km', False)
	5.63±0.05ms	5.60±0.1ms	0.99	mpas_ocean.GeoDataFrame.time_to_geodataframe('480km', True)
	350M	350M	1	mpas_ocean.Gradient.peakmem_gradient('120km')
	173±0.4ms	174±0.2ms	1	mpas_ocean.Gradient.time_gradient('120km')
	12.4±0.06ms	12.5±0.05ms	1.01	mpas_ocean.Gradient.time_gradient('480km')
	226±2μs	229±4μs	1.01	mpas_ocean.HoleEdgeIndices.time_construct_hole_edge_indices('120km')
	131±0.9μs	132±0.7μs	1.01	mpas_ocean.HoleEdgeIndices.time_construct_hole_edge_indices('480km')
	350M	349M	1	mpas_ocean.Integrate.peakmem_integrate('120km')
	329M	328M	1	mpas_ocean.Integrate.peakmem_integrate('480km')
	218±0.8μs	220±2μs	1.01	mpas_ocean.Integrate.time_integrate('120km')
	200±2μs	202±8μs	1.01	mpas_ocean.Integrate.time_integrate('480km')
	184±0.8ms	182±0.9ms	0.99	mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('120km', 'exclude')
	183±0.3ms	183±1ms	1	mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('120km', 'include')
	184±1ms	183±3ms	1	mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('120km', 'split')
	13.6±0.1ms	13.5±0.1ms	0.99	mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('480km', 'exclude')
	13.6±0.07ms	13.7±0.1ms	1.01	mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('480km', 'include')
	14.2±0.5ms	13.9±0.3ms	0.98	mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('480km', 'split')
	350±2μs	352±3μs	1.01	mpas_ocean.PointInPolygon.time_face_search_lonlat('120km')
	353±2μs	351±1μs	0.99	mpas_ocean.PointInPolygon.time_face_search_lonlat('480km')
	333±3μs	336±2μs	1.01	mpas_ocean.PointInPolygon.time_face_search_xyz('120km')
	337±2μs	337±4μs	1	mpas_ocean.PointInPolygon.time_face_search_xyz('480km')
	242±1ms	244±0.6ms	1.01	mpas_ocean.RemapDownsample.time_bilinear_remapping
	291±2ms	295±0.9ms	1.01	mpas_ocean.RemapDownsample.time_inverse_distance_weighted_remapping
	4.34±0.03ms	4.32±0.05ms	0.99	mpas_ocean.RemapDownsample.time_nearest_neighbor_remapping
	1.44±0s	1.47±0.05s	1.02	mpas_ocean.RemapUpsample.time_bilinear_remapping
	36.7±0.3ms	36.3±0.5ms	0.99	mpas_ocean.RemapUpsample.time_inverse_distance_weighted_remapping
	9.49±0.1ms	9.44±0.2ms	0.99	mpas_ocean.RemapUpsample.time_nearest_neighbor_remapping
	26.0±0.2ms	26.5±0.2ms	1.02	mpas_ocean.ZonalAverage.time_zonal_average('120km')
	5.82±0.05ms	5.83±0.04ms	1	mpas_ocean.ZonalAverage.time_zonal_average('480km')
	326M	328M	1.01	quad_hexagon.QuadHexagon.peakmem_open_dataset
	324M	324M	1	quad_hexagon.QuadHexagon.peakmem_open_grid
	6.92±0.08ms	6.99±0.1ms	1.01	quad_hexagon.QuadHexagon.time_open_dataset
	5.93±0.09ms	5.93±0.1ms	1	quad_hexagon.QuadHexagon.time_open_grid

[Sevans711]

Thank you for proposing and creating these additions to the docs pages! Overall, these all look like good changes which can help new users understand uxarray more easily.

I have a few miscellaneous questions / suggestions / requests:

1. For the iso_grid.png, can the image be shrunk to be smaller without losing too much image quality? The docs are currently roughly 28 MB, so it's not a huge deal to add 1.5 MB, but if it wouldn't make the image too blurry it could be nice to reduce file size further.
2. This phrasing was a bit confusing for me "Grid points store information about which faces, edges, and nodes they are connected to…" What are "grid points"? Additionally, it is not the grid points themselves which store such information, but rather the information is stored in the underlying uxarray.Grid object, if that makes sense?
3. The unstructured_grid.png diagram bottom row was a bit confusing, in particular, why is there more empty space between hexagons there than above? In the structured_grid.png I can interpret the empty space between faces as being placed there for visual emphasis, to help talk about the different faces. I could interpret it that way for the unstructured_grid.png too if the empty space was consistent, but now that it is inconsistent I am not sure what to think.
4. Optional suggestion: add a non-hexagon face in the unstructured_grid diagram to emphasize that "number of nodes per face" can also vary.
5. Claims at the bottom of the new unstructured-grids.html about unstructured grids granting efficiency improvements are nice, and okay to move forward as-is, but may be more convincing with links to any relevant publications or resources providing direct evidence for unstructured grids' improvements over structured grids in practice. Maybe @erogluorhan and @rajeeja could provide suggestions about that?
6. In data-structures.ipynb, maybe use the spelling "UxDataArray" instead of "Data Array"? Additionally, maybe edit the description of uxarray.UxDataArray to not call itself a data variable? It could say something like "A single array of data residing on the faces, nodes, or edges of a grid, along with the underlying Grid object."
7. It looks like you tried to change the color for Yes and No cells in grid-formats.rst, but the tables still render with the same exact colors when I viewed them. Is this intentional?
8. Can you explicitly clarify which changes solve which parts of issue #1582? For example, Point (2) of that issue refers to user-guide/representation, but I noticed none of the changes here touch that file. Is point (2) solved elsewhere, or still needs to be solved before that issue could be closed as completed?

[dylannelson]

@Sevans711 Good notes! And thank you for the through read!

1. Good idea, I can compress it a bit and see how it looks, I'll include that next
2. Yeah I struggled a bit when trying to find the best words to convey the ideas in a more approachable way as opposed to using too many terms. In retrospect "grid points" should likely be replaced by "Faces". For the 2nd point where data is stored, I was trying to visualize/explain it in a way that was more along the lines how objects in OOP and networks are explained/visualized. Like how each object has a set of variables, references, and properties that can be used to connect to others. I'll make a few revisions to make the distinction more clear
3. @erogluorhan and I just talked about the graphs and I'll make a few tweaks regarding that and a few other things
4. same as above
5. Good idea for sure. If we could get some specific examples that would be great.
6. I'll change it to UxDataArray. For the second suggestion, that sounds like it may be a bit hard to digest. That level of specificity may also be more valuable later on in the page where it goes into more detail here. I was trying to imagine it as how one might describe a series vs dataframe in pandas, where a Dataframe holds all your variables in your dataset, each in a Series, and each series is one individual variable. (Connecting the two definitions in an easy way when they are first introduced) This could make sense to people who only have excel experience, only understand what a dataset is, etc. And the more fine details come later on the page for those that need it
7. It wasn't intentional, what's the best way to check how it rendered before pushing the changes? (the bot above made a link here. Is there anything you do to make a live preview? I have vscode extensions for live preview of html and markdown projects, but haven't tried with rst.
8. I had been keeping track of all my changes and suggestions in a Doc outside of github as it got long and I wanted the extra formatting, and I let them get out of sync. I'll update both and send the doc to you directly

[Sevans711]

Thank you for your detailed reply @dylannelson, the ideas here sound good, and I will take a closer look again once the changes are ready! In the meantime, following up on a few of those points:

• (6) Avoiding being too specific too early definitely makes sense. Maybe worthwhile also to skim xarray's descriptions of DataArray and Dataset for clear/concise phrasing ideas? (Though, feel free to ignore it if it doesn't actually help).
• (7) For a live preview, the easiest option is definitely to just click whatever link gets produced after you push them. Though, you could also consider installing sphinx and telling it to build the docs on your machine. If you end up trying that, let's message separately about it if you get stuck, and leave a note here afterwards to clarify the steps you used, for future reference to anyone else following this conversation.
• (8) Sounds good! Just adding a quick note, even with updating the original issue and sending along the doc, I think my original comment here still stands, as it will be easier to review if you can describe at least one way in which each point from the original issue has been addressed.

[erogluorhan]

This is going great! I've added a few inline comments, and they refer to another document from our cookbooks. Once you review it, and if you want to modify anything in your comparison file here, once you're done with that, I can give another review on that file. Also:

• If possible, add some randomness and break the symmetry in unstructured_grid.png‎, at least removing one of the two pentagons?

[Sevans711]

Looks like great work so far!

I have some suggestions / comments on the new version. There are a decent number of them but I think most of them are minor. All lingering feedback has been left as inline comments rather than in this message, in case that makes things easier to track.

Checking points from my original review:

1. (done!) I see that iso_grid.png file is <1MB now.
2. (done!) I don't see "grid points" in the new version anymore.
3. (done/followed up with inline comment) The new unstructured_grid.png diagram looks improved compared to the old one.
4. (done!) The new unstructured_grid.png diagram contains both hexagon and non-hexagon faces.
5. (done/in progress?) The expanded example descriptions have made links less necessary. Still could add links to relevant publications if available, but okay to move forward without them.
6. (done!) Changed spelling to "UxDataArray" instead of "Data Array" in UxDataset description, and explained in PR comment threads the reason for not editing UxDataArray description as suggestion.
7. (not done) Colors are still unchanged. I left an inline comment in this review, to help track this issue more easily.
8. (done) The original issue description and the PR descriptions have both been updated to clearly show how each part of the issue has been solved.

[erogluorhan]

Getting there, please see some more comments below

[rajeeja]

One higher-level direction that may help simplify the remaining edits: rather than making this a broad, standalone primer on all structured-versus-unstructured-grid tradeoffs, could we center it on the question a new UXarray user has: what is different about an unstructured grid, and what does UXarray expose to work with it?

I suggest keeping the visual comparison intentionally short, then following it with a small “Working with an unstructured grid in UXarray” section that:

1. introduces faces, nodes, edges, and connectivity as the information that makes an irregular mesh navigable;
2. states that Grid retains this topology alongside the data; and
3. links readers to the terminology/data-structures guides and one focused cookbook example for a next step.

The current detailed discussion of polar singularities, land masking, model specialization, and performance is useful context, but it is hard to state generally without qualifications and overlaps with the cookbook material. It may be better as a concise “Why models use them” callout with links, or kept in the cookbook. This would give the page a clearer UXarray-specific learning path while reducing the amount of broad background that needs continued refinement.

[rajeeja]

One higher-level direction that may help simplify the remaining edits: rather than making this a broad, standalone primer on all structured-versus-unstructured-grid tradeoffs, could we center it on the question a new UXarray user has: what is different about an unstructured grid, and what does UXarray expose to work with it?

I suggest keeping the visual comparison intentionally short, then following it with a small “Working with an unstructured grid in UXarray” section that:

1. introduces faces, nodes, edges, and connectivity as the information that makes an irregular mesh navigable;
2. states that Grid retains this topology alongside the data; and
3. links readers to the terminology/data-structures guides and one focused cookbook example for a next step.

The current detailed discussion of polar singularities, land masking, model specialization, and performance is useful context, but it is hard to state generally without qualifications and overlaps with the cookbook material. It may be better as a concise “Why models use them” callout with links, or kept in the cookbook. This would give the page a clearer UXarray-specific learning path while reducing the amount of broad background that needs continued refinement.

Basically two suggestions that could help focus this page:
Keep it to a concise structured-vs-unstructured grid comparison, and link out for the broader efficiency and model tradeoffs.
Add a short UXarray bridge: explain that Grid stores mesh topology, then link to terminology, data structures, and the cookbook.

[rljacob]

I don't really see the need for an explainer on structured vs. unstructured grid within the UXarray docs. Who is this for? Anyone landing on the UXarray page already has unstructured grid data and is looking for a python library to work with it. We only need to explain what subsets of unstructured grids we handle (which is done in #1626) and high level usage differences with Xarray.

[erogluorhan]

I don't really see the need for an explainer on structured vs. unstructured grid within the UXarray docs. Who is this for? Anyone landing on the UXarray page already has unstructured grid data and is looking for a python library to work with it. We only need to explain what subsets of unstructured grids we handle (which is done in #1626) and high level usage differences with Xarray.

Yeah that makes sense, given UXarray is already targeting this domain. How about something like this:

1. Host the information (partially or fully) in this document in the corresponding place in the UXarray Cookbook instead
2. Add a frequently asked question into UXarray's FAQs about structured vs unstructured
   • Link to the cookbook (and maybe some other foundational docs such as UGRID conventions etc.) when answering that question, also clarify UXarray targets a domain and doesn't aim at foundational training?

cc: @rajeeja to discuss it with your high level suggestions

[dylannelson]

@rljacob@rajeeja The goal of this was to target a different user workflow. Like from my experience, I was educated as a developer, but work within domains that I wasn't formally educated in, like transit systems or meteorology. I have been assigned to incorporate many geospatial tools, packages, etc without my employer training me in said tools. I know the struggle of being skilled in a field, but having to apply it to a new domain with little knowledge about said domain, while in a company that can't/won't teach or train you. The docs are the first place a developer with a desire for knowledge will go, and I thought it may benefit us to sprinkle bits of education along the path a new user would take, so they can understand the package better, share it with others in words they understand, and feel more confident incorporating it into their workflow. Because this content is so specific and niche, there aren't many other places to learn this content from. I understand this doesn't benefit the core users, but the core users likely aren't on pages like Tutorials and Videos anyways.

From the follow up conversations, it seems like this kind of new user content is sufficiently explained on the Pythia site and many resources can be found there, so I've added a redirect there where @erogluorhan and I discussed separately. For now the content there still seems heavily tailored to users already familiar with geospatial language. I have removed the Structured vs Unstructured Grids content, and replaced old connections in favor of redirects to Project Pythia.

[Sevans711]

Thank you for all your work on this, @dylannelson, even as you ended up removing a big chunk of it from this PR. I see you clarified some of the changes above. I would be happy to review again, but first a few bookkeeping questions/thoughts:

1. Could you clarify the list of changes this PR is no longer intended to make to the docs pages?
2. Could you clarify the list of changes this PR is still intended to make?
3. Are changes now planned elsewhere (e.g. updates to Pythia notebooks?) or will this be the full set of relevant changes addressing Adding beginner friendly explanations on the Docs #1582? If they are planned elsewhere, I would suggest we swap the message to "Fixes part of Adding beginner friendly explanations on the Docs #1582 but does not fully close it." If this is the full set of relevant changes, please leave a comment in Adding beginner friendly explanations on the Docs #1582 summarizing which parts of the issue are now intentionally "not planned".

While answering these questions please feel free to point to your updated original message in this PR (e.g. maybe it already answers (1) and (2), but I just wanted to clarify before reviewing).

[dylannelson]

@Sevans711 Sorry I'm a bit confused about what you mean. It's mostly just the two points mentioned in the description. Content was added to the Tutorials/Videos page, made a slight tweak to a definition in a notebook, and two other small changes not mentioned: changing the colors in a table, and making some image sizes smaller. Did you want this info placed somewhere else too?

The original page that was planned has been removed and is now crossed out in the description. Just scrapping it for now as it seemed to not be needed. I just crossed it out in the issue as well but if you think it needs a comment also discussing it there, I can do that as well, but why would it be needed when these two discussions are linked?

[Sevans711]

No worries, I am happy to try to clarify further. Please let me know if this helps!

With (1) & (2), I was asking them because the scope of the PR changed. I can see the changes that have been made, but I am hoping for more clarity on what exactly is the goal of this PR now, such as a comprehensive list of tasks it intends to complete. When reviewing, I want to be able to answer the question "has this PR actually accomplished everything it claimed to accomplish?"

To answer (2), it would be sufficient to put a list in a comment in this thread. E.g.: "Here are all the changes this PR intends to make: (i) reduce file size for some images, (ii) soften colors on grid comparison table, (iii) add links to tutorial videos on the tutorials.rst page, (iv) …"

To answer (1), it would be sufficient to say something like "All other initially-proposed changes are no longer intended to be part of this PR, as per discussion above."

For (3), I have been thinking of issue reports and PRs as distinct entities. The issue report should provide a set of desired changes and a reason for wanting those changes. In this case (#1582), the list of desired changes was made explicit, while the reason remains implicit. Either way is fine, as long as they can be inferred (e.g., it is clear here that the reason is something like "the docs should be more beginner-friendly").

When the scope of the PR changes due to discussion in the PR thread (like what happened here), that signals to me one of the following:

• (A) The PR scope did not actually align with the initially-proposed changes.
• (B) The proposed changes did not align with the reason for wanting those changes.
• (C) The reason itself is questioned; perhaps others disagree with moving uxarray development in that direction, or it was deemed not high enough priority to address fully. (This is what happened in this PR.)

When (A) happens, the issue is just with the PR, and it makes sense to fix it just within the PR, without touching the original issue. However, (B) and (C) indicate something is "wrong" or unexpected with the original issue, and a shift in goals from "solve this as written" to "solve only part of this" or "solve it differently than how it was written". My question (3) was leaning into this notion; to me it makes the most sense to leave a comment on the initial issue clarifying that (B) or (C) occurred, and explaining why it occurred (even if the explanation is just "see discussion in PR for details"). Without any comments to indicate otherwise, when I'm looking through closed issues my default assumption is that each one has been fully implemented as described/implied by the issue report, for the reasons described/implied by the report.

[dylannelson]

@Sevans711

hoping for more clarity on what exactly is the goal of this PR now, such as a comprehensive list of tasks it intends to complete

1. Updating Tutorials and Videos Page

• Added content to docs/tutorials.rst
• Added 2 new links to 2 videos from 2024
• Added brief context for each of the 3 links now on the page

2. More distinct defintions for UxDataAray vs UxDataset

• Defined here: user-guide/data-structures
• Changed slightly after gathering feedback from team

3. Other Fixes

• Changes colors of a table
• Reduced image file size

Could you clarify the list of changes this PR is no longer intended to make to the docs pages?

The original page that was planned has been removed and is now crossed out in the description. Just scrapping it for now as it seemed to not be needed, as per the discussion above.

(C) The reason itself is questioned; perhaps others disagree with moving uxarray development in that direction, or it was deemed not high enough priority to address fully. (This is what happened in this PR.)

The priorities and direction changed, as per the discussion above

Are changes now planned elsewhere (e.g. updates to Pythia notebooks?) or will this be the full set of relevant changes addressing #1582?

Yes, it may be going to Pythia in some capacity

I hope that answers the questions above

[Sevans711]

Looks good to me! Confirmed all now-intended changes have been incorporated and look good, as per @dylannelson's last comment:

1. Updating Tutorials and Videos Page

• (done!) Added content to docs/tutorials.rst
• (done!) Added 2 new links to 2 videos from 2024
• (done!) Added brief context for each of the 3 links now on the page

2. More distinct defintions for UxDataAray vs UxDataset

• (done!) Defined here: user-guide/data-structures
• (done) Changed slightly after gathering feedback from team

3. Other Fixes

• (done!) Changes colors of a table
• (done!) Reduced image file size

Thank you also for leaving a comment on the original issue. I think it is now safe to say this PR fully closes the clarified-to-have-reduced-scope issue.

Yes, it may be going to Pythia in some capacity

That would be great! I appreciated your writeups and that seems like a good way to keep these efforts and helpful materials from getting lost. (But, this can be a separate issue at a later time. This PR seems ready to merge as-is.)

[erogluorhan]

Thanks very much for pushing this through all the iterations!