---
jupytext:
  formats: md:myst
  text_representation:
    extension: .md
    format_name: myst
mystnb:
  execution_timeout: 360
---

(l3)=
# L3

The Level 3 altimeter dataset represents a simplified version of the L2P. 
Along-track measurements from different missions are merged together into single
daily multi-mission files and only key variables are kept. The L2P 
measurements lower than 3 (good quality) are discarded in the L3 which only 
contains the best quality measurements. This dataset is intended for users 
who only care about SWH values.

For altimeters, only the Ku band measurements are considered, when available 
(the only current exception being SARAL for which only Ka band is provided).

This section describes in detail the specific content of the {{cci_version}} L3 
dataset, configured as shown in the table {numref}`l3_content_summary`, which 
can be used to locate the appropriate detailed information in this document. 

```{table} Summary description of the contents of a CCI Sea State L3 data product
:name: l3_content_summary

| netCDF File Contents | Description                                                                                               |
|----------------------|-----------------------------------------------------------------------------------------------------------|
| **Coordinate variables**  | Information to permit locating data on non-orthogonal grids, as defined in {numref}`coordinate_variables` | 
| **Geophysical data record variables** | environmental variables for 1st band altimeter (usually Ku) as defined in {numref}`l3_variables_environmental` |
| **Traceability data record variables** | traceability variables to source measurements as defined in {numref}`l3_variables_traceability` |  
| **Global Attributes**  | A collection of required global attributes describing general characteristics of the file, as defined in section {numref}`global_attributes`  |
```

(l3_variables_environmental)=
## L3 geophysical data record format specification
The {numref}`table_l3_variables_environmental` provides an overview of the CCI 
Sea State L3 environmental data records together with a link to their detailed 
description.

```{table} Summary description of CCI Sea State L3 SWH environmental records
:name: table_l3_variables_environmental

| Variable Name          | Description           | Units  |
|-----------------------|------------------------|--------|
| [swh](__l2p_swh) | Significant wave height, as retrieved from the altimeter retracker, averaged over 1 Hz cells, without bias correction. | m |
| [swh_adjusted](__l2p_swh_adjusted) | Significant wave height, averaged over 1 Hz cells, with cross-mission bias correction. | m |
| [swh_denoised](__l2p_swh_denoised) | Significant wave height, averaged over 1 Hz cells, with cross-mission bias correction and denoising. | m |
| [swh_uncertainty](__l2p_swh_uncertainty) |  Uncertainty of the significant wave height averaged over 1 Hz cells.  | 1 | 
```

(l3_variables_traceability)=
## L3 traceability data record format specification
The {numref}`table_l3_variables_traceability` provides an overview of the 
variables that detail the source and context of each SWH measurement. 

```{table} Summary description of CCI Sea State L4 traceability records
:name: table_l3_variables_traceability

| Variable Name          | Description           | Units  |
|-----------------------|------------------------|--------|
| [satellite](__l3_satellite) | Mean of median significant wave height values | code |
| [cycle](__l3_cycle) | Maximum median significant wave height value  | int |
| [relative_pass](__l3_relative_pass) | RMS of median significant wave height values | int |
```

(__l3_satellite)=
### `satellite`

This variable provides the identifier of the satellite from which a SWH
measurement originates. The identifier is one of the following enumerate code:

| value | satellite mission |
| ----- |-------------------|
| 0 | Cryosat-2         |
| 1 | Jason-1           | 
| 2 | Jason-2           | 
| 3 | Jason-3           |
| 4 | Saral             |
| 5 | Sentinel-3 A      | 
| 6 | ENVISAT           |
| 7 | Topex-Poseidon    |
| 8 | ERS-1             |
| 9 | ERS-2             |
| 10 | Ssentinel-3 B     |
| 11 | Sentinel-6 A      |


```{table} CDL example description of **<span style="font-family:courier;">satellite</span>** variable
:name: l3_satellite

| **Storage type**  | **Name**  | **Unit** |
|-------------------|-----------|----------|
| float             | `satellite`     | code |
```

```{code-cell}
:tags: [remove-input]
:name: l3_satellite

!bash -c "ncdump -h ../samples/ESACCI-SEASTATE-L3-SWH-MULTI_1D-19950719-fv01.nc | grep $'[ , \t]satellite[(,:]'| sed 's/[[:space:]]//'"
```

(__l3_cycle)=
### `cycle`

The number of the satellite cycle a given SWH measurement originates from. Note 
that this information may not be available for all satellite missions.

```{table} CDL example description of **<span style="font-family:courier;">cycle</span>** variable
:name: l3_cycle

| **Storage type**  | **Name**  | **Unit** |
|-------------------|-----------|----------|
| float             | `cycle`     | int |
```

```{code-cell}
:tags: [remove-input]
:name: l3_cycle

!bash -c "ncdump -h ../samples/ESACCI-SEASTATE-L3-SWH-MULTI_1D-19950719-fv01.nc | grep $'[ , \t]cycle[(,:]'| sed 's/[[:space:]]//'"
```


(__l3_relative_pass)=
### `relative_pass`

The number of the satellite relative pass with a cycle a given SWH measurement 
originates from. Note that this information may not be available for all 
satellite missions.

```{table} CDL example description of **<span style="font-family:courier;">relative_pass</span>** variable
:name: l3_relative_pass

| **Storage type**  | **Name**  | **Unit** |
|-------------------|-----------|----------|
| float             | `relative_pass`     | int |
```

```{code-cell}
:tags: [remove-input]
:name: l3_relative_pass

!bash -c "ncdump -h ../samples/ESACCI-SEASTATE-L3-SWH-MULTI_1D-19950719-fv01.nc | grep $'[ , \t]relative_pass[(,:]'| sed 's/[[:space:]]//'"
```

(l3_variables_auxiliary)=
## L3 auxiliary data record format specification
The {numref}`table_l3_variables_auxiliary` provides an overview of the auxiliary
data record within a L3 file together with a link to their detailed description.

```{table} Summary description of CCI Sea State L3 ancillary data records
:name: table_l3_variables_auxiliary

| Variable Name          | Description           | Units  |
|-----------------------|------------------------|--------|
| [distance_to_coast](__l2p_distance_to_coast) | Distance to the nearest shoreline | m |
| [bathymetry](__l2p_bathymetry) | Water depth to sea floor | m |
```