concatenator v3.2.3¶

Mercurial revision 5770:c90c3015e72d | 2026-05-22

Description¶

concatenator is a tool designed to concatenate model grid and output files in NetCDF format. It ensures that:

The output file does not already exist.
All input files are readable.

If fewer than 2 arguments are provided, the help message is displayed.

Usage¶

concatenator [OPTION] input1.nc [input2.nc ...] -o OUTPUT

Options¶

Option	Description
`-a <name>`	Specify the time dimension name to use for concatenation. Default: automatically detected. See also `-t`.
`-v <var1,var2,...>`	Comma-separated list of variables to concatenate. Default: all variables.
`-t <var1,var2,...>`	Comma-separated list of variables to which a time dimension should be added. Only needed when all files contain a single time step and the time reference is in their name.
`-o <file>`	Specify the output file path.
`-f`	Force overwrite if the output file already exists.
`-deflate <level>`	Set the compression level (0-9) for the output NetCDF file.

Examples¶

Basic Concatenation¶

Concatenate two NetCDF files into output.nc:

concatenator input1.nc input2.nc -o output.nc

Concatenate Specific Variables¶

Concatenate only temperature and salinity variables:

concatenator -v temperature,salinity input1.nc input2.nc -o output.nc

Specify Time Dimension¶

Concatenate files with a custom time dimension name time_counter:

concatenator -a time_counter input1.nc input2.nc -o output.nc

Add Time Dimension to Variables¶

Add a time dimension to variables ssh and temp (useful when files contain single time steps):

concatenator -t ssh,temp input1.nc input2.nc -o output.nc

Force Overwrite Output¶

Overwrite the output file if it already exists:

concatenator -f input1.nc input2.nc -o output.nc

Compress Output¶

Concatenate files with compression level 5:

concatenator -deflate 5 input1.nc input2.nc -o output.nc

Combined Options¶

Concatenate specific variables with a custom time dimension and compression:

concatenator -v ssh,temp -a time_counter -deflate 4 input1.nc input2.nc -o output.nc

Environment Variables¶

This tool does not rely on specific environment variables. However, it uses the NetCDF library, which may be influenced by:

HDF5_PLUGIN_PATH (for HDF5 plugin paths).
NC_DEBUG (for NetCDF debugging).

Notes¶

Input Files:

Must be valid NetCDF files.
The tool will exit if any input file is unreadable.

Output File:

The tool will exit if the output file already exists (unless -f is used).
The output file is created in NetCDF4 format with the specified compression level (-deflate).

Time Dimension:

If -a is not specified, the tool attempts to auto-detect the time dimension.
If -t is used, a time dimension is added to the specified variables. This is useful when input files contain single time steps and the time reference is embedded in the filename.

Variable Handling:

By default, all variables are concatenated.
Use -v to restrict concatenation to specific variables.

Performance:

For large datasets, consider using -deflate to reduce file size.