shrecc.download

Functions

cleaning_data(data, data_dir)

Cleans the data and adds missing countries. Note that missing countries need to be manually added to country_codes.

get_data(year[, path_to_data, max_retries, retry_delay])

Main function for downloading data.

get_package_user_data_dir([package_name])

Get the user data dir through appdirs.

get_prod(start, end, country[, cumul, rolling])

Downloads production data from the Energy Charts API. Gets called from get_data().

get_trade(start, end, country)

Downloads trade data from the Energy Charts API. Gets called from get_data().

year_to_unix(year)

Converts a year to Unix timestamps representing the start and end of the year in UTC.

Module Contents

shrecc.download.cleaning_data(data, data_dir)[source]

Cleans the data and adds missing countries. Note that missing countries need to be manually added to country_codes. Gets called from get_data().

Parameters:

  • data (pd.DataFrame) – The dataframe containing production and trade data.

  • root (Path) – location of the data.

Returns:

A dataframe with missing countries added.

Return type:

pd.DataFrame

shrecc.download.get_data(year, path_to_data=None, max_retries=3, retry_delay=5)[source]

Main function for downloading data.

Parameters:

  • year (int) – The selected year for which data is to be downloaded, e.g., 2023.

  • path_to_data (str or Path) – location of the data.

  • max_retries (int) – The maximum number of retries for each country download in case of problems.

  • retry_delay (int) – The delay in seconds between retries.

Returns:

A dataframe containing both production and trade data for all countries in the selected year.

Return type:

pd.DataFrame

shrecc.download.get_package_user_data_dir(package_name='shrecc')[source]

Get the user data dir through appdirs. If it doesn’t exist, it will create it.

Parameters:

package_name (str) – the name of the package

Returns

Path : the existing or newly created directory.

shrecc.download.get_prod(start, end, country, cumul=False, rolling=False)[source]

Downloads production data from the Energy Charts API. Gets called from get_data().

Parameters:

  • start (int) – Start of the download period (output of year_to_unix()) in unix seconds.

  • end (int) – End of the download period (output of year_to_unix()) in unix seconds.

  • country (list of str) – The country for which data needs to be downloaded.

  • cumul (bool) – If True, calculate the cumulative sum of production.

  • rolling (bool) – If True, calculate the rolling average of production.

Returns:

A tuple containing:

  • A dataframe of production.

  • A dataframe of load.

  • An array of all available technologies.

Return type:

Tuple[pd.DataFrame, pd.DataFrame, np.ndarray]

shrecc.download.get_trade(start, end, country)[source]

Downloads trade data from the Energy Charts API. Gets called from get_data(). Uses the “cbpf” endpoint of the API.

Parameters:

  • start (int) – Start of the download period (output of year_to_unix()) in unix seconds.

  • end (int) – End of the download period (output of year_to_unix()) in unix seconds.

  • country (list of str) – The country for which data needs to be downloaded.

Returns:

A tuple containing:

  • A dataframe of trades between countries.

  • An array of all available regions.

Return type:

Tuple[pd.DataFrame, np.ndarray]

shrecc.download.year_to_unix(year)[source]

Converts a year to Unix timestamps representing the start and end of the year in UTC.

Parameters:

year (int) – The selected year, passed from get_data().

Returns:

A tuple containing:

  • The start of the year in Unix seconds (UTC).

  • The end of the year in Unix seconds (UTC).

Return type:

Tuple[int, int]