Merge pull request #613 from xylar/transects-general-vertical-coord

Several updates to ocean transects

Author: xylar

conda_package/docs/api.rst

@@ -252,23 +252,24 @@ Ocean Tools
    inject_preserve_floodplain
 
 
-.. currentmodule:: mpas_tools.ocean.transects
+.. currentmodule:: mpas_tools.ocean.viz.transect
 
 .. autosummary::
    :toctree: generated/
 
+   compute_transect
    find_transect_levels_and_weights
-   interp_mpas_to_transect_triangles
-   interp_mpas_to_transect_triangle_nodes
-   interp_transect_grid_to_transect_triangle_nodes
-   get_outline_segments
+   interp_mpas_to_transect_cells
+   interp_mpas_to_transect_nodes
+   interp_transect_grid_to_transect_nodes
+   plot_feature_transects
+   plot_transect
 
 .. currentmodule:: mpas_tools.ocean.viz
 
 .. autosummary::
    :toctree: generated/
 
-   plot_ocean_transects
    add_inset
 
 Sea-ice Tools
@@ -374,14 +375,16 @@ Visualization
 
    mesh_to_triangles
 
-.. currentmodule:: mpas_tools.viz.transects
+.. currentmodule:: mpas_tools.viz.transect
 
 .. autosummary::
    :toctree: generated/
 
-   make_triangle_tree
-   find_transect_cells_and_weights
    find_planar_transect_cells_and_weights
+   find_spherical_transect_cells_and_weights
+   interp_mpas_horiz_to_transect_nodes
+   make_triangle_tree
+   mesh_to_triangles
 
 .. currentmodule:: mpas_tools.viz.colormaps
 

conda_package/docs/ocean/visualization.rst

@@ -13,10 +13,16 @@ Plotting Ocean Transects
    :width: 500 px
    :align: center
 
-The function :py:func:`mpas_tools.ocean.viz.plot_ocean_transects()` and the
-associated ``plot_ocean_transects`` command-line tool can be used to plot
-transects of various MPAS-Ocean variables.  The arguments to the command-line
-tool are:
+The function :py:func:`mpas_tools.ocean.viz.transect.plot_transect()` is
+used to plot transects of various MPAS-Ocean variables. This function provide
+high-level plotting capabilities for visualizing transects of MPAS-Ocean
+data. It can create transect plots useful for visualizing test cases or
+analyzing global simulation output and comparing with observations.
+
+The function :py:func:`mpas_tools.ocean.viz.transect.plot_feature_transects()`
+and the associated ``plot_ocean_transects`` command-line tool can be used to
+plot transects of various MPAS-Ocean variables.  The arguments to the
+command-line tool are:
 
 .. code-block:: none
 
@@ -38,6 +44,9 @@ tool are:
       -c COLORMAP, --colormap COLORMAP
                             A colormap to use for the plots, default depends on the field name.
       --flip                Flip the x axis for all transects
+      --write_netcdf        Whether to write a NetCDF file for the transect in addition to the image
+      --method METHOD       The type of interpolation to use in plots. Options are "flat" and "bilinear"
+
 
 See `transects <https://github.com/MPAS-Dev/geometric_features/tree/main/geometric_data/ocean/transect>`_
 from ``geometric_features`` for a examples of what a geojson transect might
@@ -107,3 +116,61 @@ One way of customizing these visualizaitons is to make your own copy of
 `transects.py <https://github.com/MPAS-Dev/MPAS-Tools/blob/master/conda_package/mpas_tools/ocean/viz/transects.py>`_
 and change ``_plot_transect()`` to suite your needs, (changing figure size, dpi,
 colorbar, etc.)
+
+.. _ocean_viz_transects_interp:
+
+Ocean Transect Interpolation
+============================
+
+The ``mpas_tools.ocean.viz.transect.vert`` module provides functions for
+interpolating MPAS-Ocean data onto a vertical transect. This is useful for
+visualizing data along a specific path through the ocean, showing the
+vertical structure of ocean properties. These functions allow you to create
+cross-sectional plots of temperature, salinity, and other variables.
+
+The following functions are available:
+
+The function :py:func:`mpas_tools.ocean.viz.transect.compute_transect()`
+builds a sequence of quads showing the transect intersecting MPAS cells.
+This function takes horizontal and vertical mesh information and constructs
+a set of quadrilaterals that represent the transect's path through the
+MPAS-Ocean mesh. The resulting quads can then be used for plotting or
+further analysis.
+
+The remaining functions and those in :ref:`viz_transect_horiz` are lower level
+functions that are used by ``compute_transect()`` and are not typically called
+directly.
+
+The function
+:py:func:`mpas_tools.ocean.viz.transect.find_transect_levels_and_weights()`
+constructs a vertical coordinate for a transect and computes interpolation
+weights that can be used in ``interp_mpas_to_transect_nodes()`` to performed
+linear interpolation.
+
+The function
+:py:func:`mpas_tools.ocean.viz.transect.interp_mpas_to_transect_cells()`
+interpolates an MPAS-Ocean DataArray to transect cells, keeping constant values
+over each MPAS-Ocean cell. This function uses the indices computed by
+``find_transect_levels_and_weights()`` to map data from the MPAS-Ocean mesh
+onto the transect. The result is an ``xarray.DataArray`` with values
+sampled to transect cells.
+
+
+The function
+:py:func:`mpas_tools.ocean.viz.transect.interp_mpas_to_transect_nodes()`
+interpolates an MPAS-Ocean DataArray to transect nodes, linearly
+interpolating fields between the closest neighboring cells. This function
+uses the interpolation weights computed by
+``find_transect_levels_and_weights()`` to map data from the MPAS-Ocean mesh
+onto the transect. The result is an ``xarray.DataArray`` with values
+interpolated to the transect's nodes.
+
+The function
+:py:func:`mpas_tools.ocean.viz.transect.interp_transect_grid_to_transect_nodes()`
+interpolates a 2D grid of data to transect nodes, linearly interpolating
+fields between the closest neighboring cells. This requires that the
+``z_transect`` parameter has been passed into function
+``find_transect_levels_and_weights()`` (or ``compute_transect()``) uses
+weights generated in ``find_transect_levels_and_weights()`` to interpolate data
+from the MPAS-Ocean mesh to transect nodes the transect, resulting an
+``xarray.DataArray`` with values.

conda_package/docs/visualization.rst

@@ -131,3 +131,57 @@ In this example, we use the ``3Wbgy5`` colormap:
 .. image:: images/so60to12_res.png
    :width: 500 px
    :align: center
+
+.. _viz_transect_horiz:
+
+Horizontal Transect Interpolation
+=================================
+
+The ``mpas_tools.viz.transect.horiz`` module provides functions for
+interpolating MPAS data onto a horizontal transect. This is useful for
+visualizing data along a specific path on the horizontal plane of the
+mesh.
+
+The function
+:py:func:`mpas_tools.viz.transect.mesh_to_triangles()` converts an MPAS
+mesh to a triangle mesh by decomposing each cell into one triangle connecting
+the cell center to each edge. The resulting triangle mesh can then be used
+for visualization or for other spatial analysis tasks.
+
+The function
+:py:func:`mpas_tools.viz.transect.make_triangle_tree()` creates a triangle
+tree for efficient point location. This function is used internally to
+speed up the process of finding which triangle a given point lies within.
+It constructs a data structure that allows for fast spatial queries,
+making it more efficient to determine the location of points relative to
+the mesh. This is especially useful for high-resolution meshes or when
+performing a large number of point location operations.
+
+The function
+:py:func:`mpas_tools.viz.transect.find_planar_transect_cells_and_weights()`
+finds the cells that intersect a planar transect and the weights for
+interpolating data from cell centers to the transect nodes. The function
+takes the MPAS mesh as an ``xarray.Dataset`` object and the start and end
+points of the transect as Cartesian coordinates. The function
+returns the cell indices and weights for interpolating data from cell
+centers to the transect nodes, the indices of the cells that intersect
+the transect, and the Cartesian coordinates of the transect nodes. This
+is a key step in creating transect plots of MPAS data.
+
+The function
+:py:func:`mpas_tools.viz.transect.find_spherical_transect_cells_and_weights()`
+does the same for a transect on the sphere. It
+identifies the cells intersected by a great circle path defined by
+longitude and latitude coordinates. Like its planar counterpart, it
+returns cell indices, interpolation weights, intersected cell indices,
+and transect node coordinates, but all calculations are performed on the
+sphere.
+
+The function
+:py:func:`mpas_tools.viz.transect.interp_mpas_horiz_to_transect_nodes()`
+interpolates MPAS data to transect nodes. This function takes the MPAS
+data field and the transect node information (cell indices and weights)
+generated by either the planar or spherical transect finding functions.
+It then performs a weighted average of the data values at the cell
+centers to estimate the data values at the transect nodes. The result is
+a 1D array of interpolated data values along the transect.