From 795319d679eb4da6453a16b99fc3859d4fffbc1b Mon Sep 17 00:00:00 2001 From: "Navid C. Constantinou" Date: Tue, 24 Dec 2024 08:54:54 +1100 Subject: [PATCH] fix docstring rendering + few typos --- src/Bathymetry.jl | 75 +++++++++++++++++++++++++---------------------- 1 file changed, 40 insertions(+), 35 deletions(-) diff --git a/src/Bathymetry.jl b/src/Bathymetry.jl index bf9ee264..f80daf95 100644 --- a/src/Bathymetry.jl +++ b/src/Bathymetry.jl @@ -32,65 +32,70 @@ end """ regrid_bathymetry(target_grid; - url = "https://www.ngdc.noaa.gov/thredds/fileServer/global/ETOPO2022/60s/60s_surface_elev_netcdf", - height_above_water = , + height_above_water = nothing, minimum_depth = 0, - dir = download_cache, - filename = "ETOPO_2022_v1_60s_N90W180_surface.nc") + dir = download_bathymetry_cache, + url = "https://www.ngdc.noaa.gov/thredds/fileServer/global/ETOPO2022/60s/60s_surface_elev_netcdf", + filename = "ETOPO_2022_v1_60s_N90W180_surface.nc", + interpolation_passes = 1, + major_basins = 1) -Regrid bathymetry associated with the NetCDF file at `path = joinpath(dir, filename)` to `target_grid`. +Return bathymetry associated with the NetCDF file at `path = joinpath(dir, filename)` regridded onto `target_grid`. If `path` does not exist, then a download is attempted from `joinpath(url, filename)`. Arguments ========= -- `target_grid`: grid to interpolate onto +- `target_grid`: grid to interpolate the bathymetry onto. Keyword Arguments ================= -- `height_above_water`: limits the maximum height of above-water topography (where h > 0). If - `nothing` the original topography is retained +- `height_above_water`: limits the maximum height of above-water topography (where ``h > 0``). + Default: `nothing`, which implies that the original topography is retained. - `minimum_depth`: minimum depth for the shallow regions, defined as a positive value. - `h > - minimum_depth` will be considered land + `h > - minimum_depth` is considered land. Default: 0. -- `dir`: directory of the bathymetry-containing file +- `dir`: directory of the bathymetry-containing file. Default: `download_bathymetry_cache`. -- `filename`: file containing bathymetric data. Must be netcdf with fields: - (1) `lat` vector of latitude nodes - (2) `lon` vector of longitude nodes - (3) `z` matrix of depth values +- `filename`: file containing bathymetric data. Must be netCDF with fields: + 1. `lat` vector of latitude nodes + 2. `lon` vector of longitude nodes + 3. `z` matrix of depth values - `interpolation_passes`: regridding/interpolation passes. The bathymetry is interpolated in - `interpolation_passes - 1` intermediate steps. With more steps the - final bathymetry will be smoother. - - Example: interpolating from a 400x200 grid to a 100x100 grid in 4 passes involves: + `interpolation_passes - 1` intermediate steps. The more the interpolation + steps the smoother the final bathymetry becomes. - * 400x200 → 325x175 - * 325x175 → 250x150 - * 250x150 → 175x125 - * 175x125 → 100x100 + Example + ======= + + Interpolating from a 400 x 200 grid to a 100 x 100 grid in 4 passes involves: + + * 400 x 200 → 325 x 175 + * 325 x 175 → 250 x 150 + * 250 x 150 → 175 x 125 + * 175 x 125 → 100 x 100 If _coarsening_ the original grid, linear interpolation in passes is equivalent to applying a smoothing filter, with more passes increasing the strength of the filter. - If _refining_ the original grid, additional passes will not help and no intermediate - steps will be performed. + If _refining_ the original grid, additional passes do not help and no intermediate + steps are performed. - `major_basins`: Number of "independent major basins", or fluid regions fully encompassed by land, that are retained by [`remove_minor_basins!`](@ref). Basins are removed by order of size: - the smallest basins are removed first. `major_basins=1` will retain only the largest basin. - Default: `Inf`, which does not remove any basins. + the smallest basins are removed first. `major_basins = 1` retains only the largest basin. + If `Inf` then no basins are removed. Default: 1. """ function regrid_bathymetry(target_grid; height_above_water = nothing, minimum_depth = 0, dir = download_bathymetry_cache, - url = "https://www.ngdc.noaa.gov/thredds/fileServer/global/ETOPO2022/60s/60s_surface_elev_netcdf", + url = "https://www.ngdc.noaa.gov/thredds/fileServer/global/ETOPO2022/60s/60s_surface_elev_netcdf", filename = "ETOPO_2022_v1_60s_N90W180_surface.nc", interpolation_passes = 1, - major_basins = 1) # Allow an `Inf` number of ``lakes'' + major_basins = 1) # Allow an `Inf` number of "lakes" filepath = joinpath(dir, filename) fileurl = url * "/" * filename # joinpath on windows creates the wrong url @@ -191,7 +196,7 @@ function regrid_bathymetry(target_grid; end # Here we can either use `regrid!` (three dimensional version) or `interpolate` -function interpolate_bathymetry_in_passes(native_z, target_grid; +function interpolate_bathymetry_in_passes(native_z, target_grid; passes = 10) Nλt, Nφt = Nt = size(target_grid) Nλn, Nφn = Nn = size(native_z) @@ -201,9 +206,9 @@ function interpolate_bathymetry_in_passes(native_z, target_grid; if Nλt > Nλn || Nφt > Nφn target_z = Field{Center, Center, Nothing}(target_grid) interpolate!(target_z, native_z) - @info string("Skipping passes for interplating bathymetry of size $Nn ", '\n', + @info string("Skipping passes for interpolating bathymetry of size $Nn ", '\n', "to target grid of size $Nt. Interpolation passes may only ", '\n', - "be used to refine bathymetryand requires that the bathymetry ", '\n', + "be used to refine bathymetry and require that the bathymetry ", '\n', "is larger than the target grid in both horizontal directions.") return target_z end @@ -230,9 +235,9 @@ function interpolate_bathymetry_in_passes(native_z, target_grid; @debug "Bathymetry interpolation pass $pass with size $new_size" new_grid = LatitudeLongitudeGrid(architecture(target_grid), - size = new_size, - latitude = (latitude[1], latitude[2]), - longitude = (longitude[1], longitude[2]), + size = new_size, + latitude = (latitude[1], latitude[2]), + longitude = (longitude[1], longitude[2]), z = (0, 1), topology = (TX, TY, Bounded)) @@ -276,7 +281,7 @@ function regrid_bathymetry(target_grid::DistributedGrid; kw...) local_bottom_height = Field{Center, Center, Nothing}(target_grid) set!(local_bottom_height, bottom_height) fill_halo_regions!(local_bottom_height) - + return local_bottom_height end