Last updated on Feb 20, 2026.

netsse.model.era5#

Retrieve and process sea state information from the ERA5 dataset.

Last updated on 20-02-2026 by R.E.G. Mounet

Attributes#

`ERA5_PARAMS`
`index_request`

Functions#

`retrieve_dirwavespec`([index_month, folder_output])	Retrieve directional wave spectrum data from the ERA5 dataset (Hersbach et al., 2020, 2023).
`retrieve_params`([index_request, folder_output])	Retrieve wave parameter data from the ERA5 dataset (Hersbach et al., 2020, 2023).

Module Contents#

netsse.model.era5.retrieve_dirwavespec(index_month=0, folder_output='../Output/')[source]#

Retrieve directional wave spectrum data from the ERA5 dataset (Hersbach et al., 2020, 2023).

The function retrieves data from the ERA5 dataset for a specific period of time and geographical area. The latter must be specified in a dedicated ‘ERA5_request.csv’ file at the location path given in folder_output informing the spatial and temporal coverage of the data to be retrieved. The content of the file must follow the example below (including the header line!):

,Year,Month,Day_start,Day_end,NrDays,Longitude_min,Longitude_max,Latitude_min,Latitude_max
0,2007,9,12,25,30,-55.0,-5.0,46.0,50.0
1,2007,10,12,26,31,-55.0,-5.0,45.0,50.0

There can be as many lines as needed in the ERA5 request file, each line corresponding to a single retrieval request of data located all within the same month. The function retrieves the directional wave spectrum data for the request line having the index index_month in the file. The default value for index_month is 0, which means to submit the first request in the request file.

The data is retrieved for the month and year specified in the ‘Month’ and ‘Year’ columns of the request file; e.g., September 2007 in the first request contained in the above example). The retrieval period covers from the start day at 00:00 to the end day at 23:00; e.g., from 12 September 2007 at 00:00 to 25 September 2007 at 23:00 in the first request contained in the above example.

Longitudes are specified in degrees East and latitudes in degrees North. The data is retrieved for the geographical area defined by the minimum and maximum longitudes and latitudes; e.g., from 46.0 to 50.0 degrees North and from -55.0 to -5.0 degrees East in the first request contained in the above example. The spatial resolution is fixed to 0.5 degrees in both latitude and longitude.

The data is retrieved using the Copernicus Climate Data Store (CDS) API. The user must have a valid CDS API key to access the data. The downloaded data is stored in a NetCDF file at the location path specified in the variable folder_output. The default value for folder_output is '../Output/'.

References

Hersbach, H., Bell, B., Berrisford, P., Hirahara, S., Horányi, A., Muñoz-Sabater, J., Nicolas, J., Peubey, C., Radu, R., Schepers, D., Simmons, A., Soci, C., Abdalla, S., Abellan, X., Balsamo, G., Bechtold, P., Biavati, G., Bidlot, J., Bonavita, M., De Chiara, G., Dahlgren, P., Dee, D., Diamantakis, M., Dragani, R., Flemming, J., Forbes, R., Fuentes, M., Geer, A., Haimberger, L., Healy, S., Hogan, R. J., Hólm, E., Janisková, M., Keeley, S., Laloyaux, P., Lopez, P., Lupu, C., Radnoti, G., de Rosnay, P., Rozum, I., Vamborg, F., Villaume, S., and Thépaut, J. N. The ERA5 global reanalysis. Quarterly Journal of the Royal Meteorological Society 146, 730 (2020), 1999–2049, DOI: 10.1002/qj.3803.
Hersbach, H., Bell, B., Berrisford, P., Biavati, G., Horányi, A., Muñoz Sabater, J., Nicolas, J., Peubey, C., Radu, R., Rozum, I., Schepers, D., Simmons, A., Soci, C., Dee, D., Thépaut, J-N. (2023): ERA5 hourly data on single levels from 1940 to present. Copernicus Climate Change Service (C3S) Climate Data Store (CDS), DOI: 10.24381/cds.adbb2d47 (Accessed on 26-02-2025).

See also

retrieve_params: Function to retrieve wave parameter data from the ERA5 dataset.

Example

To retrieve the directional wave spectrum data for the month with index 1 in the file ‘ERA5_request.csv’ stored in the folder ‘../Output/’, run:

>>> retrieve_dirwavespec(index_month=1,folder_output='../Output/')
>>> # Output:
>>> # Retrieving ERA5 data for the month with index 1...
>>> # Selected dates: 2007-10-12/to/2007-10-26
>>> # Selected area: 50.0/-55.0/45.0/-5.0
>>> # The downloaded file is stored at '../Output/ERA5_2D_spectra_2007-10.nc'.

netsse.model.era5.retrieve_params(index_request=0, folder_output='../Output/')[source]#

Retrieve wave parameter data from the ERA5 dataset (Hersbach et al., 2020, 2023).

The function retrieves data from the ERA5 dataset for a specific period of time and geographical area. The latter must be specified in a dedicated ‘ERA5_request_params.csv’ file at the location path given in folder_output informing the spatial and temporal coverage of the data to be retrieved. The content of the file must follow the example below (including the header line!):

,Year,Month_start,Month_end,Longitude_min,Longitude_max,Latitude_min,Latitude_max,Var1,Var2,Var3,Var4,Var5,Var6,Var7,Var8
0,2020,1,3,0.5,5.5,55.0,58.5,swh,mp1,p1ps,p1ww,pp1d,shts,shww,wmb
1,2020,4,6,0.5,5.5,55.0,58.5,swh,mp1,p1ps,p1ww,pp1d,shts,shww,wmb

There can be as many lines as needed in the ERA5 request file, each line corresponding to a single retrieval request of data located all within the same year. The function retrieves the parameter data for the request line having the index index_request in the file. The default value for index_request is 0, which means to submit the first request in the request file.

The data is retrieved for the year specified in the ‘Year’ column of the request file. It is possible to specify which months should be downloaded using the ‘Month_start’ and ‘Month_end’ columns; e.g., January-March 2020 in the first request contained in the above example). The retrieval period covers from the first day of the start month at 00:00 to the last day of the end month at 23:00; e.g., from 1 January 2020 at 00:00 to 31 March 2020 at 23:00 in the first request contained in the above example.

Longitudes are specified in degrees East and latitudes in degrees North. The data is retrieved for the geographical area defined by the minimum and maximum longitudes and latitudes; e.g., from 55.0 to 58.5 degrees North and from 0.5 to 5.5 degrees East in the first request contained in the above example. The spatial resolution is fixed to 0.5 degrees in both latitude and longitude.

The parameters to be retrieved are specified in the columns ‘VarX’ of the request file. The available wave parameters are listed in Table 7 of the ERA5 documentation. The short names of the parameters can be used in the request file; e.g., ‘swh’ for significant height of combined wind waves and swell, ‘mp1’ for mean wave period based on first moment, etc. The number of parameters that can be downloaded at once is unlimited, and as many columns named ‘VarX can be added as needed in the request file. In the above example, both requests retrieve 8 parameters.

Warning

For the request to be validated by the Copernicus Climate Data Store (CDS) API, the request size should not exceed a certain limit set by the CDS. If the request is too large, it is recommended to split it into smaller requests by reducing the number of months and/or the geographical area covered in each request. The present function will check the request size and compare it to a conservative reference set by the NetSSE developers. If the request exceeds this reference limit, the function will display a warning message and advise the user to modify the request parameters accordingly.