roms-tools 1.4.2__py3-none-any.whl → 1.6.0__py3-none-any.whl

roms_tools/setup/datasets.py

@@ -12,8 +12,10 @@ from roms_tools.setup.utils import (
     interpolate_from_climatology,
     get_time_type,
     convert_cftime_to_datetime,
+    one_dim_fill,
 )
 from roms_tools.setup.download import download_correction_data
+from roms_tools.setup.fill import LateralFill
 
 
 @dataclass(frozen=True, kw_only=True)
@@ -117,6 +119,8 @@ class Dataset:
             # Make sure that depth is ascending
             ds = self.ensure_dimension_is_ascending(ds, dim="depth")
 
+        self.infer_horizontal_resolution(ds)
+
         # Check whether the data covers the entire globe
         object.__setattr__(self, "is_global", self.check_if_global(ds))
 
@@ -487,6 +491,34 @@ class Dataset:
 
         return ds
 
+    def infer_horizontal_resolution(self, ds: xr.Dataset):
+        """Estimate and set the average horizontal resolution of a dataset based on
+        latitude and longitude spacing.
+
+        Parameters
+        ----------
+        ds : xr.Dataset
+            Dataset containing latitude and longitude dimensions.
+
+        Sets
+        ----
+        resolution : float
+            The average horizontal resolution, derived from the mean spacing
+            between points in latitude and longitude.
+        """
+        lat_dim = self.dim_names["latitude"]
+        lon_dim = self.dim_names["longitude"]
+
+        # Calculate mean difference along latitude and longitude
+        lat_resolution = ds[lat_dim].diff(dim=lat_dim).mean(dim=lat_dim)
+        lon_resolution = ds[lon_dim].diff(dim=lon_dim).mean(dim=lon_dim)
+
+        # Compute the average horizontal resolution
+        resolution = np.mean([lat_resolution, lon_resolution])
+
+        # Set the computed resolution as an attribute
+        object.__setattr__(self, "resolution", resolution)
+
     def check_if_global(self, ds) -> bool:
         """Checks if the dataset covers the entire globe in the longitude dimension.
 
@@ -569,40 +601,31 @@ class Dataset:
         """
         pass
 
-    def choose_subdomain(
-        self, latitude_range, longitude_range, margin, straddle, return_subdomain=False
-    ):
-        """Selects a subdomain from the xarray Dataset based on specified latitude and
-        longitude ranges, extending the selection by a specified margin. Handles
-        longitude conversions to accommodate different longitude ranges.
+    def choose_subdomain(self, target_coords, buffer_points=20, return_copy=False):
+        """Selects a subdomain from the xarray Dataset based on specified target
+        coordinates, extending the selection by a defined buffer. Adjusts longitude
+        ranges as necessary to accommodate the dataset's expected range and handles
+        potential discontinuities.
 
         Parameters
         ----------
-        latitude_range : tuple of float
-            A tuple (lat_min, lat_max) specifying the minimum and maximum latitude values of the subdomain.
-        longitude_range : tuple of float
-            A tuple (lon_min, lon_max) specifying the minimum and maximum longitude values of the subdomain.
-        margin : float
-            Margin in degrees to extend beyond the specified latitude and longitude ranges when selecting the subdomain.
-        straddle : bool
-            If True, target longitudes are expected in the range [-180, 180].
-            If False, target longitudes are expected in the range [0, 360].
+        target_coords : dict
+            A dictionary containing the target latitude and longitude coordinates, typically
+            with keys "lat", "lon", and "straddle".
+        buffer_points : int
+            The number of grid points to extend beyond the specified latitude and longitude
+            ranges when selecting the subdomain. Defaults to 20.
         return_subdomain : bool, optional
-            If True, returns the subset of the original dataset as an xarray Dataset. If False, assigns the subset to `self.ds`.
-            Defaults to False.
+            If True, returns the subset of the original dataset representing the chosen
+            subdomain. If False, assigns the subset to `self.ds`. Defaults to False.
 
         Returns
         -------
         xr.Dataset or None
-            If `return_subdomain` is True, returns the subset of the original dataset representing the chosen subdomain,
-            including an extended area to cover one extra grid point beyond the specified ranges. If `return_subdomain` is False,
-            returns None as the subset is assigned to `self.ds`.
-
-        Notes
-        -----
-        This method adjusts the longitude range if necessary to ensure it matches the expected range for the dataset.
-        It also handles longitude discontinuities that can occur when converting to different longitude ranges.
-        This is important for avoiding artifacts in the interpolation process.
+            Returns the subset of the original dataset as an xarray Dataset if
+            `return_subdomain` is True, including an extended area covering additional
+            grid points beyond the specified ranges. Returns None if `return_subdomain`
+            is False, as the subset is assigned to `self.ds`.
 
         Raises
         ------
@@ -610,13 +633,17 @@ class Dataset:
             If the selected latitude or longitude range does not intersect with the dataset.
         """
 
-        lat_min, lat_max = latitude_range
-        lon_min, lon_max = longitude_range
+        lat_min = target_coords["lat"].min().values
+        lat_max = target_coords["lat"].max().values
+        lon_min = target_coords["lon"].min().values
+        lon_max = target_coords["lon"].max().values
+
+        margin = self.resolution * buffer_points
 
         if not self.is_global:
             # Adjust longitude range if needed to match the expected range
             lon = self.ds[self.dim_names["longitude"]]
-            if not straddle:
+            if not target_coords["straddle"]:
                 if lon.min() < -180:
                     if lon_max + margin > 0:
                         lon_min -= 360
@@ -626,7 +653,7 @@ class Dataset:
                         lon_min -= 360
                         lon_max -= 360
 
-            if straddle:
+            if target_coords["straddle"]:
                 if lon.max() > 360:
                     if lon_min - margin < 180:
                         lon_min += 360
@@ -637,6 +664,7 @@ class Dataset:
                         lon_max += 360
 
         # Select the subdomain
+
         subdomain = self.ds.sel(
             **{
                 self.dim_names["latitude"]: slice(lat_min - margin, lat_max + margin),
@@ -655,16 +683,109 @@ class Dataset:
 
         # Adjust longitudes to expected range if needed
         lon = subdomain[self.dim_names["longitude"]]
-        if straddle:
+        if target_coords["straddle"]:
             subdomain[self.dim_names["longitude"]] = xr.where(lon > 180, lon - 360, lon)
         else:
             subdomain[self.dim_names["longitude"]] = xr.where(lon < 0, lon + 360, lon)
 
-        if return_subdomain:
-            return subdomain
+        if return_copy:
+            return Dataset.from_ds(self, subdomain)
         else:
             object.__setattr__(self, "ds", subdomain)
 
+    def apply_lateral_fill(self):
+        """Apply lateral fill to variables using the dataset's mask and grid dimensions.
+
+        This method fills masked values in `self.ds` using `LateralFill` based on
+        the horizontal grid dimensions. A separate mask (`mask_vel`) is used for
+        velocity variables (e.g., `u`, `v`) if available in the dataset.
+
+        Notes
+        -----
+        Looping over `self.ds.data_vars` instead of `self.var_names` ensures that each
+        dataset variable is filled only once, even if multiple entries in `self.var_names`
+        point to the same variable in the dataset.
+        """
+        lateral_fill = LateralFill(
+            self.ds["mask"],
+            [self.dim_names["latitude"], self.dim_names["longitude"]],
+        )
+
+        separate_fill_for_velocities = False
+        if "mask_vel" in self.ds.data_vars:
+            lateral_fill_vel = LateralFill(
+                self.ds["mask_vel"],
+                [self.dim_names["latitude"], self.dim_names["longitude"]],
+            )
+            separate_fill_for_velocities = True
+
+        for var_name in self.ds.data_vars:
+            if var_name.startswith("mask"):
+                # Skip variables that are mask types
+                continue
+            elif (
+                separate_fill_for_velocities
+                and "u" in self.var_names
+                and "v" in self.var_names
+                and var_name in [self.var_names["u"], self.var_names["v"]]
+            ):
+                # Apply lateral fill with velocity mask for velocity variables if present
+                self.ds[var_name] = lateral_fill_vel.apply(self.ds[var_name])
+            else:
+                # Apply standard lateral fill for other variables
+                self.ds[var_name] = lateral_fill.apply(self.ds[var_name])
+
+    def extrapolate_deepest_to_bottom(self):
+        """Extrapolate deepest non-NaN values to fill bottom NaNs along the depth
+        dimension.
+
+        For each variable with a depth dimension, fills missing values at the bottom by
+        propagating the deepest available data downward.
+        """
+
+        if "depth" in self.dim_names:
+            for var_name in self.ds.data_vars:
+                if self.dim_names["depth"] in self.ds[var_name].dims:
+                    self.ds[var_name] = one_dim_fill(
+                        self.ds[var_name], self.dim_names["depth"], direction="forward"
+                    )
+
+    @classmethod
+    def from_ds(cls, original_dataset: "Dataset", ds: xr.Dataset) -> "Dataset":
+        """Substitute the internal dataset of a Dataset object with a new xarray
+        Dataset.
+
+        This method creates a new Dataset instance, bypassing the usual `__init__`
+        and `__post_init__` processes. It allows for the direct assignment of the
+        provided xarray Dataset (`ds`) to the new instance's `ds` attribute. All
+        other attributes from the original dataset instance are copied to the new one.
+
+        Parameters
+        ----------
+        original_dataset : Dataset
+            The original Dataset instance from which attributes will be copied.
+        ds : xarray.Dataset
+            The new xarray Dataset to assign to the `ds` attribute of the new instance.
+
+        Returns
+        -------
+        Dataset
+            A new Dataset instance with the `ds` attribute set to the provided dataset
+            and other attributes copied from the original instance.
+        """
+        # Create a new Dataset instance without calling __init__ or __post_init__
+        dataset = cls.__new__(cls)
+
+        # Directly set the provided dataset as the 'ds' attribute
+        object.__setattr__(dataset, "ds", ds)
+
+        # Copy all other attributes from the original data instance
+        for attr in vars(original_dataset):
+            if attr != "ds":
+                object.__setattr__(dataset, attr, getattr(original_dataset, attr))
+
+        return dataset
+
 
 @dataclass(frozen=True, kw_only=True)
 class TPXODataset(Dataset):
@@ -803,12 +924,17 @@ class TPXODataset(Dataset):
         """
 
         if "depth" in self.var_names.keys():
+            ds = self.ds
             mask = xr.where(self.ds["depth"] > 0, 1, 0)
+            ds["mask"] = mask
+            ds = ds.drop_vars(["depth"])
 
-            for var in self.ds.data_vars:
-                self.ds[var] = xr.where(mask == 1, self.ds[var], np.nan)
+            object.__setattr__(self, "ds", ds)
 
-            self.ds["mask"] = mask
+        # Remove "depth" from var_names
+        updated_var_names = {**self.var_names}  # Create a copy of the dictionary
+        updated_var_names.pop("depth", None)  # Remove "depth" if it exists
+        object.__setattr__(self, "var_names", updated_var_names)
 
 
 @dataclass(frozen=True, kw_only=True)
@@ -878,11 +1004,16 @@ class GLORYSDataset(Dataset):
             0,
             1,
         )
-
-        for var in self.ds.data_vars:
-            self.ds[var] = xr.where(mask == 1, self.ds[var], np.nan)
+        mask_vel = xr.where(
+            self.ds[self.var_names["u"]]
+            .isel({self.dim_names["time"]: 0, self.dim_names["depth"]: 0})
+            .isnull(),
+            0,
+            1,
+        )
 
         self.ds["mask"] = mask
+        self.ds["mask_vel"] = mask_vel
 
 
 @dataclass(frozen=True, kw_only=True)
@@ -1088,9 +1219,6 @@ class CESMBGCDataset(CESMDataset):
             1,
         )
 
-        for var in self.ds.data_vars:
-            self.ds[var] = xr.where(mask == 1, self.ds[var], np.nan)
-
         self.ds["mask"] = mask
 
 
@@ -1160,9 +1288,6 @@ class CESMBGCSurfaceForcingDataset(CESMDataset):
             1,
         )
 
-        for var in self.ds.data_vars:
-            self.ds[var] = xr.where(mask == 1, self.ds[var], np.nan)
-
         self.ds["mask"] = mask
 
 
@@ -1260,21 +1385,30 @@ class ERA5Dataset(Dataset):
                 )
             )
             cff = cff * qair
-            self.ds["qair"] = 0.62197 * (cff / (patm - 0.378 * cff))
-            self.ds["qair"].attrs["long_name"] = "Absolute humidity at 2m"
-            self.ds["qair"].attrs["units"] = "kg/kg"
+
+            ds = self.ds
+            ds["qair"] = 0.62197 * (cff / (patm - 0.378 * cff))
+            ds["qair"].attrs["long_name"] = "Absolute humidity at 2m"
+            ds["qair"].attrs["units"] = "kg/kg"
+            ds = ds.drop_vars([self.var_names["d2m"]])
+            object.__setattr__(self, "ds", ds)
 
             # Update var_names dictionary
             var_names = {**self.var_names, "qair": "qair"}
+            var_names.pop("d2m")
             object.__setattr__(self, "var_names", var_names)
 
         if "mask" in self.var_names.keys():
+            ds = self.ds
             mask = xr.where(self.ds[self.var_names["mask"]].isel(time=0).isnull(), 0, 1)
+            ds["mask"] = mask
+            ds = ds.drop_vars([self.var_names["mask"]])
+            object.__setattr__(self, "ds", ds)
 
-            for var in self.ds.data_vars:
-                self.ds[var] = xr.where(mask == 1, self.ds[var], np.nan)
-
-            self.ds["mask"] = mask
+            # Remove mask from var_names dictionary
+            var_names = self.var_names
+            var_names.pop("mask")
+            object.__setattr__(self, "var_names", var_names)
 
 
 @dataclass(frozen=True, kw_only=True)

roms_tools/setup/fill.py

@@ -15,7 +15,7 @@ class LateralFill:
             A 2D boolean mask indicating valid points (True) and land points (False).
             Boundary points are automatically set to land (True).
         dims : list of str
-            Dimensions along which to perform the lateral fill. Defaults to ["latitude", "longitude"].
+            Dimensions along which to perform the lateral fill.
         tol : float, optional
             Tolerance for the iterative solver, determining convergence. Default is 1.0e-4.
 
@@ -65,7 +65,7 @@ class LateralFill:
             non-NaN values.
         """
         # Apply fill to anomaly field
-        mean = var.mean(dim=self.dims, skipna=True)
+        mean = var.where(self.mask).mean(dim=self.dims, skipna=True)
         var = var - mean
 
         # Setup the right-hand side (RHS): ocean points take their original values, land points are set to 0