# comp_season_miss_4d

## Authors

Pascal Terray (LOCEAN/IPSL)

## Latest revision

30/04/2026

## Purpose

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

It is assumed that the input NetCDF variable has a scalar missing_value or _FillValue attribute, which allows a proper identification of the missing values in the dataset, otherwise the procedure will exit with an error message.

The time averages are computed for each point in the time series of the 3-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_miss_4d 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 does not contain missing values (in addition to those associated with a constant land-sea mask) use comp_season_4d instead of comp_season_miss_4d to estimate time averages from your dataset.

Finally, if the NetCDF variable is tridimensional use comp_season_miss_3d instead of comp_season_miss_4d.

## Further Details

### Usage

    $ comp_season_miss_4d \
      -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) \
      -z=level1,level2                  (optional) \
      -t=time1,time2                    (optional) \
      -m=input_mesh_mask_netcdf_file    (optional) \
      -g=grid_type                      (optional : n, t, u, v, w, f) \
      -ns=nobs_limit_by_season          (optional) \
      -compact                          (optional) \
      -bigfile                          (optional) \
      -hdf5                             (optional) \
      -cdf5                             (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
> -z=
>   the whole vertical resolution 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
> -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
> -ns=
>   the nobs_limit_by_season is set to `1`, which means that a time average is set to missing only if all time observations averaged are missing
> -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
> -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 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 argument gives the periodicity of the input data for the netcdf_variable. For example, with monthly data -p=`12` should be specified.

>    The -p=periodicity_of_data argument is a strictly positive integer.

> 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, -y=lat1,lat2 and -z=level1,level2 arguments are missing the whole geographical domain and vertical resolution associated with the netcdf_variable is used.

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

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

> 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 missing values in addition to those associated with a constant land-sea mask. If it is not the case, use comp_season_4d instead of comp_season_miss_4d.

>    It is further 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_value or _FillValue attribute.

> 9. The -ns=nobs_limit_by_season argument specifies a limit for computing a seasonal mean or time average. nobs_limit_by_season is a positive integer less than or equal to the length of the season as specified by the -s= argument. If the number of observations by season or for a time inerval is less than nobs_limit_by_season, the corresponding seasonal mean or time average is set to missing in the output NetCDF file. The default value for nobs_limit_by_season is `1`, which means that a time average is set to missing only if all time observations averaged are missing.

> 10. If the -compact argument is specified and a domain is selected (with the -x=, -y= and -z= arguments) then only data for the selected domain will be output. By default, the whole 3-D grid is stored (with missing values outside the selected domain) in the output NetCDF file.

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

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

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

> 14. 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_miss_4d 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, nlev, nlat and nlon are the lengths of the geographical 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,nlev,nlat,nlon)` : the computed time averages for each point in the time series of the 3-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=, -y= and -z= arguments (e.g., in this case `nlev`=level2-level1+`1`, `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 fourdimensional NetCDF variable `votemper` in the NetCDF file `ST7_1m_00101_20012_grid_T_votemper.nc` and store the results in a NetCDF file named `ST7_4m_00101_20012_grid_T_votemper.nc` use the following command (note that cyclostationarity is assumed for the `votemper` variable since -p=`12` is specified) :

>        $ comp_season_miss_4d \
>          -f=ST7_1m_0101_20012_grid_T_votemper.nc \
>          -v=votemper \
>          -p=12 \
>          -s=4 \
>          -m=mask_orca2.nc \
>          -o=sST7_4m_0101_20012_grid_T_votemper.nc