subsettools.clm
-------------------------

.. py:module:: subsettools.clm

.. autoapi-nested-parse::

   Functions to configure CLM for coupled ParFlow-CLM simulations.





Functions
~~~~~~~~

.. autoapisummary::

   subsettools.clm.config_clm
   subsettools.clm.vegm_to_land_cover



.. py:function:: config_clm(ij_bounds, start, end, dataset, write_dir, time_zone='UTC')

   Modify template CLM driver files for a desired subdomain and run duration.

   This function will obtain template clm driver files (specifically vegm, vep
   and drv_clmin) from the existing national simulations on HydroData and modify
   them to reflect the desired subdomain (indicated by the ij_bounds) and run
   duration (indicated by the start and end dates). The modified files will be
   written out to a user specified directory. These files are required if you
   are going to run a ParFlow-CLM simulation.

   :param ij_bounds: bounding box for subset. This should be given as
                     i,j index values where 0,0 is the lower left hand corner of a domain.
                     ij_bounds are given relative to whatever grid is being used for the
                     subset.
   :type ij_bounds: tuple[int]
   :param start: start date (inclusive), in the form 'yyyy-mm-dd'
   :type start: str
   :param end: end date (exlusive), in the form 'yyyy-mm-dd'
   :type end: str
   :param dataset: the dataset that the files should be obtained from name
                   e.g. "conus1_baseline_mod"
   :type dataset: str
   :param write_dir: directory where the subset files will be written
   :type write_dir: str
   :param time_zone: timezone information for start and end dates. This
                     should be a zoneinfo-supported time zone. Defaults to "UTC".
   :type time_zone: str

   :returns: A dictionary mapping the CLM file types ("vegp", "vegm", "drv_clm") to
             the corresponging filepaths where the CLM files were written.

   Example:

   .. code-block:: python

       filepaths = config_clm(
           ij_bounds=(375, 239, 487, 329),
           start="2005-10-01",
           end="2006-10-01",
           dataset="conus1_baseline_mod",
           write_dir="/path/to/your/chosen/directory"
       )


.. py:function:: vegm_to_land_cover(vegm_path, write_pfb_path=None)

   Convert a vegm.dat file in CLM format into a land cover array.

   This function assumes the vegm.dat file is in the standard format.
   That is, the file has 1 row per grid cell and each row contains 25 columns
   The columns are ordered as: x, y, lat, lon, sand, clay, color, then 18
   columns representing the fractional coverage of the grid cell by vegetation
   class (these final 18 columns add to 1.0 for each row). The rows are in
   ascending order by grid cell index with y as the outer loop and x as the
   inner loop.

   In cases in which the fractional vegetation coverage results in a tie
   between multiple vegetation classes, the final land cover array will
   use the first (lowest) land cover designation to break the tie
   (ie. the land cover array will contain designation 1 for a grid cell
   in which the vegetation distribution is 0.5 class 1 and 0.5 class 5).

   :param vegm_path: path to vegm file
   :type vegm_path: str
   :param write_pfb_path: path to write output .pfb file to disk
   :type write_pfb_path: str; optional

   :returns: NumPy array containing the calculated land cover type for
             each domain grid cell.

             If `pfb_path` is provided, .pfb file is written to disk at the
             specified path.

   Example:

   .. code-block:: python

       land_cover_array = vegm_to_land_cover("/path/to/vegm/vegm.dat")