:py:mod:`bw_timex.matrix_modifier`
==================================

.. py:module:: bw_timex.matrix_modifier


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

Classes
~~~~~~~

.. autoapisummary::

   bw_timex.matrix_modifier.MatrixModifier




.. py:class:: MatrixModifier(timeline: pandas.DataFrame, database_dates_static: dict, demand_timing: dict, nodes: dict, interdatabase_activity_mapping: bw_timex.helper_classes.InterDatabaseMapping, name: Optional[str] = None)


   Class for adding and re-linking time-explicit processes in the LCA matrices.

   This is done by creating datapackages that add or change matrix entries in the technosphere and
   biosphere matrices, based on a process timeline (from TimelineBuilder.build_timeline()).
   "Temporal markets" are created for processes that are linked to background databases, temporally
   distributing the amounts to time-explicit background databases.

   Initializes the MatrixModifier object and creates empty sets to collect
   the ids of temporalized processes and temporal markets.

   :param timeline: A DataFrame of the timeline of exchanges
   :type timeline: pd.DataFrame
   :param database_dates_static: A dictionary mapping the static background databases to dates.
   :type database_dates_static: dict
   :param demand_timing: A dictionary mapping the demand to its timing.
   :type demand_timing: dict
   :param name: An optional name for the MatrixModifier instance. Default is None.
   :type name: str, optional

   .. py:method:: create_datapackage() -> None

      Creates a list of datapackages for the technosphere and biosphere matrices,
      by calling the respective functions.

      :param None:

      :returns: A list of the technosphere and biosphere datapackages.
      :rtype: list


   .. py:method:: create_technosphere_datapackage() -> bw_processing.Datapackage

      Creates the modifications to the technosphere matrix in form of a datapackage.
      Datapackages add or overwrite data points in the LCA matrices before LCA calculations.
      The technosphere datapackage adds the temporalized processes from the timeline
      to the technosphere matrix.

      The heavy lifting of this method happens in the method `add_row_to_technosphere_datapackage()`.
      Here, each node with a temporal distribution is "exploded", which means each occurrence
      of this node (e.g. steel production on 2020-01-01 and steel production on 2015-01-01)
      becomes a separate, time-explicit new node, by adding the new elements to the technosphere matrix.
      For processes at the intersection with background databases, the timing of the exchanges
      determines which background database to link to in so called "Temporal Markets".

      :param None:

      :returns: A datapackage containing the modifications for the technosphere matrix.
      :rtype: bwp.Datapackage


   .. py:method:: create_biosphere_datapackage() -> bw_processing.Datapackage

      Creates the modifications to the biosphere matrix in form of a datapackage.
      Datapackages add or overwrite data points in the LCA matrices before LCA calculations.
      It adds the biosphere flows to the exploded technosphere processes.

      This function iterates over each unique producer, and for each biosphere exchange
      of the original activity, it creates a new biosphere exchange for the new "temporalized" node.

      Temporal markets have no biosphere exchanges, as they only divide the amount of
      a technosphere exchange between the different databases.

      :param None:

      :returns: A datapackage containing the modifications for the biosphere matrix.
      :rtype: bwp.Datapackage


   .. py:method:: add_row_to_technosphere_datapackage(row: pandas.core.frame, datapackage: bw_processing.Datapackage, new_nodes: set) -> None

      This adds the modifications to the technosphere matrix for each time-dependent exchange
      as datapackage elements to a given `bwp.Datapackage`.


      Modifications include:

      1) Exploded processes: new matrix elements for time-explicit consumer and time-explicit
      producer, representing the temporal edge between them.

      2) Temporal markets: new matrix entries for "temporal markets" and links to the producers
      in temporally matching background databases. Processes in the background databases are
      matched on name, reference product and location.

      3) Diagonal entries: ones on the diagonal for new nodes.

      This function also collects the ids of new nodes, temporalized nodes and temporal markets.

      :param row: A row of the timeline DataFrame representing an temporalized edge
      :type row: pd.core.frame
      :param datapackage: Append to this datapackage, if available. Otherwise create a new datapackage.
      :type datapackage: bwp.Datapackage
      :param new_nodes: Set of tuples (node_id, production_amount) to which new node ids are added.
      :type new_nodes: set

      :returns: Adds elements for this edge to the bwp.Datapackage and stores the ids of new nodes, temporalized nodes and temporal markets.
      :rtype: None