comp_section_4d

Authors

Pascal Terray (LOCEAN/IPSL)

Latest revision

28/05/2024

Purpose

Compute a longitude-level-time, latitude-level-time or longitude-latitude-time section (see the description of the -s= argument below) from a fourdimensional variable extracted from a NetCDF dataset.

Different options are available for computing the cross-section from raw data, anomalies after the removal of a climatology or standardized anomalies (see the description of the -a= argument below). Different options are also available for averaging the grid-point time series in the selected domain (see the description of the -d= argument below).

The computed cross-section is stored in an output NetCDF dataset.

If the NetCDF variable is tridimensional use comp_section_3d instead of comp_section_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 cross-section with only one pass through the data and an out-of-core strategy which is highly efficient on huge datasets.

Further Details

Usage

$ comp_section_4d \
  -f=input_netcdf_file \
  -v=input_netcdf_variable \
  -m=input_mesh_mask_netcdf_file \
  -o=output_netcdf_file \
  -n=output_netcdf_variable \
  -s=section                           (optional : lon, lat,dep) \
  -g=grid_type                         (optional : n, t, u, v, w, f) \
  -r=resolution                        (optional : r2, r4) \
  -b=nlon_orca, nlat_orca, nlevel_orca (optional) \
  -x=lon1,lon2                         (optional) \
  -y=lat1,lat2                         (optional) \
  -z=level1,level2                     (optional) \
  -t=time1,time2                       (optional) \
  -c=input_climatology_netcdf_file     (optional) \
  -a=type_of_analysis                  (optional : scp, cov, cor) \
  -d=type_of_distance                  (optional : dist2, dist3, ident) \
  -sm=smoothing_factor                 (optional) \
  -mi=missing_value                    (optional) \
  -double                              (optional) \
  -bigfile                             (optional) \
  -hdf5                                (optional) \
  -tlimited                            (optional)

By default

-s=

by default a latitude-time section is computed, which is equivalent to use lon for the -s= argument

-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

-r=

if the input netcdf_variable is from the NEMO model (e.g., if -g= argument is not set to n) the resolution is assumed to be r2

-b=

if -g= is not set to n, the dimensions of the 3-D grid-mesh, nlon_orca, nlat_orca and nlevel_orca are determined from the -r= argument. However, you may override this choice by default with the -b= argument

-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

-a=

the type_of_analysis is set to scp. This means that the section is computed from the raw data

-d=

the type_of_distance is set to dist3. This means that the section is computed as a weighted average and that the weight associated with each grid-point time series in the selected domain is proportional to the volume or the weight associated with it

-sm=

no time smoothing is applied to the section

-mi=

by default, the missing_value in the output NetCDF variable is set to 1.e+20

-double

the section is stored as single-precision floating point numbers in the output NetCDF file. If -double is activated, the section is stored as double-precision floating point numbers

-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 section 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 section. 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 allowed for lon1. In this case the longitude domain is from nlon+lon1+1 to lon2 where nlon is the number of longitude points in the grid associated with the NetCDF variable and it is assumed that the grid is periodic.

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

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

   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 land-sea mask.

5. The -s= argument determines how the cross-section is computed. If:

   • -s=lon, a latitude-level-time section is computed
   • -s=lat, a longitude-level-time section is computed
   • -s=dep, a longitude-latitude-time section is computed.

6. 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). In this case, the duplicate points from the ORCA grid are removed before computing the section, as far as possible, and, in particular, if the 3-D grid-mesh of the input NetCDF variable covers the whole globe.

   If -g= is set to n, it is assumed that the 3-D grid-mesh is regular or Gaussian and as such has no duplicate points.

7. If -g= is set to t, u, v, w or f (e.g., if the NetCDF variable is from an experiment with the NEMO model), the -r= argument gives the resolution used. If:

   • -r=r2, the NetCDF variable is from an experiment with the ORCA R2 configuration
   • -r=r4, the NetCDF variable is from an experiment with the ORCA R4 configuration.

8. If the NetCDF variable is from an experiment with the NEMO model, but the resolution is not R2 or R4, the dimensions of the ORCA grid must be specified explicitly with the -b= argument.

9. The -a= argument specifies if the grid-point time series are centered or standardized with an input climatology (specified with the -c= argument) before computing the cross-section for the selected domain. If:

   • -a=scp, the section is computed from the raw data
   • -a=cov, the section is computed from the anomalies
   • -a=cor, the section is computed from the standardized anomalies.

10. The input_climatology_netcdf_file specified with the -c= argument is needed only if -a=cov or -a=cor.

11. If -a=cov or -a=cor, the selected time period must agree with the climatology. This means that the first selected time observation (time1 if the -t= argument is present) must correspond to the first day, month, season of the climatology specified with the -c= argument.

12. 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), and the climatology (in the input_climatology_netcdf_file) must agree.

13. The -d= argument specifies the weighting method for computing the cross-section. If:

    • -d=dist3, the section is computed with the diagonal distance associated with the whole 3-D grid-mesh (each grid point is weighted accordingly to the volume or weight associated with it)
    • -d=dist2, the section is computed with the diagonal distance associated with the horizontal 2-D grid-mesh (each grid point is weighted accordingly to the surface associated with it)
    • -d=ident, the section is computed with the identity metric (each grid point has the same weight when computing the cross-section).

14. -sm=smoothing_factor means that the section must be smoothed in time with a moving average of approximately 2*smoothing_factor+1 terms. smoothing_factor must be an integer greater than 0.

15. The -n=output_netcdf_variable argument specifies the NetCDF variable which will contains the computed section in the output NetCDF file, output_netcdf_file, specified by the -o= argument.

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

17. The -double argument specify that the results are stored as double-precision floating point numbers in the output NetCDF file.

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

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

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

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

Outputs

comp_section_4d creates an output NetCDF file that contains the computed cross-section. The output NetCDF dataset contains the following NetCDF variable (in the description below, lat3, lon3 and lev3 are, respectively, equal to lat2 - lat1 + 1, lon2 - lon1 + 1 and lev2 - lev1 + 1 ) :

If -s=lon is specified:

1. output_netcdf_variable(ntime,lev3,lat3) : the computed latitude-level-time section.

If -s=lat is specified:

1. output_netcdf_variable(ntime,lev3,lon3) : the computed longitude-level-time section.

If -s=dep is specified:

1. output_netcdf_variable(ntime,lat3,lon3) : the computed longitude-latitude-time section.

Examples

1. For computing a monthly longitude-level-time section from the file ST7_1m_0101_20012_grid_T_votemper.nc, which includes a NetCDF variable votemper, and store the results in a NetCDF variable named temp in the file section_temp.orca2.nc, use the following command (note that the cross-section is computed from monthly anomalies) :

   $ comp_section_4d \
     -f=ST7_1m_0101_20012_grid_T_votemper.nc \
     -v=votemper \
     -m=meshmask.orca2.nc \
     -o=section_temp.orca2.nc \
     -n=temp \
     -s=lat \
     -g=t \
     -c=clim_votemper_grid_T.nc \
     -a=cov \
     -d=dist3