# comp_serie_miss_3d

## Authors

Pascal Terray (LOCEAN/IPSL)

## Latest revision

30/04/2026

## Purpose

Compute a time series from a tridimensional variable with missing values 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 your data does not contain missing values, use comp_serie_3d instead of comp_serie_miss_3d to compute the time series 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 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_miss_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) \
      -mi=missing_value                 (optional) \
      -3d                               (optional) \
      -double                           (optional) \
      -hdf5                             (optional) \
      -cdf5                             (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 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
> -mi=
>   the missing_value attribute for the output_netcdf_variable is set to `1.e+20`
> -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 by default, the results are stored as single-precision floating point numbers in the output NetCDF 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 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 compute 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_miss_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 missing values in addition to those associated with a constant land-sea mask. If your dataset has no missing values, use comp_serie_3d instead of comp_serie_miss_3d.

> 5. It is assumed that the specified input 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.

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

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

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

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

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

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

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

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

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

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

> 16. The -mi=missing_value argument specifies the missing value indicator associated with the netcdf_variable (specified by the -n= argument) in the output_netcdf_file. missing_value must be a real number outside of the range of the netcdf_variable.

>     If the -mi= argument is not specified missing_value is set to `1.e+20`.

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

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

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

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

> 21. 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_miss_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 `HadISST2_1m_187001_200702_sst_reg1m.nc`, which includes a NetCDF variable `sst` with missing values, and store the results in a NetCDF variable named `nino34_sst` in the file `HadISST2_1m_187001_200702_nino34sst.nc`, use the following command :

>        $ comp_serie_miss_3d \
>          -f=HadISST2_1m_187001_200702_sst_reg1m.nc \
>          -v=sst \
>          -x=11,60 \
>          -y=86,95 \
>          -m=mask_HadISST2_sst.nc \
>          -n=nino34_sst \
>          -o=HadISST2_1m_187001_200702_nino34sst.nc

> 2. For computing a monthly global time series from the file `hadcrut2v.nc`, which includes a NetCDF variable `temanom` with missing values, and store the results in a NetCDF variable named `glob_temp` in the file `hadcrut2v_1m_glob_tempanom.nc`, use the following command :

>        $ comp_serie_miss_3d \
>          -f=hadcrut2v.nc \
>          -v=temanom \
>          -m=mesh_mask_hadcrut2v.nc \
>          -g=n \
>          -a=scp \
>          -n=glob_temp \
>          -o=hadcrut2v_1m_glob_tempanom.nc