OTIS

• Reads OTIS format tidal solutions provided by Oregon State University and ESR

  • multi-constituent OTIS binary

  • ATLAS-compact binary

  • single-constituent OTIS binary

  • TMD3 consolidated netCDF4

Calling Sequence

import pyTMD.io
ds = pyTMD.io.OTIS.open_dataset(model_file, grid_file, group='z', format='OTIS')

Source code

pyTMD.io.OTIS.open_dataset(model_file: str | list | Path, grid_file: str | Path | None = None, format: str = 'OTIS', **kwargs)

Open OTIS/ATLAS/TMD3 model files

Parameters:

model_file: str or pathlib.Path

Input model file

grid_file: str, pathlib.Path or None, default None

Input model grid file

format: str, default ‘OTIS’

Model format

• 'ATLAS'

• 'OTIS'

• 'TMD3'

group: str, default ‘z’

Tidal variable to read

• 'z': heights

• 'u': zonal currents

• 'U': zonal depth-averaged transport

• 'v': meridional currents

• 'V': meridional depth-averaged transport

kwargs: dict

Additional keyword arguments for opening files

Returns:

ds: xarray.Dataset

Tide model data

pyTMD.io.OTIS.open_mfdataset(model_files: list[str] | list[Path], group: str = 'z', **kwargs)

Open multiple OTIS model files

Parameters:

model_files: list of str or pathlib.Path

List of OTIS model files

group: str, default ‘z’

Tidal variable to read

• 'z': heights

• 'u': zonal currents

• 'U': zonal depth-averaged transport

• 'v': meridional currents

• 'V': meridional depth-averaged transport

parallel: bool, default False

Open files in parallel using dask.delayed

kwargs: dict

Additional keyword arguments for opening OTIS files

Returns:

ds: xarray.Dataset

OTIS tide model data

pyTMD.io.OTIS.open_otis_dataset(model_file: str | list | Path, grid_file: str | Path, group: str | None = 'z', **kwargs)

Open OTIS model files

Parameters:

model_file: str, list or pathlib.Path

Input model file(s)

grid_file: str, pathlib.Path

Input model grid file

group: str, default ‘z’

Tidal variable to read

• 'z': heights

• 'u': zonal currents

• 'U': zonal depth-averaged transport

• 'v': meridional currents

• 'V': meridional depth-averaged transport

crs: int, str or dict, default 4326

Coordinate reference system for the model data

use_mmap: bool, default False

Use memory mapping to read data

Returns:

ds: xarray.Dataset

OTIS tide model data

pyTMD.io.OTIS.open_atlas_dataset(model_file: str | Path, grid_file: str | Path, group: str | None = 'z', chunks: int | dict | str | None = None, use_mmap: bool = False, **kwargs)

Open ATLAS model files

Parameters:

model_file: str or pathlib.Path

Input model file

grid_file: str, pathlib.Path

Input model grid file

group: str, default ‘z’

Tidal variable to read

• 'z': heights

• 'u': zonal currents

• 'U': zonal depth-averaged transport

• 'v': meridional currents

• 'V': meridional depth-averaged transport

crs: int, str or dict, default 4326

Coordinate reference system for the model data

chunks: int, dict, str, or None, default None

Coerce output to specified chunks

use_mmap: bool, default False

Use memory mapping to read data

Returns:

ds: xarray.Dataset

ATLAS tide model data

pyTMD.io.OTIS.open_tmd3_dataset(input_file: str | Path, group: str | None = 'z', chunks: int | dict | str | None = None, **kwargs)

Open TMD3-formatted netCDF4 files

Parameters:

input_file: str or pathlib.Path

Input TMD3 netCDF4 file

group: str, default ‘z’

Tidal variable to read

• 'z': heights

• 'u': zonal currents

• 'U': zonal depth-averaged transport

• 'v': meridional currents

• 'V': meridional depth-averaged transport

chunks: int, dict, str, or None, default None

Variable chunk sizes for dask (see xarray.open_dataset)

Returns:

ds: xarray.Dataset

TMD3 tide model data

pyTMD.io.OTIS.open_otis_grid(input_file: str | Path, chunks: int | dict | str | None = None, use_mmap: bool = False, **kwargs)

Open OTIS model grid files

Parameters:

input_file: str or pathlib.Path

Input OTIS grid file

chunks: int, dict, str, or None, default None

Coerce output to specified chunks

use_mmap: bool, default False

Use memory mapping to read data

Returns:

ds: xarray.Dataset

OTIS grid data

pyTMD.io.OTIS.open_otis_elevation(input_file: str | Path, chunks: int | dict | str | None = None, use_mmap: bool = False, **kwargs)

Read OTIS tidal elevation files

Parameters:

input_file: str or pathlib.Path

Input OTIS elevation file

chunks: int, dict, str, or None, default None

Coerce output to specified chunks

use_mmap: bool, default False

Use memory mapping to read data

Returns:

ds: xarray.Dataset

OTIS tidal elevation data

pyTMD.io.OTIS.open_otis_transport(input_file: str | Path, chunks: int | dict | str | None = None, use_mmap: bool = False, **kwargs)

Read OTIS tidal transport files

Parameters:

input_file: str or pathlib.Path

Input OTIS transport file

chunks: int, dict, str, or None, default None

Coerce output to specified chunks

use_mmap: bool, default False

Use memory mapping to read data

Returns:

dsu: xarray.Dataset

OTIS zonal tidal transport data

dsv: xarray.Dataset

OTIS meridional tidal transport data

pyTMD.io.OTIS.open_atlas_grid(input_file: str | Path, use_mmap: bool = False, **kwargs)

Open ATLAS-compressed model grid files

Parameters:

input_file: str or pathlib.Path

Input ATLAS grid file

use_mmap: bool, default False

Use memory mapping to read data

Returns:

ds: xarray.Dataset

ATLAS global grid data

dtree: xarray.DataTree

Local ATLAS grid solutions

pyTMD.io.OTIS.open_atlas_elevation(input_file: str | Path, use_mmap: bool = False, **kwargs)

Open ATLAS-compressed tidal elevation files

Parameters:

input_file: str or pathlib.Path

Input ATLAS elevation file

use_mmap: bool, default False

Use memory mapping to read data

Returns:

ds: xarray.Dataset

ATLAS global tidal elevation data

dtree: xarray.DataTree

Local ATLAS tidal elevation solutions

pyTMD.io.OTIS.open_atlas_transport(input_file: str | Path, use_mmap: bool = False, **kwargs)

Open ATLAS-compressed tidal transport files

Parameters:

input_file: str or pathlib.Path

Input ATLAS transport file

use_mmap: bool, default False

Use memory mapping to read data

Returns:

dsu: xarray.Dataset

ATLAS global zonal tidal transport data

dsv: xarray.Dataset

ATLAS global meridional tidal transport data

dtu: xarray.DataTree

Local ATLAS zonal tidal transport solutions

dtv: xarray.DataTree

Local ATLAS meridional tidal transport solutions

pyTMD.io.OTIS.read_raw_binary(path: str | Path, dtype: dtype | str, shape: tuple, use_mmap: bool = False, offset: int = 0, order: str = 'C', **kwargs)

Read a variable from a raw binary file

Parameters:

path: str or pathlib.Path

Path to input file

dtype: numpy.dtype or str

Variable data type

shape: tuple

Shape of the data

use_mmap: bool, default False

Create a memory-map of the variable

offset: int, default 0

Offset to apply on read

order: str, default ‘C’

Memory layout of array

Returns:

var: numpy.ndarray

Data variable

pyTMD.io.OTIS.write_raw_binary(path: str | Path, variable: ndarray, offset: int = 0, order: str = 'C', **kwargs)

Write a variable to a raw binary file with memory-mapping

Parameters:

path: str or pathlib.Path

Path to input file

variable: numpy.ndarray

Data variable to write

offset: int, default 0

Offset to apply on read

order: str, default ‘C’

Memory layout of array

kwargs: dict

Additional keyword arguments for np.memmap

class pyTMD.io.OTIS.OTISDataset(ds)

xarray.Dataset utilities for OTIS tidal models

merge(ds, group: str = 'z')

Merge grid and model datasets while interpolating grid variables from zeta nodes to u and v nodes

Parameters:

ds: xarray.Dataset

OTIS tide model data

group: str, default ‘z’

Tidal variable of input dataset

• 'z': heights

• 'u': zonal currents

• 'U': zonal depth-averaged transport

• 'v': meridional currents

• 'V': meridional depth-averaged transport

property crs

Coordinate reference system of the Dataset

property is_global: bool

Determine if the dataset covers a global domain

class pyTMD.io.OTIS.OTISDataTree(dtree)

xarray.DataTree utilities for OTIS tidal models

to_grid(path: str | Path)

Writes OTIS-format grid files

Parameters:

path: str or pathlib.Path

Output OTIS grid file name

to_elevation(path: str | Path, **kwargs)

Writes OTIS-format elevation files

Parameters:

path: str or pathlib.Path

Output OTIS elevation file name

to_transport(path: str | Path, **kwargs)

Writes OTIS-format transport files

Parameters:

path: str or pathlib.Path

Output OTIS elevation file name

to_mfelevation(directory: str | Path)

Writes OTIS-format singular elevation files

Parameters:

directory: str or pathlib.Path

Output directory for OTIS elevation files

to_mftransport(directory: str | Path)

Writes OTIS-format singular transport files

Parameters:

directory: str or pathlib.Path

Output directory for OTIS transport files

class pyTMD.io.OTIS.CompactDataset(ds, spacing: float | list[float] = 0.03333333333333333)

xarray.Dataset utilities for ATLAS-compact tidal models

refine()

Refine data resolution to a finer resolution

combine_local(dtree: DataTree, chunks: int | dict | str | None = None)

Combine ATLAS model solutions into a single xarray Dataset

Parameters:

dtree: xarray.DataTree

Local ATLAS model solutions

chunks: int, dict, str, or None, default None

Coerce output to specified chunks

Returns:

ds: xarray.Dataset

ATLAS tide model data

property shape

Grid dimensions

property size

Grid size