tfv-get-tools 0.2.0__py3-none-any.whl

tfv_get_tools/fvc/_tide.py

@@ -0,0 +1,195 @@
+import re
+from pathlib import Path
+from typing import List, Optional, Union
+
+import xarray as xr
+
+from tfv_get_tools.fvc._fvc import FVCWriter
+
+
+class TideFVCWriter(FVCWriter):
+    """Writer for TIDE profile FVC files."""
+
+    def __init__(self, source=None, info_url=None):
+        """Initialize tide FVC writer."""
+        super().__init__(requires_coordinates=False, source=source, info_url=info_url)
+        self.nodestrings: Dict[str, str] = {}  # Maps ns prefix to ID
+
+    def detect_nodestrings(self, ds: xr.Dataset) -> None:
+        """Detect nodestrings from dataset variables.
+
+        Looks for variables with pattern 'nsX_*' where X is the nodestring identifier.
+
+        Args:
+            ds: Input xarray Dataset
+
+        Raises:
+            ValueError: If no nodestring variables are found
+        """
+        # Find all variables starting with 'ns'
+        ns_pattern = re.compile(r"^ns(.+)_[^_]*$")
+
+        # Get unique nodestring identifiers
+        self.nodestrings = {}
+        for var_name in ds.data_vars:
+            match = ns_pattern.match(var_name)
+            if match:
+                ns_id = match.group(1)
+                ns_prefix = f"ns{ns_id}"
+                self.nodestrings[ns_prefix] = ns_id
+
+        if not self.nodestrings:
+            raise ValueError(
+                "No nodestring variables found in dataset. "
+                "Expected variables with pattern 'nsX_*' where X is the nodestring identifier."
+            )
+
+    def validate_nodestring_variables(self, ds: xr.Dataset) -> None:
+        """Validate dataset has required variables for each nodestring.
+
+        Args:
+            ds: Input xarray Dataset
+
+        Raises:
+            ValueError: If required variables are missing
+        """
+        required_suffixes = ["_chainage", "_wl"]
+        missing = []
+
+        for ns_prefix in self.nodestrings:
+            for suffix in required_suffixes:
+                var_name = f"{ns_prefix}{suffix}"
+                if var_name not in ds:
+                    missing.append(var_name)
+
+        if missing:
+            raise ValueError(
+                f"Missing required variables for tide configuration: {', '.join(missing)}"
+            )
+
+    def write_boundary_conditions(
+        self,
+        lines: List[str],
+        nc_path: str,
+    ) -> None:
+        """Write boundary conditions block.
+
+        Args:
+            lines: List to append lines to
+            nc_path: Path to the NetCDF file
+        """
+        for ns_prefix, ns_id in sorted(self.nodestrings.items()):
+            lines.extend(
+                [
+                    f"BC == WL_CURT, {ns_id}, {nc_path}",
+                    f"  BC Header == {self.time_var}, {ns_prefix}_chainage, dummy, {ns_prefix}_wl",
+                    "  BC Update dt == 60.",
+                    "  BC Time Units == days",
+                    "  BC Reference Time == 01/01/1990 00:00",
+                    "  BC Default == NaN",
+                    "  Includes MSLP == 0",
+                    "End BC",
+                    "",
+                ]
+            )
+
+    def generate(
+        self,
+        ds: xr.Dataset,
+        nc_path: str = "tide_forcing.nc",
+    ) -> List[str]:
+        """Generate FVC configuration content for tide forcing.
+
+        Args:
+            ds: Input xarray Dataset containing tide variables
+            nc_path: Path or filename for the NetCDF file (referenced in FVC content)
+
+        Returns:
+            List[str]: FVC configuration content as a list of strings
+
+        Raises:
+            ValueError: If required variables are missing for any nodestring
+        """
+        # Process dataset to detect time settings and nodestrings
+        self.process_dataset(ds)
+        self.detect_nodestrings(ds)
+        self.validate_nodestring_variables(ds)
+
+        lines = []
+
+        # Write header with detected nodestrings
+        source = ds.attrs.get("source", "")
+        self.write_header(lines, f"{source} TIDE Dataset", ds)
+        lines.append(f"! Nodestrings: {', '.join(sorted(self.nodestrings.values()))}")
+        lines.append("")
+
+        # Write boundary conditions
+        self.write_boundary_conditions(lines, nc_path)
+
+        return lines
+
+    def write_file(
+        self,
+        lines: List[str],
+        output_path: Union[str, Path],
+        filename: Optional[str] = None,
+    ) -> None:
+        """Write FVC content to a file."""
+        output_path = Path(output_path)
+        filename = filename or "tide_forcing.fvc"
+        if not filename.endswith(".fvc"):
+            filename = filename.replace(".nc", ".fvc")
+
+        output_path.mkdir(parents=True, exist_ok=True)
+        with open(output_path / filename, "w") as f:
+            for line in lines:
+                f.write(line + "\n")
+
+
+def write_tide_fvc(
+    ds: xr.Dataset,
+    nc_path: str = "tide_forcing.nc",
+    output_path: Optional[Union[str, Path]] = None,
+    filename: Optional[str] = None,
+    source: Optional[str] = None,
+    info_url: Optional[str] = None,
+) -> List[str]:
+    """Generate (and optionally write) TUFLOW-FV tide forcing configuration.
+
+    Args:
+        ds: Input xarray Dataset containing tide variables
+        nc_path: Path or filename for the NetCDF file (referenced in FVC content)
+        output_path: Optional path to write FVC file (if None, no file is written)
+        filename: Optional filename for FVC file (if None, derives from nc_path)
+        info_url: Optional URL for source information to be printed in FVC
+
+    Returns:
+        List[str]: FVC configuration content as a list of strings
+
+    Examples:
+        # Dataset with numeric nodestring identifiers
+        >>> ds = xr.Dataset({
+        ...     'ns1_chainage': [...],
+        ...     'ns1_wl': [...],
+        ...     'ns2_chainage': [...],
+        ...     'ns2_wl': [...]
+        ... })
+        >>> lines = write_tide_fvc(ds, nc_path="tide.nc")
+
+        # Dataset with named nodestring identifiers
+        >>> ds = xr.Dataset({
+        ...     'nsEast_chainage': [...],
+        ...     'nsEast_wl': [...],
+        ...     'nsWest_chainage': [...],
+        ...     'nsWest_wl': [...]
+        ... })
+        >>> lines = write_tide_fvc(ds, nc_path="tide.nc")
+    """
+    writer = TideFVCWriter(source=source, info_url=info_url)
+
+    lines = writer.generate(ds, nc_path)
+
+    if output_path is not None:
+        writer.write_file(lines, output_path, filename)
+
+    return lines

tfv_get_tools/ocean.py

@@ -0,0 +1,170 @@
+from datetime import datetime
+from pathlib import Path
+from typing import Union, Tuple, Optional, List, Literal
+import pandas as pd
+
+from tfv_get_tools.utilities._tfv_bc import write_tuflowfv_fvc
+from tfv_get_tools.providers._downloader import BatchDownloadResult
+
+
+def DownloadOcean(
+    start_date: Union[str, datetime, pd.Timestamp],
+    end_date: Union[str, datetime, pd.Timestamp],
+    xlims: Tuple[float, float],
+    ylims: Tuple[float, float],
+    zlims: Optional[Tuple[float, float]] = None,
+    out_path: Union[str, Path] = Path("./raw"),
+    source: str = "HYCOM",
+    model: str = "default",
+    prefix: Optional[str] = None,
+    verbose: bool = False,
+    variables: Optional[List[str]] = None,
+    time_interval: Union[int, Literal["best"]] = 24,
+    skip_check: bool = False,
+    **kwargs,
+) -> BatchDownloadResult:
+    """Download Ocean Data
+    
+    Users should call this function, not the individual downloader classes directly.
+    
+    This module will download ocean data from several possible sources to facilitate 
+    TUFLOW FV and SWAN modelling.
+
+    The following sources have been implemented:
+        - `HYCOM` - Naval Research Laboratory - Global Ocean Forecast System (GOFS) 3.1
+        - `Copernicus` - Various models from the Copernicus Marine Service
+            - `GLO` - Global model domain
+
+    Args:
+        start_date: Start date. The string format is `%Y-%m-%d` (e.g., '2011-01-01')
+        end_date: End date. The string format is `%Y-%m-%d` (e.g., '2011-02-01')
+        xlims: Minimum and maximum longitude, as floats. e.g., (115, 120)
+        ylims: Minimum and maximum latitude, as floats. e.g., (-40, -35)
+        zlims: Minimum and maximum depth, as floats. e.g., (50, 250). 
+            Defaults to the maximum per data source.
+        out_path: Output directory for data files
+        source: Data source to download. One of {'HYCOM', 'Copernicus'}
+        model: Choice of model, depending on "source"
+        prefix: Extra file name prefix
+        verbose: Print extra program information
+        variables: List of variables to download (surf_el, salinity, water_temp, water_u, water_v)
+        time_interval: Time interval in hours for HYCOM only. Defaults to 24. Use "best" for the highest available. 
+        skip_check: Skip user confirmation
+        **kwargs: Additional arguments
+        
+    Returns:
+        BatchDownloadResult: Results of the download operation
+    """
+    
+    if source.lower() == "hycom":
+        from tfv_get_tools.providers.ocean.hycom import DownloadHycom
+        
+        downloader = DownloadHycom(
+            start_date=start_date,
+            end_date=end_date,
+            xlims=xlims,
+            ylims=ylims,
+            zlims=zlims,
+            out_path=out_path,
+            model=model,
+            prefix=prefix,
+            time_interval=time_interval,
+            verbose=verbose,
+            variables=variables,
+            skip_check=skip_check,
+            **kwargs
+        )
+        
+        return downloader.execute_download()
+    
+    elif source.lower() == "copernicus":
+        from tfv_get_tools.providers.ocean.copernicus_ocean import DownloadCopernicusOcean
+        
+        downloader = DownloadCopernicusOcean(
+            start_date=start_date,
+            end_date=end_date,
+            xlims=xlims,
+            ylims=ylims,
+            zlims=zlims,
+            out_path=out_path,
+            model=model,
+            prefix=prefix,
+            time_interval=time_interval,
+            verbose=verbose,
+            variables=variables,
+            skip_check=skip_check,
+            **kwargs
+        )
+        
+        return downloader.execute_download()
+        
+    else:
+        raise ValueError(f'Unrecognised source {source}. Must be one of: HYCOM, Copernicus')
+
+
+def MergeOcean(
+    in_path: Path = Path("./raw"),
+    out_path: Path = Path("."),
+    source: str = 'HYCOM',
+    model: str = 'default',
+    fname: str = None,
+    time_start: str = None,
+    time_end: str = None,
+    write_fvc=True,
+    reproject: int = None,
+    local_tz: Tuple[float, str] = None,
+    pad_dry: bool = False,
+    wrapto360=False,
+    write=True,
+):
+    """
+    Merge raw downloaded ocean datafiles into a single netcdf file, ready for TUFLOW-FV modelling
+    Optionally create an accompanying .fvc file.
+
+    **Use the same `source` and `model` that was supplied to the Downloader function**
+
+    Args:
+        in_path (Path, optional): Directory of the raw ocean data-files. Defaults to Path(".").
+        out_path (Path, optional): Output directory for the merged ocean netcdf and (opt) the fvc. Defaults to Path(".").
+        fname (str, optional): Merged ocean netcdf filename. Defaults to None.
+        source (str, optional): Source to be merged. Defaults to HYCOM.
+        model (str, optional): Model for source to be merged. Defaults to 'default'.
+        time_start (str, optional): Start time limit of the merged dataset (str: "YYYY-mm-dd HH:MM"). Defaults to None.
+        time_end (str, optional): End time limit of the merged dataset (str: "YYYY-mm-dd HH:MM"). Defaults to None.
+        write_fvc (bool, optional): Optionally write an accompanying .fvc file. Defaults to True.
+        reproject (int, optional): Optionally reproject based, based on EPSG code. Defaults to None.
+        local_tz: (Tuple(float, str): optional): Add local timezone format is a tuple with Offset[float] and Label[str]
+        pad_dry: (bool, optional): Optionally pad horizontally (i.e., fill nans with respect to depth). Defaults to False.
+        wrapto360: (bool, optional): Optionally wrap longitude to (0, 360) rather than (-180, 180). Defaults to False.
+        write (bool): Write the dataset. If False, the virtual merged dataset will be returned.
+    """
+    
+    args = tuple()
+
+    kwargs = dict(
+        in_path=in_path,
+        out_path=out_path,
+        fname=fname,
+        source=source,
+        model=model,
+        time_start=time_start,
+        time_end=time_end,
+        # write_fvc=write_fvc,
+        reproject=reproject,
+        local_tz=local_tz,
+        pad_dry=pad_dry,
+        wrapto360=wrapto360,
+        write=write,
+    )
+
+    if source.lower() == "hycom":
+        from tfv_get_tools.providers.ocean.hycom import MergeHYCOM
+        mrg = MergeHYCOM(*args, **kwargs)
+    
+    elif source.lower() == "copernicus":
+        from tfv_get_tools.providers.ocean.copernicus_ocean import MergeCopernicusOcean
+        mrg = MergeCopernicusOcean(*args, **kwargs)
+    
+    # If the user requested no-write, return the dataset object.
+    if not write:
+        return mrg.ds

tfv_get_tools/providers/_custom_conversions.py

@@ -0,0 +1,34 @@
+import xarray as xr
+import numpy as np
+from xarray import DataArray
+import dask.array as da
+
+def freq_to_period(freq: xr.DataArray) -> xr.DataArray:
+    """Inverse frequency to get period (s)"""    
+    return 1/freq
+
+def dewpt_to_relhum(dew_temp: DataArray, sfc_temp: DataArray) -> DataArray:
+    """Calculate relative humidity using dew_temp and sfc_temp
+    RH (%) = (e/esat)*100
+    a1=611.21 ; a3=17.502 ; a4=32.19 ; T0=273.16
+    https://confluence.ecmwf.int/pages/viewpage.action?pageId=171411214
+
+    Args:
+        dew_temp (np.ndarray): dew point temperature in Kelvin
+        sfc_temp (np.ndarray): surface temperature in Kelvin
+
+    Returns:
+        np.ndarray: Relative humidity (%)
+    """
+
+    a1=611.21
+    a3=17.502
+    a4=32.19
+    T0=273.16
+    
+    esat = a1*np.exp(a3*((sfc_temp-T0)/(sfc_temp-a4)))
+    e = a1*np.exp(a3*((dew_temp-T0)/(dew_temp-a4)))
+    
+    rel_hum = (e/esat)*100
+    
+    return rel_hum