comp_serie_4d

Authors

Pascal Terray (LOCEAN/IPSL)

Latest revision

28/05/2024

Purpose

Compute a time series from a fourdimensional variable extracted from a NetCDF dataset.

Different options are available for computing the time series 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 different point time series in the selected domain (see the description of the -d= argument below).

The computed time series is stored in an output NetCDF dataset.

If the NetCDF variable is tridimensional, use comp_serie_3d instead of comp_serie_4d.

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 time series with only one pass through the data and an out-of-core strategy which is highly efficient on huge datasets.

Further Details

Usage

$ comp_serie_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) \
  -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) \
  -3d                                  (optional) \
  -double                              (optional) \
  -hdf5                                (optional) \
  -tlimited                            (optional)

By default

-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 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 by default, nlon_orca, nlat_orca and nlevel_orca are determined from the -r= 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 averaged time series is computed from the raw data

-d=

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

-sm=

no smoothing is applied to the time series

-3d

the output_netcdf_variable is defined as an unidimensional NetCDF variable. However, if -3d is activated, the output_netcdf_variable is defined as an tridimensional NetCDF variable but with two dummy dimensions (e.g., with a length equal to 1 )

-double

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

-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 time series 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 and vertical resolution associated with the netcdf_variable is used for computing the time series.

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

3. If the -t=time1,time2 argument is missing, the whole time period associated with the netcdf_variable is used to compute the time series.

   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. 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 time series, 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.

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

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

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

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

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

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

11. The geographical shapes of the netcdf_variable (in the input_netcdf_file), the mask (in the 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.

12. The -d= argument specifies the weighting method for computing the averaged time series. If:

    • -d=dist3, the averaged time series 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 averaged time series 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 time series is computed with the identity metric (each grid point has the same weight when computing the averaged time series).

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

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

15. The -3d argument specifies that the averaged time series must be stored as a tridimensional NetCDF variable with two dummy dimensions in the output NetCDF file.

    By default, the time series is stored as an unidimensional NetCDF variable.

16. The -double argument specifies that, the time series is stored as double-precision floating point numbers in the output NetCDF file.

    By default, the time series is stored as single-precision floating point numbers in the output NetCDF file.

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

18. 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_serie_4d creates an output NetCDF file that contains the computed time series. The output NetCDF dataset contains the following NetCDF variable (in the description below, ntime is the number of time steps selected with the -t= argument) :

1. output_netcdf_variable(ntime) : the averaged time series defined as an unidimensional variable.

or if the -3d argument has been specified :

1. output_netcdf_variable(ntime,1,1) : the averaged time series defined as a tridimensional variable with two dummy dimensions.

Examples

1. For computing a monthly anomaly time series from the file ST7_1m_0101_20012_grid_T_votemper.nc, which includes a NetCDF variable votemper (from the NEMO model), and store the results in a NetCDF variable pacific_votemper in the file pacific_votemper.orca2.nc, use the following command :

   $ comp_serie_4d \
     -f=ST7_1m_0101_20012_grid_T_votemper.nc \
     -v=votemper \
     -m=meshmask.orca2.nc \
     -o=pacific_votemper.orca2.nc \
     -n=pacific_votemper \
     -g=t \
     -c=clim_grid_T_votemper.nc \
     -a=cov \
     -d=dist3