Oceantools

Collection of tools for oceanography

How to install

The tool is written in Python3, the use of a virtual environment is suggested.

In the oceantools/install you can find the yaml file to build a new environment:

• cd oceantools/install
• conda env create -f environment.yml

Please be sure that anaconda is installed under your machine!

Activate the virtual environment:

• conda activate oceantools

How to run spatial regridding for regular netcdf files

spatial_regrid.py performs horizontal and vertical bilinear interpolation of regular netcdf file, from an input file to a target user-defined grid. The procedure includes also a Sea-Over-Land step before regridding.

The command is:

• cd oceantools/geometry
• python spatial_regrid.py -i input_file -o output_grid -n output filename

input_file is the absolute path to the file you want to regrid. The file needs to have 1D spatial coordinates (as in CF-compliant netcdf). The tool is not able to manage 2D coordinates (e.g NEMO based files).

output_grid is the target grid which can (or not) have a vertical dimension. If the vertical dimension is not present, the interpolation will be performed only at the first layer of the input_file . If a vertical dimension is present in the target grid, the data will be interpolated also in vertical.

output filename name for the output netcdf

The user should provides also some information about the name for dimensions and variable using the catalog.yaml file.

Here an example:

-------- catalog.yaml file -------- source:

input_file:

fillvalue: 1e20

coords:

 latitude: lat

 longitude: lon

 depth: depth

 time: time

variables:

 temperature: thetao
 #salinity: so

output_grid:
fillvalue: 9999 sol_iterations: 5 coords:

 latitude: lat
 longitude: lon
 depth: depth

variables:

   lsm: mask

----------------------------------------

# is the comment character in catalog.

input_file block allows to define:

• fill values of the input file
• in the coords block, the latitude and longitude names. If the input_file has also time and/or depth dimensions these must be declared here. If not, the procedure raise a self-explaining error. If the input_file has time dimension, the regridding will be applied at each time. !!!Only four names allowed in the coords block: latitude, longitude, time, depth!!!
• in the variables block, the variable/s to regrid. Here the user can define one or more variables, and the keys used in the block (temperature and salinity in the example) will be used as variable name in the output file.

output_grid block allows to define:

• fill values to be used in the output file
• sol_iterations: number of iterations for SeaOvearLand
• in the coords block, the latitude and longitude names. If the output_grid has also vertical coordinate, this has to be defined here. If the vertical coordinate is not defined here, (using depth key in catalog) the regrid will be applied only at the first level of the input_file.
• in the variables block the user defines the name of the land-sea mask variable. The mask should has been defined as following: ocean=1 (or True), land=0 (or False)

Test

In _oceantools/geometry/tests directory some example netcdf are available, with/without time and depth dimensions, with one or two variables.

Examples of test commands:

• python ./spatial_regrid.py -i ./tests/NWP_noTime.nc -o ./tests/mask.nc -n example_1 ---> for temperature horizontal and vertical regrid without time dimension
• python ./spatial_regrid.py -i ./tests/NWP_2vars.nc -o ./tests/mask.nc -n example_2 ---> for salinity and temperature horizontal and vertical regrid
• python ./spatial_regrid.py -i ./tests/NWP_complete.nc -o ./tests/mask.nc -n example_3 ---> temperature horizontal and vertical regrid with time dimension

Each of these examples requires a proper configuration of the catalog according to dimensions/variables in each input_file/output_file. If the configuration is not properly set, an error warns about the catalog check needed. The log will also show the dumping of files and catalogs, so the user can easily checks where is the error.

Notes

Before interpolation on the new grid, the tool applies a Sea-Over-Land (SOL) procedure. Here SOL is a python application implemented by E.Jansen at CMCC from a G. Girardi's fortran development. SOL extrapolates sea information on the land to avoid the loosing of data near coast due to interpolation with NaN or FillValue. . Please consider that SOL affects only data on land, and if, for example, the procedure fills completely an island, nothing occurs anymore even if the iterations continue.

Author reference

Please contact Salvatore at [email protected] for questions, bugs, suggestions.