roms-tools 1.5.0__py3-none-any.whl → 1.6.1__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,9 +924,12 @@ 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"])
 
-            self.ds["mask"] = mask
+            object.__setattr__(self, "ds", ds)
 
         # Remove "depth" from var_names
         updated_var_names = {**self.var_names}  # Create a copy of the dictionary
@@ -1261,9 +1385,13 @@ 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"}
@@ -1271,9 +1399,11 @@ class ERA5Dataset(Dataset):
             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)
-
-            self.ds["mask"] = mask
+            ds["mask"] = mask
+            ds = ds.drop_vars([self.var_names["mask"]])
+            object.__setattr__(self, "ds", ds)
 
             # Remove mask from var_names dictionary
             var_names = self.var_names

roms_tools/setup/fill.py

@@ -301,39 +301,3 @@ def stencil_grid_mod(S, grid, msk, dtype=None, format=None):
                 data[4, i + diags[4]] = 0
 
     return sparse.dia_matrix((data, diags), shape=(N_v, N_v)).asformat(format)
-
-
-def _lateral_fill(data_vars, data):
-    """Wrapper function to apply lateral fill to variables using the dataset's mask and
-    grid dimensions.
-
-    Parameters
-    ----------
-    data_vars : dict of str : xarray.DataArray
-        Dictionary of variables to be filled.
-    data : Dataset
-        Dataset containing the mask and grid dimensions.
-
-    Returns
-    -------
-    dict of str : xarray.DataArray
-        Dictionary of filled variables.
-    """
-    lateral_fill = LateralFill(
-        data.ds["mask"],
-        [data.dim_names["latitude"], data.dim_names["longitude"]],
-    )
-
-    if "mask_vel" in data.ds.data_vars:
-        lateral_fill_vel = LateralFill(
-            data.ds["mask_vel"],
-            [data.dim_names["latitude"], data.dim_names["longitude"]],
-        )
-
-    for var in data.var_names:
-        if var in ["u", "v"]:
-            data_vars[var] = lateral_fill_vel.apply(data_vars[var])
-        else:
-            data_vars[var] = lateral_fill.apply(data_vars[var])
-
-    return data_vars

roms_tools/setup/grid.py

@@ -679,7 +679,7 @@ class Grid:
             # Write header
             file.write(header)
             # Write YAML data
-            yaml.dump(yaml_data, file, default_flow_style=False)
+            yaml.dump(yaml_data, file, default_flow_style=False, sort_keys=False)
 
     @classmethod
     def from_yaml(cls, filepath: Union[str, Path]) -> "Grid":