# unpack_masked_data_3d

## Authors

Eric Maisonnave (CERFACS) and Pascal Terray (LOCEAN/IPSL)

## Latest revision

30/04/2026

## Purpose

Unpack a packed tridimensional NetCDF variable produced by pack_masked_data_3d or derived from an NCSTAT analysis of such packed tridimensional NetCDF variable and store the results in an output NetCDF dataset.

## Further Details

### Usage

    $ unpack_masked_data_3d \
      -f=input_netcdf_file \
      -v=packed_netcdf_variable \
      -m=input_mesh_mask_netcdf_file \
      -o=output_netcdf_file \
      -t=time1,time2                    (optional) \
      -g=grid_type                      (optional : n, t, u, v, w, f) \
      -bigfile                          (optional) \
      -hdf5                             (optional) \
      -cdf5                             (optional) \
      -tlimited                         (optional)

### By default

> -t=
>   the whole time period associated with the packed_netcdf_variable
> -g=
>   the grid_type is set to `n` which means that the 2-D grid-mesh associated with the original (unpacked) NetCDF variable is assumed to be regular or Gaussian
> -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=packed_netcdf_variable argument specifies the NetCDF variable which must be unpacked and the -f=input_netcdf_file argument specifies that this NetCDF variable must be extracted from the NetCDF file input_netcdf_file.

> 2. The argument -m=input_mesh_mask_netcdf_file specifies that the land-sea mask to use for unpacking the packed_netcdf_variable must be read from the input_mesh_mask_netcdf_file.

>    This input_mesh_mask_netcdf_file may be created by comp_clim_3d if the 2-D grid-mesh is regular or gaussian and it must be the one used originally to pack the data with pack_masked_data_3d.

> 3. If the -t=time1,time2 argument is missing the whole time period associated with the packed_netcdf_variable is used to construct the output NetCDF variable.

>    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. If -g= is set to `t`, `u`, `v`, `w` or `f` it is assumed that the original NetCDF variable is from an experiment with the ORCA or NEMO model.

>    If -g= is set to `n`, it is assumed that the 2-D grid-mesh is regular or Gaussian.

>    The -g= argument is also used to determine the name of the NetCDF variable which contains the 2-D mesh-mask in the input_mesh_mask_netcdf_file (e.g., it is assumed that this variable is named grid_type `mask`).

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

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

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

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

### Examples

> 1. For unpacking a NetCDF variable `sosstsst` extracted from the NetCDF dataset `packed_ST7_1m_0101_20012_grid_T_sosstsst.nc` with the help of a land-sea mask extracted from the NetCDF file `mesh_ocean.nc` and store the results in a NetCDF file named `ST7_1m_0101_20012_grid_T_sosstsst.nc` use the following command (note that the variable `sosstsst` is from a NEMO simulation since -g=`t` is specified) :

>        $ unpack_masked_data_3d \
>          -f=ST7_1m_0101_20012_grid_T_sosstsst.nc \
>          -v=sosstsst \
>          -m=mesh_ocean.nc \
>          -o=ST7_1m_0101_20012_grid_T_sosstsst.nc \
>          -g=t