ATLAS

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

  • Spatially interpolates tidal constituents to input coordinates

Calling Sequence

import pyTMD.io
amp,ph,D,c = pyTMD.io.ATLAS.extract_constants(ilon, ilat, grid_file, model_files,
   type='z',
   method='spline')

Source code

pyTMD.io.ATLAS.extract_constants(ilon: ndarray, ilat: ndarray, grid_file: str | Path | None = None, model_files: str | list | Path | None = None, **kwargs)[source]

Reads files for ATLAS netCDF4 tidal models

Makes initial calculations to run the tide program

Spatially interpolates tidal constituents to input coordinates

Parameters:
ilon: np.ndarray

longitude to interpolate

ilat: np.ndarray

latitude to interpolate

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

grid file for model

model_files: str, list, pathlib.Path or NoneType, default None

list of model files for each constituent

type: str, default ‘z’

Tidal variable to read

  • 'z': heights

  • 'u': horizontal transport velocities

  • 'U': horizontal depth-averaged transport

  • 'v': vertical transport velocities

  • 'V': vertical depth-averaged transport

crop: bool, default False

Crop tide model data to (buffered) bounds

bounds: list or NoneType, default None

Boundaries for cropping tide model data

buffer: int, float or NoneType, default None

Buffer angle for cropping tide model data

method: str, default ‘spline’

Interpolation method

  • 'bilinear': quick bilinear interpolation

  • 'spline': scipy bivariate spline interpolation

  • 'linear', 'nearest': scipy regular grid interpolations

extrapolate: bool, default False

Extrapolate model using nearest-neighbors

cutoff: float, default 10.0

Extrapolation cutoff in kilometers

Set to np.inf to extrapolate for all points

compressed: bool, default False

Input files are gzip compressed

scale: float, default 1.0

Scaling factor for converting to output units

Returns:
amplitude: np.ndarray

amplitudes of tidal constituents

phase: np.ndarray

phases of tidal constituents

D: np.ndarray

bathymetry of tide model

constituents: list

Tide model constituent names

pyTMD.io.ATLAS.read_constants(grid_file: str | Path | None = None, model_files: str | list | Path | None = None, **kwargs)[source]

Reads files for ATLAS netCDF4 tidal models

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

grid file for model

model_files: str, list, pathlib.Path or NoneType, default None

list of model files for each constituent

type: str, default ‘z’

Tidal variable to read

  • 'z': heights

  • 'u': horizontal transport velocities

  • 'U': horizontal depth-averaged transport

  • 'v': vertical transport velocities

  • 'V': vertical depth-averaged transport

compressed: bool, default False

Input files are gzip compressed

crop: bool, default False

Crop tide model data to (buffered) bounds

bounds: list or NoneType, default None

Boundaries for cropping tide model data

buffer: int or float, default 0

Buffer angle for cropping tide model data

Returns:
constituents: obj

complex form of tide model constituents

pyTMD.io.ATLAS.interpolate_constants(ilon: ndarray, ilat: ndarray, constituents, **kwargs)[source]

Interpolate constants from ATLAS tidal models to input coordinates

Makes initial calculations to run the tide program

Parameters:
ilon: np.ndarray

longitude to interpolate

ilat: np.ndarray

latitude to interpolate

constituents: obj

Tide model constituents (complex form)

type: str, default ‘z’

Tidal variable to read

  • 'z': heights

  • 'u': horizontal transport velocities

  • 'U': horizontal depth-averaged transport

  • 'v': vertical transport velocities

  • 'V': vertical depth-averaged transport

method: str, default ‘spline’

Interpolation method

  • 'bilinear': quick bilinear interpolation

  • 'spline': scipy bivariate spline interpolation

  • 'linear', 'nearest': scipy regular grid interpolations

extrapolate: bool, default False

Extrapolate model using nearest-neighbors

cutoff: float, default 10.0

Extrapolation cutoff in kilometers

Set to np.inf to extrapolate for all points

scale: float, default 1.0

Scaling factor for converting to output units

Returns:
amplitude: np.ndarray

amplitudes of tidal constituents

phase: np.ndarray

phases of tidal constituents

D: np.ndarray

bathymetry of tide model

pyTMD.io.ATLAS.read_netcdf_grid(input_file: str | Path, variable: str, **kwargs)[source]

Read grid file to extract model coordinates and bathymetry

Parameters:
input_file: str or pathlib.Path

input grid file

variable: str

Tidal variable to read

  • 'z': heights

  • 'u': horizontal transport velocities

  • 'U': horizontal depth-averaged transport

  • 'v': vertical transport velocities

  • 'V': vertical depth-averaged transport

compressed: bool, default False

Input file is gzip compressed

Returns:
lon: np.ndarray

longitudinal coordinates of input grid

lat: np.ndarray

latitudinal coordinates of input grid

bathymetry: np.ndarray

model bathymetry

pyTMD.io.ATLAS.read_netcdf_file(input_file: str | Path, variable: str, **kwargs)[source]

Wrapper function for reading netCDF4 files to extract real and imaginary components for constituent

Parameters:
input_file: str or pathlib.Path

input transport file

variable: str

Tidal variable to read

  • 'z': heights

  • 'u': horizontal transport velocities

  • 'U': horizontal depth-averaged transport

  • 'v': vertical transport velocities

  • 'V': vertical depth-averaged transport

compressed: bool, default False

Input file is gzip compressed

Returns:
hc: np.ndarray

tidal constituent

con: str

tidal constituent ID

pyTMD.io.ATLAS.read_netcdf_elevation(input_file: str | Path, **kwargs)[source]

Read elevation file to extract real and imaginary components for constituent

Parameters:
input_file: str or pathlib.Path

input elevation file

compressed: bool, default False

Input file is gzip compressed

Returns:
hc: np.ndarray

tidal elevation

con: str

tidal constituent ID

pyTMD.io.ATLAS.read_netcdf_transport(input_file: str | Path, variable: str, **kwargs)[source]

Read transport file to extract real and imaginary components for constituent

Parameters:
input_file: str or pathlib.Path

input transport file

variable: str

Tidal variable to read

  • 'u': horizontal transport velocities

  • 'U': horizontal depth-averaged transport

  • 'v': vertical transport velocities

  • 'V': vertical depth-averaged transport

compressed: bool, default False

Input file is gzip compressed

Returns:
hc: np.ndarray

tidal transport

con: str

tidal constituent ID

pyTMD.io.ATLAS.output_netcdf_grid(FILE: str | Path, hz: ndarray, hu: ndarray, hv: ndarray, lon_z: ndarray, lat_z: ndarray, lon_u: ndarray, lat_u: ndarray, lon_v: ndarray, lat_v: ndarray)[source]

Writes grid parameters to netCDF4 files in ATLAS format

Parameters:
FILE: str or pathlib.Path

output ATLAS grid file name

hz: np.ndarray

model bathymetry at z-nodes

hu: np.ndarray

model bathymetry at u-nodes

hv: np.ndarray

model bathymetry at v-nodes

lon_z: np.ndarray

longitude coordinates at z-nodes

lat_z: np.ndarray

latitude coordinates at z-nodes

lon_u: np.ndarray

longitude coordinates at u-nodes

lat_u: np.ndarray

latitude coordinates at u-nodes

lon_v: np.ndarray

longitude coordinates at v-nodes

lat_v: np.ndarray

latitude coordinates at v-nodes

pyTMD.io.ATLAS.output_netcdf_elevation(FILE: str | Path, h: ndarray, lon_z: ndarray, lat_z: ndarray, constituent: str)[source]

Writes elevation constituents to netCDF4 files in ATLAS format

Parameters:
FILE: str or pathlib.Path

output ATLAS elevation file name

h: np.ndarray

Eulerian form of tidal elevation oscillation

lon_z: np.ndarray

longitude coordinates at z-nodes

lat_z: np.ndarray

latitude coordinates at z-nodes

constituent: str

tidal constituent ID

pyTMD.io.ATLAS.output_netcdf_transport(FILE: str | Path, u: ndarray, v: ndarray, lon_u: ndarray, lat_u: ndarray, lon_v: ndarray, lat_v: ndarray, constituent: str)[source]

Writes transport constituents to netCDF4 files in ATLAS format

Parameters:
FILE: str or pathlib.Path

output ATLAS transport file name

u: np.ndarray

Eulerian form of tidal zonal transport oscillation

v: np.ndarray

Eulerian form of tidal meridional transport oscillation

lon_u: np.ndarray

longitude coordinates at u-nodes

lat_u: np.ndarray

latitude coordinates at u-nodes

lon_v: np.ndarray

longitude coordinates at v-nodes

lat_v: np.ndarray

latitude coordinates at v-nodes

constituents: str

tidal constituent ID

pyTMD.io.ATLAS._extend_array(input_array: ndarray, step_size: float)[source]

Extends a longitude array

Parameters:
input_array: np.ndarray

array to extend

step_size: float

step size between elements of array

Returns:
temp: np.ndarray

extended array

pyTMD.io.ATLAS._extend_matrix(input_matrix: ndarray)[source]

Extends a global matrix

Parameters:
input_matrix: np.ndarray

matrix to extend

Returns:
temp: np.ndarray

extended matrix

pyTMD.io.ATLAS._crop(input_matrix: ndarray, ilon: ndarray, ilat: ndarray, bounds: list | tuple, buffer: int | float = 0)[source]

Crop tide model data to bounds

Parameters:
input_matrix: np.ndarray

matrix to crop

ilon: np.ndarray

longitude of tidal model

ilat: np.ndarray

latitude of tidal model

bounds: list, tuple

bounding box: [xmin, xmax, ymin, ymax]

buffer: int or float, default 0

buffer to add to bounds for cropping

Returns:
temp: np.ndarray

cropped matrix

lon: np.ndarray

cropped longitude

lat: np.ndarray

cropped latitude

pyTMD.io.ATLAS._shift(input_matrix: ndarray, ilon: ndarray, lon0: int | float = 180, cyclic: int | float = 360, direction: str = 'west')[source]

Shift global grid east or west to a new base longitude

Parameters:
input_matrix: np.ndarray

input matrix to shift

ilon: np.ndarray

longitude of tidal model

lon0: int or float, default 180

Starting longitude for shifted grid

cyclic: int or float, default 360

width of periodic domain

direction: str, default ‘west’

Direction to shift grid

  • 'west'

  • 'east'

Returns:
temp: np.ndarray

shifted matrix

lon: np.ndarray

shifted longitude