dynamic-characterization 0.0.1.dev1__tar.gz → 0.0.3__tar.gz

{dynamic_characterization-0.0.1.dev1/dynamic_characterization.egg-info → dynamic_characterization-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dynamic_characterization
-Version: 0.0.1.dev1
+Version: 0.0.3
 Summary: Collection of dynamic characterization functions for life cycle inventories with temporal information
 Author-email: Timo Diepers <timo.diepers@ltt.rwth-aachen.de>
 Maintainer-email: Timo Diepers <timo.diepers@ltt.rwth-aachen.de>
@@ -20,6 +20,9 @@ Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: bw2data
 Provides-Extra: testing
 Requires-Dist: dynamic_characterization; extra == "testing"
 Requires-Dist: pytest; extra == "testing"
@@ -76,11 +79,12 @@ Here's an example of what such a function could look like:
 
 ```python
 def characterize_something(series, period: int = 100, cumulative=False) -> pd.DataFrame:
-    date_beginning: np.datetime64 = series["date"].to_numpy()
-    date_characterized: np.ndarray = date_beginning + np.arange(
+    date_beginning: np.datetime64 = series.date.to_numpy()
+    dates_characterized: np.ndarray = date_beginning + np.arange(
         start=0, stop=period, dtype="timedelta64[Y]"
     ).astype("timedelta64[s]")
 
+    # let's assume some simple decay function
     decay_multipliers: list = np.array(
         [
             1.234 * (1 - np.exp(-year / 56.789))
@@ -88,13 +92,14 @@ def characterize_something(series, period: int = 100, cumulative=False) -> pd.Da
         ]
     )
 
-    forcing = pd.Series(data=series.amount * decay_multipliers, dtype="float64")
+    forcing = np.array(series.amount * decay_multipliers, dtype="float64")
+
     if not cumulative:
-        forcing = forcing.diff(periods=1).fillna(0)
+        forcing = np.diff(forcing, prepend=0)
 
     return pd.DataFrame(
         {
-            "date": pd.Series(data=date_characterized, dtype="datetime64[s]"),
+            "date": np.array(dates_characterized, dtype="datetime64[s]"),
             "amount": forcing,
             "flow": series.flow,
             "activity": series.activity,
@@ -131,6 +136,9 @@ _dynamic_characterization_ is free and open source software.
 If you encounter any problems,
 please [file an issue][Issue Tracker] along with a detailed description.
 
+## Support
+
+If you have any questions or need help, do not hesitate to contact Timo Diepers ([timo.diepers@ltt.rwth-aachen.de](mailto:timo.diepers@ltt.rwth-aachen.de))
 
 <!-- github-only -->
 

{dynamic_characterization-0.0.1.dev1 → dynamic_characterization-0.0.3}/README.md

@@ -40,11 +40,12 @@ Here's an example of what such a function could look like:
 
 ```python
 def characterize_something(series, period: int = 100, cumulative=False) -> pd.DataFrame:
-    date_beginning: np.datetime64 = series["date"].to_numpy()
-    date_characterized: np.ndarray = date_beginning + np.arange(
+    date_beginning: np.datetime64 = series.date.to_numpy()
+    dates_characterized: np.ndarray = date_beginning + np.arange(
         start=0, stop=period, dtype="timedelta64[Y]"
     ).astype("timedelta64[s]")
 
+    # let's assume some simple decay function
     decay_multipliers: list = np.array(
         [
             1.234 * (1 - np.exp(-year / 56.789))
@@ -52,13 +53,14 @@ def characterize_something(series, period: int = 100, cumulative=False) -> pd.Da
         ]
     )
 
-    forcing = pd.Series(data=series.amount * decay_multipliers, dtype="float64")
+    forcing = np.array(series.amount * decay_multipliers, dtype="float64")
+
     if not cumulative:
-        forcing = forcing.diff(periods=1).fillna(0)
+        forcing = np.diff(forcing, prepend=0)
 
     return pd.DataFrame(
         {
-            "date": pd.Series(data=date_characterized, dtype="datetime64[s]"),
+            "date": np.array(dates_characterized, dtype="datetime64[s]"),
             "amount": forcing,
             "flow": series.flow,
             "activity": series.activity,
@@ -95,6 +97,9 @@ _dynamic_characterization_ is free and open source software.
 If you encounter any problems,
 please [file an issue][Issue Tracker] along with a detailed description.
 
+## Support
+
+If you have any questions or need help, do not hesitate to contact Timo Diepers ([timo.diepers@ltt.rwth-aachen.de](mailto:timo.diepers@ltt.rwth-aachen.de))
 
 <!-- github-only -->
 

{dynamic_characterization-0.0.1.dev1 → dynamic_characterization-0.0.3}/dynamic_characterization/__init__.py

@@ -4,12 +4,14 @@ Collection of dynamic characterization functions for life cycle inventories with
 
 __all__ = (
     "__version__",
+    "dynamic_characterization.characterize_dynamic_inventory",
     "temporalis",
     "timex",
     # Add functions and variables you want exposed in `dynamic_characterization.` namespace here
 )
 
-__version__ = "0.0.1dev1"
+__version__ = "0.0.3"
 
+from .dynamic_characterization import characterize_dynamic_inventory
 from . import temporalis
 from . import timex

dynamic_characterization-0.0.3/dynamic_characterization/classes.py

@@ -0,0 +1,5 @@
+from collections import namedtuple
+
+CharacterizedRow = namedtuple(
+    "CharacterizedRow", ["date", "amount", "flow", "activity"]
+)

dynamic_characterization-0.0.3/dynamic_characterization/dynamic_characterization.py

@@ -0,0 +1,335 @@
+import json
+import os
+import warnings
+from collections.abc import Collection
+from datetime import datetime
+from typing import Callable, Dict, Tuple
+
+import bw2data as bd
+import numpy as np
+import pandas as pd
+from bw2data.utils import UnknownObject
+
+from dynamic_characterization.timex.radiative_forcing import (
+            characterize_ch4,
+            characterize_co,
+            characterize_co2,
+            characterize_co2_uptake,
+            characterize_n2o,
+            create_generic_characterization_function,
+)
+
+
+def characterize_dynamic_inventory(
+    dynamic_inventory_df: pd.DataFrame,
+    metric: str = "radiative_forcing",
+    characterization_function_dict: Dict[str, Callable] = None,
+    base_lcia_method: Tuple[str, ...] = None,
+    time_horizon: int = 100,
+    fixed_time_horizon: bool = False,
+    time_horizon_start: datetime = datetime.now(),
+    characterization_function_co2: Callable = None,
+) -> pd.DataFrame:
+    """
+    Characterizes the dynamic inventory, formatted as a Dataframe, by evaluating each emission (row in DataFrame) using given dynamic characterization functions.
+
+    Available metrics are radiative forcing [W/m2] and GWP [kg CO2eq], defaulting to `radiative_forcing`.
+    
+    In case users don't provide own dynamic characterization functions, it adds dynamic characterization functions from the timex submodule
+    for the GHGs mentioned in the IPCC AR6 Chapter 7, if these GHG are also characterized in the selected static LCA method.
+
+    This method applies the dynamic characterization functions to each row of the dynamic_inventory_df for the duration of `time_horizon`, defaulting to 100 years.
+    The `fixed_time_horizon` parameter determines whether the evaluation time horizon for all emissions is calculated from the
+    functional unit (`fixed_time_horizon=True`), regardless of when the actual emission occurs, or from the time of the emission itself(`fixed_time_horizon=False`).
+    The former is the implementation of the Levasseur approach (https://doi.org/10.1021/es9030003), while the latter is how conventional LCA is done.
+    The Levasseur approach means that earlier emissions are characterized for a longer time period than later emissions.
+
+    Parameters
+    ----------
+    dynamic_inventory_df : pd.DataFrame
+        Dynamic inventory, formatted as a DataFrame, which contains the timing, id and amount of emissions and the emitting activity.
+    metric : str, optional
+        The metric for which the dynamic LCIA should be calculated. Default is "GWP". Available: "GWP" and "radiative_forcing". Default is "radiative_forcing".
+    characterization_function_dict : dict, optional
+        A dictionary of the form {biosphere_flow_id: dynamic_characterization_function} allowing users to specify their own functions and what flows to apply them to.
+        Default is none, in which case a set of default functions are added based on the base_lcia_method.
+    base_lcia_method : tuple, optional
+        Tuple of the selcted the LCIA method, e.g. `("EF v3.1", "climate change", "global warming potential (GWP100)")`. This is
+        required for adding the default characterization functions and can be kept empty if custom ones are provided.
+    time_horizon: int, optional
+        Length of the time horizon for the dynamic characterization. Default is 100 years.
+    fixed_time_horizon: bool, optional
+        If True, the time horizon is calculated from the time of the functional unit (FU) instead of the time of emission. Default is False.
+    time_horizon_start: pd.Timestamp, optional
+        The starting timestamp of the time horizon for the dynamic characterization. Only needed for fixed time horizons. Default is datetime.now().
+    characterization_function_co2: Callable, optional
+        Characterization function for CO2. This is required for the GWP calculation. If None is given, we try using timex' default CO2 function from the (separate) dynamic_characterization package (https://dynamic-characterization.readthedocs.io/en/latest/).
+
+    Returns
+    -------
+    pd.DataFrame
+        characterized dynamic inventory
+    """
+
+    if metric not in {"radiative_forcing", "GWP"}:
+        raise ValueError(
+            f"Metric must be either 'radiative_forcing' or 'GWP', not {metric}"
+        )
+
+    if not characterization_function_dict:
+        warnings.warn(
+            "No custom dynamic characterization functions provided. Using default dynamic characterization functions from `dynamic_characterization` meant to work with biosphere3 flows. The flows that are characterized are based on the selection of the initially chosen impact category. You can look up the mapping in the bw_timex.dynamic_characterizer.characterization_function_dict."
+        )
+        if not base_lcia_method:
+            raise ValueError(
+                "Please provide an LCIA method to base the default dynamic characterization functions on."
+            )
+        characterization_function_dict = create_default_characterization_function_dict(
+            base_lcia_method
+        )
+
+    if metric == "GWP" and not characterization_function_co2:
+        characterization_function_co2 = _get_default_co2_function()
+
+    characterized_inventory_data = []
+
+    for row in dynamic_inventory_df.itertuples(index=False):
+
+        # skip uncharacterized biosphere flows
+        if row.flow not in characterization_function_dict.keys():
+            continue
+
+        dynamic_time_horizon = _calculate_dynamic_time_horizon(
+            emission_date=row.date,
+            time_horizon_start=time_horizon_start,
+            time_horizon=time_horizon,
+            fixed_time_horizon=fixed_time_horizon,
+        )
+
+        if metric == "radiative_forcing":  # radiative forcing in W/m2
+            characterized_inventory_data.append(
+                _characterize_radiative_forcing(
+                    characterization_function_dict, row, dynamic_time_horizon
+                )
+            )
+
+        if metric == "GWP":  # scale radiative forcing to GWP [kg CO2 equivalent]
+            characterized_inventory_data.append(
+                _characterize_gwp(
+                    characterization_function_dict=characterization_function_dict,
+                    row=row,
+                    original_time_horizon=time_horizon,
+                    dynamic_time_horizon=dynamic_time_horizon,
+                    characterization_function_co2=characterization_function_co2,
+                )
+            )
+
+    if not characterized_inventory_data:
+        raise ValueError(
+            "There are no flows to characterize. Please make sure your time horizon matches the timing of emissions and make sure there are characterization functions for the flows in the dynamic inventories."
+        )
+
+    characterized_inventory = (
+        pd.DataFrame(characterized_inventory_data)
+        .explode(["amount", "date"])
+        .astype({"amount": "float64"})
+        .query("amount != 0")[["date", "amount", "flow", "activity"]]
+        .sort_values(by="date")
+        .reset_index(drop=True)
+    )
+
+    return characterized_inventory
+
+def create_default_characterization_function_dict(
+    base_lcia_method: Tuple[str, ...]
+) -> dict:
+    """
+    Add default dynamic characterization functions from the (separate) dynamic_characterization package (https://dynamic-characterization.readthedocs.io/en/latest/)
+    for CO2, CH4, N2O and other GHGs, based on IPCC AR6 Chapter 7 decay curves.
+
+    Please note: Currently, only CO2, CH4 and N2O include climate-carbon feedbacks.
+
+    This has not yet been added for other GHGs. Refer to https://esd.copernicus.org/articles/8/235/2017/esd-8-235-2017.html"
+    "Methane, non-fossil" is currently also excluded from the default characterization functions, as it has a different static CF than fossil methane and we need to check the correct value (#TODO)
+
+    Parameters
+    ----------
+    base_lcia_method : tuple
+        Tuple of the selected the LCIA method, e.g. `("EF v3.1", "climate change", "global warming potential (GWP100)")`.
+
+    Returns
+    -------
+    None but adds default dynamic characterization functions to the `characterization_function_dict` attribute of the DynamicCharacterization object.
+
+    """
+
+    characterization_function_dict = dict()
+    
+    # load pre-calculated decay multipliers for GHGs (except for CO2, CH4, N2O & CO)
+    filepath = os.path.join(
+        os.path.dirname(os.path.abspath(__file__)), "data", "decay_multipliers.json"
+    )
+
+    with open(filepath) as json_file:
+        decay_multipliers = json.load(json_file)
+
+    # look up which GHGs are characterized in the selected static LCA method
+    method_data = bd.Method(base_lcia_method).load()
+
+    biosphere_db = bd.Database(bd.config.biosphere)
+
+    # the bioflow-identifier stored in the method data can be the database id or the tuple (database, code)
+    def get_bioflow_node(identifier):
+        if (
+            isinstance(identifier, Collection) and len(identifier) == 2
+        ):  # is (probably) tuple of (database, code)
+            try:
+                biosphere_node = biosphere_db.get(
+                    database=identifier[0], code=identifier[1]
+                )
+            except UnknownObject as e:
+                raise UnknownObject(
+                    f"Failed to set up the default characterization functions because a biosphere node was not found. Make sure the biosphere is set up correctly or provide a characterization_function_dict. Original error: {e}"
+                )
+            return biosphere_node
+
+        if isinstance(identifier, int):  # id is an int
+            return biosphere_db.get(id=identifier)
+        else:
+            raise ValueError(
+                "The flow-identifier stored in the selected method is neither an id nor the tuple (database, code). No automatic matching possible."
+            )
+
+    bioflow_nodes = set(
+        get_bioflow_node(identifier) for identifier, _ in method_data
+    )
+
+    for node in bioflow_nodes:
+        if "carbon dioxide" in node["name"].lower():
+            if "soil" in node.get("categories", []):
+                characterization_function_dict[node.id] = (
+                    characterize_co2_uptake  # negative emission because uptake by soil
+                )
+
+            else:
+                characterization_function_dict[node.id] = characterize_co2
+
+        elif (
+            "methane, fossil" in node["name"].lower()
+            or "methane, from soil or biomass stock" in node["name"].lower()
+        ):
+            # TODO Check why "methane, non-fossil" has a CF of 27 instead of 29.8, currently excluded
+            characterization_function_dict[node.id] = characterize_ch4
+
+        elif "dinitrogen monoxide" in node["name"].lower():
+            characterization_function_dict[node.id] = characterize_n2o
+
+        elif "carbon monoxide" in node["name"].lower():
+            characterization_function_dict[node.id] = characterize_co
+
+        else:
+            cas_number = node.get("CAS number")
+            if cas_number:
+                decay_series = decay_multipliers.get(cas_number)
+                if decay_series is not None:
+                    characterization_function_dict[node.id] = (
+                        create_generic_characterization_function(
+                            np.array(decay_series)
+                        )
+                    )
+    return characterization_function_dict
+
+def _get_default_co2_function() -> Callable:
+    """
+    Get the default CO2 characterization function from the (separate) dynamic_characterization package (https://dynamic-characterization.readthedocs.io/en/latest/).
+
+    Parameters
+    ----------
+    None
+
+    Returns
+    -------
+    Callable
+        Default CO2 characterization function
+    """
+    try:
+        from dynamic_characterization.timex.radiative_forcing import (
+            characterize_co2,
+        )
+    except ImportError:
+        raise ImportError(
+            "The default CO2 characterization function could not be loaded. Please make sure the package 'dynamic_characterization' (https://dynamic-characterization.readthedocs.io/en/latest/) is installed or provide your own function for the dynamic characterization of CO2. This is necessary for the GWP calculations."
+        )
+    warnings.warn(
+        "Using bw_timex's default CO2 characterization function for GWP reference."
+    )
+    return characterize_co2
+
+def _calculate_dynamic_time_horizon(
+    emission_date: pd.Timestamp,
+    time_horizon_start: pd.Timestamp,
+    time_horizon: int,
+    fixed_time_horizon: bool,
+) -> datetime:
+    """
+    Calculate the dynamic time horizon for the dynamic characterization of an emission.
+    Distinguishes between the Levasseur approach (fixed_time_horizon = True) and the conventional approach (fixed_time_horizon = False).
+
+    Parameters
+    ----------
+    emission_date: pd.Timestamp
+        The date of the emission
+    time_horizon_start: pd.Timestamp
+        Start timestamp of the time horizon
+    time_horizon: int
+        Length of the time horizon in years
+    fixed_time_horizon: bool
+        If True, the time horizon is calculated from the time of the functional unit (FU) instead of the time of emission
+
+    Returns
+    -------
+    datetime.datetime
+        dynamic time horizon for the specific emission
+    """
+    if fixed_time_horizon:
+        # Levasseur approach: time_horizon for all emissions starts at timing of FU + time_horizon
+        # e.g. an emission occuring n years before FU is characterized for time_horizon+n years
+        end_time_horizon = time_horizon_start + pd.DateOffset(years=time_horizon)
+        emission_datetime = emission_date.to_pydatetime()
+
+        return max(0, round((end_time_horizon - emission_datetime).days / 365.25))
+
+    else:
+        # conventional approach, emission is calculated from t emission for the length of time horizon
+        return time_horizon
+
+def _characterize_radiative_forcing(characterization_function_dict, row, time_horizon) -> Dict:
+    return characterization_function_dict[row.flow](row, time_horizon)
+
+def _characterize_gwp(
+    characterization_function_dict,
+    row,
+    original_time_horizon,
+    dynamic_time_horizon,
+    characterization_function_co2,
+) -> Dict:
+    radiative_forcing_ghg = characterization_function_dict[row.flow](
+        row,
+        dynamic_time_horizon,
+    )
+
+    # calculate reference radiative forcing for 1 kg of CO2
+    radiative_forcing_co2 = characterization_function_co2(
+        row._replace(amount=1), original_time_horizon
+    )
+
+    ghg_integral = radiative_forcing_ghg.amount.sum()
+    co2_integral = radiative_forcing_co2.amount.sum()
+    co2_equiv = ghg_integral / co2_integral
+
+    return {
+        "date": row.date,
+        "amount": co2_equiv,
+        "flow": row.flow,
+        "activity": row.activity,
+    }

dynamic_characterization-0.0.3/dynamic_characterization/temporalis/__init__.py

@@ -0,0 +1,15 @@
+"""
+Dynamic characterization functions from the bw_temporalis package (https://github.com/brightway-lca/bw_temporalis).
+"""
+
+__all__ = (
+    "__version__",
+    "characterize_co2",
+    "characterize_methane",
+    # Add functions and variables you want exposed in `dynamic_characterization.` namespace here
+)
+
+__version__ = "0.0.1"
+
+from .radiative_forcing import characterize_co2
+from .radiative_forcing import characterize_methane

dynamic_characterization-0.0.3/dynamic_characterization/temporalis/radiative_forcing.py

@@ -0,0 +1,137 @@
+import numpy as np
+import pandas as pd
+
+from dynamic_characterization.classes import CharacterizedRow
+
+
+def characterize_co2(
+    series,
+    period: int | None = 100,
+    cumulative: bool | None = False,
+) -> CharacterizedRow:
+    """
+    Calculate the cumulative or marginal radiative forcing (CRF) from CO2 for each year in a given period.
+
+    If `cumulative` is True, the cumulative CRF is calculated. If `cumulative` is False, the marginal CRF is calculated.
+    Takes a single row of the TimeSeries Pandas DataFrame (corresponding to a set of (`date`/`amount`/`flow`/`activity`).
+    For each year in the given period, the CRF is calculated.
+    Units are watts/square meter/kilogram of CO2.
+
+    Returns
+    -------
+    A TimeSeries dataframe with the following columns:
+    - date: datetime64[s]
+    - amount: float
+    - flow: str
+    - activity: str
+
+    Notes
+    -----
+    See also the relevant scientific publication on CRF: https://doi.org/10.5194/acp-13-2793-2013
+    See also the relevant scientific publication on the numerical calculation of CRF: http://pubs.acs.org/doi/abs/10.1021/acs.est.5b01118
+
+    See Also
+    --------
+    characterize_methane: The same function for CH4
+    """
+
+    # functional variables and units (from publications listed in docstring)
+    RE = 1.76e-15  # Radiative forcing (W/m2/kg)
+    alpha_0, alpha_1, alpha_2, alpha_3 = 0.2173, 0.2240, 0.2824, 0.2763
+    tau_1, tau_2, tau_3 = 394.4, 36.54, 4.304
+    decay_term = lambda year, alpha, tau: alpha * tau * (1 - np.exp(-year / tau))
+
+    date_beginning: np.datetime64 = series.date.to_numpy()
+    dates_characterized: np.ndarray = date_beginning + np.arange(
+        start=0, stop=period, dtype="timedelta64[Y]"
+    ).astype("timedelta64[s]")
+
+    decay_multipliers: np.ndarray = np.array(
+        [
+            RE
+            * (
+                alpha_0 * year
+                + decay_term(year, alpha_1, tau_1)
+                + decay_term(year, alpha_2, tau_2)
+                + decay_term(year, alpha_3, tau_3)
+            )
+            for year in range(period)
+        ]
+    )
+
+    forcing = pd.Series(data=series.amount * decay_multipliers, dtype="float64")
+    if not cumulative:
+        forcing = forcing.diff(periods=1).fillna(0)
+
+    return CharacterizedRow(
+        date=np.array(dates_characterized, dtype="datetime64[s]"),
+        amount=forcing,
+        flow=series.flow,
+        activity=series.activity,
+    )
+
+
+def characterize_methane(series, period: int = 100, cumulative=False) -> CharacterizedRow:
+    """
+    Calculate the cumulative or marginal radiative forcing (CRF) from CH4 for each year in a given period.
+
+    If `cumulative` is True, the cumulative CRF is calculated. If `cumulative` is False, the marginal CRF is calculated.
+    Takes a single row of the TimeSeries Pandas DataFrame (corresponding to a set of (`date`/`amount`/`flow`/`activity`).
+    For earch year in the given period, the CRF is calculated.
+    Units are watts/square meter/kilogram of CH4.
+
+    Parameters
+    ----------
+    series : array-like
+        A single row of the TimeSeries dataframe.
+    period : int, optional
+        Time period for calculation (number of years), by default 100
+    cumulative : bool, optional
+        Should the RF amounts be summed over time?
+
+    Returns
+    -------
+    A TimeSeries dataframe with the following columns:
+    - date: datetime64[s]
+    - amount: float
+    - flow: str
+    - activity: str
+
+    Notes
+    -----
+    See also the relevant scientific publication on CRF: https://doi.org/10.5194/acp-13-2793-2013
+    See also the relevant scientific publication on the numerical calculation of CRF: http://pubs.acs.org/doi/abs/10.1021/acs.est.5b01118
+
+    See Also
+    --------
+    characterize_co2: The same function for CO2
+    """
+
+    # functional variables and units (from publications listed in docstring)
+    f1 = 0.5  # Unitless
+    f2 = 0.15  # Unitless
+    alpha = 1.27e-13  # Radiative forcing (W/m2/kg)
+    tau = 12.4  # Lifetime (years)
+
+    date_beginning: np.datetime64 = series.date.to_numpy()
+    dates_characterized: np.ndarray = date_beginning + np.arange(
+        start=0, stop=period, dtype="timedelta64[Y]"
+    ).astype("timedelta64[s]")
+
+    decay_multipliers: list = np.array(
+        [
+            (1 + f1 + f2) * alpha * tau * (1 - np.exp(-year / tau))
+            for year in range(period)
+        ]
+    )
+
+    forcing = pd.Series(data=series.amount * decay_multipliers, dtype="float64")
+    if not cumulative:
+        forcing = forcing.diff(periods=1).fillna(0)
+
+    return CharacterizedRow(
+        date=np.array(dates_characterized, dtype="datetime64[s]"),
+        amount=forcing,
+        flow=series.flow,
+        activity=series.activity,
+    )

dynamic_characterization-0.0.3/dynamic_characterization/timex/__init__.py

@@ -0,0 +1,23 @@
+"""
+Dynamic characterization functions from the bw_timex package (https://github.com/brightway-lca/bw_timex).
+"""
+
+__all__ = (
+    "__version__",
+    "characterize_co2",
+    "characterize_co2_uptake",
+    "characterize_co",
+    "characterize_ch4",
+    "characterize_n2o",
+    "create_generic_characterization_function",
+    # Add functions and variables you want exposed in `dynamic_characterization.` namespace here
+)
+
+__version__ = "0.0.1"
+
+from .radiative_forcing import characterize_co2
+from .radiative_forcing import characterize_co2_uptake
+from .radiative_forcing import characterize_co
+from .radiative_forcing import characterize_ch4
+from .radiative_forcing import characterize_n2o
+from .radiative_forcing import create_generic_characterization_function

dynamic_characterization-0.0.3/dynamic_characterization/timex/radiative_forcing.py

@@ -0,0 +1,471 @@
+import pandas as pd
+import numpy as np
+
+from dynamic_characterization.classes import CharacterizedRow
+
+
+def IRF_co2(year) -> callable:
+    """
+    Impulse Resonse Function (IRF) of CO2
+
+    Parameters
+    ----------
+    year : int
+        The year after emission for which the IRF is calculated.
+
+    Returns
+    -------
+    float
+        The IRF value for the given year.
+
+    """
+    alpha_0, alpha_1, alpha_2, alpha_3 = 0.2173, 0.2240, 0.2824, 0.2763
+    tau_1, tau_2, tau_3 = 394.4, 36.54, 4.304
+    exponentials = lambda year, alpha, tau: alpha * tau * (1 - np.exp(-year / tau))
+    return (
+        alpha_0 * year
+        + exponentials(year, alpha_1, tau_1)
+        + exponentials(year, alpha_2, tau_2)
+        + exponentials(year, alpha_3, tau_3)
+    )
+
+
+def characterize_co2(
+    series,
+    period: int | None = 100,
+    cumulative: bool | None = False,
+) -> CharacterizedRow:
+    """
+    Calculate the cumulative or marginal radiative forcing (CRF) from CO2 for each year in a given period.
+
+    Based on characterize_co2 from bw_temporalis, but updated numerical values from IPCC AR6 Ch7 & SM.
+
+    If `cumulative` is True, the cumulative CRF is calculated. If `cumulative` is False, the marginal CRF is calculated.
+    Takes a single row of the TimeSeries Pandas DataFrame (corresponding to a set of (`date`/`amount`/`flow`/`activity`).
+    For each year in the given period, the CRF is calculated.
+    Units are watts/square meter/kilogram of CO2.
+
+    Returns
+    -------
+    A TimeSeries dataframe with the following columns:
+    - date: datetime64[s]
+    - amount: float
+    - flow: str
+    - activity: str
+
+    See also
+    --------
+    Joos2013: Relevant scientific publication on CRF: https://doi.org/10.5194/acp-13-2793-2013
+    Schivley2015: Relevant scientific publication on the numerical calculation of CRF: https://doi.org/10.1021/acs.est.5b01118
+    Forster2023: Updated numerical values from IPCC AR6 Chapter 7 (Table 7.15): https://doi.org/10.1017/9781009157896.009
+    """
+
+    # functional variables and units (from publications listed in docstring)
+    radiative_efficiency_ppb = (
+        1.33e-5  # W/m2/ppb; 2019 background co2 concentration; IPCC AR6 Table 7.15
+    )
+
+    # for conversion from ppb to kg-CO2
+    M_co2 = 44.01  # g/mol
+    M_air = 28.97  # g/mol, dry air
+    m_atmosphere = 5.135e18  # kg [Trenberth and Smith, 2005]
+
+    radiative_efficiency_kg = (
+        radiative_efficiency_ppb * M_air / M_co2 * 1e9 / m_atmosphere
+    )  # W/m2/kg-CO2
+
+    date_beginning: np.datetime64 = series.date.to_numpy()
+    dates_characterized: np.ndarray = date_beginning + np.arange(
+        start=0, stop=period, dtype="timedelta64[Y]"
+    ).astype("timedelta64[s]")
+
+    decay_multipliers: np.ndarray = np.array(
+        [radiative_efficiency_kg * IRF_co2(year) for year in range(period)]
+    )
+
+    forcing = np.array(series.amount * decay_multipliers, dtype="float64")
+
+    if not cumulative:
+        forcing = np.diff(forcing, prepend=0)
+
+    return CharacterizedRow(
+        date=np.array(dates_characterized, dtype="datetime64[s]"),
+        amount=forcing,
+        flow=series.flow,
+        activity=series.activity,
+    )
+
+
+def characterize_co2_uptake(
+    series,
+    period: int | None = 100,
+    cumulative: bool | None = False,
+) -> CharacterizedRow:
+    """
+    The same as characterize_co2, but with a negative sign for uptake of CO2.
+
+    Based on characterize_co2 from bw_temporalis, but updated numerical values from IPCC AR6 Ch7 & SM.
+
+    Calculate the negative cumulative or marginal radiative forcing (CRF) from CO2-uptake for each year in a given period.
+
+    If `cumulative` is True, the cumulative CRF is calculated. If `cumulative` is False, the marginal CRF is calculated.
+    Takes a single row of the TimeSeries Pandas DataFrame (corresponding to a set of (`date`/`amount`/`flow`/`activity`).
+    For each year in the given period, the CRF is calculated.
+    Units are watts/square meter/kilogram of CO2.
+
+    Returns
+    -------
+    A TimeSeries dataframe with the following columns:
+    - date: datetime64[s]
+    - amount: float
+    - flow: str
+    - activity: str
+
+    See also
+    --------
+    Joos2013: Relevant scientific publication on CRF: https://doi.org/10.5194/acp-13-2793-2013
+    Schivley2015: Relevant scientific publication on the numerical calculation of CRF: https://doi.org/10.1021/acs.est.5b01118
+    Forster2023: Updated numerical values from IPCC AR6 Chapter 7 (Table 7.15): https://doi.org/10.1017/9781009157896.009
+    """
+
+    # functional variables and units (from publications listed in docstring)
+    radiative_efficiency_ppb = (
+        1.33e-5  # W/m2/ppb; 2019 background co2 concentration; IPCC AR6 Table 7.15
+    )
+
+    # for conversion from ppb to kg-CO2
+    M_co2 = 44.01  # g/mol
+    M_air = 28.97  # g/mol, dry air
+    m_atmosphere = 5.135e18  # kg [Trenberth and Smith, 2005]
+
+    radiative_efficiency_kg = (
+        radiative_efficiency_ppb * M_air / M_co2 * 1e9 / m_atmosphere
+    )  # W/m2/kg-CO2
+
+    date_beginning: np.datetime64 = series.date.to_numpy()
+    dates_characterized: np.ndarray = date_beginning + np.arange(
+        start=0, stop=period, dtype="timedelta64[Y]"
+    ).astype("timedelta64[s]")
+
+    decay_multipliers: np.ndarray = np.array(
+        [radiative_efficiency_kg * IRF_co2(year) for year in range(period)]
+    )
+
+    forcing = np.array(series.amount * decay_multipliers, dtype="float64")
+
+    # flip the sign of the characterization function for CO2 uptake and not release
+    forcing = -forcing
+
+    if not cumulative:
+        forcing = np.diff(forcing, prepend=0)
+
+    return CharacterizedRow(
+        date=np.array(dates_characterized, dtype="datetime64[s]"),
+        amount=forcing,
+        flow=series.flow,
+        activity=series.activity,
+    )
+
+
+def characterize_co(
+    series,
+    period: int | None = 100,
+    cumulative: bool | None = False,
+) -> CharacterizedRow:
+    """
+    Calculate the cumulative or marginal radiative forcing (CRF) from CO for each year in a given period.
+
+    This is exactly the same function as for CO2, it's just scaled by the ratio of molar masses of CO and CO2. This is because CO is very short-lived (lifetime ~2 months) and we assume that it completely reacts to CO2 within the first year.
+
+    Based on characterize_co2 from bw_temporalis, but updated numerical values from IPCC AR6 Ch7 & SM.
+
+    Calculate the cumulative or marginal radiative forcing (CRF) from CO2 for each year in a given period.
+
+    If `cumulative` is True, the cumulative CRF is calculated. If `cumulative` is False, the marginal CRF is calculated.
+    Takes a single row of the TimeSeries Pandas DataFrame (corresponding to a set of (`date`/`amount`/`flow`/`activity`).
+    For each year in the given period, the CRF is calculated.
+    Units are watts/square meter/kilogram of CO2.
+
+    Returns
+    -------
+    A TimeSeries dataframe with the following columns:
+    - date: datetime64[s]
+    - amount: float
+    - flow: str
+    - activity: str
+
+    See also
+    --------
+    Joos2013: Relevant scientific publication on CRF: https://doi.org/10.5194/acp-13-2793-2013
+    Schivley2015: Relevant scientific publication on the numerical calculation of CRF: https://doi.org/10.1021/acs.est.5b01118
+    Forster2023: Updated numerical values from IPCC AR6 Chapter 7 (Table 7.15): https://doi.org/10.1017/9781009157896.009
+    """
+
+    # functional variables and units (from publications listed in docstring)
+    radiative_efficiency_ppb = (
+        1.33e-5  # W/m2/ppb; 2019 background co2 concentration; IPCC AR6 Table 7.15
+    )
+
+    # for conversion from ppb to kg-CO2
+    M_co2 = 44.01  # g/mol
+    M_co = 28.01  # g/mol
+    M_air = 28.97  # g/mol, dry air
+    m_atmosphere = 5.135e18  # kg [Trenberth and Smith, 2005]
+
+    radiative_efficiency_kg = (
+        radiative_efficiency_ppb * M_air / M_co2 * 1e9 / m_atmosphere
+    )  # W/m2/kg-CO2
+
+    date_beginning: np.datetime64 = series.date.to_numpy()
+    dates_characterized: np.ndarray = date_beginning + np.arange(
+        start=0, stop=period, dtype="timedelta64[Y]"
+    ).astype("timedelta64[s]")
+
+    decay_multipliers: np.ndarray = np.array(
+        [
+            M_co2 / M_co * radiative_efficiency_kg * IRF_co2(year)
+            for year in range(period)
+        ]  # <-- Scaling from co2 to co is done here
+    )
+
+    forcing = np.array(series.amount * decay_multipliers, dtype="float64")
+
+    if not cumulative:
+        forcing = np.diff(forcing, prepend=0)
+
+    return CharacterizedRow(
+        date=np.array(dates_characterized, dtype="datetime64[s]"),
+        amount=forcing,
+        flow=series.flow,
+        activity=series.activity,
+    )
+
+
+def characterize_ch4(
+    series,
+    period: int = 100,
+    cumulative=False,
+) -> CharacterizedRow:
+    """
+    Calculate the cumulative or marginal radiative forcing (CRF) from CH4 for each year in a given period.
+
+    Based on characterize_methane from bw_temporalis, but updated numerical values from IPCC AR6 Ch7 & SM.
+
+    This DOES include indirect effects of CH4 on ozone and water vapor, but DOES NOT include the decay to CO2.
+    For more info on that, see the deprecated version of bw_temporalis.
+
+    If `cumulative` is True, the cumulative CRF is calculated. If `cumulative` is False, the marginal CRF is calculated.
+    Takes a single row of the TimeSeries Pandas DataFrame (corresponding to a set of (`date`/`amount`/`flow`/`activity`).
+    For earch year in the given period, the CRF is calculated.
+    Units are watts/square meter/kilogram of CH4.
+
+    Parameters
+    ----------
+    series : array-like
+        A single row of the TimeSeries dataframe.
+    period : int, optional
+        Time period for calculation (number of years), by default 100
+    cumulative : bool, optional
+        Should the RF amounts be summed over time?
+
+    Returns
+    -------
+    A TimeSeries dataframe with the following columns:
+    - date: datetime64[s]
+    - amount: float
+    - flow: str
+    - activity: str
+
+    See also
+    --------
+    Joos2013: Relevant scientific publication on CRF: https://doi.org/10.5194/acp-13-2793-2013
+    Schivley2015: Relevant scientific publication on the numerical calculation of CRF: https://doi.org/10.1021/acs.est.5b01118
+    Forster2023: Updated numerical values from IPCC AR6 Chapter 7 (Table 7.15): https://doi.org/10.1017/9781009157896.009
+    """
+
+    # functional variables and units (from publications listed in docstring)
+    radiative_efficiency_ppb = 5.7e-4  # # W/m2/ppb; 2019 background cch4 concentration; IPCC AR6 Table 7.15. This number includes indirect effects.
+
+    # for conversion from ppb to kg-CH4
+    M_ch4 = 16.04  # g/mol
+    M_air = 28.97  # g/mol, dry air
+    m_atmosphere = 5.135e18  # kg [Trenberth and Smith, 2005]
+
+    radiative_efficiency_kg = (
+        radiative_efficiency_ppb * M_air / M_ch4 * 1e9 / m_atmosphere
+    )  # W/m2/kg-CH4
+
+    tau = 11.8  # Lifetime (years)
+
+    date_beginning: np.datetime64 = series.date.to_numpy()
+    dates_characterized: np.ndarray = date_beginning + np.arange(
+        start=0, stop=period, dtype="timedelta64[Y]"
+    ).astype("timedelta64[s]")
+
+    decay_multipliers: list = np.array(
+        [
+            radiative_efficiency_kg * tau * (1 - np.exp(-year / tau))
+            for year in range(period)
+        ]
+    )
+
+    forcing = np.array(series.amount * decay_multipliers, dtype="float64")
+
+    if not cumulative:
+        forcing = np.diff(forcing, prepend=0)
+
+    return CharacterizedRow(
+        date=np.array(dates_characterized, dtype="datetime64[s]"),
+        amount=forcing,
+        flow=series.flow,
+        activity=series.activity,
+    )
+
+
+def characterize_n2o(
+    series,
+    period: int = 100,
+    cumulative=False,
+) -> CharacterizedRow:
+    """
+    Calculate the cumulative or marginal radiative forcing (CRF) from N2O for each year in a given period.
+
+    Based on characterize_methane from bw_temporalis, but updated numerical values from IPCC AR6 Ch7 & SM.
+
+    If `cumulative` is True, the cumulative CRF is calculated. If `cumulative` is False, the marginal CRF is calculated.
+    Takes a single row of the TimeSeries Pandas DataFrame (corresponding to a set of (`date`/`amount`/`flow`/`activity`).
+    For earch year in the given period, the CRF is calculated.
+    Units are watts/square meter/kilogram of N2O.
+
+    Parameters
+    ----------
+    series : array-like
+        A single row of the TimeSeries dataframe.
+    period : int, optional
+        Time period for calculation (number of years), by default 100
+    cumulative : bool, optional
+        Should the RF amounts be summed over time?
+
+    Returns
+    -------
+    A TimeSeries dataframe with the following columns:
+    - date: datetime64[s]
+    - amount: float
+    - flow: str
+    - activity: str
+
+    See also
+    --------
+    Joos2013: Relevant scientific publication on CRF: https://doi.org/10.5194/acp-13-2793-2013
+    Schivley2015: Relevant scientific publication on the numerical calculation of CRF: https://doi.org/10.1021/acs.est.5b01118
+    Forster2023: Updated numerical values from IPCC AR6 Chapter 7 (Table 7.15): https://doi.org/10.1017/9781009157896.009
+    """
+
+    # functional variables and units (from publications listed in docstring)
+    radiative_efficiency_ppb = 2.8e-3  # # W/m2/ppb; 2019 background cch4 concentration; IPCC AR6 Table 7.15. This number includes indirect effects.
+
+    # for conversion from ppb to kg-CH4
+    M_n2o = 44.01  # g/mol
+    M_air = 28.97  # g/mol, dry air
+    m_atmosphere = 5.135e18  # kg [Trenberth and Smith, 2005]
+
+    radiative_efficiency_kg = (
+        radiative_efficiency_ppb * M_air / M_n2o * 1e9 / m_atmosphere
+    )  # W/m2/kg-N2O
+
+    tau = 109  # Lifetime (years)
+
+    date_beginning: np.datetime64 = series.date.to_numpy()
+    dates_characterized: np.ndarray = date_beginning + np.arange(
+        start=0, stop=period, dtype="timedelta64[Y]"
+    ).astype("timedelta64[s]")
+
+    decay_multipliers: list = np.array(
+        [
+            radiative_efficiency_kg * tau * (1 - np.exp(-year / tau))
+            for year in range(period)
+        ]
+    )
+
+    forcing = np.array(series.amount * decay_multipliers, dtype="float64")
+    if not cumulative:
+        forcing = np.diff(forcing, prepend=0)
+
+    return CharacterizedRow(
+        date=np.array(dates_characterized, dtype="datetime64[s]"),
+        amount=forcing,
+        flow=series.flow,
+        activity=series.activity,
+    )
+
+
+def create_generic_characterization_function(decay_series) -> CharacterizedRow:
+    """
+    Creates a characterization function for a GHG based on a decay series, by calling the nested method `characterize_generic()`.
+
+    Parameters
+    ----------
+    decay_series : np.ndarray
+        A decay series for a specific GHG. This is retrieved from `../data/decay_multipliers.pkl`
+
+    Returns
+    -------
+    A function called `characterize_generic`, which in turn returns a TimeSeries dataframe that contains the forcing of the emission of the row over the given period based on the decay series of that biosphere flow.
+
+    """
+
+    def characterize_generic(
+        series,
+        period: int = 100,
+        cumulative=False,
+    ) -> CharacterizedRow:
+        """
+        Uses lookup generated in /dev/calculate_metrics.ipynb
+        Data originates from https://doi.org/10.1029/2019RG000691
+
+        Parameters
+        ----------
+        series : array-like
+            A single row of the dynamic inventory dataframe.
+        period : int, optional
+            Time period for calculation (number of years), by default 100
+        cumulative : bool,
+            cumulative impact
+
+        Returns
+        -------
+        A TimeSeries dataframe that contains the forcing of the point emission from the row for each year in the given period.
+          date: datetime64[s]
+          amount: float (forcing at this timestep)
+          flow: str
+          activity: str
+
+        See also
+        --------
+        Joos2013: Relevant scientific publication on CRF: https://doi.org/10.5194/acp-13-2793-2013
+        Schivley2015: Relevant scientific publication on the numerical calculation of CRF: https://doi.org/10.1021/acs.est.5b01118
+        Forster2023: Updated numerical values from IPCC AR6 Chapter 7 (Table 7.15): https://doi.org/10.1017/9781009157896.009
+
+        """
+
+        date_beginning: np.datetime64 = series.date.to_numpy()
+
+        dates_characterized: np.ndarray = date_beginning + np.arange(
+            start=0, stop=period, dtype="timedelta64[Y]"
+        ).astype("timedelta64[s]")
+
+        decay_multipliers = decay_series[:period]
+
+        forcing = np.array(series.amount * decay_multipliers, dtype="float64")
+
+        if not cumulative:
+            forcing = np.diff(forcing, prepend=0)
+
+        return CharacterizedRow(
+            date=np.array(dates_characterized, dtype="datetime64[s]"),
+            amount=forcing,
+            flow=series.flow,
+            activity=series.activity,
+        )
+
+    return characterize_generic

{dynamic_characterization-0.0.1.dev1 → dynamic_characterization-0.0.3/dynamic_characterization.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dynamic_characterization
-Version: 0.0.1.dev1
+Version: 0.0.3
 Summary: Collection of dynamic characterization functions for life cycle inventories with temporal information
 Author-email: Timo Diepers <timo.diepers@ltt.rwth-aachen.de>
 Maintainer-email: Timo Diepers <timo.diepers@ltt.rwth-aachen.de>
@@ -20,6 +20,9 @@ Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: bw2data
 Provides-Extra: testing
 Requires-Dist: dynamic_characterization; extra == "testing"
 Requires-Dist: pytest; extra == "testing"
@@ -76,11 +79,12 @@ Here's an example of what such a function could look like:
 
 ```python
 def characterize_something(series, period: int = 100, cumulative=False) -> pd.DataFrame:
-    date_beginning: np.datetime64 = series["date"].to_numpy()
-    date_characterized: np.ndarray = date_beginning + np.arange(
+    date_beginning: np.datetime64 = series.date.to_numpy()
+    dates_characterized: np.ndarray = date_beginning + np.arange(
         start=0, stop=period, dtype="timedelta64[Y]"
     ).astype("timedelta64[s]")
 
+    # let's assume some simple decay function
     decay_multipliers: list = np.array(
         [
             1.234 * (1 - np.exp(-year / 56.789))
@@ -88,13 +92,14 @@ def characterize_something(series, period: int = 100, cumulative=False) -> pd.Da
         ]
     )
 
-    forcing = pd.Series(data=series.amount * decay_multipliers, dtype="float64")
+    forcing = np.array(series.amount * decay_multipliers, dtype="float64")
+
     if not cumulative:
-        forcing = forcing.diff(periods=1).fillna(0)
+        forcing = np.diff(forcing, prepend=0)
 
     return pd.DataFrame(
         {
-            "date": pd.Series(data=date_characterized, dtype="datetime64[s]"),
+            "date": np.array(dates_characterized, dtype="datetime64[s]"),
             "amount": forcing,
             "flow": series.flow,
             "activity": series.activity,
@@ -131,6 +136,9 @@ _dynamic_characterization_ is free and open source software.
 If you encounter any problems,
 please [file an issue][Issue Tracker] along with a detailed description.
 
+## Support
+
+If you have any questions or need help, do not hesitate to contact Timo Diepers ([timo.diepers@ltt.rwth-aachen.de](mailto:timo.diepers@ltt.rwth-aachen.de))
 
 <!-- github-only -->
 

dynamic_characterization-0.0.3/dynamic_characterization.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+dynamic_characterization/__init__.py
+dynamic_characterization/classes.py
+dynamic_characterization/dynamic_characterization.py
+dynamic_characterization.egg-info/PKG-INFO
+dynamic_characterization.egg-info/SOURCES.txt
+dynamic_characterization.egg-info/dependency_links.txt
+dynamic_characterization.egg-info/requires.txt
+dynamic_characterization.egg-info/top_level.txt
+dynamic_characterization/temporalis/__init__.py
+dynamic_characterization/temporalis/radiative_forcing.py
+dynamic_characterization/timex/__init__.py
+dynamic_characterization/timex/radiative_forcing.py

{dynamic_characterization-0.0.1.dev1 → dynamic_characterization-0.0.3}/dynamic_characterization.egg-info/requires.txt

@@ -1,3 +1,6 @@
+pandas
+numpy
+bw2data
 
 [dev]
 build

{dynamic_characterization-0.0.1.dev1 → dynamic_characterization-0.0.3}/pyproject.toml

@@ -31,6 +31,9 @@ requires-python = ">=3.9"
 dependencies = [
     # dependencies as strings with quotes, e.g. "foo"
     # You can add version requirements like "foo>2.0"
+    "pandas",
+    "numpy",
+    "bw2data",
 ]
 
 [project.urls]
@@ -60,7 +63,11 @@ dev = [
 [tool.setuptools]
 license-files = ["LICENSE"]
 include-package-data = true
-packages = ["dynamic_characterization"]
+packages = [
+    "dynamic_characterization", 
+    "dynamic_characterization.temporalis", 
+    "dynamic_characterization.timex",
+    ]
 
 [tool.setuptools.dynamic]
 version = {attr = "dynamic_characterization.__version__"}

dynamic_characterization-0.0.1.dev1/dynamic_characterization.egg-info/SOURCES.txt

@@ -1,10 +0,0 @@
-LICENSE
-MANIFEST.in
-README.md
-pyproject.toml
-dynamic_characterization/__init__.py
-dynamic_characterization.egg-info/PKG-INFO
-dynamic_characterization.egg-info/SOURCES.txt
-dynamic_characterization.egg-info/dependency_links.txt
-dynamic_characterization.egg-info/requires.txt
-dynamic_characterization.egg-info/top_level.txt