# comp_section_miss_3d

## Authors

Pascal Terray (LOCEAN/IPSL)

## Latest revision

30/04/2026

## Purpose

Compute a longitude-time or latitude-time section (see the description of the -s= argument below) from a tridimensional variable with missing values 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 section is stored in an output NetCDF dataset.

If your data has no missing values, excepted for a constant land-sea mask, use comp_section_3d instead of comp_section_miss_3d to compute the cross-section from your dataset.

This procedure is parallelized if OpenMP is used and the NCSTAT software has been built with the _PARALLEL_READ CPP macro. 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_miss_3d \
      -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) \
      -g=grid_type                      (optional : n, t, u, v, w, f) \
      -r=resolution                     (optional : r2, r4) \
      -b=nlon_orca, nlat_orca           (optional) \
      -x=lon1,lon2                      (optional) \
      -y=lat1,lat2                      (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, ident) \
      -sm=smoothing_factor              (optional) \
      -mi=missing_value                 (optional) \
      -3d                               (optional)
      -double                           (optional) \
      -bigfile                          (optional) \
      -hdf5                             (optional) \
      -cdf5                             (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 2-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 2-D grid-mesh, nlon_orca and nlat_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
> -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 `dist2`. This means that the section is computed as a weighted average and that the weight associated with each point time series in the selected domain is proportional to the surface 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`
> -3d
>   the output_netcdf_variable is defined as an bidimensional NetCDF variable. However, if -3d is activated, the output_netcdf_variable is defined as a tridimensional NetCDF variable, but with one dummy dimension (e.g., with a length equal to `1` )
> -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
> -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 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. It is 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 attribute.

> 3. It is assumed that the data has missing values in addition to those associated with a constant land-sea mask. If your dataset has no missing values, use comp_section_3d instead of comp_section_miss_3d.

> 4. If the -x=lon1,lon2 and -y=lat1,lat2 arguments are missing the whole geographical domain associated with the netcdf_variable is used for computing the section. The longitude or latitude 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_3d for transforming geographical coordinates as indices before using comp_section_miss_3d.

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

> 6. The -s= argument determines if a latitude-time or longitude-time section is computed. If:

>    - -s=`lon`, a latitude-time section is computed
>    - -s=`lat`, a longitude-time section is computed.

> 7. 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 2-D grid-mesh of the input NetCDF variable covers the whole globe.

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

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

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

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

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

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

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

> 14. The -d= argument specifies the weighting method for computing the section. If:

>     - -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 averaged time series).

> 15. -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`. However, if missing values are present in the computed time section, smoothing is not allowed.

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

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

> 18. The -3d argument specifies that the latitude-time or longitude-time section must be stored as a tridimensional NetCDF variable with a dummy dimension in the output NetCDF file.

>     By default, the section is stored as a bidimensional NetCDF variable.

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

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

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

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

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

### Outputs

> comp_section_miss_3d 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 and lon3 are, respectively, equal to `lat2 - lat1 + 1` and `lon2 - lon1 + 1` or `lon2 - nlon - lon1 - 1` if lon1 is negative) :

> If -s=`lon` is specified:

> 1. output_netcdf_variable`(ntime,lat3)` : the computed latitude-time section.

> Or if -s=`lon` and -3d arguments have been specified :

> 1. output_netcdf_variable`(ntime,lat3,1)` : the computed latitude-time section defined as a tridimensional variable with one dummy dimension.

> If -s=`lat` is specified:

> 1. output_netcdf_variable`(ntime,lon3)` : the computed longitude-time section.

> Or if -s=`lat` and -3d arguments have been specified :

> 1. output_netcdf_variable`(ntime,1,lon3)` : the computed longitude-time section defined as a tridimensional variable with one dummy dimension.

### Examples

> 1. For computing a monthly longitude-time section from the file `ST7_1m_0101_20012_grid_T_sosstsst.nc`, which includes a NetCDF variable `sosstsst`, and store the results in a NetCDF variable named `sst` in the file `section_sst.orca2.nc`, use the following command (note that the cross-section is computed from monthly anomalies since -a=`cov` is specified) :

>        $ comp_section_miss_3d \
>          -f=ST7_1m_0101_20012_grid_T_sosstsst.nc \
>          -v=sosstsst \
>          -m=meshmask.orca2.nc \
>          -o=section_sst.orca2.nc \
>          -n=sst \
>          -s=lat \
>          -g=t \
>          -c=clim_sosstsst_grid_T.nc \
>          -a=cov \
>          -d=dist2