dynamic-characterization 1.3.1
Collection of functions for characterizing life cycle inventories with temporal information
Requires Python: >=3.9

# 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)
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/brightway-lca/dynamic_characterization/main?labpath=notebooks%2Fdynamic_characterization_demo.ipynb)

This is a package for the dynamic characterization of Life Cycle Inventories with temporal information. It includes a collection of dynamic characterization functions for various environmental flows. We also provide a simple interface to apply these functions to an existing dynamic LCI (coming from, e.g., [bw_temporalis](https://github.com/brightway-lca/bw_temporalis) or [bw_timex](https://github.com/brightway-lca/bw_timex)).

The following dynamic characterization functions are currently included:

| module |impact category | metric | covered emissions | source
|--------|-------|----------|----------|--|
| ipcc_ar6 | climate change | radiative forcing, GWP | 247 GHGs | radiative efficiencies & lifetimes from [IPCC AR6 Ch.7](https://www.ipcc.ch/report/ar6/wg1/chapter/chapter-7/) |
| prospective | climate change | prospective_radiative_forcing, pGWP, pGTP | CO2, CH4, N2O | prospective characterization factors from [Barbosa Watanabe et al. (2026)](https://pubs.acs.org/doi/10.1021/acs.est.5c12391) |
| original_temporalis_functions| climate change | radiative forcing | CO2, CH4 |[bw_temporalis](https://github.com/brightway-lca/bw_temporalis/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        |

## How do I use this package?

The workflow could look like this:

```python
import pandas as pd
from dynamic_characterization import characterize
from dynamic_characterization.ipcc_ar6 import characterize_co2, characterize_ch4

# defining a dummy dynamic inventory that you somehow got
dynamic_inventory_df = pd.DataFrame(
        data={
            "date": pd.Series(
                data=[
                    "15-12-2020",
                    "20-12-2020",
                    "25-05-2022",
                ],
                dtype="datetime64[s]",
            ),
            "amount": pd.Series(data=[10.0, 20.0, 50.0], dtype="float64"),
            "flow": pd.Series(data=[1, 1, 3], dtype="int"),
            "activity": pd.Series(data=[2, 2, 4], dtype="int"),
        }
    )

df_characterized = characterize(
        dynamic_inventory_df,
        metric="radiative_forcing", # could also be GWP
        characterization_functions={
            1: characterize_co2,
            3: characterize_ch4,
        },
        time_horizon=2,
    )
```

If you use this package with [Brightway](https://docs.brightway.dev/en/latest/), stuff can get even easier: if you have an impact assessment method at hand, you can pass it to the characterize function via the `base_lcia_method` attribute and we'll try to automatically match the flows that are characterized in that method to the flows we have characterization functions for. This matching is based on the names or the CAS numbers, depending on the flow. The function call could look like this then:

```python
method = ('EF v3.1', 'climate change', 'global warming potential (GWP100)')

df_characterized = characterize(
        dynamic_inventory_df,
        metric="radiative_forcing", # could also be GWP
        base_lcia_method=method,
        time_horizon=2,

)
```

## Prospective Characterization

The `prospective` module provides **prospective characterization factors** based on [Barbosa Watanabe et al. (2026)](https://pubs.acs.org/doi/10.1021/acs.est.5c12391). These factors account for how radiative efficiencies change over time under different climate scenarios, making them more appropriate for future-oriented LCA studies.

> For an interactive demo of pLCIA, [open the example notebook on Binder](https://mybinder.org/v2/gh/brightway-lca/dynamic_characterization/main?labpath=notebooks%2Fprospective_dynamic_lcia_demo.ipynb)

> NOTE: Currently, only the IAM scenarios and pathways from Barbosa Watanabe et al. (2026) are supported. This will change soon.

### Setting up a scenario

Before using prospective metrics, you must set a background scenario:

```python
import dynamic_characterization.prospective as prospective

# Set the scenario (required before using pGWP or pGTP)
prospective.set_scenario(iam="IMAGE", ssp="SSP1", rcp="2.6")
```

Available scenario combinations:
- **IAMs**: IMAGE, AIM, GCAM4, MESSAGE, REMIND
- **SSPs**: SSP1-SSP5 (availability depends on IAM)
- **RCPs**: 2.6, 4.5, 6.0, 8.5

### Using prospective metrics

```python
from dynamic_characterization import characterize

# Using prospective radiative forcing (W/m² time series)
df_prf = characterize(
    dynamic_inventory_df,
    metric="prospective_radiative_forcing",
    base_lcia_method=method,
    time_horizon=100,
)

# Using prospective GWP (kg CO2eq)
df_pgwp = characterize(
    dynamic_inventory_df,
    metric="pGWP",
    base_lcia_method=method,
    time_horizon=100,
)

# Using prospective GTP (kg CO2eq)
df_pgtp = characterize(
    dynamic_inventory_df,
    metric="pGTP",
    base_lcia_method=method,
    time_horizon=100,
)
```

### Fallback to IPCC for unsupported GHGs

The Watanabe module only provides prospective characterization for CO2, CH4, and N2O. By default, other GHGs (like CO and the 244 other GHGs from IPCC AR6) fall back to standard IPCC characterization:

```python
# Default: use IPCC for GHGs not in Watanabe (fallback_to_ipcc=True)
df_prf = characterize(
    dynamic_inventory_df,
    metric="prospective_radiative_forcing",
    base_lcia_method=method,
    fallback_to_ipcc=True,  # default
)

# Strict mode: only characterize CO2, CH4, N2O
df_prf_strict = characterize(
    dynamic_inventory_df,
    metric="prospective_radiative_forcing",
    base_lcia_method=method,
    fallback_to_ipcc=False,  # skip GHGs not in Watanabe
)
```

### Time-varying radiative efficiency

By default, the radiative efficiency (RE) is fixed at the emission year (IPCC standard approach). You can enable time-varying RE for more physical accuracy:

```python
df_pgwp = characterize(
    dynamic_inventory_df,
    metric="pGWP",
    base_lcia_method=method,
    time_varying_re=True,  # RE evolves as gas decays
)
```

## What do dynamic characterization functions look like?

Here's an example of what such a function could look like:

```python
def example_characterization_function(series: namedtuple, period: int = 2) -> namedtuple:
    date_beginning: np.datetime64 = series.date.to_numpy()
    dates_characterized: np.ndarray = date_beginning + np.arange(
        start=0, stop=period, dtype="timedelta64[D]"
    ).astype("timedelta64[s]")

    amount_beginning: float = series.amount

    # in reality, this would probably something more complex like an exponential decay function
    amount_characterized: np.ndarray = amount_beginning - np.arange(
        start=0, stop=period, dtype="int"
    )

    return namedtuple("CharacterizedRow", ["date", "amount", "flow", "activity"])(
        date=np.array(dates_characterized, dtype="datetime64[s]"),
        amount=amount_characterized,
        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.

## 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 -->

[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