bathyreq.request

Module provides the BathyRequest class for requesting bathymetric data from a public data source.

Examples:

>>> import bathyreq
>>> req = bathyreq.BathyRequest()
>>> data, lonvec, latvec = req.get_area(
...     longitude=[-117.43000, -117.23000],
...     latitude=[32.55000, 32.75000],
...     size=[400, 400],
... )
>>> print(data.shape)
(400, 400)
>>> data = req.get_point(longitude=-117.43000, latitude=32.55000)
[-1017.61428833]

`bathyreq.request.BathyRequest`

Request bathymetry data from a data source.

Attributes:

source –

Bathymetric data source.
cache_dir –

Path to cache directory.
clear_cache –

Clear cache after use.

`init(source='ncei', cache_dir=CACHE_DIR, clear_cache=True)`

Initialize the BathyRequest class.

Parameters:

source (str, default: 'ncei' ) –

Data source.
cache_dir (Path, default: CACHE_DIR ) –

Directory to cache downloaded data.
clear_cache (bool, default: True ) –

Whether or not to delete files downloaded by this instance immediately after use.

`create_great_circle_transect(lon1, lat1, lon2, lat2, num_points=100)` `staticmethod`

Generate a great circle transect between two geographic points.

`download_data(url, filepath)` `staticmethod`

Download data from URL to filepath.

Parameters:

url (str) –

URL to download data from.
filepath (Path) –

Path to save data to.

Raises:

HTTPError –

If the request to the URL fails.

`form_bbox(longitude, latitude, single_point=False)` `staticmethod`

Form bounding box from longitude and latitude.

Parameters:

longitude (float | Sequence[float]) –

Longitude in the form [lon_min, lon_max].
latitude (float | Sequence[float]) –

Latitude in the form [lat_min, lat_max].
single_point (bool, default: False ) –

If True, add a small buffer to the bounding box.

Returns:

list[float, float, float, float] –

Bounding box in the form [lon_min, lat_min, lon_max, lat_max].

`generate_filename()` `staticmethod`

Generate a filename for the cache.

Returns:

str –

Filename.

`get_area(longitude, latitude, single_point=False, **source_kwargs)`

Get bathymetric data for an area.

The area is defined by the min/max of the longitude and latitude vectors. The data source is instantiated and request URL built. Data are downloaded to the cache and loaded into memory. The cache is cleared if requested. Latitude and longitude grids (vectors) are generated from the bounding box and according to the bathymetric data dimensions.

Examples:

>>> import bathyreq
>>> req = bathyreq.BathyRequest()
>>> data, lonvec, latvec = req.get_area(
...     longitude=[-117.43000, -117.23000],
...     latitude=[32.55000, 32.75000],
...     size=[100, 400],
... )
>>> print(data.shape)
(400, 100)

Parameters:

longitude (float | Sequence[float]) –

Longitude in the form [lon_min, lon_max].
latitude (float | Sequence[float]) –

Latitude in the form [lat_min, lat_max].
single_point (bool, default: False ) –

If True, add a small buffer to the bounding box.
**source_kwargs (dict, default: {} ) –

Keyword arguments to pass to Source. For example, size=[100, 400] ([n_longitude, n_latitude]).

Returns:

ndarray –

Bathymetric data (n_latitude, n_longitude)
ndarray –

Longitude grid
ndarray –

Latitude grid.

Raises:

HTTPError –

If the request to the URL fails.

`get_latlon_grids(bounds, data)` `staticmethod`

Get lat/lon grids from bounding box and data.

Parameters:

bounds (BoundingBox) –

Bounding box.
data (ndarray) –

Bathymetric data (n_latitude x n_longitude).

Returns:

tuple[ndarray, ndarray] –

Longitude and latitude grids.

`get_point(longitude, latitude, interp_method='linear', **source_kwargs)`

Get bathymetric data for a single point.

A small area of bathymetry surrounding the query point is downloaded and interpolated at the query points longitude and latitude.

Parameters:

longitude (float | Sequence[float]) –

Longitude.
latitude (float | Sequence[float]) –

Latitude.
interp_method (str, default: 'linear' ) –

Interpolation method, by default "linear".
**source_kwargs (dict, default: {} ) –

Keyword arguments to pass to the data source.

Returns:

ndarray –

Bathymetric data interpolated at the query points longitude and latitude.

`get_points(points, interp_method='linear', **source_kwargs)`

Get bathymetry for a list of longitude/latitude points.

Parameters:

points (Sequence[tuple[float, float]]) –

List of longitude/latitude points specified as tuples.
interp_method (str, default: 'linear' ) –

Interpolation method, by default "linear".
**source_kwargs (dict, default: {} ) –

Keyword arguments to pass to the data source.

Returns:

list[float] –

List of bathymetric data for each point.

`get_transect(point1, point2, num_points=100, interp_method='linear', **source_kwargs)`

Get bathymetry along a great circle transect.

Parameters:

point1 (Sequence[float]) –

First point (longitude, latitude).
point2 (Sequence[float]) –

Second point (longitude, latitude).
num_points (int, default: 100 ) –

Number of points along the transect, by default 100.
interp_method (str, default: 'linear' ) –

Interpolation method, by default "linear".
**source_kwargs (dict, default: {} ) –

Keyword arguments to pass to the data source.

Returns:

list[tuple[float, float]] –

Points along the transect.
list[float] –

Bathymetry at each point.
list[float] –

Distances along the transect.

`load_data(filepath)` `staticmethod`

Load data from filepath.

Parameters:

filepath (Path) –

Path to load data from.

Returns:

ndarray –

Bathymetric data (n_latitude x n_longitude).
BoundingBox –

Bounding box.