# 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

```bash
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`:

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

### **Concatenate Specific Variables**

Concatenate only `temperature` and `salinity` variables:

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

### **Specify Time Dimension**

Concatenate files with a custom time dimension name `time_counter`:

```bash
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):

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

### **Force Overwrite Output**

Overwrite the output file if it already exists:

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

### **Compress Output**

Concatenate files with compression level `5`:

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

### **Combined Options**

Concatenate specific variables with a custom time dimension and compression:

```bash
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

1. **Input Files:**
  - Must be **valid NetCDF files**.
  - The tool will **exit** if any input file is unreadable.
2. **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`).
3. **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.
4. **Variable Handling:**
  - By default, **all variables** are concatenated.
  - Use `-v` to **restrict** concatenation to specific variables.
5. **Performance:**
  - For large datasets, consider using `-deflate` to **reduce file size**.

---

## See Also

- [NetCDF Documentation](https://www.unidata.ucar.edu/software/netcdf/)
- [NetCDF4 Format](https://www.unidata.ucar.edu/software/netcdf/netcdf-4/)
- [HDF5 Plugin Path](https://portal.hdfgroup.org/display/support)