Skip to content

heiplanet_data.inout module⚓︎

heiplanet_data.inout ⚓︎

Functions:

download_data ⚓︎

download_data(output_file, dataset, request, overwrite=False)

Download data from Copernicus's CDS using the cdsapi.

Parameters:

  • output_file (Path) –

    The path to the output file where data will be saved.

  • dataset (str) –

    The name of the dataset to download.

  • request (Dict[str, Any]) –

    A dictionary containing the request parameters.

  • overwrite (bool, default: False ) –

    Whether to overwrite the output file if it already exists. Default is False.

download_isimip_data ⚓︎

download_isimip_data(output_file, file_url, overwrite=False)

Download a data file from ISIMIP using the isimip-client.

Mirrors download_data for CDS downloads: use find_isimip_file first to look up file_url (and the file name to build output_file from).

Parameters:

  • output_file (Path) –

    The path to the output file where data will be saved.

  • file_url (str) –

    The download URL of the ISIMIP file, as returned by find_isimip_file.

  • overwrite (bool, default: False ) –

    Whether to overwrite the output file if it already exists. Default is False.

download_total_precipitation_from_hourly_era5_land ⚓︎

download_total_precipitation_from_hourly_era5_land(start_date, end_date, area=None, out_dir=Path('.'), base_name='era5_land_data', data_format='netcdf', ds_name='reanalysis-era5-land', coord_name='valid_time', var_name='total_precipitation', clean_tmp_files=False)

Download total precipitation data from hourly ERA5-Land dataset. Due to the nature of this dataset, value at 00:00 is total precipitation of the previous day. Therefore, to get total precipitation for the given range, We need to download data for the given range shifted by 1 day forward, then shift the time value back by 1 day after downloading.

Parameters:

  • start_date (str) –

    Start date in "YYYY-MM-DD" format.

  • end_date (str) –

    End date in "YYYY-MM-DD" format.

  • area (List[float] | None, default: None ) –

    Geographical area [North, West, South, East]. Default is None (global).

  • out_dir (Path, default: Path('.') ) –

    Output directory to save the downloaded file. Default is current directory.

  • base_name (str, default: 'era5_land_data' ) –

    Base name for the file. Default is "era5_land_data".

  • data_format (str, default: 'netcdf' ) –

    Data format (e.g., "netcdf", "grib"). Default is "netcdf".

  • ds_name (str, default: 'reanalysis-era5-land' ) –

    Dataset name. Default is "reanalysis-era5-land". Only modify this if CDS changes the name of the dataset.

  • coord_name (str, default: 'valid_time' ) –

    Name of the time coordinate in the dataset. Default is "valid_time". Only modify this if CDS changes the name of the coordinate.

  • var_name (str | list(str), default: 'total_precipitation' ) –

    Name of the data variable. Default is "total_precipitation".

  • clean_tmp_files (bool, default: False ) –

    Flag to indicate if temporary files should be deleted after processing. Default is False.

Returns:

  • str ( str ) –

    The path to the downloaded file.

find_isimip_file ⚓︎

find_isimip_file(search_path, file_match)

Look up a file in the ISIMIP dataset repository.

Searches under search_path (the same path shown on the ISIMIP website, e.g. "ISIMIP3a/InputData/socioeconomic/pop/histsoc/population") and returns the name and download URL of the first file whose name contains file_match. Counterpart to suggest_filename for CDS downloads: it only looks up metadata, it does not download anything.

Parameters:

  • search_path (str) –

    ISIMIP dataset path to search under.

  • file_match (str) –

    Substring the target file name must contain (e.g. "population_histsoc_30arcmin_annual_1901_2021").

Returns:

  • tuple[str, str] –

    Tuple[str, str]: The file name and its download URL.

Raises:

  • ValueError –

    If search_path or file_match is not a non-empty string.

  • FileNotFoundError –

    If no matching file is found on ISIMIP.

save_to_netcdf ⚓︎

save_to_netcdf(data, filename, encoding=None)

Save data to a NetCDF file.

Parameters:

  • data (DataArray) –

    Data to be saved.

  • filename (str) –

    The name of the output NetCDF file.

  • encoding (Dict, default: None ) –

    Encoding options for the NetCDF file.

suggest_filename ⚓︎

suggest_filename(ds_name, data_format, years, months, days=None, times=None, has_area=False, base_name='era5_land_data', variables=None)

Suggest a filename that contains key metadata about the dataset. The format is: {base_name}{year_str}{day_str} {var_str}}_{area_str}_raw.{ext

Parameters:

  • ds_name (str) –

    Dataset name.

  • data_format (str) –

    Data format (e.g., "netcdf", "grib").

  • years (List[str] | None) –

    List of years.

  • months (List[str] | None) –

    List of months.

  • days (List[str] | None, default: None ) –

    List of days.

  • times (List[str] | None, default: None ) –

    List of times.

  • has_area (bool, default: False ) –

    Flag indicating if area is included.

  • base_name (str, default: 'era5_land_data' ) –

    Base name for the file. Default is "era5_land_data".

  • variables (List[str], default: None ) –

    List of variables. Default is ["2m_temperature"].

Returns:

  • str ( str ) –

    Generated file name.