bluemath_tk.downloaders.copernicus package

Submodules

bluemath_tk.downloaders.copernicus.copernicus_downloader module

class bluemath_tk.downloaders.copernicus.copernicus_downloader.CopernicusDownloader(product: str, base_path_to_download: str, api_key: str, debug: bool = True)[source]

Bases: BaseDownloader

Simple downloader for Copernicus Climate Data Store.

Examples

>>> downloader = CopernicusDownloader(
...     product="ERA5",
...     base_path_to_download="./copernicus_data",
...     token="your_token"
... )
>>> result = downloader.download_data(
...     variables=["swh"],
...     years=["2020"],
...     months=["01"],
...     force=False,
...     dry_run=False
... )
property client: Client

CDS API client (initialized with API key).

Returns:

CDS API client instance.

Return type:

cdsapi.Client

download_data(dry_run: bool = True, *args, **kwargs) → DownloadResult[source]

Download data for the product.

Routes to product-specific download methods based on the product type.

Parameters:

  • dry_run (bool, optional) – If True, only check what would be downloaded without actually downloading. Default is True.

  • *args – Arguments passed to product-specific download method.

  • **kwargs – Keyword arguments passed to product-specific download method.

Returns:

Result with information about downloaded, skipped, and error files.

Return type:

DownloadResult

Raises:

ValueError – If the product is not supported.

download_data_cerra(variables: List[str], years: List[str], months: List[str], days: List[str] = None, times: List[str] = None, area: List[float] = None, level_type: str = 'surface_or_atmosphere', data_type: List[str] = None, product_type: str = 'analysis', data_format: str = 'netcdf', force: bool = False, dry_run: bool = True) → DownloadResult[source]

Download CERRA data.

Downloads CERRA reanalysis data for specified variables, time periods, and optionally a geographic area. Files are saved to: base_path_to_download/product/dataset/type/product_type/variable/filename.nc

Parameters:

  • variables (List[str]) – List of variable names to download. If empty, downloads all available variables.

  • years (List[str]) – List of years to download (e.g., [“2020”, “2021”]).

  • months (List[str]) – List of months to download (e.g., [“01”, “02”]).

  • days (List[str], optional) – List of days to download. If None, downloads all days (1-31). Default is None.

  • times (List[str], optional) – List of times to download (e.g., [“00:00”, “12:00”]). If None, downloads standard times (00:00, 03:00, 06:00, 09:00, 12:00, 15:00, 18:00, 21:00). Default is None.

  • area (List[float], optional) – Geographic area as [north, west, south, east]. If None, downloads global data. Default is None.

  • level_type (str, optional) – Level type (e.g., “surface_or_atmosphere”). Default is “surface_or_atmosphere”.

  • data_type (List[str], optional) – Data type (e.g., [“reanalysis”]). If None, uses [“reanalysis”]. Default is None.

  • product_type (str, optional) – Product type (e.g., “analysis”, “forecast”). Default is “analysis”.

  • data_format (str, optional) – Data format. Default is “netcdf”.

  • force (bool, optional) – Force re-download even if file exists. Default is False.

  • dry_run (bool, optional) – If True, only check what would be downloaded. Default is True.

Returns:

Result with all downloaded files and download statistics.

Return type:

DownloadResult

Raises:

ValueError – If years or months are empty lists.

download_data_era5(variables: List[str], years: List[str], months: List[str], days: List[str] = None, times: List[str] = None, area: List[float] = None, product_type: str = 'reanalysis', data_format: str = 'netcdf', download_format: str = 'unarchived', force: bool = False, dry_run: bool = True) → DownloadResult[source]

Download ERA5 data.

Downloads ERA5 reanalysis data for specified variables, time periods, and optionally a geographic area. Files are saved to: base_path_to_download/product/dataset/type/product_type/variable/filename.nc

Parameters:

  • variables (List[str]) – List of variable names to download. If empty, downloads all available variables.

  • years (List[str]) – List of years to download (e.g., [“2020”, “2021”]).

  • months (List[str]) – List of months to download (e.g., [“01”, “02”]).

  • days (List[str], optional) – List of days to download. If None, downloads all days (1-31). Default is None.

  • times (List[str], optional) – List of times to download (e.g., [“00:00”, “12:00”]). If None, downloads all hours. Default is None.

  • area (List[float], optional) – Geographic area as [north, west, south, east]. If None, downloads global data. Default is None.

  • product_type (str, optional) – Product type (e.g., “reanalysis”, “ensemble_mean”). Default is “reanalysis”.

  • data_format (str, optional) – Data format. Default is “netcdf”.

  • download_format (str, optional) – Download format. Default is “unarchived”.

  • force (bool, optional) – Force re-download even if file exists. Default is False.

  • dry_run (bool, optional) – If True, only check what would be downloaded. Default is True.

Returns:

Result with all downloaded files and download statistics.

Return type:

DownloadResult

Raises:

ValueError – If years or months are empty lists.

list_variables(type: str = None) → List[str][source]

List variables available for the product.

Parameters:

type (str, optional) – Filter by type (e.g., “ocean”). Default is None.

Returns:

List of variable names.

Return type:

List[str]

property product_config: dict

Product configuration dictionary loaded from config file.

Returns:

Product configuration dictionary.

Return type:

dict

products_configs = {'CERRA': {'datasets': {'reanalysis-cerra-single-levels': {'description': 'CERRA Sub-daily Regional Reanalysis Data for Europe on Single Levels', 'mandatory_fields': ['variable', 'level_type', 'data_type', 'product_type', 'year', 'month', 'data_format'], 'optional_fields': ['day', 'time', 'area'], 'template': {'data_format': 'netcdf', 'data_type': ['reanalysis'], 'day': ['02'], 'level_type': 'surface_or_atmosphere', 'month': ['02'], 'product_type': 'analysis', 'time': ['00:00'], 'variable': ['10m_wind_direction'], 'year': ['1985']}, 'types': ['surface_or_atmosphere'], 'url': 'https://cds.climate.copernicus.eu/datasets/reanalysis-cerra-single-levels?tab=overview'}}, 'url': 'https://cds.climate.copernicus.eu/api', 'variables': {'10m_wind_direction': {'cds_name': '10m_wind_direction', 'dataset': 'reanalysis-cerra-single-levels', 'long_name': '10m wind direction', 'nc_name': '10m_wind_direction', 'type': 'surface_or_atmosphere', 'units': 'degree'}, '10m_wind_speed': {'cds_name': '10m_wind_speed', 'dataset': 'reanalysis-cerra-single-levels', 'long_name': '10m wind speed', 'nc_name': '10m_wind_speed', 'type': 'surface_or_atmosphere', 'units': 'm s-1'}, '2m_relative_humidity': {'cds_name': '2m_relative_humidity', 'dataset': 'reanalysis-cerra-single-levels', 'long_name': '2m relative humidity', 'nc_name': '2m_relative_humidity', 'type': 'surface_or_atmosphere', 'units': '%'}, '2m_temperature': {'cds_name': '2m_temperature', 'dataset': 'reanalysis-cerra-single-levels', 'long_name': '2m temperature', 'nc_name': '2m_temperature', 'type': 'surface_or_atmosphere', 'units': 'K'}, 'mean_sea_level_pressure': {'cds_name': 'mean_sea_level_pressure', 'dataset': 'reanalysis-cerra-single-levels', 'long_name': 'Mean sea level pressure', 'nc_name': 'mean_sea_level_pressure', 'type': 'surface_or_atmosphere', 'units': 'Pa'}, 'surface_pressure': {'cds_name': 'surface_pressure', 'dataset': 'reanalysis-cerra-single-levels', 'long_name': 'Surface pressure', 'nc_name': 'surface_pressure', 'type': 'surface_or_atmosphere', 'units': 'Pa'}, 'total_cloud_cover': {'cds_name': 'total_cloud_cover', 'dataset': 'reanalysis-cerra-single-levels', 'long_name': 'Total cloud cover', 'nc_name': 'total_cloud_cover', 'type': 'surface_or_atmosphere', 'units': '%'}, 'total_precipitation': {'cds_name': 'total_precipitation', 'dataset': 'reanalysis-cerra-single-levels', 'long_name': 'Total precipitation', 'nc_name': 'total_precipitation', 'type': 'surface_or_atmosphere', 'units': 'kg m-2'}}}, 'ERA5': {'datasets': {'reanalysis-era5-complete': {'description': 'ERA5 Complete Dataset', 'mandatory_fields': ['class', 'date', 'direction', 'domain', 'expver', 'frequency', 'param', 'stream', 'time', 'type', 'area', 'format', 'grid'], 'optional_fields': [], 'template': {'class': 'ea', 'direction': '1/2/3/4/5/6/7/8/9/10/11/12/13/14/15/16/17/18/19/20/21/22/23/24', 'domain': 'g', 'expver': '1', 'format': 'netcdf', 'frequency': '1/2/3/4/5/6/7/8/9/10/11/12/13/14/15/16/17/18/19/20/21/22/23/24/25/26/27/28/29/30', 'grid': '0.5/0.5', 'param': '251.140', 'stream': 'wave', 'time': '00:00:00/01:00:00/02:00:00/03:00:00/04:00:00/05:00:00/06:00:00/07:00:00/08:00:00/09:00:00/10:00:00/11:00:00/12:00:00/13:00:00/14:00:00/15:00:00/16:00:00/17:00:00/18:00:00/19:00:00/20:00:00/21:00:00/22:00:00/23:00:00', 'type': 'an'}, 'types': ['ocean'], 'url': 'https://cds.climate.copernicus.eu/datasets/reanalysis-era5-complete?tab=overview'}, 'reanalysis-era5-pressure-levels': {'description': 'ERA5 Pressure Levels', 'mandatory_fields': ['product_type', 'variable', 'year', 'month', 'pressure_level', 'data_format', 'download_format'], 'optional_fields': ['day', 'time', 'area'], 'template': {'data_format': 'netcdf', 'day': ['01'], 'download_format': 'unarchived', 'month': ['01'], 'pressure_level': ['500'], 'product_type': ['reanalysis'], 'time': ['00:00'], 'variable': ['geopotential'], 'year': ['2019']}, 'types': ['pressure'], 'url': 'https://cds.climate.copernicus.eu/datasets/reanalysis-era5-pressure-levels?tab=overview'}, 'reanalysis-era5-single-levels': {'description': 'ERA5 Single Levels', 'mandatory_fields': ['product_type', 'variable', 'year', 'month', 'data_format', 'download_format'], 'optional_fields': ['day', 'time', 'area'], 'template': {'data_format': 'netcdf', 'day': ['01'], 'download_format': 'unarchived', 'month': ['01'], 'product_type': ['reanalysis'], 'time': ['00:00'], 'variable': ['significant_wave_height_of_first_swell_partition'], 'year': ['2019']}, 'types': ['atmosphere', 'ocean'], 'url': 'https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-single-levels?tab=form'}}, 'url': 'https://cds.climate.copernicus.eu/api', 'variables': {'dwww': {'cds_name': 'wave_spectral_directional_width_for_wind_waves', 'dataset': 'reanalysis-era5-single-levels', 'long_name': 'Wave spectral directional width for wind waves', 'nc_name': 'dwww', 'type': 'ocean', 'units': 'degrees'}, 'mdww': {'cds_name': 'mean_direction_of_wind_waves', 'dataset': 'reanalysis-era5-single-levels', 'long_name': 'Mean direction of wind waves', 'nc_name': 'mdww', 'type': 'ocean', 'units': 'degrees'}, 'mpww': {'cds_name': 'mean_period_of_wind_waves', 'dataset': 'reanalysis-era5-single-levels', 'long_name': 'Mean period of wind waves', 'nc_name': 'mpww', 'type': 'ocean', 'units': 's'}, 'mwd': {'cds_name': 'mean_wave_direction', 'dataset': 'reanalysis-era5-single-levels', 'long_name': 'Mean wave direction', 'nc_name': 'mwd', 'type': 'ocean', 'units': 'degrees'}, 'mwp': {'cds_name': 'mean_wave_period', 'dataset': 'reanalysis-era5-single-levels', 'long_name': 'Mean wave period', 'nc_name': 'mwp', 'type': 'ocean', 'units': 's'}, 'p140121': {'cds_name': 'significant_wave_height_of_first_swell_partition', 'dataset': 'reanalysis-era5-single-levels', 'long_name': 'Significant wave height of first swell partition', 'nc_name': 'p140121', 'type': 'ocean', 'units': 'm'}, 'p140122': {'cds_name': 'mean_wave_direction_of_first_swell_partition', 'dataset': 'reanalysis-era5-single-levels', 'long_name': 'Mean wave direction of first swell partition', 'nc_name': 'p140122', 'type': 'ocean', 'units': 'degrees'}, 'p140123': {'cds_name': 'mean_wave_period_of_first_swell_partition', 'dataset': 'reanalysis-era5-single-levels', 'long_name': 'Mean wave period of first swell partition', 'nc_name': 'p140123', 'type': 'ocean', 'units': 's'}, 'p140124': {'cds_name': 'significant_wave_height_of_second_swell_partition', 'dataset': 'reanalysis-era5-single-levels', 'long_name': 'Significant wave height of second swell partition', 'nc_name': 'p140124', 'type': 'ocean', 'units': 'm'}, 'p140125': {'cds_name': 'mean_wave_direction_of_second_swell_partition', 'dataset': 'reanalysis-era5-single-levels', 'long_name': 'Mean wave direction of second swell partition', 'nc_name': 'p140125', 'type': 'ocean', 'units': 'degrees'}, 'p140126': {'cds_name': 'mean_wave_period_of_second_swell_partition', 'dataset': 'reanalysis-era5-single-levels', 'long_name': 'Mean wave period of second swell partition', 'nc_name': 'p140126', 'type': 'ocean', 'units': 's'}, 'p140127': {'cds_name': 'significant_wave_height_of_third_swell_partition', 'dataset': 'reanalysis-era5-single-levels', 'long_name': 'Significant wave height of third swell partition', 'nc_name': 'p140127', 'type': 'ocean', 'units': 'm'}, 'p140128': {'cds_name': 'mean_wave_direction_of_third_swell_partition', 'dataset': 'reanalysis-era5-single-levels', 'long_name': 'Mean wave direction of third swell partition', 'nc_name': 'p140128', 'type': 'ocean', 'units': 'degrees'}, 'p140129': {'cds_name': 'mean_wave_period_of_third_swell_partition', 'dataset': 'reanalysis-era5-single-levels', 'long_name': 'Mean wave period of third swell partition', 'nc_name': 'p140129', 'type': 'ocean', 'units': 's'}, 'pp1d': {'cds_name': 'peak_wave_period', 'dataset': 'reanalysis-era5-single-levels', 'long_name': 'Peak wave period', 'nc_name': 'pp1d', 'type': 'ocean', 'units': 's'}, 'shww': {'cds_name': 'significant_height_of_wind_waves', 'dataset': 'reanalysis-era5-single-levels', 'long_name': 'Significant height of wind waves', 'nc_name': 'shww', 'type': 'ocean', 'units': 'm'}, 'spectra': {'cds_name': 'full_wave_spectra', 'dataset': 'reanalysis-era5-complete', 'long_name': 'Full wave spectra', 'nc_name': 'spectra', 'type': 'ocean', 'units': 'm^2/Hz·radian'}, 'swh': {'cds_name': 'significant_height_of_combined_wind_waves_and_swell', 'dataset': 'reanalysis-era5-single-levels', 'long_name': 'Significant height of combined wind waves and swell', 'nc_name': 'swh', 'type': 'ocean', 'units': 'm'}}}}

Module contents