Data - Bathymetry & Pangaea
cruiseplan.data package.
This package contains data management and external data integration modules:
bathymetry: Bathymetry data handling using ETOPO datasets with interpolationcache: File-based caching system for expensive computations and downloadseez_boundaries: EEZ boundary data management and spatial operationspangaea: Integration with Pangaea data repository for oceanographic data
These modules handle external data sources, caching strategies, and data processing required for cruise planning, including bathymetric information and scientific datasets.
cruiseplan.data.bathymetry module
Bathymetry data download and management.
This module provides functionality for downloading, caching, and accessing bathymetry data from ETOPO and GEBCO datasets for depth lookups.
When the file for the requested source is missing, too small or unreadable,
depth lookups return the fill value DEFAULT_DEPTH (-9999.0) and a warning
names the file and how to obtain it. No other source is substituted.
- class cruiseplan.data.bathymetry.BathymetryManager(source: str = 'gebco2025', data_dir: str = 'data/bathymetry')[source]
Bases:
objectHandles ETOPO bathymetry data with lazy loading and bilinear interpolation.
Manages bathymetric data from ETOPO and GEBCO datasets, providing depth lookups and grid subsets for oceanographic applications. When the file for
sourceis missing, too small or unreadable, depth lookups returnDEFAULT_DEPTHand grid subsets are empty; a warning names the file.- source
Bathymetry data source identifier.
- Type:
str
- data_dir
Directory containing bathymetry data files.
- Type:
Path
- file_path
Expected path of the bathymetry file for
source.- Type:
Path
- available
True when the bathymetry file was loaded.
- Type:
bool
- _dataset
NetCDF dataset object when loaded.
- Type:
Optional[nc.Dataset]
- _lats
Latitude coordinate array.
- Type:
Optional[np.ndarray]
- _lons
Longitude coordinate array.
- Type:
Optional[np.ndarray]
- __init__(source: str = 'gebco2025', data_dir: str = 'data/bathymetry') None[source]
Initialize the bathymetry manager.
- Parameters:
source (str, optional) – Bathymetry data source (default: “gebco2025”).
data_dir (str, optional) – Data directory. Can be absolute path or relative to current working directory (default: “data/bathymetry”).
- close() None[source]
Close the NetCDF dataset if open.
Should be called when the manager is no longer needed to free resources.
- ensure_gebco_2025(silent_if_exists: bool = False) bool[source]
Ensure GEBCO 2025 dataset is available for high-resolution bathymetry.
Downloads and extracts GEBCO 2025 data if not present or corrupted. The full dataset is ~7.5GB uncompressed, downloaded as ~4GB zip.
- Parameters:
silent_if_exists (bool, optional) – If True, don’t log when file already exists (default: False).
- Returns:
True if GEBCO 2025 is available, False if download failed or cancelled.
- Return type:
bool
- get_depth_at_point(lat: float, lon: float) float[source]
Get depth at a specific geographic point.
Returns depth in meters (negative values indicate depth below sea level). Uses bilinear interpolation on the ETOPO grid for accurate results.
- Parameters:
lat (float) – Latitude in decimal degrees.
lon (float) – Longitude in decimal degrees.
- Returns:
Depth in meters (negative for below sea level), or
DEFAULT_DEPTHwhen the file is unavailable or the point is outside the grid.- Return type:
float
- get_grid_subset(lat_min: float, lat_max: float, lon_min: float, lon_max: float, stride: int = 1) tuple[ndarray, ndarray, ndarray][source]
Get a subset of the bathymetry grid for contour plotting.
Returns 2D arrays suitable for matplotlib contour plotting. Supports downsampling with stride parameter for performance.
- Parameters:
lat_min (float) – Minimum latitude of the subset.
lat_max (float) – Maximum latitude of the subset.
lon_min (float) – Minimum longitude of the subset.
lon_max (float) – Maximum longitude of the subset.
stride (int, optional) – Downsampling factor (default: 1, no downsampling).
- Returns:
(lons, lats, depths) as 2D arrays for contour plotting. All three are empty when the file is unavailable or the region is outside it.
- Return type:
tuple of numpy.ndarray
Notes
This method performs expensive NetCDF grid slicing operations. Consider using cruiseplan.utils.cache.CacheManager for repeated grid subset requests with overlapping geographic bounds, especially in interactive applications like station_picker and map generation workflows.
- cruiseplan.data.bathymetry.check_bathymetry_availability(source: str, data_dir: str = 'data/bathymetry') bool[source]
Check if the bathymetry file for the specified source is present and complete.
- Parameters:
source (str) – Bathymetry source identifier (e.g. “etopo2022”, “gebco2025”).
data_dir (str, optional) – Directory containing bathymetry files (default: “data/bathymetry”).
- Returns:
True if the file exists and is at least the minimum expected size.
- Return type:
bool
- cruiseplan.data.bathymetry.download_bathymetry(target_dir: str = 'data/bathymetry', source: str = 'gebco2025') str | bool | None[source]
Download bathymetry dataset with progress bar.
Downloads ETOPO 2022 (60 s resolution) or GEBCO 2025 (15 s resolution). For the local-only sources (
msm142,msm142_jj,msm142_dt) the file is not downloaded; its presence is checked instead.- Parameters:
target_dir (str, optional) – Target directory for bathymetry files (default: “data/bathymetry”). Files will be saved directly in this directory.
source (str, optional) – Bathymetry source to download (default: “gebco2025”). Options: “etopo2022”, “gebco2025”, “msm142”, “msm142_jj”, “msm142_dt”.
- Returns:
Returns file path (str) if successful or file exists, False if explicitly cancelled, None if download failed completely.
- Return type:
str, bool, or None
- Raises:
ValueError – If
sourcecannot be downloaded (for example"gebco2023", which has no download location here and must be placed by hand).
- cruiseplan.data.bathymetry.get_bathymetry_manager(source: str = 'gebco2025', data_dir: str = 'data/bathymetry') BathymetryManager[source]
Return a BathymetryManager, shared within a
shared_bathymetryblock.- Parameters:
source (str, optional) – Bathymetry source identifier (default: “gebco2025”).
data_dir (str, optional) – Directory containing bathymetry files (default: “data/bathymetry”).
- Returns:
A new manager, or the one already opened for the same source and directory inside the current
shared_bathymetryblock.- Return type:
- cruiseplan.data.bathymetry.get_bathymetry_singleton() BathymetryManager[source]
Get the singleton BathymetryManager instance (lazy initialization).
Share one BathymetryManager per source and directory inside the block.
get_bathymetry_managercalls inside the block return the same open manager, so a pipeline run opens each bathymetry file once and warns about a missing file once. Managers are closed when the block exits.- Yields:
None – Control returns to the caller with sharing active.
- cruiseplan.data.bathymetry.source_file(source: str) tuple[str, float][source]
Return the expected file name and minimum size for a bathymetry source.
- Parameters:
source (str) – Bathymetry source identifier (e.g.
"gebco2025"). An unknown identifier maps to"<source>.nc"with a 10 MB minimum.- Returns:
File name inside the bathymetry directory and minimum size in MB.
- Return type:
tuple of (str, float)
cruiseplan.data.pangaea module
PANGAEA database integration and data retrieval.
This module provides functionality for searching, downloading, and processing oceanographic datasets from the PANGAEA data repository.
- class cruiseplan.data.pangaea.PangaeaManager(cache_dir: str = '.cache')[source]
Bases:
objectManager for PANGAEA dataset search and retrieval.
Provides functionality to search PANGAEA datasets using spatial queries, fetch metadata and coordinate data, and cache results for performance. Integrates with the cruise planning system for incorporating existing cruise tracks into planning workflows.
- cache
File-based cache for storing fetched dataset metadata.
- Type:
- __init__(cache_dir: str = '.cache') None[source]
Initialize PANGAEA manager.
- Parameters:
cache_dir (str, optional) – Directory for cache storage (default: “.cache”).
- create_map(datasets: list[dict[str, Any]], filename: str = 'pangaea_map.html', include_eez: bool = True) Path[source]
Plot the datasets fetched by this manager on an interactive map.
- Parameters:
datasets (List[Dict[str, Any]]) – List of dataset dictionaries with latitude/longitude data.
filename (str, optional) – Output filename for the HTML map (default: “pangaea_map.html”).
include_eez (bool, optional) – Include EEZ boundaries on the map (default: True).
- Returns:
Path to the generated HTML map file.
- Return type:
Path
- fetch_datasets(doi_list: list[str], rate_limit: float | None = None, merge_campaigns: bool = False, progress_callback: Callable[[int, int, str], None] | None = None) list[dict[str, Any]][source]
Process a list of DOIs and return standardized metadata objects.
- Parameters:
doi_list (List[str]) – List of DOI strings to fetch.
rate_limit (Optional[float], optional) – Optional requests per second limit (None = no rate limiting).
merge_campaigns (bool, optional) – Whether to merge campaigns with same name (default: False).
progress_callback (Optional[Callable[[int, int, str], None]], optional) – Optional function(current, total, message) for progress updates.
- Returns:
List of dataset dictionaries with standardized metadata.
- Return type:
List[Dict[str, Any]]
- search(query: str, bbox: tuple | None = None, limit: int = 10) list[dict[str, Any]][source]
Search PANGAEA using the native PanQuery bbox support.
- Parameters:
query (str) – Search query string for PANGAEA datasets.
bbox (tuple, optional) – Bounding box as (min_lon, min_lat, max_lon, max_lat).
limit (int, optional) – Maximum number of results to return (default: 10).
- Returns:
List of dataset metadata dictionaries.
- Return type:
List[Dict[str, Any]]
- cruiseplan.data.pangaea.load_campaign_data(file_path: str | Path, merge_tracks: bool = True) list[dict][source]
Load pre-processed PANGAEA campaign data from pickle file.
This function is required by the CLI to integrate with the interactive picker. If merge_tracks is True, it ensures that all datasets with the same label are combined into a single track before being returned.
- Parameters:
file_path (Union[str, Path]) – Path to the pickled PANGAEA campaign file.
merge_tracks (bool) – If True, runs merge_campaign_tracks on the loaded data. (Default: True)
- Returns:
List of campaign datasets (merged if requested).
- Return type:
List[Dict]
- cruiseplan.data.pangaea.merge_campaign_tracks(datasets: list[dict]) list[dict][source]
Merge datasets by their ‘label’ (campaign).
Aggregates coordinates into single arrays and collects all source DOIs.
- Parameters:
datasets (List[Dict]) – List of dataset dictionaries to merge.
- Returns:
Merged campaign datasets with combined coordinates.
- Return type:
List[Dict]
- cruiseplan.data.pangaea.read_doi_list(file_path: str | Path) list[str][source]
Read DOI list from text file, filtering out comments and empty lines.
- Parameters:
file_path (Union[str, Path]) – Path to DOI list file
- Returns:
List of DOI strings
- Return type:
list[str]
- Raises:
ValueError – If file cannot be read or contains no valid DOIs
- cruiseplan.data.pangaea.save_campaign_data(datasets: list[dict], file_path: str | Path, progress_callback: Callable[[str], None] | None = None, original_dataset_count: int | None = None) None[source]
Save PANGAEA datasets to pickle file.
- Parameters:
datasets (List[Dict]) – List of dataset dictionaries to save.
file_path (Union[str, Path]) – Output file path for the pickle file.
progress_callback (Optional[Callable[[str], None]], optional) – Optional function(message) for progress updates.
original_dataset_count (Optional[int], optional) – Optional count of datasets before merging for summary.
- Raises:
ValueError – If there’s an error saving the file.