xshelftransects 0.1.1__py3-none-any.whl

xshelftransects/__init__.py

@@ -0,0 +1,36 @@
+from .transects import cross_shelf_transects, xesmf_interpolation, xarray_interpolation
+from .isobath import longest_boundary_contour, longest_contour
+from .geometry import (
+    _project_lonlat,
+    _resample_contour_xy,
+    _tangent_normal_xy,
+    _make_transect_lonlat,
+    _orient_normals_by_offshore_slope,
+)
+from .sampling import (
+    _locstream_out,
+    _as_dataset,
+    _sample_vars_xesmf,
+    _sample_vars_xarray,
+    _sample_vars,
+    _unstack_loc,
+)
+
+__all__ = [
+    "cross_shelf_transects",
+    "xesmf_interpolation",
+    "xarray_interpolation",
+    "longest_boundary_contour",
+    "longest_contour",
+    "_project_lonlat",
+    "_resample_contour_xy",
+    "_tangent_normal_xy",
+    "_make_transect_lonlat",
+    "_orient_normals_by_offshore_slope",
+    "_locstream_out",
+    "_as_dataset",
+    "_sample_vars_xesmf",
+    "_sample_vars_xarray",
+    "_sample_vars",
+    "_unstack_loc",
+]

xshelftransects/geometry.py

@@ -0,0 +1,239 @@
+import warnings
+import numpy as np
+import xarray as xr
+
+try:
+    from scipy.stats import theilslopes
+except ModuleNotFoundError:
+    theilslopes = None
+
+def _project_lonlat(lon2d, lat2d, crs_out):
+    """
+    Project 2D lon/lat arrays to x/y in meters for a specified projected CRS.
+
+    Parameters
+    ----------
+    lon2d, lat2d : array-like
+        2D longitude/latitude arrays (degrees).
+    crs_out : str
+        Projected CRS (meters), e.g., "EPSG:3031" for Antarctica, "EPSG:3413" for
+        the Arctic, or "EPSG:3857" for a global web-mercator projection.
+
+    Returns
+    -------
+    x2d, y2d : ndarray
+        Projected coordinates in meters.
+    """
+    from pyproj import Transformer
+
+    # Build a lon/lat (EPSG:4326) -> projected CRS transformer; EPSG:4326 is degrees,
+    # so projected outputs are in meters when crs_out is a meter-based CRS (e.g., EPSG:3031).
+    tf = Transformer.from_crs("EPSG:4326", crs_out, always_xy=True)
+    return tf.transform(np.asarray(lon2d), np.asarray(lat2d))
+
+
+def _resample_contour_xy(contour_xy, transect_spacing):
+    """
+    Resample a contour to approximately uniform spacing along arc-length.
+
+    This is used to generate evenly spaced "sections" along a predefined contour. 
+
+    Parameters
+    ----------
+    contour_xy : (N,2) ndarray
+        Contour vertices in projected meters.
+    transect_spacing : float
+        Target along-contour spacing (meters).
+
+    Returns
+    -------
+    contour_xy_rs : (M,2) ndarray
+        Resampled contour vertices in projected meters.
+    s_m : (M,) ndarray
+        Along-contour distance from start (meters) for each resampled vertex.
+    """
+    contour_xy = np.asarray(contour_xy)
+    seg = np.sqrt(np.sum(np.diff(contour_xy, axis=0) ** 2, axis=1))
+    s = np.concatenate([[0.0], np.cumsum(seg)])
+    if s[-1] <= 0:
+        return contour_xy, s
+    n = max(2, int(np.floor(s[-1] / transect_spacing)) + 1)
+    si = np.linspace(0.0, s[-1], n)
+    xi = np.interp(si, s, contour_xy[:, 0])
+    yi = np.interp(si, s, contour_xy[:, 1])
+    return np.c_[xi, yi], si
+
+
+def _tangent_normal_xy(contour_xy):
+    """
+    Unit tangents and normals along a contour line in Cartesian coordinates.
+
+    Notes
+    -----
+    - np.gradient is taken with respect to vertex index, not an explicit spatial coordinate.
+      Because the contour is resampled to roughly uniform spacing and we normalize to unit
+      vectors, this is typically adequate.
+    - The normal sign is arbitrary here; it is oriented later using contour orientation.
+    """
+    dxy = np.gradient(np.asarray(contour_xy), axis=0)
+    t = dxy / np.maximum(np.linalg.norm(dxy, axis=1, keepdims=True), 1e-12)
+    n = np.c_[-t[:, 1], t[:, 0]]
+    return t, n
+
+
+def _contour_outward_sign(contour_xy):
+    """
+    Determine a global sign (+1 or -1) for outward normals based on contour orientation.
+
+    Notes
+    -----
+    - For a counter-clockwise contour, the left normal points inward, so outward is -1.
+    - For a clockwise contour, the left normal points outward, so outward is +1.
+    """
+    contour_xy = np.asarray(contour_xy)
+    if contour_xy.shape[0] < 3:
+        return 1.0
+    x = contour_xy[:, 0]
+    y = contour_xy[:, 1]
+    area = 0.5 * np.sum(x[:-1] * y[1:] - x[1:] * y[:-1])
+    if not np.isfinite(area) or area == 0.0:
+        return 1.0
+    return -1.0 if area > 0.0 else 1.0
+
+
+def _make_transect_lonlat(tf_inv, x0, y0, nx, ny, X):
+    """
+    Create transect target points (lon/lat) from projected anchors and unit normals.
+
+    Each transect is a straight line:
+        (x,y)(section, transect_length) = (x0,y0)(section) + transect_length * (nx,ny)(section)
+
+    Returns
+    -------
+    lon_t, lat_t : (nsec, nx) ndarrays
+        Target lon/lat coordinates for sampling.
+    """
+    xt = x0[:, None] + nx[:, None] * X[None, :]
+    yt = y0[:, None] + ny[:, None] * X[None, :]
+    lon_t, lat_t = tf_inv.transform(xt, yt)
+    return np.asarray(lon_t), np.asarray(lat_t)
+
+
+def _orient_normals_by_offshore_slope(transect_length, dloc0, offshore_slope_window=200e3, min_wet_fraction=0.5):
+    """
+    Orient normals so that +transect_length points offshore (depth increases with transect_length).
+
+    Mechanism
+    ---------
+    - Given depth sampled along provisional transects (dloc0[section, transect_length]),
+      check that near-boundary points are wet, then estimate the near-boundary slope
+      from points within offshore_slope_window of the boundary.
+    - If the median slope < 0, flip the normal for that section.
+
+    Returns
+    -------
+    flip : (nsec,) ndarray of {+1, -1}
+    """
+    depth_tran0 = xr.DataArray(
+        dloc0,
+        dims=("section", "transect_length"),
+        coords={"section": np.arange(dloc0.shape[0]), "transect_length": transect_length},
+    ).where(lambda z: z > 0)
+
+    x = depth_tran0["transect_length"]
+    window_mask = x <= offshore_slope_window
+    wet_mask = xr.apply_ufunc(np.isfinite, depth_tran0).astype(bool)
+    wet_first = wet_mask.where(window_mask).sum("transect_length")
+    n_window = window_mask.sum().item()
+    min_wet = max(1, int(np.ceil(min_wet_fraction * n_window)))
+
+    dx = xr.DataArray(
+        np.diff(np.asarray(transect_length)),
+        dims=("transect_length",),
+        coords={"transect_length": depth_tran0["transect_length"].isel(transect_length=slice(0, -1))},
+    )
+    depth_filled = depth_tran0.fillna(0.0)
+    slopes = depth_filled.diff("transect_length") / dx
+    valid_pair = wet_mask & wet_mask.shift(transect_length=-1, fill_value=False)
+    slopes = slopes.where(valid_pair.isel(transect_length=slice(0, -1)))
+    slopes_window = slopes.where(window_mask.isel(transect_length=slice(0, -1)))
+    slope_med = slopes_window.median("transect_length", skipna=True)
+
+    def _theil_sen_1d(y, x_vals):
+        if theilslopes is None:
+            raise ModuleNotFoundError(
+                "Theil-Sen slope requires scipy. Install scipy or choose a different orientation method."
+            )
+        valid = np.isfinite(y)
+        if valid.sum() < 2:
+            warnings.warn("Theil-Sen slope: fewer than 2 valid points; returning NaN.", RuntimeWarning)
+            return np.nan
+        xi = x_vals[valid]
+        yi = y[valid]
+        slope, _, _, _ = theilslopes(yi, xi)
+        return slope
+
+    depth_window = depth_tran0.where(window_mask)
+    slope_ts = xr.apply_ufunc(
+        lambda y: _theil_sen_1d(y, np.asarray(transect_length)),
+        depth_window,
+        input_core_dims=[["transect_length"]],
+        output_core_dims=[[]],
+        vectorize=True,
+        dask="parallelized",
+        output_dtypes=[float],
+    )
+
+    flip = xr.where(wet_first < min_wet, -1.0, 1.0)
+    flip = xr.where(slope_med < 0, -1.0, flip)
+    flip = xr.where(slope_ts < 0, -1.0, flip)
+    return flip.values
+
+
+def _build_transect_geometry_dataset(
+    lon0,
+    lat0,
+    nx,
+    ny,
+    dloc,
+    contour_lon,
+    contour_lat,
+    s_m,
+    transect_length,
+    crs,
+    engine,
+    method,
+    transect_spacing,
+):
+    """
+    Build the geometry dataset for cross-shelf transects.
+    """
+    return xr.Dataset(
+        data_vars=dict(
+            lon0=(("section",), np.asarray(lon0), {"units": "degrees_east", "description": "Longitude where transect intersects boundary (transect_length=0)."}),
+            lat0=(("section",), np.asarray(lat0), {"units": "degrees_north", "description": "Latitude where transect intersects boundary (transect_length=0)."}),
+            s_m=(("section",), np.asarray(s_m), {"units": "m", "description": "Along-boundary distance from start."}),
+            nx=(("section",), np.asarray(nx), {"units": "1", "description": "Unit normal x-component in projected CRS."}),
+            ny=(("section",), np.asarray(ny), {"units": "1", "description": "Unit normal y-component in projected CRS."}),
+            depth_xshelf=(("section", "transect_length"), dloc, {"units": "m", "description": "Sampled depth along transects."}),
+            contour_lon=(("contour_pt",), np.asarray(contour_lon), {"units": "degrees_east", "description": "Boundary contour longitude."}),
+            contour_lat=(("contour_pt",), np.asarray(contour_lat), {"units": "degrees_north", "description": "Boundary contour latitude."}),
+        ),
+        coords=dict(
+            section=("section", np.arange(s_m.size), {"description": "Section index along boundary."}),
+            transect_length=("transect_length", transect_length, {"units": "m", "description": "Cross-shelf distance from boundary."}),
+            contour_pt=("contour_pt", np.arange(np.asarray(contour_lon).size), {"description": "Boundary contour vertex index."}),
+        ),
+        attrs=dict(
+            crs=crs,
+            engine=engine,
+            sampling_method=method,
+            description=(
+                "Cross-shelf transects built from boundary_mask contour; transect_length=0 at "
+                "contour; +transect_length oriented toward deeper water; land masked to NaN."
+            ),
+            deptho_convention="deptho is ocean depth in meters, positive downward; deptho<=0 treated as land/ice.",
+            transect_spacing=float(transect_spacing),
+            optional_dependency="xesmf is only required when engine='xesmf'",
+        ),
+    )

xshelftransects/isobath.py

@@ -0,0 +1,85 @@
+import numpy as np
+from pyproj import Transformer
+
+try:
+    import contourpy as cp
+except ModuleNotFoundError:
+    cp = None
+
+
+# =============================================================================
+# Isobath / contour helpers
+# =============================================================================
+
+def _contour_arclen(v):
+    """
+    Arc-length of a contour vertex list v[:, (x,y)] in the same units as v (typically meters).
+    """
+    dv = np.diff(v, axis=0)
+    return np.sum(np.sqrt((dv**2).sum(axis=1)))
+
+
+def longest_boundary_contour(ds, boundary_mask, crs="EPSG:3031"):
+    """
+    Extract the longest boundary contour of a mask.
+
+    What this does
+    --------------
+    - Treats `boundary_mask` as a binary field (0/1) and extracts its boundary by contouring at
+      the midpoint value (0.5), which corresponds to the 0/1 interface.
+    - Among all contour segments, selects the longest segment (by arc-length in a projected CRS).
+    - Returns both:
+        (i) the contour vertex list in projected meters (for geometry),
+        (ii) the same contour in lon/lat (for plotting).
+
+    Requirements
+    ------------
+    - `ds` must contain ds["lon"], ds["lat"] as 2D arrays on the same grid as boundary_mask.
+
+    Parameters
+    ----------
+    ds : xarray.Dataset
+        Must contain ds["lon"], ds["lat"] (2D).
+    boundary_mask : xarray.DataArray
+        Binary/boolean mask on the same horizontal grid as ds["lon"]/ds["lat"].
+    crs : str
+        Projected CRS used internally for length/geometry (meters).
+
+    Returns
+    -------
+    contour_xy : (N,2) ndarray
+        Contour vertices in projected coordinates (meters).
+    contour_lon, contour_lat : (N,) ndarrays
+        Same contour vertices in degrees (EPSG:4326).
+    """
+    from .geometry import _project_lonlat
+
+    lon2d = ds["lon"]
+    lat2d = ds["lat"]
+    x2d, y2d = _project_lonlat(lon2d, lat2d, crs_out=crs)
+
+    m = boundary_mask.astype(float).fillna(0.0)
+
+    if cp is None:
+        raise ModuleNotFoundError(
+            "contourpy is required to extract boundary contours. Install contourpy."
+        )
+    cg = cp.contour_generator(x=x2d, y=y2d, z=np.asarray(m))
+    segs = cg.lines(0.5)
+
+    if len(segs) == 0:
+        raise ValueError("No contour found for boundary_mask (level=0.5).")
+
+    lens = np.array([_contour_arclen(v) for v in segs])
+    contour_xy = segs[int(np.argmax(lens))]
+
+    tf_inv = Transformer.from_crs(crs, "EPSG:4326", always_xy=True)
+    contour_lon, contour_lat = tf_inv.transform(contour_xy[:, 0], contour_xy[:, 1])
+    return contour_xy, np.asarray(contour_lon), np.asarray(contour_lat)
+
+
+def longest_contour(ds, boundary_mask, crs="EPSG:3031"):
+    """
+    Backwards-compatible alias for longest_boundary_contour.
+    """
+    return longest_boundary_contour(ds, boundary_mask, crs=crs)

xshelftransects/sampling.py

@@ -0,0 +1,170 @@
+import numpy as np
+import xarray as xr
+import pandas as pd
+
+try:
+    import xesmf as xe
+except ModuleNotFoundError:
+    xe = None
+
+
+# =============================================================================
+# Sampling helpers
+# =============================================================================
+
+def _locstream_out(lon_t, lat_t):
+    """
+    Build a LocStream output grid (1D 'loc') from (section, transect_length) lon/lat arrays.
+    """
+    return xr.Dataset(
+        {"lon": xr.DataArray(np.asarray(lon_t).ravel(), dims=("loc",)),
+         "lat": xr.DataArray(np.asarray(lat_t).ravel(), dims=("loc",))}
+    )
+
+
+def _as_dataset(obj):
+    """
+    Normalize a DataArray/Dataset into a Dataset so multi-variable sampling is uniform.
+
+    Returns
+    -------
+    xarray.Dataset
+    """
+    if isinstance(obj, xr.Dataset):
+        return obj
+    if isinstance(obj, xr.DataArray):
+        name = obj.name if obj.name is not None else "var"
+        return obj.to_dataset(name=name)
+    raise TypeError("obj must be xarray.DataArray or xarray.Dataset")
+
+
+def _sample_vars_xesmf(ds_in, obj, lon_t, lat_t, method, regridder=None):
+    """
+    xESMF-based sampling at LocStream target points (optional dependency).
+
+    Parameters
+    ----------
+    ds_in : xarray.Dataset
+        Must contain ds_in["lon"], ds_in["lat"] defining the source grid (typically 2D).
+    obj : xarray.DataArray or xarray.Dataset
+        Field(s) on the source grid to sample.
+    lon_t, lat_t : ndarray
+        Target lon/lat arrays with shape (section, transect_length).
+    method : str
+        xESMF method, e.g. "bilinear" or "nearest_s2d".
+    regridder : xesmf.Regridder or None
+        If provided, used directly.
+
+    Returns
+    -------
+    xarray.Dataset
+        Sampled output with trailing dimension "loc".
+    """
+    if xe is None:
+        raise ModuleNotFoundError(
+            "engine='xesmf' requires the optional dependency 'xesmf'. "
+            "Install it (and its ESMF backend) to use xESMF-based sampling."
+        )
+
+    ds_out = _locstream_out(lon_t, lat_t)
+    if regridder is None:
+        regridder = xe.Regridder(
+            ds_in,
+            ds_out,
+            method,
+            locstream_out=True,
+            unmapped_to_nan=True,
+        )
+    return regridder(_as_dataset(obj))
+
+
+def _sample_vars_xarray(obj, lon_t, lat_t, method, lon_name="lon", lat_name="lat"):
+    """
+    xarray.interp-based sampling at LocStream target points.
+
+    Important limitation
+    --------------------
+    This only applies to rectilinear grids where `obj` has 1D lon/lat coordinates
+    (tensor-product grid). It is not a curvilinear regridder.
+
+    method mapping
+    --------------
+    - method="bilinear" -> xarray method="linear"
+
+    Returns
+    -------
+    xarray.Dataset
+        Sampled output with trailing dimension "loc".
+    """
+    ds_out = _locstream_out(lon_t, lat_t)
+    interp_method = "linear" if method == "bilinear" else method
+
+    out = xr.Dataset()
+    lon_loc = ds_out["lon"]
+    lat_loc = ds_out["lat"]
+    for vn, da in _as_dataset(obj).data_vars.items():
+        out[vn] = da.interp({lon_name: lon_loc, lat_name: lat_loc}, method=interp_method)
+    return out
+
+
+def _sample_vars(
+    ds,
+    ds_in,
+    obj,
+    lon_t,
+    lat_t,
+    engine="xesmf",
+    method="bilinear",
+    regridder=None,
+    lon_name="lon",
+    lat_name="lat",
+):
+    """
+    Dispatch sampling to either xESMF or xarray.
+
+    Returns
+    -------
+    xarray.Dataset with trailing dimension "loc".
+    """
+    if engine == "xesmf":
+        return _sample_vars_xesmf(
+            ds_in, obj, lon_t, lat_t, method,
+            regridder=regridder,
+        )
+    if engine == "xarray":
+        return _sample_vars_xarray(obj, lon_t, lat_t, method, lon_name=lon_name, lat_name=lat_name)
+    raise ValueError("engine must be 'xesmf' or 'xarray'")
+
+
+def _unstack_loc(vloc_ds, transect_length, s_m):
+    """
+    Convert (..., loc) output back to (..., section, transect_length) using a MultiIndex.
+
+    Parameters
+    ----------
+    vloc_ds : xarray.Dataset
+        Output from _sample_vars with a trailing 'loc' dimension.
+    transect_length : (nx,) ndarray
+        Cross-shelf coordinate values.
+    s_m : (nsec,) ndarray
+        Along-boundary distances for sections.
+
+    Returns
+    -------
+    xarray.Dataset
+        Same data with dimensions (..., section, transect_length), plus coord s_m(section).
+    """
+    nsec = s_m.size
+    # MultiIndex flattens the (section, transect_length) grid into a 1D "loc" index.
+    mi = pd.MultiIndex.from_product([np.arange(nsec), transect_length], names=("section", "transect_length"))
+    # Explicitly wrap the MultiIndex to keep xarray's coordinate behavior stable.
+    mindex_coords = xr.Coordinates.from_pandas_multiindex(mi, "loc")
+    return (
+        vloc_ds
+        # The loc dimension is a flattened (section, transect_length) grid.
+        .assign_coords(mindex_coords)
+        # Unstack loc back into 2D section/transect_length dimensions.
+        .unstack("loc")
+        # Keep along-boundary distance as a section coordinate.
+        .assign_coords(s_m=("section", np.asarray(s_m)))
+    )

xshelftransects/transects.py

@@ -0,0 +1,193 @@
+import numpy as np
+import xarray as xr
+from pyproj import Transformer
+
+from .geometry import (
+    _build_transect_geometry_dataset,
+    _contour_outward_sign,
+    _make_transect_lonlat,
+    _resample_contour_xy,
+    _tangent_normal_xy,
+)
+from .isobath import longest_boundary_contour
+from .sampling import (
+    _sample_vars,
+    _sample_vars_xarray,
+    _sample_vars_xesmf,
+    _unstack_loc,
+)
+
+
+# =============================================================================
+# Public API
+# =============================================================================
+
+def xesmf_interpolation(ds_in, obj, lon_t, lat_t, method="bilinear", regridder=None):
+    """
+    Public wrapper around the xESMF LocStream sampling helper.
+    """
+    return _sample_vars_xesmf(
+        ds_in,
+        obj,
+        lon_t,
+        lat_t,
+        method,
+        regridder=regridder,
+    )
+
+
+def xarray_interpolation(obj, lon_t, lat_t, method="bilinear", lon_name="lon", lat_name="lat"):
+    """
+    Public wrapper around the xarray.interp sampling helper.
+    """
+    return _sample_vars_xarray(obj, lon_t, lat_t, method, lon_name=lon_name, lat_name=lat_name)
+
+
+def cross_shelf_transects(
+    ds,
+    var,                    # str | list[str]
+    boundary_mask,          # DataArray; binary mask where the 0/1 interface defines transect_length=0
+    transect_length=np.arange(0.0, 200e3 + 2e3, 2e3),
+    transect_spacing=10e3,
+    crs="EPSG:3031",
+    engine="xesmf",
+    method="bilinear",
+    lon_name="lon",
+    lat_name="lat",
+    return_geometry=True,
+):
+    """
+    Construct and sample cross-shelf transects from a mask boundary.
+
+    Parameters
+    ----------
+    ds : xarray.Dataset
+        Dataset containing 2D lon/lat coordinates and bathymetry.
+    var : str or list[str]
+        Variable name(s) in ds to sample along transects.
+    boundary_mask : xarray.DataArray
+        Binary mask whose 0/1 interface defines the transect anchor line
+        (transect_length = 0). The interface is extracted by contouring
+        at the midpoint value (0.5).
+    transect_length : 1D array-like
+        Cross-shelf distances (meters). Convention is transect_length >= 0 (offshore direction).
+    transect_spacing : float
+        Target spacing along the boundary between successive sections (meters).
+    crs : str
+        Projected CRS used for along-boundary geometry (meters), e.g., "EPSG:3031"
+        for Antarctica, "EPSG:3413" for the Arctic, or "EPSG:3857" for a more
+        general global projection.
+    engine : {"xesmf", "xarray"}
+        Sampling backend. "xesmf" supports curvilinear grids; "xarray" requires 1D lon/lat.
+    method : str
+        Interpolation method for sampling (e.g., "bilinear", "nearest_s2d").
+    lon_name, lat_name : str
+        Coordinate names for lon/lat when engine="xarray".
+    return_geometry : bool
+        If True, return the geometry dataset in addition to sampled values.
+
+    Returns
+    -------
+    xshelf : xarray.DataArray or xarray.Dataset
+        Sampled values with dims (..., section, transect_length). If `var` is a string, returns a DataArray;
+        if `var` is a list, returns a Dataset.
+    geometry : xarray.Dataset
+        Returned only if return_geometry=True. Contains:
+          - anchor lon0/lat0 (section)
+          - along-boundary distance s_m (section)
+          - normals nx/ny (section)
+          - sampled depth along transects depth_xshelf (section, transect_length)
+          - boundary contour lon/lat (contour_pt)
+
+    Notes
+    -----
+    The boundary is extracted as the longest contour of `boundary_mask` at the 0/1
+    midpoint (0.5), resampled at `transect_spacing`. Transects are oriented by
+    contour winding so +transect_length points away from the enclosed mask, and
+    land/ice (deptho <= 0) are masked to NaN.
+    """
+    if ("lon" not in ds) or ("lat" not in ds):
+        raise KeyError(
+            "cross_shelf_transects requires ds['lon'] and ds['lat'] as 2D horizontal coordinates. "
+            "Rename your coordinate variables to 'lon'/'lat'."
+        )
+    if "deptho" not in ds:
+        raise KeyError(
+            "cross_shelf_transects requires ds['deptho'] (ocean depth in meters, positive downward). "
+            "Rename your bathymetry variable to 'deptho'."
+        )
+
+    ds_in = ds[["lon", "lat"]] if engine == "xesmf" else None
+
+    vars = [var] if isinstance(var, (str, bytes)) else list(var)
+    X = np.asarray(transect_length, dtype=float)
+
+    # (1) Boundary contour and (2) resampled sections along it
+    contour_xy, contour_lon, contour_lat = longest_boundary_contour(ds, boundary_mask, crs=crs)
+    contour_xy, s_m = _resample_contour_xy(contour_xy, transect_spacing)
+    _, n = _tangent_normal_xy(contour_xy)
+    normal_sign = _contour_outward_sign(contour_xy)
+
+    x0, y0 = contour_xy[:, 0], contour_xy[:, 1]
+    nx, ny = n[:, 0].copy() * normal_sign, n[:, 1].copy() * normal_sign
+
+    tf_inv = Transformer.from_crs(crs, "EPSG:4326", always_xy=True)
+    deptho_filled = ds["deptho"].fillna(0.0)
+
+    # (3) Final transects
+    lon_t, lat_t = _make_transect_lonlat(tf_inv, x0, y0, nx, ny, X)
+
+    # (6) Sample requested variables
+    obj_vars = [vn for vn in vars if vn != "deptho"]
+    obj = ds[obj_vars + ["deptho"]].where(deptho_filled > 0)
+    vloc = _sample_vars(
+        ds, ds_in, obj, lon_t, lat_t,
+        engine=engine, method=method, regridder=None,
+        lon_name=lon_name, lat_name=lat_name,
+    )
+    vloc = _unstack_loc(vloc, X, s_m)
+    dloc = vloc["deptho"].values
+    wet = np.isfinite(dloc) & (dloc > 0)
+    vloc = vloc.where(wet)
+    if "deptho" not in vars:
+        vloc = vloc.drop_vars("deptho")
+    vloc = vloc.assign_coords(
+        depth=(
+            ("section", "transect_length"),
+            np.where(wet, dloc, np.nan),
+            {"units": "m", "description": "Sampled depth along transects."},
+        ),
+        lon=(
+            ("section", "transect_length"),
+            lon_t,
+            {"units": "degrees_east", "description": "Transect longitude."},
+        ),
+        lat=(
+            ("section", "transect_length"),
+            lat_t,
+            {"units": "degrees_north", "description": "Transect latitude."},
+        ),
+    )
+
+    xshelf = vloc[vars[0]] if len(vars) == 1 else vloc
+    if not return_geometry:
+        return xshelf
+
+    lon0, lat0 = tf_inv.transform(x0, y0)
+    geometry = _build_transect_geometry_dataset(
+        lon0=lon0,
+        lat0=lat0,
+        nx=nx,
+        ny=ny,
+        dloc=dloc,
+        contour_lon=contour_lon,
+        contour_lat=contour_lat,
+        s_m=s_m,
+        transect_length=X,
+        crs=crs,
+        engine=engine,
+        method=method,
+        transect_spacing=transect_spacing,
+    )
+
+    return xshelf, geometry

xshelftransects-0.1.1.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: xshelftransects
+Version: 0.1.1
+Summary: 
+Author: Anthony Meza
+Author-email: 64243783+anthony-meza@users.noreply.github.com
+Requires-Python: >=3.11
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: cartopy
+Requires-Dist: contourpy
+Requires-Dist: intake (>=2.0.8,<3.0.0)
+Requires-Dist: intake-esm (>=2025.12.12,<2026.0.0)
+Requires-Dist: intake-geopandas[all] (>=0.4.0,<0.5.0)
+Requires-Dist: intake-xarray[all] (>=2.0.0,<3.0.0)
+Requires-Dist: netcdf4 (<1.7.3)
+Requires-Dist: pyarrow (<=19.0.0)
+Requires-Dist: pyproj (<3.7)
+Requires-Dist: requests (>=2.32.5,<3.0.0)
+Requires-Dist: scipy (<=1.16.0)
+Requires-Dist: xarray[complete]
+Description-Content-Type: text/markdown
+
+xshelftransects
+==============
+
+Build and sample cross-shelf transects from a binary boundary mask on model grids. Useful for understanding gravity current and coastally-trapped waves, which are defined by their orientation and proximity to the continental shelves. 
+
+Install
+-------
+```bash
+conda create --name xshelftransects python=3.11
+conda activate xshelftransects
+pip install -e .
+```
+
+Optional dependencies
+---------------------
+- xesmf (for `engine="xesmf"` on curvilinear grids)
+- scipy (for Theil-Sen based transect orientation)
+
+Basic usage
+-----------
+```python
+import numpy as np
+import xshelftransects
+
+transects, geometry = xshelftransects.cross_shelf_transects(
+    ds,
+    "thetao",
+    boundary_mask,  # binary mask: 0/1 interface is transect_length=0
+    transect_length=np.arange(0.0, 200e3 + 2e3, 2e3),
+    transect_spacing=10e3,
+    crs="EPSG:3031",
+    engine="xesmf",
+)
+```
+
+Inputs and expectations
+- `ds["lon"]`, `ds["lat"]`: 2D longitude/latitude arrays.
+- `ds["deptho"]`: ocean depth in meters, positive downward (deptho <= 0 treated as land/ice).
+- `boundary_mask`: DataArray on the same grid as lon/lat; 0/1 interface is the boundary.
+- `crs`: projected CRS in meters (e.g., "EPSG:3031" Antarctica, "EPSG:3413" Arctic,
+  "EPSG:3857" global).
+
+Outputs
+- `transects`: sampled values with dims (..., section, transect_length) and lon/lat coords.
+- `geometry`: Dataset with anchor points, normals, and boundary contour.
+

xshelftransects-0.1.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+xshelftransects/__init__.py,sha256=pu9xG_DqDwJSYOEpbCJITMRRcmO8RoVcrBl-P00_iPs,897
+xshelftransects/geometry.py,sha256=IFcX1XCub_BqH6a9miLF5LUq3B9Ud1Bvmhxs3Y0cFYk,9195
+xshelftransects/isobath.py,sha256=cdaXgSvnIqrnzhv0HemN1BlopdVm_hOOgnpoBK3BdIY,2818
+xshelftransects/sampling.py,sha256=40apbhLkaaoG0tUmctDAl_MOcPoZ3SXFyu_1d7qN7wY,5143
+xshelftransects/transects.py,sha256=KfQCkyRB9F9EWbh5ghEgdhHUm7qX9Uvq3Jk2JF9A8a0,6725
+xshelftransects-0.1.1.dist-info/METADATA,sha256=t1uMBe2-7kPNcfW6Ux5YDsEnz03nq0gR0yqiq28Se5w,2359
+xshelftransects-0.1.1.dist-info/WHEEL,sha256=3ny-bZhpXrU6vSQ1UPG34FoxZBp3lVcvK0LkgUz6VLk,88
+xshelftransects-0.1.1.dist-info/RECORD,,

xshelftransects-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.3.0
+Root-Is-Purelib: true
+Tag: py3-none-any