dfm-tools 0.42.0__py3-none-any.whl

dfm_tools/__init__.py

@@ -0,0 +1,24 @@
+"""
+Pre- and postprocessing D-FlowFM model input and output files
+"""
+
+__author__ = """Jelmer Veenstra"""
+__email__ = "jelmer.veenstra@deltares.nl"
+__version__ = "0.42.0"
+
+from dfm_tools.deprecated_functions import *
+from dfm_tools.download import *
+from dfm_tools.get_nc import *
+from dfm_tools.get_nc_helpers import *
+from dfm_tools.hydrolib_helpers import *
+from dfm_tools.meshkernel_helpers import *
+from dfm_tools.interpolate_grid2bnd import *
+from dfm_tools.linebuilder import *
+from dfm_tools.modplot import *
+from dfm_tools.xarray_helpers import *
+from dfm_tools.xugrid_helpers import *
+from dfm_tools.bathymetry import *
+from dfm_tools.coastlines import *
+from dfm_tools import data
+from dfm_tools.modelbuilder import *
+from dfm_tools.observations import *

dfm_tools/bathymetry.py

@@ -0,0 +1,101 @@
+import numpy as np
+import xarray as xr
+
+
+def write_bathy_toasc(filename_asc,lon_sel_ext,lat_sel_ext,elev_sel_ext,asc_fmt='%9.2f',nodata_val=32767):
+    """
+    empty docstring
+    """
+
+    print('writing to asc file')
+    if elev_sel_ext.shape != (lat_sel_ext.shape[0], lon_sel_ext.shape[0]):
+        raise ValueError('resulting shape of elev_sel_ext %s is not consistent with lat_sel_ext/lon_sel_ext vars %s'%(elev_sel_ext.shape,(lat_sel_ext.shape[0], lon_sel_ext.shape[0])))
+    if isinstance(elev_sel_ext,np.ma.core.MaskedArray): #masked has to be filled in order for the nans to be visible
+        elev_sel_ext = elev_sel_ext.filled(np.nan)
+    if np.isnan(elev_sel_ext).sum()>0:
+        elev_sel_ext = elev_sel_ext.copy()
+        elev_sel_ext[np.isnan(elev_sel_ext)] = nodata_val
+        print('replaced nan values with %d'%(nodata_val))
+    resinv_lonlat = np.round(1/np.diff(lon_sel_ext[:2]),2)[0]
+    resinv_lat = np.round(1/np.diff(lat_sel_ext[:2]),2)[0]
+    if resinv_lonlat!=resinv_lat:
+        raise ValueError('inconsistent resolution over lat/lon')
+    
+    with open(filename_asc,'w') as file_asc:
+        file_asc.write('ncols         %d\n'%(elev_sel_ext.shape[1]))
+        file_asc.write('nrows         %d\n'%(elev_sel_ext.shape[0]))
+        file_asc.write('xllcenter     %13.8f\n'%(lon_sel_ext[0]))
+        file_asc.write('yllcenter     %13.8f\n'%(lat_sel_ext[0]))
+        file_asc.write('cellsize      %16.11f\n'%(1/resinv_lonlat))
+        #file_asc.write('NODATA_value  %d\n'%(nodata_val))
+        file_asc.write('NODATA_value  '+asc_fmt%(nodata_val)+'\n')
+    with open(filename_asc,'a') as file_asc:
+        np.savetxt(file_asc,np.flip(elev_sel_ext,axis=0),fmt=asc_fmt)
+    print('...finished')
+
+
+def read_asc(file_asc:str) -> xr.Dataset:
+    """
+    Reading asc file into a xarray.Dataset
+
+    Parameters
+    ----------
+    file_asc : str
+        asc file with header ncols, nrows, xllcenter, yllcenter, cellsize, NODATA_value.
+
+    Returns
+    -------
+    ds_asc : xr.Dataset
+        xarray.Dataset with the data from the asc file as an array and 
+        the lat/lon coordinates as separate coordinate variables.
+
+    """
+    # read header
+    header_dict = {}
+    with open(file_asc) as f:
+        for linenum, line in enumerate(f, 1):
+            linesplit = line.split()
+            linestart = linesplit[0]
+            linestop = linesplit[-1]
+            
+            try:
+                # try to convert it to float, this will fail for headerlines
+                # it will succeed for numeric lines, but then the loop breaks
+                float(linestart)
+                break
+            except ValueError:
+                # convert header values to int if possible or float if not
+                try:
+                    header_value = int(linestop)
+                except ValueError:
+                    header_value = float(linestop)
+                header_dict[linestart] = header_value
+                skiprows = linenum
+    
+    # read data
+    asc_np = np.loadtxt(file_asc, skiprows=skiprows, dtype=float)
+    
+    # derive x/y values and assert shape
+    num_x = header_dict['ncols']
+    num_y = header_dict['nrows']
+    start_x = header_dict['xllcenter']
+    start_y = header_dict['yllcenter']
+    step = header_dict['cellsize']
+    nodata = header_dict['NODATA_value']
+    
+    assert asc_np.shape == (num_y, num_x)
+    
+    x_vals = np.arange(0, num_x) * step + start_x
+    y_vals = np.arange(0, num_y) * step + start_y
+    
+    # flip over latitude and replace nodata with nan
+    asc_np = np.flipud(asc_np)
+    asc_np[asc_np==nodata] = np.nan
+    
+    ds_asc = xr.Dataset()
+    ds_asc['lon'] = xr.DataArray(x_vals, dims=('lon'))
+    ds_asc['lat'] = xr.DataArray(y_vals, dims=('lat'))
+    ds_asc['data'] = xr.DataArray(asc_np, dims=('lat','lon'))
+    ds_asc = ds_asc.assign_attrs(header_dict)
+    return ds_asc
+

dfm_tools/coastlines.py

@@ -0,0 +1,186 @@
+import os
+import geopandas as gpd
+import matplotlib.pyplot as plt
+import pandas as pd
+import datetime as dt
+from dfm_tools.data import gshhs_coastlines_shp
+
+__all__ = ["get_coastlines_gdb",
+           "plot_coastlines",
+           "get_borders_gdb",
+           "plot_borders",
+    ]
+
+
+def bbox_convert_crs(bbox, crs):
+    """
+    convert bbox from input crs to WGS84
+    """
+    bbox_points = gpd.points_from_xy(x=[bbox[0],bbox[2]], y=[bbox[1],bbox[3]], crs=crs)
+    bbox_points = bbox_points.to_crs('EPSG:4326') #convert to WGS84
+    bbox = (bbox_points.x[0], bbox_points.y[0], bbox_points.x[1], bbox_points.y[1])
+    return bbox
+
+
+def get_coastlines_gdb(res:str='h', bbox:tuple = (-180, -90, 180, 90), min_area:float = 0, crs:str = None, columns:list = ['area']) -> gpd.geoseries.GeoSeries:
+    """
+    GSHHS coastlines: https://www.ngdc.noaa.gov/mgg/shorelines/data/gshhg/latest/readme.txt
+    geopandas docs https://geopandas.org/en/stable/docs/reference/api/geopandas.read_file.html
+    
+    Parameters
+    ----------
+    res : str, optional
+        f(ull), h(igh), i(ntermediate), l(ow), c(oarse) resolution. The default is 'h'.
+    bbox : tuple, optional
+        (minx, miny, maxx, maxy), also includes shapes that are partly in the bbox. The default is (-180, -90, 180, 90).
+    min_area : float, optional
+        in km2, min_area>0 speeds up process. The default is 0.
+    crs : str, optional
+        coordinate reference system
+    columns : list, optional
+        which shapefile columns to include, None gives all. The default is ['area'].
+
+    Returns
+    -------
+    coastlines_gdb : TYPE
+        DESCRIPTION.
+
+    """
+    
+    if res not in 'fhilc':
+        raise KeyError(f'invalid res="{res}", resolution options are f(ull), h(igh), i(ntermediate), l(ow), c(oarse)')
+    if crs is not None:
+        bbox = bbox_convert_crs(bbox, crs)
+        
+    # download gshhs data if not present and return dir
+    dir_gshhs = gshhs_coastlines_shp()
+
+    file_shp_L1 = os.path.join(dir_gshhs,'GSHHS_shp',res,f'GSHHS_{res}_L1.shp') #coastlines
+    file_shp_L6 = os.path.join(dir_gshhs,'GSHHS_shp',res,f'GSHHS_{res}_L6.shp') #Antarctic grounding-line polygons
+    file_shp_L2 = os.path.join(dir_gshhs,'GSHHS_shp',res,f'GSHHS_{res}_L2.shp') #lakes
+    file_shp_L3 = os.path.join(dir_gshhs,'GSHHS_shp',res,f'GSHHS_{res}_L3.shp') #islands-in-lakes
+    
+    print('>> reading coastlines: ',end='')
+    dtstart = dt.datetime.now()
+    coastlines_gdb_L1 = gpd.read_file(file_shp_L1, columns=columns, where=f"area>{min_area}", bbox=bbox)
+    coastlines_gdb_L6 = gpd.read_file(file_shp_L6, columns=columns, where=f"area>{min_area}", bbox=bbox)
+    coastlines_gdb_list = [coastlines_gdb_L1,coastlines_gdb_L6]
+    if len(coastlines_gdb_L1)<2: #if only one L1 polygon is selected, automatically add lakes and islands-in-lakes
+        coastlines_gdb_L2 = gpd.read_file(file_shp_L2, columns=columns, where=f"area>{min_area}", bbox=bbox)
+        coastlines_gdb_list.append(coastlines_gdb_L2)
+        coastlines_gdb_L3 = gpd.read_file(file_shp_L3, columns=columns, where=f"area>{min_area}", bbox=bbox)
+        coastlines_gdb_list.append(coastlines_gdb_L3)
+    
+    # remove empty geodataframes from list to avoid FutureWarning
+    # escape for empty resulting list and concatenate otherwise
+    coastlines_gdb_list = [x for x in coastlines_gdb_list if not x.empty]
+    if not coastlines_gdb_list:
+        return gpd.GeoDataFrame()
+    coastlines_gdb = pd.concat(coastlines_gdb_list)
+    print(f'{(dt.datetime.now()-dtstart).total_seconds():.2f} sec')
+    
+    if crs:
+        coastlines_gdb = coastlines_gdb.to_crs(crs)
+    
+    return coastlines_gdb
+
+
+def get_borders_gdb(res:str='h', bbox:tuple = (-180, -90, 180, 90), crs:str = None) -> gpd.geoseries.GeoSeries:
+    """
+    GSHHS coastlines: https://www.ngdc.noaa.gov/mgg/shorelines/data/gshhg/latest/readme.txt
+    geopandas docs https://geopandas.org/en/stable/docs/reference/api/geopandas.read_file.html
+    
+    Parameters
+    ----------
+    res : str, optional
+        f(ull), h(igh), i(ntermediate), l(ow), c(oarse) resolution. The default is 'h'.
+    bbox : tuple, optional
+        (minx, miny, maxx, maxy), also includes shapes that are partly in the bbox. The default is (-180, -90, 180, 90).
+    crs : str, optional
+        coordinate reference system
+    
+    Returns
+    -------
+    coastlines_gdb : TYPE
+        DESCRIPTION.
+
+    """
+    
+    if res not in 'fhilc':
+        raise KeyError(f'invalid res="{res}", resolution options are f(ull), h(igh), i(ntermediate), l(ow), c(oarse)')
+    if crs is not None:
+        bbox = bbox_convert_crs(bbox, crs)
+        
+    # download gshhs data if not present and return dir
+    dir_gshhs = gshhs_coastlines_shp()
+
+    file_shp_L1 = os.path.join(dir_gshhs,'WDBII_shp',res,f'WDBII_border_{res}_L1.shp') #borders
+    
+    print('>> reading country borders: ',end='')
+    dtstart = dt.datetime.now()
+    coastlines_gdb = gpd.read_file(file_shp_L1, bbox=bbox)
+    print(f'{(dt.datetime.now()-dtstart).total_seconds():.2f} sec')
+    
+    if crs:
+        coastlines_gdb = coastlines_gdb.to_crs(crs)
+    
+    return coastlines_gdb
+
+
+def plot_coastlines(ax=None, res:str='h', min_area:float = 0, crs=None, **kwargs):
+    """
+    get coastlines with get_coastlines_gdb and bbox depending on axlims, plot on ax and set axlims back to original values
+    """
+    #TODO: if ax is GeoAxis, get crs from ax
+    
+    if ax is None:
+        ax = plt.gca()
+    
+    xlim = ax.get_xlim()
+    ylim = ax.get_ylim()
+    bbox = (xlim[0], ylim[0], xlim[1], ylim[1])
+    
+    if 'edgecolor' not in kwargs:
+        kwargs['edgecolor'] = 'k'
+    if 'facecolor' not in kwargs:
+        kwargs['facecolor'] = 'none'
+    if 'linewidth' not in kwargs:
+        kwargs['linewidth'] = 0.5
+    
+    coastlines_gdb = get_coastlines_gdb(bbox=bbox, res=res, min_area=min_area, crs=crs)
+    if coastlines_gdb.empty:
+        return
+    
+    coastlines_gdb.plot(ax=ax, **kwargs)
+    
+    ax.set_xlim(xlim)
+    ax.set_ylim(ylim)
+
+
+def plot_borders(ax=None, res:str='h', crs=None, **kwargs):
+    """
+    get borders with get_borders_gdb and bbox depending on axlims, plot on ax and set axlims back to original values
+    """
+    #TODO: if ax is GeoAxis, get crs from ax
+    
+    if ax is None:
+        ax = plt.gca()
+    
+    xlim = ax.get_xlim()
+    ylim = ax.get_ylim()
+    bbox = (xlim[0], ylim[0], xlim[1], ylim[1])
+    
+    if 'edgecolor' not in kwargs:
+        kwargs['edgecolor'] = 'grey'
+    if 'linewidth' not in kwargs:
+        kwargs['linewidth'] = 0.5
+    
+    coastlines_gdb = get_borders_gdb(bbox=bbox, res=res, crs=crs)
+    if coastlines_gdb.empty:
+        return
+    
+    coastlines_gdb.plot(ax=ax, **kwargs)
+    
+    ax.set_xlim(xlim)
+    ax.set_ylim(ylim)
+

dfm_tools/data.py

@@ -0,0 +1,336 @@
+import os
+import requests
+import xarray as xr
+import xugrid as xu
+import pooch
+import zipfile
+from dfm_tools.xugrid_helpers import (open_partitioned_dataset,
+                                      open_dataset_delft3d4,
+                                      enrich_rst_with_map,
+                                      )
+from dfm_tools.xarray_helpers import preprocess_hisnc
+
+__all__ = ["fm_grevelingen_map",
+           "fm_grevelingen_his",
+           "fm_grevelingen_net",
+           "fm_curvedbend_map",
+           "fm_curvedbend_his",
+           "fm_westernscheldt_map",
+           "d3d_westernscheldt_trim",
+           "d3d_curvedbend_trim",
+           "d3d_curvedbend_trih",
+   ]
+
+
+def get_dir_testdata():
+    # create cache dir like %USERPROFILE%/AppData/Local/dfm_tools/dfm_tools/Cache
+    # TODO: add SHA256 checking and more, like: https://github.com/Deltares/xugrid/blob/main/xugrid/data/sample_data.py
+    dir_testdata = str(pooch.os_cache('dfm_tools'))
+    os.makedirs(dir_testdata, exist_ok=True)
+    return dir_testdata
+
+
+def maybe_download_opendap_data(file_nc,dir_subfolder=None):
+    if os.path.exists(file_nc): # only download if file does not exist already
+        return
+    
+    #opendap catalog: https://opendap.deltares.nl/thredds/catalog/opendap/deltares/Delft3D/netcdf_example_files/catalog.html
+    opendap_url = 'https://opendap.deltares.nl/thredds/fileServer/opendap/deltares/Delft3D/netcdf_example_files'
+    if dir_subfolder is not None:
+        opendap_url = f'{opendap_url}/{dir_subfolder}'
+    fname = os.path.basename(file_nc)
+    file_url = f'{opendap_url}/{fname}'
+
+    print(f'downloading "{fname}" from opendap.deltares.nl to cachedir')
+    r = requests.get(file_url, allow_redirects=True)
+    r.raise_for_status() #raise HTTPError if url not exists
+    with open(file_nc, 'wb') as f:
+        f.write(r.content)
+
+
+def fm_grevelingen_map(return_filepath:bool = False) -> xu.UgridDataset:
+    
+    dir_subfolder = 'DFM_grevelingen_3D'
+    dir_testdata = get_dir_testdata()
+    
+    file_nc_pat = os.path.join(dir_testdata,'Grevelingen-FM_0*_map.nc')
+    
+    #download data if not present
+    for part in range(8):
+        file_nc = file_nc_pat.replace('0*',f'{part:04d}')
+        maybe_download_opendap_data(file_nc,dir_subfolder)
+    
+    #potentially only return filepath of downloaded file(s)
+    filepath = file_nc_pat
+    if return_filepath:
+        return filepath
+    
+    #open as xugrid.UgridDataset
+    uds = open_partitioned_dataset(filepath)
+    return uds
+
+
+def fm_grevelingen_his(return_filepath:bool = False) -> xr.Dataset:
+    
+    dir_subfolder = 'DFM_grevelingen_3D'
+    dir_testdata = get_dir_testdata()
+    
+    #download data if not present
+    file_nc = os.path.join(dir_testdata,'Grevelingen-FM_0000_his.nc')
+    maybe_download_opendap_data(file_nc,dir_subfolder)
+    
+    #potentially only return filepath of downloaded file(s)
+    filepath = file_nc
+    if return_filepath:
+        return filepath
+    
+    #open as xarray.Dataset
+    ds = xr.open_mfdataset(filepath,preprocess=preprocess_hisnc)
+    return ds
+
+
+def fm_grevelingen_net(return_filepath:bool = False) -> xu.UgridDataset:
+    
+    dir_subfolder = 'DFM_grevelingen_3D'
+    dir_testdata = get_dir_testdata()
+    
+    #download data if not present
+    file_nc = os.path.join(dir_testdata,'Grevelingen_FM_grid_20190603_net.nc')
+    maybe_download_opendap_data(file_nc,dir_subfolder)
+    
+    #potentially only return filepath of downloaded file(s)
+    filepath = file_nc
+    if return_filepath:
+        return filepath
+    
+    #open as xugrid.UgridDataset
+    uds = open_partitioned_dataset(filepath)
+    return uds
+
+
+def fm_curvedbend_map(return_filepath:bool = False) -> xu.UgridDataset:
+    
+    dir_subfolder = 'DFM_curvedbend_3D'
+    dir_testdata = get_dir_testdata()
+    
+    #download data if not present
+    file_nc = os.path.join(dir_testdata,'cb_3d_map.nc')
+    maybe_download_opendap_data(file_nc,dir_subfolder)
+    
+    #potentially only return filepath of downloaded file(s)
+    filepath = file_nc
+    if return_filepath:
+        return filepath
+    
+    #open as xugrid.UgridDataset
+    uds = open_partitioned_dataset(filepath)
+    return uds
+
+
+def fm_curvedbend_his(return_filepath:bool = False) -> xr.Dataset:
+    
+    dir_subfolder = 'DFM_curvedbend_3D'
+    dir_testdata = get_dir_testdata()
+    
+    #download data if not present
+    file_nc = os.path.join(dir_testdata,'cb_3d_his.nc')
+    maybe_download_opendap_data(file_nc,dir_subfolder)
+    
+    #potentially only return filepath of downloaded file(s)
+    filepath = file_nc
+    if return_filepath:
+        return filepath
+    
+    #open as xarray.Dataset
+    ds = xr.open_mfdataset(filepath,preprocess=preprocess_hisnc)
+    return ds
+
+
+def fm_westernscheldt_map(return_filepath:bool = False) -> xu.UgridDataset:
+    # from p:\dflowfm\maintenance\JIRA\05000-05999\05477\c103_ws_3d_fourier
+    
+    dir_subfolder = 'DFM_westernscheldt_3D'
+    dir_testdata = get_dir_testdata()
+    
+    #download data if not present
+    file_nc = os.path.join(dir_testdata,'westerscheldt01_0subst_map.nc')
+    maybe_download_opendap_data(file_nc,dir_subfolder)
+    
+    #potentially only return filepath of downloaded file(s)
+    filepath = file_nc
+    if return_filepath:
+        return filepath
+    
+    #open as UgridDataset
+    uds = open_partitioned_dataset(filepath, remove_edges=True)
+    return uds
+
+
+def fm_westernscheldt_fou(return_filepath:bool = False) -> xu.UgridDataset:
+    # from p:\dflowfm\maintenance\JIRA\05000-05999\05477\c103_ws_3d_fourier
+    
+    dir_subfolder = 'DFM_westernscheldt_3D'
+    dir_testdata = get_dir_testdata()
+    
+    #download data if not present
+    file_nc = os.path.join(dir_testdata,'westerscheldt01_0subst_fou.nc')
+    maybe_download_opendap_data(file_nc,dir_subfolder)
+    
+    #potentially only return filepath of downloaded file(s)
+    filepath = file_nc
+    if return_filepath:
+        return filepath
+    
+    #open as UgridDataset
+    uds = open_partitioned_dataset(filepath, remove_edges=True)
+    return uds
+
+
+def fm_westernscheldt_rst(return_filepath:bool = False) -> xu.UgridDataset:
+    # from p:\dflowfm\maintenance\JIRA\05000-05999\05477\c103_ws_3d_fourier
+    
+    dir_subfolder = 'DFM_westernscheldt_3D'
+    dir_testdata = get_dir_testdata()
+    
+    #download data if not present
+    file_nc = os.path.join(dir_testdata,'westerscheldt01_0subst_20140101_004640_rst.nc')
+    maybe_download_opendap_data(file_nc,dir_subfolder)
+    
+    #potentially only return filepath of downloaded file(s)
+    filepath = file_nc
+    if return_filepath:
+        return filepath
+    
+    #open as UgridDataset
+    uds = open_partitioned_dataset(filepath, preprocess=enrich_rst_with_map)
+    return uds
+
+
+def fm_westernscheldt_his(return_filepath:bool = False) -> xr.Dataset:
+    # from p:\dflowfm\maintenance\JIRA\05000-05999\05477\c103_ws_3d_fourier
+    
+    dir_subfolder = 'DFM_westernscheldt_3D'
+    dir_testdata = get_dir_testdata()
+    
+    #download data if not present
+    file_nc = os.path.join(dir_testdata,'westerscheldt01_0subst_his.nc')
+    maybe_download_opendap_data(file_nc,dir_subfolder)
+    
+    #potentially only return filepath of downloaded file(s)
+    filepath = file_nc
+    if return_filepath:
+        return filepath
+    
+    #open as xarray.Dataset
+    ds = xr.open_mfdataset(filepath,preprocess=preprocess_hisnc)
+    return ds
+
+
+def d3d_westernscheldt_trim(return_filepath:bool = False) -> xu.UgridDataset:
+    
+    dir_testdata = get_dir_testdata()
+    
+    #download data if not present
+    file_nc = os.path.join(dir_testdata,'trim-westernscheldt_sph.nc')
+    maybe_download_opendap_data(file_nc)
+    
+    #potentially only return filepath of downloaded file(s)
+    filepath = file_nc
+    if return_filepath:
+        return filepath
+    
+    #open as UgridDataset
+    uds = open_dataset_delft3d4(filepath)
+    return uds
+
+
+def d3d_curvedbend_trim(return_filepath:bool = False) -> xu.UgridDataset:
+    
+    dir_testdata = get_dir_testdata()
+    
+    #download data if not present
+    file_nc = os.path.join(dir_testdata,'trim-cb2-sal-added-3d.nc')
+    maybe_download_opendap_data(file_nc)
+    
+    #potentially only return filepath of downloaded file(s)
+    filepath = file_nc
+    if return_filepath:
+        return filepath
+    
+    #open as UgridDataset
+    uds = open_dataset_delft3d4(filepath)
+    return uds
+
+
+def d3d_curvedbend_trih(return_filepath:bool = False) -> xr.Dataset:
+    
+    dir_testdata = get_dir_testdata()
+    
+    #download data if not present
+    file_nc = os.path.join(dir_testdata,'trih-cb2-sal-added-3d.nc')
+    maybe_download_opendap_data(file_nc)
+    
+    #potentially only return filepath of downloaded file(s)
+    filepath = file_nc
+    if return_filepath:
+        return filepath
+    
+    #open as UgridDataset
+    ds = xr.open_mfdataset(filepath,preprocess=preprocess_hisnc)
+    return ds
+
+
+def gshhs_coastlines_shp() -> str:
+    """
+    Downloads and unzips GSHHS coastlines from NOAA if not present.
+    Checks presence of files for all five resolutions.
+
+    Returns
+    -------
+    str
+        DESCRIPTION.
+
+    """
+    
+    dir_testdata = get_dir_testdata()
+    
+    fname = 'gshhg-shp-2.3.7'
+    filepath_zip = os.path.join(dir_testdata, f"{fname}.zip")
+    dir_gshhs = os.path.join(dir_testdata, fname)
+    
+    def download_gshhs(url):
+        url_base = url.split("/")[2]
+        fname_zip = url.split('/')[-1]
+        print(f'downloading "{fname_zip}" from {url_base} to cachedir')
+        # url is redirected to https://objects.githubusercontent.com
+        resp = requests.get(url, allow_redirects=True)
+        # raise HTTPError if url not exists
+        resp.raise_for_status()
+        return resp
+    
+    # download zipfile if not present
+    if not os.path.exists(filepath_zip) and not os.path.exists(dir_gshhs):
+        file_url = f"https://github.com/GenericMappingTools/gshhg-gmt/releases/download/2.3.7/{fname}.zip"
+        resp = download_gshhs(file_url)
+        with open(filepath_zip, 'wb') as f:
+            f.write(resp.content)
+
+    # unzip zipfile if unzipped folder not present
+    if not os.path.exists(dir_gshhs):
+        print(f'unzipping "{fname}.zip"')
+        with zipfile.ZipFile(filepath_zip, 'r') as zip_ref:
+            zip_ref.extractall(dir_gshhs)
+    
+    # construct filepath list and check existence of shapefiles
+    filepath_shp_list = [os.path.join(dir_gshhs,'GSHHS_shp',res,f'GSHHS_{res}_L1.shp') for res in ['f','h','i','l','c']]
+    for filepath_shp in filepath_shp_list:
+        assert os.path.exists(filepath_shp) #coastlines
+        assert os.path.exists(filepath_shp.replace('L1.shp','L2.shp')) #lakes
+        assert os.path.exists(filepath_shp.replace('L1.shp','L3.shp')) #islands-in-lakes
+        assert os.path.exists(filepath_shp.replace('L1.shp','L6.shp')) #Antarctic grounding-line polygons
+    filepath_shp_list = [os.path.join(dir_gshhs,'WDBII_shp',res,f'WDBII_border_{res}_L1.shp') for res in ['f','h','i','l','c']]
+    for filepath_shp in filepath_shp_list:
+        assert os.path.exists(filepath_shp) #coastlines
+    
+    return dir_gshhs
+