comp_mask_3d

Authors

Eric Maisonnave (CERFACS) and Pascal Terray (LOCEAN/IPSL)

Latest revision

28/05/2024

Purpose

Create a mesh-mask variable by specifying geographical bounds in indices or degrees and/or by modifying an input mesh-mask readed from a NetCDF dataset and store the resulting mesh-mask variable in a NetCDF dataset if the -o= argument (described below) is specified.

If an output NetCDF dataset is not specified with the -o= argument, the geographical bounds of the selected domain are printed as indices on output of the procedure. Such indices can then be used for specifying the -x= and -y= arguments for the selected domain in other NCSTAT procedures such as use comp_serie_3d.

If you want to create a mesh-mask variable for a fourdimensional NetCDF variable, use comp_mask_4d instead of comp_mask_3d.

Further Details

Usage

$ comp_mask_3d \
  -f=input_netcdf_file \
  -vlon=longitude_variable \
  -vlat=latitude_variable \
  -g=grid_type                      (optional : n, t, u, v, w, f) \
  -x=lon1,lon2                      (optional) \
  -y=lat1,lat2                      (optional) \
  -a=type_of_coordinates            (optional : indices, degrees) \
  -imsk=in_mask_value               (optional : ident, 0, 1) \
  -omsk=out_mask_value              (optional : ident, 0, 1) \
  -fmsk=input_mask_netcdf_file      (optional) \
  -vmsk=input_mask_netcdf_variable  (optional) \
  -val=mask_value                   (optional) \
  -rel=mask_relation                (optional : eq, gt, ge, lt, le) \
  -vout=output_mask_netcdf_variable (optional) \
  -o=output_mask_netcdf_file        (optional) \
  -noscalfac                        (optional) \
  -hdf5                             (optional)

By default

-g=
the grid_type is set to n, which means that the 2-D grid-mesh associated with the input latitude_variable and longitude_variable is assumed to be regular or Gaussian
-x=
the whole longitude range associated with the longitude_variable
-y=
the whole latitude range associated with the latitude_variable
-a=
the type_of_coordinates is set to indices. This means that the geographical bounds specified in the -x= and -y= arguments are given as indices not in degrees of longitude and latitude
-imsk=
the in_mask_value is set to 1. This means that points inside the specified domain are selected
-omsk=
the out_mask_value is set to 0. This means that points outside the specified domain are not selected
-fmsk=
an input_mask_netcdf_file is not used
-vmsk=
an input_mask_netcdf_variable is not used
-val=
the mask_value is set to 1.
-rel=
the mask_relation is set to eq
-vout=
the output_mask_netcdf_variable is named grid_type//mask if an output NetCDF file is created
-o=
an output_mask_netcdf_file is not created
-noscalfac
if the -fmsk= argument is present, the scale factors NetCDF variables, if they exist in the input_mask_netcdf_file, are automatically copied to the output NetCDF file. If the -noscalfac argument is specified, the scale factors NetCDF variables are not copied in the output NetCDF file
-hdf5
a NetCDF classical format file is created. If -hdf5 is activated, the output NetCDF file is a NetCDF-4/HDF5 format file

Remarks

  1. The -vlon= and -vlat= arguments specify the coordinate variables from which the mesh-mask variable will be constructed and the -f=input_netcdf_file argument specifies that these coordinate NetCDF variables must be extracted from the NetCDF file input_netcdf_file. The longitude and latitude coordinate NetCDF variables may be one or two dimensional arrays.

  2. If the -x=lon1,lon2 and -y=lat1,lat2 arguments are missing the whole geographical domain associated with the longitude_variable and latitude_variable is used to construct the mesh-mask.

    If -a=indices (the default value), the longitude (specified with the -x= argument) or latitude (specified with the -y= argument) range must be a vector of two integers specifying the first and last selected indices along each dimension. The indices are relative to 1. Negative values for lon1 are not allowed.

    If -a=degrees, the longitude or latitude range must be a vector of two integers specifying the longitude and latitude limits of the domain in degrees of longitude or latitude, respectively. In that case, negative values are allowed for lon1, lon2, lat1 and lat2. Moreover, the longitudes lon1 and lon2 are shifted to be in the interval between -180 and 180 degrees, assuming that the grid is periodic in longitude.

  3. If -g= is set to t, u, v, w or f it is assumed that the input 2-D grid-mesh associated with the input coordinate variables is from an experiment with the ORCA model (R2, R4 or R05 resolutions).

    This argument is also used to determine the name of the output_mask_netcdf_variable in the output NetCDF file if the -vout= argument is not specified. In that case, the output_mask_netcdf_variable will be named grid_type//mask.

  4. The -imsk= argument specifies the value (0, 1 or ident) to be given to grid points inside of the specified domain (as specified by the -x= and -y= arguments). By default, values inside the specified domain are set to 1 (e.g., -imsk=1).

    If -imsk=ident, the -vmsk= and -fmsk= arguments must also be given and the values inside the selected domain are read from the input_mask_netcdf_variable and are modified according to the logical relation determined by the -rel= and -val= arguments.

  5. The -omsk= argument is identical to -imsk= argument, but concerns points outside the specified domain (as specified by the -x= and -y= arguments). By default, values outside the specified domain are set to 0 (-omsk=0).

    If -omsk=ident, the -vmsk= and -fmsk= arguments must also be given and the values outside the selected domain are read from the input_mask_netcdf_variable and are modified according to the logical relation determined by the -rel= and -val= arguments.

  6. If -imsk=ident or -omsk=ident, the -fmsk= and -vmsk= arguments must be specified. In that case, the output mesh-mask variable output_mask_netcdf_variable is first initialized from the input_mask_netcdf_variable (as specified by the -vmsk= and -fmsk= arguments) inside the domain if -imsk=ident or outside the domain if -omsk=ident, and then modified in these regions according to the logical relationship:

    • output_mask(i,j) = 1 if input_mask(i,j) .mask_relation. mask_value is true
    • output_mask(i,j) = 0 otherwise

    where mask_relation is determined from the -rel= argument and mask_value from the -val= argument.

    By default, mask_relation is set to eq and mask_value is set to 1. . mask_value must be specified as a real number.

    The -fmsk= argument must be present, if the -vmsk= argument is specified, otherwise the program will stop.

    If the -fmsk= and -vmsk= arguments are not specified, the output mesh-mask variable is computed by applying the in_mask_value value (as specified by the -imsk= argument) inside the specified domain and the out_mask_value (as specified by the -omsk= argument) outside the specified domain.

  7. The geographical shapes of the input_mask_netcdf_variable (in the input_mask_netcdf_file) must agree with the input coordinate variables longitude_variable and latitude_variable (in the input_netcdf_file) if an input_mask_netcdf_file is used.

  8. The -hdf5 argument is allowed only if the NCSTAT software has been compiled with the _USE_NETCDF4 CPP macro (e.g., -D_USE_NETCDF4) and linked to the NetCDF 4 library or higher.

    If this argument is specified, the output_mask_netcdf_file will be a NetCDF-4/HDF5 format file instead of a NetCDF classic format file. However, this argument is recognized in the procedure only if the NCSTAT software has been built with the _USE_NETCDF4 CPP macro.

  9. Duplicate parameters are allowed, but this is always the last occurrence of a parameter which will be used for the computations. Moreover, the number of specified parameters must not be greater than the total number of allowed parameters.

Outputs

comp_mask_3d creates an output NetCDF file if the -o= argument is specified. This NetCDF dataset will contain the constructed mesh-mask (e.g., with values equal to 0 or 1) in a NetCDF variable called output_mask_netcdf_variable whose spatial dimensions are the same as those associated with the 2-D grid associated with the longitude_variable and latitude_variable specified with the -vlon= and -vlat= arguments (in the description below, nlat and nlon are the lengths of the spatial dimensions of the input 2-D grid) :

  1. output_mask_netcdf_variable(nlat,nlon) : the constructed mesh-mask (e.g., with values equal to 0 or 1) on the 2-D grid-mesh associated with the input coordinate variables.

Optionally, if an input_mask_netcdf_file is specified with the -fmsk= argument and this NetCDF file contains the scale factors associated with the 2-D grid associated with the input longitude_variable and latitude_variable NetCDF variables, the output NetCDF file will also contain the following variables (if the -noscalfac argument is not specified) :

  1. netcdf_variable_e1grid_type(nlat,nlon) : the first scale factor associated with the 2-D grid-mesh of the input coordinate variables.
  2. netcdf_variable_e2grid_type(nlat,nlon) : the second scale factor associated with the 2-D grid-mesh of the input coordinate variables.

Multiplying the two scale factors together gives the surface of each cell in the 2-D grid-mesh associated with the output_mask_netcdf_variable.

Flag Counter