dynamic-characterization 0.0.1.dev0__tar.gz → 0.0.2__tar.gz

dynamic_characterization-0.0.2/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.1
+Name: dynamic_characterization
+Version: 0.0.2
+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>
+Project-URL: source, https://github.com/TimoDiepers/dynamic_characterization
+Project-URL: homepage, https://github.com/TimoDiepers/dynamic_characterization
+Project-URL: tracker, https://github.com/TimoDiepers/dynamic_characterization/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas
+Requires-Dist: numpy
+Provides-Extra: testing
+Requires-Dist: dynamic_characterization; extra == "testing"
+Requires-Dist: pytest; extra == "testing"
+Requires-Dist: pytest-cov; extra == "testing"
+Requires-Dist: python-coveralls; extra == "testing"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-randomly; extra == "dev"
+Requires-Dist: setuptools; extra == "dev"
+
+# dynamic_characterization
+
+[![Read the Docs](https://img.shields.io/readthedocs/timex?label=documentation)](https://dynamic-characterization.readthedocs.io/en/latest/)
+[![PyPI - Version](https://img.shields.io/pypi/v/dynamic-characterization?color=%2300549f)](https://pypi.org/project/dynamic-characterization/)
+[![Conda Version](https://img.shields.io/conda/v/diepers/dynamic_characterization?label=conda)](https://anaconda.org/diepers/dynamic_characterization)
+![Conda - License](https://img.shields.io/conda/l/diepers/bw_timex)
+
+This is a collection of dynamic characterization functions for life cycle inventories with temporal information. 
+
+Here's an overview of what is currently included:
+
+| impact category | metric | covered emissions | source
+|-------|----------|----------|--|
+| climate change | radiative forcing | CO2, CH4 |[bw_temporalis](https://github.com/brightway-lca/bw_temporalis/tree/main)|
+| climate change | radiative forcing | 247 GHGs from [IPCC AR6 Ch.7](https://www.ipcc.ch/report/ar6/wg1/chapter/chapter-7/) |[bw_timex](https://github.com/brightway-lca/bw_timex/tree/main)|
+
+## What do dynamic characterization functions do?
+
+The functions are meant to work with a common input format of the dynamic inventory, collected in a pandas DataFrame that looks like this:
+
+| date | amount | flow | activity |
+|-------|-------|------|----------|
+| 101   | 33    | 1    | 2        |
+| 312   | 21    | 4    | 2        |
+
+Each function takes one row of this dynamic inventory dataframe (i.e. one emission at one point in time) and transform it according to some metric. The output generated by applying a very simple function to both rows of the input dataframe could look like:
+
+| date | amount | flow | activity |
+|------|--------|------|----------|
+| 101  | 33     | 1    | 2        |
+| 102  | 31     | 1    | 2        |
+| 103  | 31     | 1    | 2        |
+| 312  | 21     | 4    | 2        |
+| 313  | 20     | 4    | 2        |
+| 314  | 19     | 4    | 2        |
+
+## What do dynamic characterization functions look like?
+
+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(
+        start=0, stop=period, dtype="timedelta64[Y]"
+    ).astype("timedelta64[s]")
+
+    decay_multipliers: list = np.array(
+        [
+            1.234 * (1 - np.exp(-year / 56.789))
+            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 pd.DataFrame(
+        {
+            "date": pd.Series(data=date_characterized, dtype="datetime64[s]"),
+            "amount": forcing,
+            "flow": series.flow,
+            "activity": series.activity,
+        }
+    )
+````
+
+## Installation
+
+You can install `dynamic_characterization` via [pip] from [PyPI]:
+
+```console
+$ pip install dynamic_characterization
+```
+
+Alternatively, you can also use conda:
+
+```console
+$ conda install -c diepers dynamic_characterization
+```
+
+## Contributing
+
+Contributions are very welcome.
+To learn more, see the [Contributor Guide][Contributor Guide].
+
+## License
+
+Distributed under the terms of the [BSD 3 Clause license][License],
+_dynamic_characterization_ is free and open source software.
+
+## Issues
+
+If you encounter any problems,
+please [file an issue][Issue Tracker] along with a detailed description.
+
+
+<!-- github-only -->
+
+[command-line reference]: https://dynamic-characterization.readthedocs.io/en/latest/usage.html
+[License]: https://github.com/TimoDiepers/dynamic_characterization/blob/main/LICENSE
+[Contributor Guide]: https://github.com/TimoDiepers/dynamic_characterization/blob/main/CONTRIBUTING.md
+[Issue Tracker]: https://github.com/TimoDiepers/dynamic_characterization/issues

dynamic_characterization-0.0.2/README.md

@@ -0,0 +1,104 @@
+# dynamic_characterization
+
+[![Read the Docs](https://img.shields.io/readthedocs/timex?label=documentation)](https://dynamic-characterization.readthedocs.io/en/latest/)
+[![PyPI - Version](https://img.shields.io/pypi/v/dynamic-characterization?color=%2300549f)](https://pypi.org/project/dynamic-characterization/)
+[![Conda Version](https://img.shields.io/conda/v/diepers/dynamic_characterization?label=conda)](https://anaconda.org/diepers/dynamic_characterization)
+![Conda - License](https://img.shields.io/conda/l/diepers/bw_timex)
+
+This is a collection of dynamic characterization functions for life cycle inventories with temporal information. 
+
+Here's an overview of what is currently included:
+
+| impact category | metric | covered emissions | source
+|-------|----------|----------|--|
+| climate change | radiative forcing | CO2, CH4 |[bw_temporalis](https://github.com/brightway-lca/bw_temporalis/tree/main)|
+| climate change | radiative forcing | 247 GHGs from [IPCC AR6 Ch.7](https://www.ipcc.ch/report/ar6/wg1/chapter/chapter-7/) |[bw_timex](https://github.com/brightway-lca/bw_timex/tree/main)|
+
+## What do dynamic characterization functions do?
+
+The functions are meant to work with a common input format of the dynamic inventory, collected in a pandas DataFrame that looks like this:
+
+| date | amount | flow | activity |
+|-------|-------|------|----------|
+| 101   | 33    | 1    | 2        |
+| 312   | 21    | 4    | 2        |
+
+Each function takes one row of this dynamic inventory dataframe (i.e. one emission at one point in time) and transform it according to some metric. The output generated by applying a very simple function to both rows of the input dataframe could look like:
+
+| date | amount | flow | activity |
+|------|--------|------|----------|
+| 101  | 33     | 1    | 2        |
+| 102  | 31     | 1    | 2        |
+| 103  | 31     | 1    | 2        |
+| 312  | 21     | 4    | 2        |
+| 313  | 20     | 4    | 2        |
+| 314  | 19     | 4    | 2        |
+
+## What do dynamic characterization functions look like?
+
+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(
+        start=0, stop=period, dtype="timedelta64[Y]"
+    ).astype("timedelta64[s]")
+
+    decay_multipliers: list = np.array(
+        [
+            1.234 * (1 - np.exp(-year / 56.789))
+            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 pd.DataFrame(
+        {
+            "date": pd.Series(data=date_characterized, dtype="datetime64[s]"),
+            "amount": forcing,
+            "flow": series.flow,
+            "activity": series.activity,
+        }
+    )
+````
+
+## Installation
+
+You can install `dynamic_characterization` via [pip] from [PyPI]:
+
+```console
+$ pip install dynamic_characterization
+```
+
+Alternatively, you can also use conda:
+
+```console
+$ conda install -c diepers dynamic_characterization
+```
+
+## Contributing
+
+Contributions are very welcome.
+To learn more, see the [Contributor Guide][Contributor Guide].
+
+## License
+
+Distributed under the terms of the [BSD 3 Clause license][License],
+_dynamic_characterization_ is free and open source software.
+
+## Issues
+
+If you encounter any problems,
+please [file an issue][Issue Tracker] along with a detailed description.
+
+
+<!-- github-only -->
+
+[command-line reference]: https://dynamic-characterization.readthedocs.io/en/latest/usage.html
+[License]: https://github.com/TimoDiepers/dynamic_characterization/blob/main/LICENSE
+[Contributor Guide]: https://github.com/TimoDiepers/dynamic_characterization/blob/main/CONTRIBUTING.md
+[Issue Tracker]: https://github.com/TimoDiepers/dynamic_characterization/issues

{dynamic_characterization-0.0.1.dev0 → dynamic_characterization-0.0.2}/dynamic_characterization/__init__.py

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

dynamic_characterization-0.0.2/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.2/dynamic_characterization/temporalis/radiative_forcing.py

@@ -0,0 +1,139 @@
+import numpy as np
+import pandas as pd
+
+
+def characterize_co2(
+    series,
+    period: int | None = 100,
+    cumulative: bool | None = False,
+) -> pd.DataFrame:
+    """
+    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()
+    date_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 pd.DataFrame(
+        {
+            "date": pd.Series(data=date_characterized, dtype="datetime64[s]"),
+            "amount": forcing,
+            "flow": series.flow,
+            "activity": series.activity,
+        }
+    )
+
+
+def characterize_methane(series, period: int = 100, cumulative=False) -> pd.DataFrame:
+    """
+    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()
+    date_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 pd.DataFrame(
+        {
+            "date": pd.Series(data=date_characterized, dtype="datetime64[s]"),
+            "amount": forcing,
+            "flow": series.flow,
+            "activity": series.activity,
+        }
+    )

dynamic_characterization-0.0.2/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