netsse.model.era5 ================= .. py:module:: netsse.model.era5 .. autoapi-nested-parse:: Retrieve and process sea state information from the **ERA5 dataset**. .. dropdown:: Copyright (C) 2023-2026 Technical University of Denmark, R.E.G. Mounet :color: primary :icon: law *This code is part of the NetSSE software.* NetSSE is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. NetSSE is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/. To credit the author, users are encouraged to use below reference: .. code-block:: text Mounet, R. E. G., & Nielsen, U. D. NetSSE: An open-source Python package for network-based sea state estimation from ships, buoys, and other observation platforms (version 2.2). Technical University of Denmark, GitLab. February 2026. https://doi.org/10.11583/DTU.26379811. *Last updated on 20-02-2026 by R.E.G. Mounet* Attributes ---------- .. autoapisummary:: netsse.model.era5.ERA5_PARAMS netsse.model.era5.index_request Functions --------- .. autoapisummary:: netsse.model.era5.retrieve_dirwavespec netsse.model.era5.retrieve_params Module Contents --------------- .. py:function:: retrieve_dirwavespec(index_month=0, folder_output='../Output/') 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!): .. code-block:: text ,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/'``. .. rubric:: References 1. 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. 2. 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). .. seealso:: :py:obj:`retrieve_params` Function to retrieve wave parameter data from the ERA5 dataset. .. rubric:: 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'. .. py:function:: retrieve_params(index_request=0, folder_output='../Output/') 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!): .. code-block:: text ,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. 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/'``. .. rubric:: References 1. 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. 2. 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). .. seealso:: :py:obj:`retrieve_dirwavespec` Function to retrieve directional wave spectrum data from the ERA5 dataset. .. rubric:: Example To retrieve the wave parameter data for the month with index 1 in the file `'ERA5_request_params.csv'` stored in the folder `'../Output/'`, run: >>> retrieve_wave_params(index_request=1,folder_output='../Output/') >>> # Output: >>> # Retrieving ERA5 data for the request with index 1... >>> # Selected dates: 2020-01-01/to/2020-03-31 >>> # Selected area: 58.5/0.5/55.0/5.5 >>> # The downloaded file is stored at '../Output/ERA5_params_2020-01to03.zip'. .. py:data:: ERA5_PARAMS .. py:data:: index_request