comp_integral_miss_4d

Authors

Pascal Terray (LOCEAN/IPSL)

Latest revision

28/05/2024

Purpose

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

It is assumed that the input NetCDF variable has a scalar missing_value or _FillValue attribute, which allows a proper identification of the missing values in the dataset, otherwise the procedure will exit with an error message.

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 no missing values, excepted those associated with a constant atmosphere or ocean mask, use comp_integral_4d instead of comp_integral_miss_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_miss_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) \
  -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

-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_miss_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. It is assumed that the data have missing values in addition to those associated with a constant atmospher or ocean mask. If it is not the case, use comp_integral_4d instead of comp_integral_miss_4d.

   It is further assumed that the specified netcdf_variable has a scalar missing_value or _FillValue attribute and that missing values in the data are identified by the value of this missing_value or _FillValue attribute.

8. 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_miss_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.

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

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

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

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

13. The -bigfile argument is allowed only if the NCSTAT software has been compiled with the _USE_NETCDF36 or _USE_NETCDF4 macros (e.g., -D_USE_NETCDF36 or -D_USE_NETCDF4) 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 or _USE_NETCDF4 CPP macros.

14. The -hdf5 argument is allowed only if the NCSTAT software has been compiled with the _USE_NETCDF4 macro (e.g., -D_USE_NETCDF4) 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 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_miss_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 . This 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+1and 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_miss_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