agrifoodpy.utils.nodes
======================

.. py:module:: agrifoodpy.utils.nodes


Functions
---------

.. autoapisummary::

   agrifoodpy.utils.nodes.add_items
   agrifoodpy.utils.nodes.add_years
   agrifoodpy.utils.nodes.copy_datablock
   agrifoodpy.utils.nodes.print_datablock
   agrifoodpy.utils.nodes.write_to_datablock
   agrifoodpy.utils.nodes.load_dataset


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

.. py:function:: add_items(dataset, items, values=None, copy_from=None, datablock=None)

   Adds a list of items to a selected dataset in the datablock and
   initializes their values.

   :param datablock: Datablock object.
   :type datablock: Datablock
   :param dataset: Datablock path to the datasets to modify.
   :type dataset: dict
   :param items: List of items or dictionary of items attributes to add. If a
                 dictionary, keys are the item names, and non-dimension coordinates.
   :type items: list, dict
   :param values: List of values to initialize the items. If not set, values are set to
                  0, unless the copy from parameter is set.
   :type values: list, optional
   :param copy_from: Items to copy the values from.
   :type copy_from: list, optional

   :returns:

             - If no datablock is provided, returns a xarray.Dataset with the new
               items.
             - If a datablock is provided, returns the datablock with the modified
               datasets on the corresponding keys.
   :rtype: dict or xarray.Dataset


.. py:function:: add_years(dataset, years, projection='empty', datablock=None)

   Extends the Year coordinates of a dataset.

   :param datablock: The datablock dictionary where the dataset is stored.
   :type datablock: dict
   :param dataset: Datablock key of the dataset to extend.
   :type dataset: str
   :param years: List of years to extend the dataset to.
   :type years: list
   :param projection: Projection mode. If "constant", the last year of the input array
                      is copied to every new year. If "empty", values are initialized and
                      set to zero. If a float array is given, these are used to populate
                      the new year using a scaling of the last year of the array
   :type projection: str


.. py:function:: copy_datablock(datablock, key, out_key)

   Copy a datablock element into a new key in the datablock

   :param datablock: The datablock to print
   :type datablock: xarray.Dataset
   :param key: The key of the datablock to print
   :type key: str
   :param out_key: The key of the datablock to copy to
   :type out_key: str

   :returns: **datablock** -- Datablock to with added key
   :rtype: dict


.. py:function:: print_datablock(datablock, key, attr=None, method=None, args=None, kwargs=None, preffix='', suffix='')

   Prints a datablock element or its attributes/methods at any point in the
   pipeline execution.

   :param datablock: The datablock to print from.
   :type datablock: dict
   :param key: The key of the datablock to print.
   :type key: str
   :param attr: Name of an attribute of the object to print.
   :type attr: str, optional
   :param method: Name of a method of the object to call and print.
   :type method: str, optional
   :param args: Positional arguments for the method call.
   :type args: list, optional
   :param kwargs: Keyword arguments for the method call.
   :type kwargs: dict, optional

   :returns: **datablock** -- Unmodified datablock to continue execution.
   :rtype: dict


.. py:function:: write_to_datablock(datablock, key, value, overwrite=True)

   Writes a value to a specified key in the datablock.

   :param datablock: The datablock to write to.
   :type datablock: dict
   :param key: The key in the datablock where the value will be written.
   :type key: str
   :param value: The value to write to the datablock.
   :type value: any
   :param overwrite: If True, overwrite the existing value at the key.
                     If False, do not overwrite.
   :type overwrite: bool, optional

   :returns: **datablock** -- The updated datablock with the new key-value pair.
   :rtype: dict


.. py:function:: load_dataset(datablock_path, path=None, module=None, data_attr=None, da=None, coords=None, scale=1.0, datablock=None)

   Loads a dataset to the specified datablock dictionary.

   :param datablock: The datablock path where the dataset is stored
   :type datablock: dict
   :param path: The path to the dataset stored in a netCDF file.
   :type path: str
   :param module: The module name where the dataset will be imported from.
   :type module: str
   :param data_attr: The attribute name of the dataset in the module.
   :type data_attr: str
   :param da: The dataarray to be loaded.
   :type da: str
   :param coords: Dictionary containing the coordinates of the dataset to be loaded.
   :type coords: dict
   :param scale: Optional multiplicative factor to be applied to the dataset on load.
   :type scale: float
   :param datablock_path: The path to the datablock where the dataset is stored.
   :type datablock_path: str