shrecc.download
===============

.. py:module:: shrecc.download


Functions
---------

.. autoapisummary::

   shrecc.download.cleaning_data
   shrecc.download.get_data
   shrecc.download.get_package_user_data_dir
   shrecc.download.get_prod
   shrecc.download.get_trade
   shrecc.download.year_to_unix


Module Contents
---------------

.. py:function:: cleaning_data(data, data_dir)

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

   :param data: The dataframe containing production and trade data.
   :type data: pd.DataFrame
   :param root: location of the data.
   :type root: Path

   :returns: A dataframe with missing countries added.
   :rtype: pd.DataFrame


.. py:function:: get_data(year, path_to_data=None, max_retries=3, retry_delay=5)

   Main function for downloading data.

   :param year: The selected year for which data is to be downloaded, e.g., 2023.
   :type year: int
   :param path_to_data: location of the data.
   :type path_to_data: str or Path
   :param max_retries: The maximum number of retries for each country download in case of problems.
   :type max_retries: int
   :param retry_delay: The delay in seconds between retries.
   :type retry_delay: int

   :returns: A dataframe containing both production and trade data for all countries in the selected year.
   :rtype: pd.DataFrame


.. py:function:: get_package_user_data_dir(package_name='shrecc')

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

   :param package_name: the name of the package
   :type package_name: str

   Returns
       Path : the existing or newly created directory.


.. py:function:: get_prod(start, end, country, cumul=False, rolling=False)

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

   :param start: Start of the download period (output of `year_to_unix()`) in unix seconds.
   :type start: int
   :param end: End of the download period (output of `year_to_unix()`) in unix seconds.
   :type end: int
   :param country: The country for which data needs to be downloaded.
   :type country: list of str
   :param cumul: If True, calculate the cumulative sum of production.
   :type cumul: bool
   :param rolling: If True, calculate the rolling average of production.
   :type rolling: bool

   :returns:

             A tuple containing:
                 - A dataframe of production.
                 - A dataframe of load.
                 - An array of all available technologies.
   :rtype: Tuple[pd.DataFrame, pd.DataFrame, np.ndarray]


.. py:function:: get_trade(start, end, country)

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

   :param start: Start of the download period (output of `year_to_unix()`) in unix seconds.
   :type start: int
   :param end: End of the download period (output of `year_to_unix()`) in unix seconds.
   :type end: int
   :param country: The country for which data needs to be downloaded.
   :type country: list of str

   :returns:

             A tuple containing:
                 - A dataframe of trades between countries.
                 - An array of all available regions.
   :rtype: Tuple[pd.DataFrame, np.ndarray]


.. py:function:: year_to_unix(year)

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

   :param year: The selected year, passed from `get_data()`.
   :type year: int

   :returns:

             A tuple containing:
                 - The start of the year in Unix seconds (UTC).
                 - The end of the year in Unix seconds (UTC).
   :rtype: Tuple[int, int]