reskit.weather.SarahSource
==========================

.. py:module:: reskit.weather.SarahSource


Classes
-------

.. autoapisummary::

   reskit.weather.SarahSource.SarahSource


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

.. py:class:: SarahSource(source, bounds=None, index_pad=5, **kwargs)

   Bases: :py:obj:`reskit.weather.NCSource`


   The SarahSource object manages weather data (as netCDF4 files) coming from the
   `SARAH satellite-reconstructed data products<https://climatedataguide.ucar.edu/climate-data/surface-solar-radiation-data-set-heliosat-sarah-edition-1>`

   If furthermore allows access a number of common functionalities and constants which are
   often encountered when simulating renewable energy technologies


   Note:
   -----
   Various constants can have been set for this weather source which can impact later simulation workflows.

   For this source, these constants include:
       MAX_LON_DIFFERENCE = 0.06
           The maximum longitude difference to accept between a grid cell's center and the coordinates
               to extract data for

       MAX_LAT_DIFFERENCE = 0.06
           The maximum latitude difference to accept between a grid cell's center and the coordinates
               to extract data for


   .. seealso:: :obj:`reskit.weather.MerraSource`, :obj:`reskit.weather.SarahSource`, :obj:`reskit.weather.Era5Source`, :obj:`Initialize`, :obj:`Compared`, :obj:`the`

   :param path: The path to the main data file(s) to load

                If multiple files are given, or if a directory of netCDF4 files is given, then it is assumed
                that all files ending with the extension '.nc' or '.nc4' should be managed by this object.
                * Be sure that all the netCDF4 files given share the same time and spatial dimensions!
   :type path: str or list of str
   :param bounds:
                  The boundaries of the data which is needed
                    * Usage of this will help with memory management
                    * If None, the full dataset is loaded in memory
                    * The actual extent of the loaded data depends on the source's
                      available data
   :type bounds: Anything acceptable to geokit.Extent.load(), optional
   :param index_pad:
                     The padding to apply to the boundaries
                       * Useful in case of interpolation
                       * Units are in longitudinal degrees
   :type index_pad: int, optional
   :param verbose: If True, then status outputs are printed when searching for and reading weather data
   :type verbose: bool, optional
   :param forward_fill: If True, then missing data in the weather file is forward-filled
                        * Generally, there should be no missing data at all. This option is only intended to
                            catch the rare scenarios where one or two timesteps are missing
   :type forward_fill: bool, optional

   .. seealso:: :obj:`MerraSource`, :obj:`SarahSource`, :obj:`Era5Source`


   .. py:attribute:: MAX_LON_DIFFERENCE
      :value: 0.06



   .. py:attribute:: MAX_LAT_DIFFERENCE
      :value: 0.06



   .. py:attribute:: loc_to_index

      Returns the closest X and Y indexes corresponding to a given location
      or set of locations


      :param loc: The location(s) to search for
                  * A single tuple with (lon, lat) is acceptable, or a list of such tuples
                  * A single point geometry (as long as it has an SRS), or a list
                    of geometries is okay
                  * geokit,Location, or geokit.LocationSet are best!
      :type loc: Anything acceptable by geokit.LocationSet
      :param outside_okay: Determines if points which are outside the source's lat/lon grid
                           are allowed
                           * If True, points outside this space will return as None
                           * If False, an error is raised
      :type outside_okay: bool, optional

      :returns: * **If a single location is given** (*tuple*) --

                  * Format: (yIndex, xIndex)
                  * y index can be accessed with '.yi'
                  * x index can be accessed with '.xi'
                * **If multiple locations are given** (*list*) --

                  * Format: [ (yIndex1, xIndex1), (yIndex2, xIndex2), ...]
                  * Order matches the given order of locations

      Note:
      -----
      The default form of this function (which is the one used here) is not very efficient, ultimately
          leading to much longer look-up than they otherwise need to be. When the weather source has
          grid cells on a regular lat/lon grid then a more efficient form of this function can be
          configured using the function generator "_loc_to_index_rect". In these instances, this is
          the recommended function to use.

      For example, if the weather source uses a latitude spacing of 0.5, and a longitude spacing of
          0.625, then the function generator can be used like:

          > source.loc_to_index = source._loc_to_index_rect(lat_step=0.5, lon_step=0.625)


   .. py:method:: sload_direct_normal_irradiance()

      Standard loader function for the variable 'direct_normal_irradiance'

      Automatically reads the variable "DNI" from the given SARAH source and saves it as the
      variable 'direct_normal_irradiance' in the data library



   .. py:method:: sload_global_horizontal_irradiance()

      Standard loader function for the variable 'global_horizontal_irradiance'

      Automatically reads the variable "SIS" from the given SARAH source and saves it as the
      variable 'global_horizontal_irradiance' in the data library