comp_season_3d

Authors

Pascal Terray (LOCEAN/IPSL)

Latest revision

28/05/2024

Purpose

Compute time (i.e., seasonal, daily, …) averages from a tridimensional variable extracted from a NetCDF dataset and write the results in an output NetCDF dataset.

The time averages are computed for each point in the time series of the 2-D grid-mesh associated with the input NetCDF variable and the time series are assumed to be strictly periodic with a periodicity given by the -p= argument (this means, in particular, that comp_season_3d cannot be used to compute monthly time series from observed daily data). Note that the date information associated with each time average in the output NetCDF dataset is the date of the first contributing input observation in each time average (if this date information is available in the input NetCDF dataset).

If your data contains missing values (excepted those associated with a constant land-sea mask) use comp_season_miss_3d instead of comp_season_3d to estimate time averages from your gappy dataset.

Finally, if the NetCDF variable is fourdimensional use comp_season_4d instead of comp_season_3d.

Further Details

Usage

$ comp_season_3d \
  -f=input_netcdf_file \
  -v=netcdf_variable \
  -p=periodicity_of_data \
  -s=length_of_season \
  -o=output_seasonal_netcdf_file \
  -x=lon1,lon2                      (optional) \
  -y=lat1,lat2                      (optional) \
  -t=time1,time2                    (optional) \
  -m=input_mesh_mask_netcdf_file    (optional) \
  -g=grid_type                      (optional : n, t, u, v, w, f) \
  -compact                          (optional) \
  -bigfile                          (optional) \
  -hdf5                             (optional) \
  -tlimited                         (optional)

By default

-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

-m=

an input_mesh_mask_netcdf_file is not used. In this case, it is assumed that the netcdf_variable does not have any missing values

-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

-compact

the output NetCDF dataset 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 which must be averaged and the -f=input_netcdf_file argument specifies that this NetCDF variable must be extracted from the NetCDF file, input_netcdf_file.

2. The -p=periodicity_of_data argument gives the periodicity of the input data for the netcdf_variable. For example, with monthly data -p=12 should be specified.

3. The -s=length_of_season argument gives the length of the season or the time interval for averaging the input data (i.e., the number of time observations used to compute the time averages in the output NetCDF file). The specified number for the -s= argument should be an exact divisor of the number specified in the -p= argument. For example, to construct a seasonal (averages of four months) dataset from a monthly dataset, -p=12 and -s=4 should be specified.

4. 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 output NetCDF file.

   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 not allowed for lon1.

   Refer to comp_mask_3d for transforming geographical coordinates as indices or generating an appropriate mesh-mask before using comp_season_3d.

5. If the -t=time1,time2 argument is missing the whole time period associated with the netcdf_variable is used to construct the output NetCDF file. The selected time period is not necessarily a multiple of the number of observations used to compute the time averages (e.g., the -s= argument). If this is not the case, the last time average is computed with less observations (i.e., less observations than the number specified in the -s= argument).

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

   The -g= argument is used only if a mesh-mask NetCDF dataset is specified with the -m= argument. This argument is also used to determine the name of the NetCDF mesh_mask variable if an input_mesh_mask_netcdf_file is used as specified with the -m= argument.

7. The geographical shapes of the netcdf_variable (in the input_netcdf_file) and the mask (in the input_mesh_mask_netcdf_file) must agree if the -m= argument is used.

8. It is assumed that the data have no missing values, excepted those associated with a constant land-sea mask (if a mesh-mask NetCDF file is used). If it is the case, use comp_season_miss_3d instead of comp_season_3d.

9. If the -compact argument is specified and a domain is selected (with the -x= and -y= arguments) then only the data for the selected domain will be written in the output NetCDF file.

   By default, the whole grid is stored (with missing values outside the selected domain) in the output NetCDF file.

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

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

12. 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_season_3d creates an output NetCDF file that contains time averages computed from the time series associated with the input NetCDF variable and the coordinate NetCDF variables of the input NetCDF dataset input_netcdf_file . This NetCDF variable will have the same dimensions and name 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 nseason time observations (corresponding to the number of time averages which have been computed from the input time series) :

1. netcdf_variable (nseason,nlat,nlon) : the computed time averages for each point in the time series of the 2-D grid-mesh 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+1 and nlon=lon2-lon1+1 ).

The number of time steps written in the output NetCDF file (e.g., ntime) is determined from the -t=, -s= and -p= arguments.

Examples

1. For computing seasonal averages (i.e., time averages of 4 months) from a monthly tridimensional NetCDF variable sosstsst in the NetCDF file ST7_1m_00101_20012_grid_T_sosstsst.nc and store the results in a NetCDF file named ST7_4m_00101_20012_grid_T_sosstsst.nc use the following command (note that cyclostationarity is assumed for the sosstsst variable since -p=12 is specified) :

   $ comp_season_3d \
     -f=ST7_1m_0101_20012_grid_T_sosstsst.nc \
     -v=sosstsst \
     -p=12 \
     -s=4 \
     -m=mask_orca2.nc \
     -o=sST7_4m_0101_20012_grid_T_sosstsst.nc