# comp_integral_4d

## Authors

Pascal Terray (LOCEAN/IPSL)

## Latest revision

30/04/2026

## Purpose

Perform vertical integrations (e.g., through the depth of the ocean or the height of the atmosphere) from a fourdimensional variable extracted from a NetCDF dataset.

Different options are available for computing the vertical integrals in the selected domain and for each time steps of the fourdimensional variable (see the description of the -d= argument below).

The computed integrals are stored in an output NetCDF dataset.

If the NetCDF variable has missing values, in addition to those associated with a constant atmosphere or ocean mask, use comp_integral_miss_4d instead of comp_integral_4d.

This procedure is parallelized if OpenMP is used and the NCSTAT software has been built with the _PARALLEL_READ CPP flag. Moreover, this procedure computes the vertical integrals with only one pass through the data and an out-of-core strategy which is efficient on huge datasets.

## Further Details

### Usage

    $ comp_integral_4d \
      -f=input_netcdf_file \
      -v=input_netcdf_variable \
      -m=input_mesh_mask_netcdf_file \
      -o=output_netcdf_file \
      -n=output_netcdf_variable \
      -g=grid_type                         (optional : n, t, u, v, w, f) \
      -x=lon1,lon2                         (optional) \
      -y=lat1,lat2                         (optional) \
      -z=level1,level2                     (optional) \
      -t=time1,time2                       (optional) \
      -d=type_of_integral                  (optional : dist3, ident) \
      -mi=missing_value                    (optional) \
      -double                              (optional) \
      -compact                             (optional) \
      -bigfile                             (optional) \
      -hdf5                                (optional) \
      -cdf5                                (optional) \
      -tlimited                            (optional)

### By default

> -g=
>   the grid_type is set to `n`, which means that the 3-D grid-mesh associated with the input NetCDF variable is assumed to be regular or Gaussian
> -x=
>   the whole longitude domain associated with the netcdf_variable
> -y=
>   the whole latitude domain associated with the netcdf_variable
> -z=
>   the whole vertical resolution associated with the netcdf_variable
> -t=
>   the whole time period associated with the netcdf_variable
> -d=
>   the type_of_integral is set to `dist3`. This means that the vertical integrals are computed as weighted averages and that the weight associated with each layer is proportional to the volume or the mass associated with it
> -mi=
>   by default, the missing_value in the output NetCDF variable is set to `1.e+20`
> -double
>   the integrals are stored as single-precision floating point numbers in the output NetCDF file. If -double is activated, the integrals are stored as double-precision floating point numbers
> -compact
>   the output NetCDF file is not compacted
> -bigfile
>   a NetCDF classical format file is created. If -bigfile is activated, the output NetCDF file is a 64-bit offset format 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
> -tlimited
>   the time dimension is defined as unlimited in the output NetCDF file. However, if -tlimited is activated, the time dimension is defined as limited in the output NetCDF file

### Remarks

> 1. The -v=netcdf_variable argument specifies the NetCDF variable from which the vertical integrals must be computed and the -f=input_netcdf_file argument specifies that this NetCDF variable must be extracted from the NetCDF file, input_netcdf_file.

> 2. If the -x=lon1,lon2, -y=lat1,lat2 and -z=level1,level2 arguments are missing the whole geographical domain associated with the netcdf_variable is used for computing the vertical integrals.

>    The longitude, latitude or level 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 are not allowed for lon1.

>    The -z= argument is used for determining the limits of the vertical integrations, which are performed.

>    Refer to comp_mask_4d for transforming geographical coordinates as indices before using comp_integral_4d.

> 3. If the -t=time1,time2 argument is missing the whole time period associated with the netcdf_variable is used for computing the vertical integrals.

>    The selected time period is a vector of two integers specifying the first and last time observations. The indices are relative to `1`. Note that the output NetCDF file will have `ntime` = time2 - time1 + `1` time observations.

> 4. It is assumed that the data has no missing values excepted those associated with a constant atmosphere or ocean mask (as specified by the input mesh-mask NetCDF file).

> 5. If -g= is set to `t`, `u`, `v`, `w` or `f`, it is assumed that the NetCDF variable is from an experiment with the NEMO model (ORCA configuration and R2, R4 or R05 resolutions).

>    If -g= is set to `n`, it is assumed that the 3-D grid-mesh is regular or Gaussian.

> 6. The geographical shapes of the netcdf_variable (in the input_netcdf_file), the mask (input_mesh_mask_netcdf_file), the scale factors (in the input_mesh_mask_netcdf_file) must agree.

> 7. The -d= argument specifies the weighting method for computing the integrals. If:

>    - -d=`dist3`, the vertical integrals are computed as weighted averages. Each layer is weighted accordingly to the volume or weight associated with it. In this case, it is assumed that the input mesh-mask NetCDF file has a variable named “e3”//grid, where grid is the value of the -g= argument, which is the third scale factor associated with the grid-mesh of the input_netcdf_variable. In the case of a regular or gaussian grid, this third scale factor is automatically computed by comp_clim_4d, comp_clim_miss_4d or comp_stat_4d. This third scale factor variable provides the weights for computing the vertical integrals in comp_integral_4d if -d=`dist3` is specified.
>    - -d=`ident`, the vertical integrals are computed as simple sums. Each layer has the same weight (equals to 1) when computing the integrals. In this case, it is not required that the input mesh-mask NetCDF file contains a third scale factor as a variable.

> 8. The -n=output_netcdf_variable argument specifies the NetCDF variable which will contain the computed vertical integrals in the output NetCDF file, output_netcdf_file, specified by the -o= argument.

> 9. The -mi=missing_value argument specifies the missing value indicator associated with the output_netcdf_variable in the output_netcdf_file. If the -mi= argument is not specified, missing_value is set to `1.e+20` in the output NetCDF dataset.

> 10. The -double argument specify that the interals are stored as double-precision floating point numbers in the output NetCDF file.

>     By default, the vertical integrals are stored as single-precision floating point numbers in the output NetCDF file.

> 11. If the -compact argument is specified and a domain is selected (with the -x= and -y= arguments) then only vertical integrals for the selected domain will be output. By default, the whole 2-D grid is stored (with missing values outside the selected domain) in the output NetCDF file.

> 12. The -bigfile argument is allowed only if the NCSTAT software has been compiled with the _USE_NETCDF36, _USE_NETCDF4 or _USE_NETCDF44 CPP macros (e.g., `-D_USE_NETCDF36` or `-D_USE_NETCDF4` or `-D_USE_NETCDF44`) and linked to the NetCDF 3.6 library or higher.

>     If this argument is specified, the output_netcdf_file will be a 64-bit offset 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_NETCDF36, _USE_NETCDF4 or _USE_NETCDF44 CPP macros.

> 13. 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.

> 14. 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.

> 15. Duplicate parameters are allowed, but this is always the last occurrence of a parameter which will be used for the computations.

### Outputs

> comp_integral_4d creates an output NetCDF file that contains the vertical integrals computed for each time step and grid point selected from the input NetCDF variable and the horizontal coordinate NetCDF variables of the input NetCDF dataset input_netcdf_file . The NetCDF variable storing the integrals will have the same horizontal dimensions as the input NetCDF variable in the file input_netcdf_file (in the description below, nlat and nlon are the lengths of the spatial dimensions of the input NetCDF variable) and ntime time observations (corresponding to the number of time steps selected with -t= argument) :

> 1. output_netcdf_variable `(ntime,nlat,nlon)` : the computed vertical integrals for the select domain and time steps associated with the input NetCDF variable.

> By default, the whole grid associated with the input NetCDF variable is stored (with missing values outside the selected domain). Note, however, that if the argument -compact is used, the geographical dimensions of the output NetCDF variable will be reduced to the selected domain as specified by the -x= and -y= arguments (e.g., in this case `nlat`=lat2-lat1+`1`and `nlon`=lon2-lon1+`1` ). The number of time steps written in the output NetCDF file (e.g., `ntime`) is determined from the -t= argument.

### Examples

> 1. For computing vertical integrals from the file `ST7_1m_0101_20012_grid_T_votemper.nc`, which includes a fourdimensional NetCDF variable `votemper`, and store the results in a NetCDF variable named `int_votemper` in the file `integral_temp.orca2.nc`, use the following command (note that the vertical integrals are computed as weighted averages for each time step and grid-point associated with the whole horizontal 2-D grid-mesh of the input NetCDF variable) :

>        $ comp_integral_4d \
>          -f=ST7_1m_0101_20012_grid_T_votemper.nc \
>          -v=votemper \
>          -m=meshmask.orca2.nc \
>          -o=integral_temp.orca2.nc \
>          -n=int_votemper \
>          -g=t \
>          -d=dist3