agrifoodpy.pipeline
===================

.. py:module:: agrifoodpy.pipeline

.. autoapi-nested-parse::

   This module provides methods to build a pipeline for the AgriFoodPy package.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/agrifoodpy/pipeline/pipeline/index


Classes
-------

.. autoapisummary::

   agrifoodpy.pipeline.Pipeline


Functions
---------

.. autoapisummary::

   agrifoodpy.pipeline.standalone
   agrifoodpy.pipeline.item_parser
   agrifoodpy.pipeline.get_dict
   agrifoodpy.pipeline.set_dict


Package Contents
----------------

.. py:class:: Pipeline(datablock=None)

   Class for constructing and running pipelines of functions with
   individual sets of parameters.


   .. py:attribute:: nodes
      :value: []



   .. py:attribute:: params
      :value: []



   .. py:attribute:: names
      :value: []



   .. py:method:: read(filename)
      :classmethod:

      :abstractmethod:


      Read a pipeline from a configuration file

      :param filename: The name of the configuration file.
      :type filename: str

      :returns: **pipeline** -- The pipeline object.
      :rtype: Pipeline



   .. py:method:: datablock_write(path, value)

      Writes a single value to the datablock at the specified path.

      :param path: The datablock path to the value to be written.
      :type path: list
      :param value: The value to be written.
      :type value: any



   .. py:method:: add_node(node, params={}, name=None)

      Adds a node to the pipeline, including its function and execution
      parameters.

      :param node: The function to be executed on this node.
      :type node: function
      :param params: The parameters to be passed to the node function.
      :type params: dict, optional
      :param name: The name of the node. If not provided, a generic name will be
                   assigned.
      :type name: str, optional



   .. py:method:: run(from_node=0, to_node=None, timing=False)

      Runs the pipeline

      :param from_node: The index of the first node to be executed. Defaults to 0.
      :type from_node: int, optional
      :param to_node: The index of the last node to be executed. If not provided, all
                      nodes will be executed
      :type to_node: int, optional
      :param timing: If True, the execution time of each node will be printed. Defaults
                     to False.
      :type timing: bool, optional



.. py:function:: standalone(input_keys, return_keys)

   Decorator to make a pipeline node available as a standalone function

   If datablock is not passed as a kwarg, and datasets are passed directly
   instead of datablock keys, a temporary datablock is created and the
   datasets associated with the arguments in input_keys are added to it.
   The function then returns the specified datasets in return_keys.

   :param input_keys: List of dataset keys to be added to the temporary datablock
   :type input_keys: list of strings
   :param return_keys: List of keys to datablock datasets to be returned by the decorated
                       function.
   :type return_keys: list of strings

   :returns: **wrapper** -- The decorated function
   :rtype: function


.. py:function:: item_parser(fbs, items)

   Extracts a list of items from a dataset using a coordinate-key tuple,
   or converts a scalar item to a list

   :param fbs: The dataset containing the coordinate-key to extract items from.
   :type fbs: xarray.Dataset or xarray.DataArray
   :param items: If a tuple, the first element is the name of the coordinate and the
                 second element is a list of items to extract. If a scalar, the item
                 is converted to a list.
   :type items: tuple, scalar

   :returns: A list of items matching the coordinate-key description, or containing
             the scalar item.
   :rtype: list


.. py:function:: get_dict(datablock, keys)

   Returns an element from a dictionary using a key or tuple of keys used
   to describe a path of keys

   :param datablock: The input dictionary
   :type datablock: dict
   :param keys: Dictionary key, or tuple of keys
   :type keys: str or tuple


.. py:function:: set_dict(datablock, keys, object, create_missing=True)

   Sets an element in a dictionary using a key or tuple of keys used to
   describe a path of keys

   :param datablock: The input dictionary
   :type datablock: dict
   :param keys: Dictionary key, or tuple of keys
   :type keys: str or tuple
   :param object: The object to set in the dictionary
   :type object: any
   :param create_missing: If True, creates missing keys in the dictionary. Defaults to True.
   :type create_missing: bool, optional

   :raises KeyError: If a key in the path does not exist and create_missing is False.