def model_tides(
+ x,
+ y,
+ time,
+ model="FES2014",
+ directory=None,
+ crs="EPSG:4326",
+ crop=True,
+ method="spline",
+ extrapolate=True,
+ cutoff=None,
+ mode="one-to-many",
+ parallel=True,
+ parallel_splits=5,
+ output_units="m",
+ output_format="long",
+ ensemble_models=None,
+ **ensemble_kwargs,
+):
+ """Compute tides at multiple points and times using tidal harmonics.
+
+ This function supports all tidal models supported by `pyTMD`,
+ including FES Finite Element Solution models, TPXO TOPEX/POSEIDON
+ models, EOT Empirical Ocean Tide models, GOT Global Ocean Tide
+ models, and HAMTIDE Hamburg direct data Assimilation Methods for
+ Tides models.
+
+ This function requires access to tide model data files.
+ These should be placed in a folder with subfolders matching
+ the formats specified by `pyTMD`:
+ <https://pytmd.readthedocs.io/en/latest/getting_started/Getting-Started.html#directories>
+
+ For FES2014 (<https://www.aviso.altimetry.fr/es/data/products/auxiliary-products/global-tide-fes/description-fes2014.html>):
+
+ - `{directory}/fes2014/ocean_tide/`
+
+ For FES2022 (<https://www.aviso.altimetry.fr/en/data/products/auxiliary-products/global-tide-fes.html>):
+
+ - `{directory}/fes2022b/ocean_tide/`
+
+ For TPXO8-atlas (<https://www.tpxo.net/tpxo-products-and-registration>):
+
+ - `{directory}/tpxo8_atlas/`
+
+ For TPXO9-atlas-v5 (<https://www.tpxo.net/tpxo-products-and-registration>):
+
+ - `{directory}/TPXO9_atlas_v5/`
+
+ For EOT20 (<https://www.seanoe.org/data/00683/79489/>):
+
+ - `{directory}/EOT20/ocean_tides/`
+
+ For GOT4.10c (<https://earth.gsfc.nasa.gov/geo/data/ocean-tide-models>):
+
+ - `{directory}/GOT4.10c/grids_oceantide_netcdf/`
+
+ For HAMTIDE (<https://www.cen.uni-hamburg.de/en/icdc/data/ocean/hamtide.html>):
+
+ - `{directory}/hamtide/`
+
+ This function is a modification of the `pyTMD` package's
+ `compute_tide_corrections` function. For more info:
+ <https://pytmd.readthedocs.io/en/stable/user_guide/compute_tide_corrections.html>
+
+ Parameters
+ ----------
+ x, y : float or list of floats
+ One or more x and y coordinates used to define
+ the location at which to model tides. By default these
+ coordinates should be lat/lon; use "crs" if they
+ are in a custom coordinate reference system.
+ time : A datetime array or pandas.DatetimeIndex
+ An array containing `datetime64[ns]` values or a
+ `pandas.DatetimeIndex` providing the times at which to
+ model tides in UTC time.
+ model : string, optional
+ The tide model used to model tides. Options include:
+
+ - "FES2014" (pre-configured on DEA Sandbox)
+ - "FES2022"
+ - "TPXO9-atlas-v5"
+ - "TPXO8-atlas"
+ - "EOT20"
+ - "HAMTIDE11"
+ - "GOT4.10"
+ - "ensemble" (advanced ensemble tide model functionality;
+ combining multiple models based on external model rankings)
+ directory : string, optional
+ The directory containing tide model data files. If no path is
+ provided, this will default to the environment variable
+ `DEA_TOOLS_TIDE_MODELS` if set, otherwise "/var/share/tide_models".
+ Tide modelling files should be stored in sub-folders for each
+ model that match the structure provided by `pyTMD`.
+
+ For example:
+
+ - `{directory}/fes2014/ocean_tide/`
+ - `{directory}/tpxo8_atlas/`
+ - `{directory}/TPXO9_atlas_v5/`
+ crs : str, optional
+ Input coordinate reference system for x and y coordinates.
+ Defaults to "EPSG:4326" (WGS84; degrees latitude, longitude).
+ crop : bool optional
+ Whether to crop tide model constituent files on-the-fly to
+ improve performance. Cropping will be performed based on a
+ 1 degree buffer around all input points. Defaults to True.
+ method : string, optional
+ Method used to interpolate tidal constituents
+ from model files. Options include:
+
+ - "spline": scipy bivariate spline interpolation (default)
+ - "bilinear": quick bilinear interpolation
+ - "linear", "nearest": scipy regular grid interpolations
+ extrapolate : bool, optional
+ Whether to extrapolate tides for x and y coordinates outside of
+ the valid tide modelling domain using nearest-neighbor.
+ cutoff : int or float, optional
+ Extrapolation cutoff in kilometers. The default is None, which
+ will extrapolate for all points regardless of distance from the
+ valid tide modelling domain.
+ mode : string, optional
+ The analysis mode to use for tide modelling. Supports two options:
+
+ - "one-to-many": Models tides for every timestep in "time" at
+ every input x and y coordinate point. This is useful if you
+ want to model tides for a specific list of timesteps across
+ multiple spatial points (e.g. for the same set of satellite
+ acquisition times at various locations across your study area).
+ - "one-to-one": Model tides using a different timestep for each
+ x and y coordinate point. In this mode, the number of x and
+ y points must equal the number of timesteps provided in "time".
+ parallel : boolean, optional
+ Whether to parallelise tide modelling using `concurrent.futures`.
+ If multiple tide models are requested, these will be run in
+ parallel. Optionally, tide modelling can also be run in parallel
+ across input x and y coordinates (see "parallel_splits" below).
+ Default is True.
+ parallel_splits : int, optional
+ Whether to split the input x and y coordinates into smaller,
+ evenly-sized chunks that are processed in parallel. This can
+ provide a large performance boost when processing large numbers
+ of coordinates. The default is 5 chunks, which will split
+ coordinates into 5 parallelised chunks.
+ output_units : str, optional
+ Whether to return modelled tides in floating point metre units,
+ or integer centimetre units (i.e. scaled by 100) or integer
+ millimetre units (i.e. scaled by 1000. Returning outputs in
+ integer units can be useful for reducing memory usage.
+ Defaults to "m" for metres; set to "cm" for centimetres or "mm"
+ for millimetres.
+ output_format : str, optional
+ Whether to return the output dataframe in long format (with
+ results stacked vertically along "tide_model" and "tide_m"
+ columns), or wide format (with a column for each tide model).
+ Defaults to "long".
+ ensemble_models : list, optional
+ An optional list of models used to generate the ensemble tide
+ model if "ensemble" tide modelling is requested. Defaults to
+ ["FES2014", "TPXO9-atlas-v5", "EOT20", "HAMTIDE11", "GOT4.10",
+ "FES2012", "TPXO8-atlas-v1"].
+ **ensemble_kwargs :
+ Keyword arguments used to customise the generation of optional
+ ensemble tide models if "ensemble" modelling are requested.
+ These are passed to the underlying `_ensemble_model` function.
+ Useful parameters include `ranking_points` (path to model
+ rankings data), `k` (for controlling how model rankings are
+ interpolated), and `ensemble_top_n` (how many top models to use
+ in the ensemble calculation).
+
+ Returns
+ -------
+ pandas.DataFrame
+ A dataframe containing modelled tide heights.
+
+ """
+ # Set tide modelling files directory. If no custom path is provided,
+ # first try global environmental var, then "/var/share/tide_models"
+ if directory is None:
+ if "DEA_TOOLS_TIDE_MODELS" in os.environ:
+ directory = os.environ["DEA_TOOLS_TIDE_MODELS"]
+ else:
+ directory = "/var/share/tide_models"
+
+ # Verify path exists
+ directory = pathlib.Path(directory).expanduser()
+ if not directory.exists():
+ raise FileNotFoundError("Invalid tide directory")
+
+ # If time passed as a single Timestamp, convert to datetime64
+ if isinstance(time, pd.Timestamp):
+ time = time.to_datetime64()
+
+ # Turn inputs into arrays for consistent handling
+ models_requested = np.atleast_1d(model)
+ x = np.atleast_1d(x)
+ y = np.atleast_1d(y)
+ time = np.atleast_1d(time)
+
+ # Validate input arguments
+ assert method in ("bilinear", "spline", "linear", "nearest")
+ assert output_units in (
+ "m",
+ "cm",
+ "mm",
+ ), "Output units must be either 'm', 'cm', or 'mm'."
+ assert output_format in (
+ "long",
+ "wide",
+ ), "Output format must be either 'long' or 'wide'."
+ assert len(x) == len(y), "x and y must be the same length."
+ if mode == "one-to-one":
+ assert len(x) == len(time), (
+ "The number of supplied x and y points and times must be "
+ "identical in 'one-to-one' mode. Use 'one-to-many' mode if "
+ "you intended to model multiple timesteps at each point."
+ )
+
+ # Verify that all provided models are supported
+ valid_models = [
+ # Standard built-in pyTMD models
+ "EOT20",
+ "FES2014",
+ "FES2022",
+ "GOT4.10",
+ "HAMTIDE11",
+ "TPXO8-atlas", # binary version, not suitable for clipping
+ "TPXO9-atlas-v5",
+ # Non-standard models, defined internally
+ "FES2012",
+ "FES2014_extrapolated",
+ "FES2022_extrapolated",
+ "GOT5.6",
+ "GOT5.6_extrapolated",
+ "TPXO8-atlas-v1", # netCDF version
+ # Advanced ensemble model functionality
+ "ensemble",
+ ]
+ if not all(m in valid_models for m in models_requested):
+ raise ValueError(
+ f"One or more of the models requested {models_requested} is "
+ f"not valid. The following models are currently supported: "
+ f"{valid_models}",
+ )
+
+ # If ensemble modelling is requested, use a custom list of models
+ # for subsequent processing
+ if "ensemble" in models_requested:
+ print("Running ensemble tide modelling")
+ models_to_process = (
+ ensemble_models
+ if ensemble_models is not None
+ else [
+ "FES2014",
+ "TPXO9-atlas-v5",
+ "EOT20",
+ "HAMTIDE11",
+ "GOT4.10",
+ "FES2012",
+ "TPXO8-atlas-v1",
+ ]
+ )
+
+ # Otherwise, models to process are the same as those requested
+ else:
+ models_to_process = models_requested
+
+ # Update tide modelling func to add default keyword arguments that
+ # are used for every iteration during parallel processing
+ iter_func = partial(
+ _model_tides,
+ directory=directory,
+ crs=crs,
+ crop=crop,
+ method=method,
+ extrapolate=extrapolate,
+ cutoff=np.inf if cutoff is None else cutoff,
+ output_units=output_units,
+ mode=mode,
+ )
+
+ # Ensure requested parallel splits is not smaller than number of points
+ parallel_splits = min(parallel_splits, len(x))
+
+ # Parallelise if either multiple models or multiple splits requested
+ if parallel & ((len(models_to_process) > 1) | (parallel_splits > 1)):
+ with ProcessPoolExecutor() as executor:
+ print(f"Modelling tides using {', '.join(models_to_process)} in parallel")
+
+ # Optionally split lon/lat points into `splits_n` chunks
+ # that will be applied in parallel
+ x_split = np.array_split(x, parallel_splits)
+ y_split = np.array_split(y, parallel_splits)
+
+ # Get every combination of models and lat/lon points, and
+ # extract as iterables that can be passed to `executor.map()`
+ # In "one-to-many" mode, pass entire set of timesteps to each
+ # parallel iteration by repeating timesteps by number of total
+ # parallel iterations. In "one-to-one" mode, split up
+ # timesteps into smaller parallel chunks too.
+ if mode == "one-to-many":
+ model_iters, x_iters, y_iters = zip(
+ *[(m, x_split[i], y_split[i]) for m in models_to_process for i in range(parallel_splits)],
+ )
+ time_iters = [time] * len(model_iters)
+ elif mode == "one-to-one":
+ time_split = np.array_split(time, parallel_splits)
+ model_iters, x_iters, y_iters, time_iters = zip(
+ *[
+ (m, x_split[i], y_split[i], time_split[i])
+ for m in models_to_process
+ for i in range(parallel_splits)
+ ],
+ )
+
+ # Apply func in parallel, iterating through each input param
+ model_outputs = list(
+ tqdm(
+ executor.map(iter_func, model_iters, x_iters, y_iters, time_iters),
+ total=len(model_iters),
+ ),
+ )
+
+ # Model tides in series if parallelisation is off
+ else:
+ model_outputs = []
+
+ for model_i in models_to_process:
+ print(f"Modelling tides using {model_i}")
+ tide_df = iter_func(model_i, x, y, time)
+ model_outputs.append(tide_df)
+
+ # Combine outputs into a single dataframe
+ tide_df = pd.concat(model_outputs, axis=0)
+
+ # Optionally compute ensemble model and add to dataframe
+ if "ensemble" in models_requested:
+ ensemble_df = _ensemble_model(x, y, crs, tide_df, models_to_process, **ensemble_kwargs)
+
+ # Update requested models with any custom ensemble models, then
+ # filter the dataframe to keep only models originally requested
+ models_requested = np.union1d(models_requested, ensemble_df.tide_model.unique())
+ tide_df = pd.concat([tide_df, ensemble_df]).query("tide_model in @models_requested")
+
+ # Optionally convert to a wide format dataframe with a tide model in
+ # each dataframe column
+ if output_format == "wide":
+ # Pivot into wide format with each time model as a column
+ print("Converting to a wide format dataframe")
+ tide_df = tide_df.pivot(columns="tide_model", values="tide_m")
+
+ # If in 'one-to-one' mode, reindex using our input time/x/y
+ # values to ensure the output is sorted the same as our inputs
+ if mode == "one-to-one":
+ output_indices = pd.MultiIndex.from_arrays([time, x, y], names=["time", "x", "y"])
+ tide_df = tide_df.reindex(output_indices)
+
+ return tide_df
+