bw2data.parameters
==================

.. py:module:: bw2data.parameters


Attributes
----------

.. autoapisummary::

   bw2data.parameters.parameters


Classes
-------

.. autoapisummary::

   bw2data.parameters.ActivityParameter
   bw2data.parameters.DatabaseParameter
   bw2data.parameters.Group
   bw2data.parameters.GroupDependency
   bw2data.parameters.ParameterizedExchange
   bw2data.parameters.ProjectParameter


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

.. py:class:: ActivityParameter

   Bases: :py:obj:`ParameterBase`


   Parameter set for a group of activities.

   Columns:

       - group: str
       - database: str
       - code: str. Code and database define the linked activity for this parameter.
       - name: str, unique within a group
       - formula: str, optional
       - amount: float, optional
       - data: object, optional. Used for any other metadata.

   Activities can only have parameters in one group. Group names cannot be 'project' or the name of any existing database.

   Activity parameter groups can depend on other activity parameter groups, so that a formula in group "a" can depend on a variable in group "b". This dependency information is stored in ``Group.order`` - in our small example, we could define the following:

   .. code-block:: python

       a = Group.get(name="a")
       a.order = ["b", "c"]
       a.save()

   In this case, a variable not found in "a" would be searched for in "b" and then "c", in that order. Database and then project parameters are also implicitly included at the end of ``Group.order``.

   Note that there is no magic for reading and writing to ``data`` (unlike ``Activity`` objects) - it must be used directly.



   .. py:class:: Meta

      .. py:attribute:: constraints


      .. py:attribute:: indexes
         :value: [(('group', 'name'), True)]




   .. py:method:: _static_dependencies(group)
      :staticmethod:


      Get dictionary of ``{name: amount}`` for all variables defined in dependency chain.

      Be careful! This could have variables which overlap with local variable names. Designed for internal use.



   .. py:method:: create_table()
      :classmethod:



   .. py:method:: dependency_chain(group, include_self=False)
      :staticmethod:


      Find where each missing variable is defined in dependency chain.

      Will also load in all parameters needed to resolve the ``ParameterizedExchanges`` for this group.

      If ``include_self`` is True will include parameters within the group as possible dependencies

      Returns:

      .. code-block:: python

          [
              {
                  'kind': one of 'project', 'database', 'activity',
                  'group': group name,
                  'names': set of variables names
              }
          ]




   .. py:method:: expired(group)
      :staticmethod:


      Return boolean - is this group expired?



   .. py:method:: insert_dummy(group: str, activity: tuple, signal: bool = True)
      :staticmethod:



   .. py:method:: is_deletable()

      Perform a test to see if the current parameter can be deleted.



   .. py:method:: is_dependency_within_group(name, group, include_order=False)
      :staticmethod:


      Determine if the given parameter `name` is a dependency within
      the given activity `group`.

      The optional ``include_order`` parameter will include dependencies
      from groups found in the the ``Group``.`order` field.



   .. py:method:: is_dependent_on(name, group)
      :staticmethod:


      Test if any activity parameters are dependent on the given
      parameter name from the given group.



   .. py:method:: load(group)
      :staticmethod:


      Return dictionary of parameter data with names as keys and ``.dict()`` as values.



   .. py:method:: recalculate(group: str, signal: bool = True)
      :staticmethod:


      Recalculate all values for activity parameters in this group, and update their underlying `Activity` and `Exchange` values.



   .. py:method:: recalculate_exchanges(group: str, signal: bool = True)
      :staticmethod:


      Recalculate formulas for all parameterized exchanges in group ``group``.



   .. py:method:: save(*args, **kwargs)

      Save this model instance



   .. py:method:: static(group, only=None, full=False)
      :staticmethod:


      Get dictionary of ``{name: amount}`` for parameters defined in ``group``.

      ``only`` restricts returned names to ones found in ``only``. ``full`` returns all names, including those found in the dependency chain.



   .. py:method:: update_formula_activity_parameter_name(old: str, new: str, include_order: bool = False, signal: bool = True)
      :classmethod:


      Performs an update of the formula of relevant parameters.

      This method specifically targets activity parameters used in activity
      formulas



   .. py:method:: update_formula_database_parameter_name(old: str, new: str, signal: bool = True)
      :classmethod:


      Performs an update of the formula of relevant parameters.

      This method specifically targets database parameters used in activity
      formulas



   .. py:method:: update_formula_project_parameter_name(old: str, new: str, signal: bool = True)
      :classmethod:


      Performs an update of the formula of relevant parameters.

      This method specifically targets project parameters used in activity
      formulas



   .. py:attribute:: _db_table
      :value: 'activityparameter'



   .. py:attribute:: _new_name
      :value: 'NEW."group"'



   .. py:attribute:: _old_name
      :value: 'OLD."group"'



   .. py:attribute:: amount


   .. py:attribute:: code


   .. py:attribute:: data


   .. py:attribute:: database


   .. py:property:: dict

      Parameter data as a standardized dictionary


   .. py:attribute:: formula


   .. py:attribute:: group


   .. py:attribute:: name


.. py:class:: DatabaseParameter

   Bases: :py:obj:`ParameterBase`


   Parameter set for a database. Group name is the name of the database.

   Columns:

       * database: str
       * name: str, unique within a database
       * formula: str, optional
       * amount: float, optional
       * data: object, optional. Used for any other metadata.

   Note that there is no magic for reading and writing to ``data`` (unlike ``Activity`` objects) - it must be used directly.



   .. py:class:: Meta

      .. py:attribute:: constraints


      .. py:attribute:: indexes
         :value: ((('database', 'name'), True),)




   .. py:method:: dependency_chain(group, include_self=False)
      :staticmethod:


      Find where each missing variable is defined in dependency chain.

      If ``include_self`` is True will include parameters within the group as possible dependencies

      Returns:

      .. code-block:: python

          [
              {
                  'kind': one of 'project', 'database', 'activity',
                  'group': group name,
                  'names': set of variables names
              }
          ]




   .. py:method:: expired(database)
      :staticmethod:


      Return boolean - is this group expired?



   .. py:method:: is_deletable()

      Perform a test to see if the current parameter can be deleted.



   .. py:method:: is_dependency_within_group(name, database)
      :staticmethod:



   .. py:method:: is_dependent_on(name)
      :staticmethod:


      Test if any database parameters are dependent on the given
      project parameter name.



   .. py:method:: load(database)
      :staticmethod:


      Return dictionary of parameter data with names as keys and ``.dict()`` as values.



   .. py:method:: recalculate(database: str, signal: bool = True)
      :staticmethod:


      Recalculate all database parameters for ``database``, if expired.



   .. py:method:: save(*args, **kwargs)

      Save this model instance



   .. py:method:: static(database, only=None)
      :staticmethod:


      Return dictionary of {name: amount} for database group.



   .. py:method:: update_formula_database_parameter_name(old: str, new: str, signal: bool = True)
      :classmethod:


      Performs an update of the formula of relevant parameters.

      This method specifically targets database parameters used in database
      formulas



   .. py:method:: update_formula_project_parameter_name(old: str, new: str, signal: bool = True)
      :classmethod:


      Performs an update of the formula of relevant parameters.

      This method specifically targets project parameters used in database
      formulas



   .. py:attribute:: _db_table
      :value: 'databaseparameter'



   .. py:attribute:: _new_name
      :value: 'NEW.database'



   .. py:attribute:: _old_name
      :value: 'OLD.database'



   .. py:attribute:: amount


   .. py:attribute:: data


   .. py:attribute:: database


   .. py:property:: dict

      Parameter data as a standardized dictionary


   .. py:attribute:: formula


   .. py:attribute:: name


.. py:class:: Group

   Bases: :py:obj:`bw2data.snowflake_ids.SnowflakeIDBaseClass`


   .. py:class:: Meta

      .. py:attribute:: table_name
         :value: 'group_table'




   .. py:method:: expire()

      Set ``fresh`` to ``False``



   .. py:method:: freshen()

      Set ``fresh`` to ``True``



   .. py:method:: purge_order()


   .. py:method:: save(*args, **kwargs)

      Save this model instance. Will remove 'project' and database names from ``order``.



   .. py:attribute:: fresh


   .. py:attribute:: name


   .. py:attribute:: order


   .. py:attribute:: updated


.. py:class:: GroupDependency

   Bases: :py:obj:`peewee.Model`


   .. py:class:: Meta

      .. py:attribute:: constraints


      .. py:attribute:: indexes
         :value: ((('group', 'depends'), True),)




   .. py:method:: create_table()
      :classmethod:



   .. py:method:: save(*args, **kwargs)


   .. py:attribute:: depends


   .. py:attribute:: group


.. py:class:: ParameterizedExchange

   Bases: :py:obj:`bw2data.snowflake_ids.SnowflakeIDBaseClass`


   .. py:method:: create_table()
      :classmethod:



   .. py:method:: load(group)
      :staticmethod:


      Return dictionary of parameter data with names as keys and ``.dict()`` as values.



   .. py:method:: recalculate(group)
      :staticmethod:


      Shortcut for ``ActivityParameter.recalculate_exchanges``.



   .. py:method:: save(*args, **kwargs)


   .. py:attribute:: exchange


   .. py:attribute:: formula


   .. py:attribute:: group


.. py:class:: ProjectParameter

   Bases: :py:obj:`ParameterBase`


   Parameter set for a project. Group name is 'project'.

   Columns:
       - name: str, unique
       - formula: str, optional
       - amount: float, optional
       - data: object, optional. Used for any other metadata.

   Note that there is no magic for reading and writing to ``data`` (unlike ``Activity`` objects) - it must be used directly.



   .. py:method:: dependency_chain()
      :staticmethod:


      Determine if ```ProjectParameter`` parameters have dependencies
      within the group.

      Returns:

      .. code-block:: python

          [
              {
                  'kind': 'project',
                  'group': 'project',
                  'names': set of variables names
              }
          ]




   .. py:method:: expired()
      :staticmethod:


      Return boolean - is this group expired?



   .. py:method:: is_deletable()

      Perform a test to see if the current parameter can be deleted.



   .. py:method:: is_dependency_within_group(name)
      :staticmethod:



   .. py:method:: load(group=None)
      :staticmethod:


      Return dictionary of parameter data with names as keys and ``.dict()`` as values.



   .. py:method:: recalculate(ignored: Optional[bool] = None, signal: bool = True)
      :staticmethod:


      Recalculate all parameters.

      ``ignored`` included for API compatibility with other ``recalculate`` methods - it will really be ignored.



   .. py:method:: save(*args, **kwargs)


   .. py:method:: static(ignored='project', only=None)
      :staticmethod:


      Get dictionary of ``{name: amount}`` for all project parameters.

      ``only`` restricts returned names to ones found in ``only``. ``ignored`` included for API compatibility with other ``recalculate`` methods.



   .. py:method:: update_formula_parameter_name(old: str, new: str, signal: bool = True)
      :classmethod:


      Performs an update of the formula of relevant parameters.

      NOTE: Make sure to wrap this in an .atomic() statement!



   .. py:attribute:: _db_table
      :value: 'projectparameter'



   .. py:attribute:: _new_name
      :value: "'project'"



   .. py:attribute:: _old_name
      :value: "'project'"



   .. py:attribute:: amount


   .. py:attribute:: data


   .. py:property:: dict

      Parameter data as a standardized dictionary


   .. py:attribute:: formula


   .. py:attribute:: name


.. py:data:: parameters