comp_serie_3d

Authors

Pascal Terray (LOCEAN/IPSL)

Latest revision

28/05/2024

Purpose

Compute a time series from a tridimensional 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 pointwise 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 your data contains missing values, use comp_serie_miss_3d instead of comp_serie_3d to compute the time series from your gappy dataset.

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

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_3d \
  -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            (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) \
  -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 or ORCA model (eg 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 averaged time series is computed from the raw data

-d=

the type_of_distance is set to dist2. 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 surface associated with it

-sm=

no smoothing is applied to the computed 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 and -y=lat1,lat2 arguments are missing, the whole geographical domain associated with the netcdf_variable is used to construct the time series.

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

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. If your dataset has missing values, use comp_serie_miss_3d instead of comp_serie_3d.

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 or ORCA model. 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 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.

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=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_3d 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 time series from the file HadISST1_1m_187001_200702_sst_reg1m.nc, which includes a NetCDF variable sst, and store the results in a NetCDF variable named nino34_sst in the file HadISST1_1m_187001_200702_nino34sst.nc, use the following command :

   $ comp_serie_3d \
     -f=HadISST1_1m_187001_200702_sst_reg1m.nc \
     -v=sst \
     -x=11,60 \
     -y=86,95 \
     -m=mask_HadISST1_sst.nc \
     -n=nino34_sst \
     -o=HadISST1_1m_187001_200702_nino34sst.nc
   

2. For computing a monthly time series from the file F31_1m_000101_011012_sosstsst_grid_T.nc, which includes a NetCDF variable sosstsst (from the NEMO model), and store the results in a NetCDF variable nino34_sosstsst in the file F31_1m_000101_011012_nino34sst.nc, use the following command :

   $ comp_serie_3d \
     -f=F31_1m_000101_011012_sosstsst_grid_T.nc \
     -v=sosstsst \
     -x=236,335 \
     -y=240,260 \
     -m=F31_mesh_mask.nc \
     -b=722,511  \
     -g=t  \
     -n=nino34_sosstsst \
     -o=F31_1m_000101_011012_nino34sst.nc