# comp_mask_4d

## Authors

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

## Latest revision

30/04/2026

## Purpose

Create a mesh-mask variable by specifying geographical bounds in indices or geographical units (e.g., degrees, meters or pressure) 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=, -y= and -z= arguments for the selected domain in other NCSTAT procedures such as use comp_serie_4d.

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

## Further Details

### Usage

    $ comp_mask_4d \
      -f=input_netcdf_file \
      -vlon=longitude_variable \
      -vlat=latitude_variable \
      -vlev=level_variable \
      -g=grid_type                      (optional : n, t, u, v, w, f) \
      -x=lon1,lon2                      (optional) \
      -y=lat1,lat2                      (optional) \
      -z=level1,level2                  (optional) \
      -a=type_of_coordinates            (optional : indices, units) \
      -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) \
      -cdf5                             (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
> -z=
>   the whole vertical range associated with the level_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 geographical units ( e.g., degrees of longitude and latitude or meters for example)
> -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
> -cdf5
>   a NetCDF classical format file is created. If -cdf5 is activated, the output NetCDF file is a CDF5 format file

### Remarks

> 1. The -vlon=, -vlat= and -vlev= 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, -y=lat1,lat2 and -z=level1,level2 arguments are missing the whole geographical domain associated with the longitude_variable and latitude_variable, and the whole vertical resolution associated with the level_variable are used to construct the mesh-mask.

>    If -a=`indices` (the default value), the longitude (specified with the -x= argument), latitude (specified with the -y= argument) or level (specified with the -z= 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=`units`, 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. The vertical range must be a vector of two integers specifying the first and last levels of the domain in the unit of the NetCDF variable given in the -vlev= argument.

> 3. If -g= is set to `t`, `u`, `v`, `w` or `f` it is assumed that the input 3-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=, -y= and -z= 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=, -y= and -z= 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,k) = `1` if input_mask(i,j,k) .mask_relation. mask_value is `true`
>    - output_mask(i,j,k) = `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, latitude_variable and level_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 or _USE_NETCDF44 CPP macros (e.g., `-D_USE_NETCDF4` or `-D_USE_NETCDF44`) and linked to the NetCDF 4 library or higher.

>    If this argument is specified, the output_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 or _USE_NETCDF44 CPP macros.

> 9. The -cdf5 argument is allowed only if the NCSTAT software has been compiled with the _USE_NETCDF44 CPP macro (e.g., `-D_USE_NETCDF44`) and linked to the NetCDF 4.4 library or higher.

>    If this argument is specified, the output_netcdf_file will be a CDF5 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_NETCDF44 CPP macro.

> 10. 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_4d 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 geographical dimensions are the same as those associated with the 3-D grid associated with the longitude_variable, latitude_variable and level_variable specified with the -vlon=, -vlat= and -vlev= arguments (in the description below, nlat, nlon and nlev are the lengths of the geographical dimensions of the input 3-D grid) :

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

> If the longitude_variable, latitude_variable and level_variable in the input_netcdf_file are unidimensional, they are also copied in the output NetCDF file.

> Optionally, if an input_mask_netcdf_file is specified with the -fmsk= argument and this NetCDF file contains the scale factors associated with the 3-D grid associated with the input longitude_variable, latitude_variable and level_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.
> 3. netcdf_variable_e3grid_type`(nlev,1,1)` : the third scale factor associated with the 3-D grid-mesh of the input coordinate variables.

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