diff --git a/.gitignore b/.gitignore
index 5beb133a..4ce94a32 100644
--- a/.gitignore
+++ b/.gitignore
@@ -205,3 +205,8 @@ pyrightconfig.json
/docs/content/examples/tutorials/
/docs/content/examples/examples/
/docs/content/examples/advanced/
+
+.claude
+.superpowers
+
+.uv-cache
\ No newline at end of file
diff --git a/CHANGES.md b/CHANGES.md
index 3c0686c5..fb0cde46 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -6,6 +6,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
+* Added `representative_time` database metadata as the default timing source: `TimexLCA` now maps background databases to points in time by reading their Brightway metadata (as written by premise >= 2.4.9.2), making `database_dates` optional ([#217](https://github.com/brightway-lca/bw_timex/issues/217))
+* Added `set_database_metadata` to record what a database represents (`representative_time`, and scenario fields such as `iam_model` or `pathway`) for databases that don't bring the metadata themselves
+* Added `TimexLCA(scenario={...})` to select one background scenario when a project holds several; `TimexLCA` raises and lists the scenarios it found if the choice is ambiguous
+* Added `UnmappedDatabaseError`, raised by `build_timeline()` when the graph traversal reaches a database that is mapped to no point in time - typically a second foreground database that neither holds the functional unit (which is marked `"dynamic"` automatically) nor was marked itself. This previously surfaced as a bare `KeyError` on a node id; the error now names the database, an affected process, and how to map it ([#217](https://github.com/brightway-lca/bw_timex/issues/217))
+* Fixed `TimexLCA(scenario={...})` silently falling back to a plain (non-time-explicit) LCA when the filter matched no database at all, e.g. a typo in a key or value; it now raises a `ValueError` naming the filter and what each of its keys is actually declared as across the project's databases. Also reworded the `database_dates`-specific error messages in `validation.py`, `timeline_builder.py`, and `edge_extractor.py` to also credit `representative_time` metadata as a source of timing ([#217](https://github.com/brightway-lca/bw_timex/issues/217))
## [1.2.1] - 2026-08-14
* Fixed `ShapeMismatch` in `lci()` for processes with more than one biosphere exchange, by sizing the biosphere `flip_array` to the number of matrix entries (only raised with `bw_processing` >= 1.5; no numeric results change) ([#213](https://github.com/brightway-lca/bw_timex/pull/213))
diff --git a/bw_timex/__init__.py b/bw_timex/__init__.py
index 6ea64abc..cf857177 100644
--- a/bw_timex/__init__.py
+++ b/bw_timex/__init__.py
@@ -5,8 +5,10 @@
)
from ._lci_cache import clear_background_lci_cache
+from .database_metadata import set_database_metadata
from .dynamic_biosphere_builder import DynamicBiosphereBuilder
from .edge_extractor import EdgeExtractor
+from .errors import UnmappedDatabaseError
from .helper_classes import SetList
from .matrix_modifier import MatrixModifier
from .timeline_builder import TimelineBuilder
@@ -35,6 +37,8 @@
"DynamicBiosphereBuilder",
"EdgeExtractor",
"SetList",
+ # errors
+ "UnmappedDatabaseError",
# utils
"add_flows_to_characterization_functions",
"add_temporal_distribution_to_exchange",
@@ -44,4 +48,5 @@
"get_temporal_evolution_factor",
"interactive_td_widget",
"plot_characterized_inventory_as_waterfall",
+ "set_database_metadata",
]
diff --git a/bw_timex/database_metadata.py b/bw_timex/database_metadata.py
new file mode 100644
index 00000000..ad36ff56
--- /dev/null
+++ b/bw_timex/database_metadata.py
@@ -0,0 +1,315 @@
+"""Read and write what a Brightway database represents.
+
+`bw_timex` needs to know which point in time each background database stands
+for. That information is stored in the database's own Brightway metadata
+(`bw2data.databases[name]`), where premise also writes it when it exports a
+prospective database:
+
+```python
+{
+ "premise_version": "2.4.9.2",
+ "iam_model": "remind",
+ "pathway": "SSP2-PkBudg500",
+ "representative_time": "2050-01-01T00:00:00",
+ "ecoinvent_version": "3.10.1",
+ "system_model": "cutoff",
+}
+```
+
+premise writes this metadata from version 2.4.9.2 onwards. Databases exported by
+an earlier premise carry none of it, and need `set_database_metadata`.
+
+Brightway stores this mapping as JSON, so dates are kept as ISO 8601 strings.
+"""
+
+from __future__ import annotations
+
+import json
+from collections import defaultdict
+from datetime import datetime
+from typing import Any
+
+import bw2data as bd
+from loguru import logger
+
+from .validation import DatabaseMetadataInputs
+
+REPRESENTATIVE_TIME = "representative_time"
+SCENARIOS = "scenarios"
+DYNAMIC = "dynamic"
+
+#: Metadata keys that identify the scenario a database represents. Two
+#: databases differing in any of these represent different scenarios.
+#: `premise_version` is deliberately absent: re-running premise on the same
+#: pathway must not look like a second scenario.
+SCENARIO_SIGNATURE_KEYS = (
+ "iam_model",
+ "pathway",
+ "system_model",
+ "ecoinvent_version",
+ "external_scenarios",
+)
+
+#: Keys Brightway maintains itself, filtered out when reporting to the user
+#: which metadata a project's databases carry.
+BRIGHTWAY_METADATA_KEYS = frozenset(
+ {
+ "backend",
+ "depends",
+ "dirty",
+ "format",
+ "geocollections",
+ "modified",
+ "number",
+ "processed",
+ "searchable",
+ }
+)
+
+
+def _database_name(database: Any) -> str:
+ """The name of a database given either as a name or as a `bd.Database`."""
+ name = getattr(database, "name", database)
+ if not isinstance(name, str):
+ raise ValueError(
+ f"database must be a database name or a bw2data Database, got "
+ f"{type(database).__name__}."
+ )
+ return name
+
+
+def _normalize_representative_time(value: Any, database: str) -> datetime | str:
+ """Turn a stored `representative_time` into a datetime or `"dynamic"`."""
+ if isinstance(value, datetime):
+ return value
+ if isinstance(value, str):
+ if value == DYNAMIC:
+ return DYNAMIC
+ try:
+ return datetime.fromisoformat(value)
+ except ValueError:
+ raise ValueError(
+ f"Database '{database}' has an invalid `{REPRESENTATIVE_TIME}` "
+ f"metadata value: {value!r}. Expected an ISO 8601 datetime string "
+ f"(e.g. '2030-01-01'), a datetime, or '{DYNAMIC}'."
+ ) from None
+ raise ValueError(
+ f"Database '{database}' has an invalid `{REPRESENTATIVE_TIME}` metadata "
+ f"value of type {type(value).__name__}: {value!r}. Expected an ISO 8601 "
+ f"datetime string, a datetime, or '{DYNAMIC}'."
+ )
+
+
+def set_database_metadata(database: str | bd.Database, **metadata) -> dict:
+ """
+ Store what a database represents in its Brightway metadata.
+
+ Use this for databases that don't bring the metadata themselves, e.g.
+ databases you built yourself or that were exported by premise < 2.4.9.2,
+ which is the first version writing this metadata. `TimexLCA` reads
+ `representative_time` from all databases of the project to map them to
+ points in time, so this replaces passing `database_dates`.
+
+ Parameters
+ ----------
+ database : str or bw2data.Database
+ Name of the database, or the database itself. Must be registered.
+ **metadata :
+ Metadata to store. `representative_time` accepts a `datetime`, an ISO
+ 8601 string, or `"dynamic"` and is always stored as a string, because
+ Brightway serializes database metadata to JSON. Any other key is stored
+ as given and must be JSON-serializable. Keys that premise (>= 2.4.9.2)
+ writes, and that `TimexLCA(scenario=...)` can select on, are
+ `iam_model`, `pathway`, `system_model`, `ecoinvent_version` and
+ `premise_version`.
+
+ Returns
+ -------
+ dict
+ The database's metadata after the update.
+
+ Examples
+ --------
+ ```python
+ set_database_metadata("db_2030", representative_time=datetime(2030, 1, 1))
+ set_database_metadata(
+ "my_2050_variant",
+ representative_time="2050-01-01",
+ iam_model="remind",
+ pathway="SSP2-PkBudg500",
+ )
+ ```
+ """
+ name = _database_name(database)
+ DatabaseMetadataInputs(database=name, metadata=metadata)
+
+ if name not in bd.databases:
+ raise ValueError(
+ f"Database '{name}' is not registered in this Brightway project. "
+ f"Available databases: {sorted(bd.databases)}."
+ )
+
+ serialized = {}
+ for key, value in metadata.items():
+ if key == REPRESENTATIVE_TIME:
+ normalized = _normalize_representative_time(value, name)
+ if isinstance(value, str):
+ # already a string (an ISO 8601 date or "dynamic"): store as given
+ serialized[key] = value
+ else:
+ serialized[key] = normalized.isoformat()
+ continue
+ try:
+ json.dumps(value)
+ except TypeError:
+ raise ValueError(
+ f"Metadata value for '{key}' is not JSON-serializable: {value!r}. "
+ f"Brightway stores database metadata as JSON."
+ ) from None
+ serialized[key] = value
+
+ bd.databases[name].update(serialized)
+ bd.databases.flush()
+ return bd.databases[name]
+
+
+def _candidate_databases() -> dict[str, dict]:
+ """Registered databases that declare a `representative_time`.
+
+ Multi-scenario databases (superstructure and scenario-array exports, which
+ carry a `scenarios` list) are skipped: `bw_timex` needs one technosphere
+ per point in time and cannot pick a scenario out of such a database. They
+ can still be used by naming them in `database_dates`.
+ """
+ candidates = {}
+ for name in bd.databases:
+ metadata = bd.databases[name]
+ if REPRESENTATIVE_TIME not in metadata:
+ continue
+ if metadata.get(SCENARIOS):
+ logger.info(
+ f"Skipping database '{name}': it holds "
+ f"{len(metadata[SCENARIOS])} scenarios, so the point in time it "
+ f"represents is ambiguous. Map it explicitly with `database_dates` "
+ f"if you want to use it anyway."
+ )
+ continue
+ candidates[name] = metadata
+ return candidates
+
+
+def _as_set(value: Any) -> set:
+ """Compare list-valued metadata (e.g. `external_scenarios`) order-insensitively."""
+ if isinstance(value, (list, tuple, set)):
+ return {str(item) for item in value}
+ return {str(value)}
+
+
+def _values_match(declared: Any, wanted: Any) -> bool:
+ if isinstance(declared, (list, tuple, set)) or isinstance(wanted, (list, tuple, set)):
+ return _as_set(declared) == _as_set(wanted)
+ return str(declared) == str(wanted)
+
+
+def _check_filter_keys(scenario: dict, candidates: dict[str, dict]) -> None:
+ """Reject filter keys no database declares, instead of silently matching nothing."""
+ declared = set()
+ for metadata in candidates.values():
+ declared.update(set(metadata) - BRIGHTWAY_METADATA_KEYS)
+ unknown = sorted(set(scenario) - declared)
+ if not unknown:
+ return
+ available = ", ".join(sorted(declared)) or "none"
+ raise ValueError(
+ f"No database in this project declares the metadata key(s) "
+ f"{unknown}. Keys declared by the databases of this project: {available}. "
+ f"Add the metadata with `bw_timex.set_database_metadata`, or check the "
+ f"spelling of your `scenario` filter."
+ )
+
+
+def _scenario_signature(metadata: dict) -> tuple:
+ return tuple(
+ (key, tuple(sorted(_as_set(metadata[key]))) if key in metadata else None)
+ for key in SCENARIO_SIGNATURE_KEYS
+ )
+
+
+def _format_scenario_sets(groups: dict[tuple, list[str]]) -> str:
+ """One line per scenario set, naming only the keys that actually differ."""
+ differing = [
+ key
+ for index, key in enumerate(SCENARIO_SIGNATURE_KEYS)
+ if len({signature[index][1] for signature in groups}) > 1
+ ]
+ lines = []
+ for signature, names in groups.items():
+ values = dict(signature)
+ description = ", ".join(
+ f"{key}={', '.join(values[key]) if values[key] else 'not set'}"
+ for key in differing
+ )
+ lines.append(f" {description}: {', '.join(sorted(names))}")
+ return "\n".join(lines)
+
+
+def _check_unambiguous(candidates: dict[str, dict]) -> None:
+ groups = defaultdict(list)
+ for name, metadata in candidates.items():
+ if any(key in metadata for key in SCENARIO_SIGNATURE_KEYS):
+ groups[_scenario_signature(metadata)].append(name)
+ if len(groups) <= 1:
+ return
+ raise ValueError(
+ f"Several background scenarios found in this project:\n"
+ f"{_format_scenario_sets(groups)}\n"
+ f"Select one, e.g. scenario={{'pathway': '...'}}, or map the databases "
+ f"explicitly with `database_dates`."
+ )
+
+
+def resolve_database_dates_from_metadata(
+ scenario: dict | None = None,
+) -> dict[str, datetime | str]:
+ """
+ Map the databases of the current project to the points in time they represent.
+
+ Reads the `representative_time` metadata of every registered database (see
+ [`set_database_metadata`][bw_timex.database_metadata.set_database_metadata]).
+
+ If the project holds databases from more than one scenario (differing in
+ any of `SCENARIO_SIGNATURE_KEYS`, e.g. two premise pathways), this raises
+ a `ValueError` unless `scenario` narrows the selection down to one.
+
+ Parameters
+ ----------
+ scenario : dict, optional
+ Metadata a database must match to be included, e.g.
+ `{"iam_model": "remind", "pathway": "SSP2-PkBudg500"}`. Databases that
+ don't declare a filtered key at all are kept, so a filter narrows down
+ an ambiguous project without excluding databases that carry no
+ scenario metadata (e.g. a dynamic foreground). Raises `ValueError` if
+ a filter key is not declared by any database in the project.
+
+ Returns
+ -------
+ dict
+ Mapping of database name to `datetime` or `"dynamic"`, ready to be used
+ as `TimexLCA.database_dates`.
+ """
+ candidates = _candidate_databases()
+ if scenario:
+ _check_filter_keys(scenario, candidates)
+ candidates = {
+ name: metadata
+ for name, metadata in candidates.items()
+ if all(
+ key not in metadata or _values_match(metadata[key], wanted)
+ for key, wanted in scenario.items()
+ )
+ }
+ _check_unambiguous(candidates)
+ return {
+ name: _normalize_representative_time(metadata[REPRESENTATIVE_TIME], name)
+ for name, metadata in candidates.items()
+ }
diff --git a/bw_timex/edge_extractor.py b/bw_timex/edge_extractor.py
index 45202374..ce5921f5 100644
--- a/bw_timex/edge_extractor.py
+++ b/bw_timex/edge_extractor.py
@@ -319,7 +319,8 @@ def _candidate_databases_for_node(self, node_id: int) -> dict:
f"one database at {date:%Y-%m-%d}: '{candidates[date]}' and "
f"'{db_name}'. bw_timex cannot tell which one to use. Give "
"the copy a distinct name, reference product or location, "
- "or remove one of the two databases from `database_dates`."
+ "or remove one of the two databases from `database_dates` or "
+ "its `representative_time` metadata."
)
candidates[date] = db_name
diff --git a/bw_timex/errors.py b/bw_timex/errors.py
new file mode 100644
index 00000000..94f3fc5b
--- /dev/null
+++ b/bw_timex/errors.py
@@ -0,0 +1,15 @@
+"""Errors raised by `bw_timex`."""
+
+from __future__ import annotations
+
+
+class UnmappedDatabaseError(ValueError):
+ """A database reached by the graph traversal is missing from the mapping.
+
+ `bw_timex` places every traversed process in time via the database it
+ lives in, so each of them must either represent a point in time or be
+ marked as `"dynamic"`. Databases holding the functional unit are treated
+ as dynamic automatically; every other database has to say what it
+ represents, through its `representative_time` metadata or through
+ `database_dates`.
+ """
diff --git a/bw_timex/timeline_builder.py b/bw_timex/timeline_builder.py
index 252882cc..9b070542 100644
--- a/bw_timex/timeline_builder.py
+++ b/bw_timex/timeline_builder.py
@@ -10,6 +10,7 @@
from loguru import logger
from .edge_extractor import Edge, EdgeExtractor, EdgeExtractorBFS
+from .errors import UnmappedDatabaseError
from .utils import (
convert_date_string_to_datetime,
extract_date_as_integer,
@@ -306,6 +307,8 @@ def build_timeline(self) -> pd.DataFrame:
grouped_edges = self._drop_edges_of_unsupplied_consumers(grouped_edges)
+ self._check_traversed_databases_are_mapped(grouped_edges)
+
# add new processes to activity_time_mapping
static_dbs = set(self.database_dates_static.keys()) if self.traverse_background else set()
for row in grouped_edges.itertuples():
@@ -381,6 +384,70 @@ def build_timeline(self) -> pd.DataFrame:
# underlying functions called by build_timeline() #
###################################################
+ def _check_traversed_databases_are_mapped(self, grouped_edges: pd.DataFrame) -> None:
+ """
+ Check that every traversed process lives in a database that is mapped.
+
+ `bw_timex` places a process in time via the database it lives in, so
+ every database the traversal reaches must either represent a point in
+ time or be marked as `"dynamic"`. Only the databases holding the
+ functional unit are treated as dynamic automatically - a foreground
+ split across several databases has to mark the other ones itself. A
+ database that is mapped nowhere has no node metadata loaded for it,
+ which would otherwise surface as a bare `KeyError` on a node id.
+
+ Parameters
+ ----------
+ grouped_edges : pd.DataFrame
+ The timeline edges, with `producer` and `consumer` node ids.
+
+ Returns
+ -------
+ None
+
+ Raises
+ ------
+ UnmappedDatabaseError
+ If any traversed process is in a database that is not mapped.
+ """
+ node_ids = set(grouped_edges["producer"]).union(grouped_edges["consumer"])
+ unmapped = sorted(
+ node_id
+ for node_id in node_ids
+ if node_id != -1 and node_id not in self.nodes
+ )
+ if not unmapped:
+ return
+
+ examples = {}
+ for node_id in unmapped:
+ node = bd.get_node(id=node_id)
+ examples.setdefault(node["database"], []).append(node["name"])
+
+ databases = ", ".join(
+ f"'{database}' (e.g. '{names[0]}'"
+ + (f", and {len(names) - 1} more" if len(names) > 1 else "")
+ + ")"
+ for database, names in examples.items()
+ )
+ first = next(iter(examples))
+ raise UnmappedDatabaseError(
+ f"The graph traversal reached processes in database(s) that are not "
+ f"mapped to a point in time: {databases}. `bw_timex` places every "
+ f"traversed process in time via its database, and only the "
+ f"database(s) holding the functional unit are treated as 'dynamic' "
+ f"automatically, so a foreground split across several databases has "
+ f"to mark the other ones itself.\n"
+ f"If '{first}' is part of your foreground, mark it as dynamic:\n"
+ f" bw_timex.set_database_metadata('{first}', representative_time='dynamic')\n"
+ f"If it represents a point in time, give it that date instead:\n"
+ f" bw_timex.set_database_metadata('{first}', "
+ f"representative_time=datetime(2030, 1, 1))\n"
+ f"Databases mapped for this calculation: "
+ f"{sorted(self.database_dates)}. When passing `database_dates` "
+ f"explicitly, it must list every database the traversal reaches."
+ )
+
def check_database_names(self) -> None:
"""
Check that the strings of the databases exist in the databases of the Brightway project.
@@ -578,7 +645,8 @@ def candidate_databases_for_producers(self, producers: set) -> dict:
f"at {date:%Y-%m-%d}: '{already}' and '{node['database']}'. "
"bw_timex cannot tell which one its temporal market should use. "
"Give the copy a distinct name, reference product or location, "
- "or remove one of the two databases from `database_dates`."
+ "or remove one of the two databases from `database_dates` or "
+ "its `representative_time` metadata."
)
candidates[producer][date] = node["database"]
matches[producer][node["database"]] = node.id
diff --git a/bw_timex/timex_lca.py b/bw_timex/timex_lca.py
index 6c1c7068..52d4f26e 100644
--- a/bw_timex/timex_lca.py
+++ b/bw_timex/timex_lca.py
@@ -31,6 +31,7 @@
from ._lci_cache import BACKGROUND_UNIT_LCI_CACHE, LCI_SOLVE_CACHE, NODES_CACHE
FACTORIZE_SOLVES_THRESHOLD = 8
+from .database_metadata import resolve_database_dates_from_metadata
from .dynamic_biosphere_builder import DynamicBiosphereBuilder
from .helper_classes import InterDatabaseMapping, LazyActivity, TimeMappingDict
from .matrix_modifier import MatrixModifier
@@ -82,19 +83,32 @@ class TimexLCA:
Examples
--------
```python
+ from bw_timex import TimexLCA, set_database_metadata
+
demand = {("my_foreground_database", "my_process"): 1}
method = ("some_method_family", "some_category", "some_method")
- database_dates = {
- "my_background_database_one": datetime.strptime("2020", "%Y"),
- "my_background_database_two": datetime.strptime("2030", "%Y"),
- "my_background_database_three": datetime.strptime("2040", "%Y"),
- # Several databases may share the same date, e.g. to keep your own
- # modified copies of background processes in their own database:
- "my_modified_background_2020": datetime.strptime("2020", "%Y"),
- "my_foreground_database": "dynamic",
- }
-
- tlca = TimexLCA(demand, method, database_dates)
+
+ # Databases exported by premise >= 2.4.9.2 already know the point in
+ # time they represent. For your own databases, say so once:
+ set_database_metadata("my_background_database_one", representative_time=datetime(2020, 1, 1))
+ set_database_metadata("my_background_database_two", representative_time=datetime(2030, 1, 1))
+
+ tlca = TimexLCA(demand, method)
+
+ # ... or map the databases explicitly, which then replaces the metadata:
+ tlca = TimexLCA(
+ demand,
+ method,
+ database_dates={
+ "my_background_database_one": datetime(2020, 1, 1),
+ "my_background_database_two": datetime(2030, 1, 1),
+ # Several databases may share the same date, e.g. to keep your own
+ # modified copies of background processes in their own database:
+ "my_modified_background_2020": datetime(2020, 1, 1),
+ "my_foreground_database": "dynamic",
+ },
+ )
+
tlca.build_timeline() # has many optional arguments
tlca.lci()
tlca.static_lcia()
@@ -110,6 +124,7 @@ def __init__(
demand: dict,
method: tuple,
database_dates: dict = None,
+ scenario: dict = None,
use_global_lci_cache: bool = True,
) -> None:
"""
@@ -126,10 +141,31 @@ def __init__(
Tuple defining the LCIA method, such as `('foo', 'bar')` or default methods, such as
`("EF v3.1", "climate change", "global warming potential (GWP100)")`
database_dates : dict, optional
- Dictionary mapping database names to dates. Several databases may
- share the same date, e.g. to keep your own modified copies of
- background processes in their own database instead of writing
- them into the shared background database for that vintage.
+ Fallback for mapping the databases yourself instead of letting
+ `bw_timex` read their metadata - useful for databases written by
+ premise < 2.4.9.2, which carry no metadata, or when you want to
+ override what the metadata says. Dictionary mapping database names
+ to the point in time they represent, as a `datetime`, or to
+ `"dynamic"` for databases whose processes are distributed over
+ time (typically the foreground).
+ Several databases may share the same date, e.g. to keep your own
+ modified copies of background processes in their own database
+ instead of writing them into the shared background database for
+ that vintage. If not given, the mapping is read from the
+ databases' own `representative_time` metadata (which premise
+ >= 2.4.9.2 writes when exporting, and which you can set yourself
+ with `bw_timex.set_database_metadata`). Passing this argument replaces
+ the metadata entirely: only the databases listed here are used.
+ scenario : dict, optional
+ Metadata a background database must match to be used, e.g.
+ `{"iam_model": "remind", "pathway": "SSP2-PkBudg500"}`. Reads the
+ scenario metadata written by premise >= 2.4.9.2 (or by you, with
+ `bw_timex.set_database_metadata`), so it does nothing for
+ databases that carry none. Only needed when the project
+ holds several scenarios - `TimexLCA`
+ raises and lists them otherwise. Databases that don't declare the
+ filtered key (your foreground, a hand-built vintage) are always
+ kept. Cannot be combined with `database_dates`.
use_global_lci_cache : bool, optional
If True (default), background unit LCI matrices are cached at
module level and reused across `TimexLCA` objects within the
@@ -146,17 +182,16 @@ def __init__(
self.demand = demand
self.method = method
- self.database_dates = database_dates
-
- if not self.database_dates:
- logger.info(
- "No database_dates provided. Treating the databases containing the functional \
- unit as dynamic. No remapping of inventories to time explicit databases will be done."
- )
- self.database_dates = {key[0]: "dynamic" for key in demand.keys()}
+ self.scenario = scenario
+ self.database_dates = self._resolve_database_dates(
+ demand=demand, database_dates=database_dates, scenario=scenario
+ )
TimexLCAInputs(
- demand=self.demand, method=self.method, database_dates=self.database_dates
+ demand=self.demand,
+ method=self.method,
+ database_dates=self.database_dates,
+ scenario=self.scenario,
)
# Filled in by `prepare_base_lca_inputs`: the databases the base LCA
@@ -231,6 +266,79 @@ def __init__(
logger.info("TimexLCA initialized.")
+ @staticmethod
+ def _resolve_database_dates(
+ demand: dict, database_dates: dict | None, scenario: dict | None
+ ) -> dict:
+ """Map databases to the points in time they represent.
+
+ Either from the explicit `database_dates` argument, which is then the
+ whole mapping, or from the databases' own `representative_time`
+ metadata. Databases holding the demand default to `"dynamic"`.
+
+ Raises
+ ------
+ ValueError
+ If both `database_dates` and `scenario` are given (`scenario`
+ only selects among databases resolved from metadata, so it makes
+ no sense once `database_dates` already gives the whole mapping),
+ or if `scenario` is given but no surviving database positively
+ declares one of its keys - almost always a typo in one of its
+ keys or values, since a filter that legitimately excludes
+ everything would leave nothing for `TimexLCA` to compute with.
+ A database that doesn't declare a filtered key at all is kept by
+ the filter (see `resolve_database_dates_from_metadata`), so
+ checking whether the *resolved mapping* is empty is not enough:
+ it stays non-empty whenever such a database happens to be
+ present, even though the filter matched none of the databases it
+ was meant to select among.
+ """
+ if database_dates is not None:
+ if scenario:
+ raise ValueError(
+ "`scenario` selects background databases by their metadata and "
+ "only applies when `database_dates` is not given. Pass one or "
+ "the other."
+ )
+ return dict(database_dates)
+
+ resolved = resolve_database_dates_from_metadata(scenario)
+
+ filter_matched = scenario and any(
+ key in bd.databases[name] for name in resolved for key in scenario
+ )
+
+ if scenario and not filter_matched:
+ declared = {}
+ for name in bd.databases:
+ metadata = bd.databases[name]
+ for key in scenario:
+ if key in metadata:
+ declared.setdefault(key, set()).add(str(metadata[key]))
+ details = "; ".join(
+ f"'{key}': "
+ f"{sorted(declared[key]) if key in declared else 'not declared by any database'}"
+ for key in scenario
+ )
+ raise ValueError(
+ f"scenario={scenario!r} matched no database in this project. "
+ f"Values actually declared for its key(s) by this project's "
+ f"databases: {details}. Check for a typo in the filter."
+ )
+ elif not resolved:
+ logger.info(
+ "No database_dates provided, and no database in this project carries "
+ "`representative_time` metadata. Treating the databases containing the "
+ "functional unit as dynamic. No remapping of inventories to time "
+ "explicit databases will be done."
+ )
+
+ for key in demand:
+ database = bd.get_node(id=get_id(key))["database"]
+ resolved.setdefault(database, "dynamic")
+
+ return resolved
+
########################################
# Main functions to be called by users #
########################################
diff --git a/bw_timex/validation.py b/bw_timex/validation.py
index 215dd81c..0db07e9a 100644
--- a/bw_timex/validation.py
+++ b/bw_timex/validation.py
@@ -18,6 +18,7 @@ class TimexLCAInputs(BaseModel):
demand: dict
method: tuple
database_dates: Optional[dict] = None
+ scenario: Optional[dict] = None
@field_validator("demand")
@classmethod
@@ -71,6 +72,26 @@ def validate_database_dates(cls, v: Optional[dict]) -> Optional[dict]:
)
return v
+ @field_validator("scenario")
+ @classmethod
+ def validate_scenario(cls, v: Optional[dict]) -> Optional[dict]:
+ if v is None:
+ return v
+ if not v:
+ raise ValueError("scenario must be a non-empty dictionary if provided.")
+ for key, value in v.items():
+ if not isinstance(key, str):
+ raise ValueError(
+ f"scenario keys must be strings (database metadata keys), got "
+ f"{type(key).__name__}."
+ )
+ if not isinstance(value, (str, int, float, bool, list, tuple)):
+ raise ValueError(
+ f"scenario values must be scalars or lists of scalars, got "
+ f"{type(value).__name__} for key '{key}'."
+ )
+ return v
+
@model_validator(mode="after")
def validate_demand_in_dynamic_databases(self) -> "TimexLCAInputs":
if self.database_dates is None:
@@ -84,7 +105,8 @@ def validate_demand_in_dynamic_databases(self) -> "TimexLCAInputs":
if act["database"] not in dynamic_database_names:
raise ValueError(
f"Demand activity {act} from database {act['database']}: "
- f"This database is not marked as 'dynamic' in database_dates. "
+ f"This database is mapped to a date rather than 'dynamic' "
+ f"(via `database_dates` or its `representative_time` metadata). "
f"Please check."
)
return self
@@ -243,3 +265,27 @@ def validate_bio_flows(cls, v: list) -> list:
f"bio_flows must contain integer database IDs, got {type(item).__name__}: {item}."
)
return v
+
+
+class DatabaseMetadataInputs(BaseModel):
+ """Validates inputs to set_database_metadata"""
+
+ model_config = {"arbitrary_types_allowed": True}
+
+ database: str
+ metadata: dict
+
+ @field_validator("metadata")
+ @classmethod
+ def validate_metadata(cls, v: dict) -> dict:
+ if not v:
+ raise ValueError(
+ "Provide at least one metadata field, e.g. "
+ "`representative_time=datetime(2030, 1, 1)`."
+ )
+ for key in v:
+ if not isinstance(key, str):
+ raise ValueError(
+ f"Metadata keys must be strings, got {type(key).__name__}: {key}."
+ )
+ return v
diff --git a/docs/api/database_metadata.md b/docs/api/database_metadata.md
new file mode 100644
index 00000000..c8e5ba9b
--- /dev/null
+++ b/docs/api/database_metadata.md
@@ -0,0 +1,13 @@
+---
+icon: lucide/calendar-clock
+tags:
+ - api
+---
+
+# Database metadata
+
+Reading and writing what a Brightway database represents: the point in time
+(`representative_time`) and, for prospective databases, the scenario it was built
+for.
+
+::: bw_timex.database_metadata
diff --git a/docs/api/errors.md b/docs/api/errors.md
new file mode 100644
index 00000000..42c5edd4
--- /dev/null
+++ b/docs/api/errors.md
@@ -0,0 +1,12 @@
+---
+icon: lucide/triangle-alert
+tags:
+ - api
+---
+
+# Errors
+
+Errors raised by `bw_timex`, importable from the top level (e.g.
+`from bw_timex import UnmappedDatabaseError`).
+
+::: bw_timex.errors
diff --git a/docs/api/index.md b/docs/api/index.md
index a242c0e0..9bd56183 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -15,4 +15,6 @@ The main user-facing class is [`TimexLCA`](timex_lca.md). It orchestrates the ot
- [`dynamic_biosphere_builder`](dynamic_biosphere_builder.md) — builds the dynamic biosphere matrix carrying emission timing.
- [`edge_extractor`](edge_extractor.md) — extracts and convolves temporal distributions during graph traversal.
- [`helper_classes`](helper_classes.md) — supporting data structures used across the package.
+- [`database_metadata`](database_metadata.md) — reads and writes what a database represents: its `representative_time` and its scenario.
+- [`errors`](errors.md) — the errors `bw_timex` raises.
- [`utils`](utils.md) — utility functions.
diff --git a/docs/content/getting_started/adding_temporal_information.md b/docs/content/getting_started/adding_temporal_information.md
index 76a08acc..f7b4c0c2 100644
--- a/docs/content/getting_started/adding_temporal_information.md
+++ b/docs/content/getting_started/adding_temporal_information.md
@@ -247,23 +247,40 @@ end
)
```
-So, as you can see, the processes at specific time steps reside within a separate normal Brightway database. To hand them to `bw_timex`, we just need to define a dictionary that maps the names of time-specific databases to the point in time that they represent:
+So, as you can see, the processes at specific time steps reside within a separate normal
+Brightway database. `bw_timex` picks these up automatically, as long as each database
+says which point in time it represents:
```python
from datetime import datetime
+from bw_timex import set_database_metadata
-# Note: The foreground does not represent a specific point in time, but should
-# later be dynamically distributed over time
-database_dates = {
- "background": datetime.strptime("2020", "%Y"),
- "background_2030": datetime.strptime("2030", "%Y"),
- "foreground": "dynamic",
-}
+set_database_metadata("background", representative_time=datetime(2020, 1, 1))
+set_database_metadata("background_2030", representative_time=datetime(2030, 1, 1))
```
+You only do this once per database - it is stored in your Brightway project. Databases
+exported by [premise](https://premise.readthedocs.io/en/latest/introduction.html)
+**>= 2.4.9.2** bring this metadata with them, so there is nothing to do for those;
+for databases from an earlier premise, set it yourself as above. The foreground doesn't
+represent a specific point in time and is distributed over time instead; `bw_timex`
+treats the databases holding your functional unit that way automatically.
+
+!!! tip "Foreground split across several databases"
+
+ Only the databases holding the functional unit become dynamic automatically. Mark
+ any other foreground database yourself:
+
+ ```python
+ set_database_metadata("my_intermediate_foreground", representative_time="dynamic")
+ ```
+
+ Otherwise `build_timeline()` raises an `UnmappedDatabaseError`, naming the database
+ it could not place in time.
+
!!! tip "Data sources"
- You can use whatever data source you want for the time-specific process data. A nice package from the Brightway cosmos that can help you is [premise](https://premise.readthedocs.io/en/latest/introduction.html).
+ You can use whatever data source you want for the time-specific process data. [premise](https://premise.readthedocs.io/en/latest/introduction.html) is a nice package from the Brightway cosmos, but you can also use any custom scenario.
### Several databases for the same point in time
@@ -272,13 +289,10 @@ background processes: keep the modified copies in your own database per point in
time, instead of writing them into ecoinvent or premise.
```python
-database_dates = {
- "ecoinvent_2020": datetime.strptime("2020", "%Y"),
- "ecoinvent_2030": datetime.strptime("2030", "%Y"),
- "my_background_2020": datetime.strptime("2020", "%Y"), # your modified copies
- "my_background_2030": datetime.strptime("2030", "%Y"),
- "foreground": "dynamic",
-}
+set_database_metadata("ecoinvent_2020", representative_time=datetime(2020, 1, 1))
+set_database_metadata("ecoinvent_2030", representative_time=datetime(2030, 1, 1))
+set_database_metadata("my_background_2020", representative_time=datetime(2020, 1, 1))
+set_database_metadata("my_background_2030", representative_time=datetime(2030, 1, 1))
```
For each process, `bw_timex` interpolates only between the databases that actually
diff --git a/docs/content/getting_started/build_process_timeline.md b/docs/content/getting_started/build_process_timeline.md
index ebedea1f..00d800ab 100644
--- a/docs/content/getting_started/build_process_timeline.md
+++ b/docs/content/getting_started/build_process_timeline.md
@@ -8,7 +8,9 @@ tags:
# Step 2 - Building the process timeline
-With all the temporal information prepared, we can now instantiate our TimexLCA object. This is very similar to a normal Brightway LCA object, but with the additional argument of our `database_dates`:
+With all the temporal information prepared, we can now instantiate our TimexLCA object.
+This is just like a normal Brightway LCA object - the timing of the background databases
+comes from their metadata:
```python
from bw_timex import TimexLCA
@@ -16,10 +18,42 @@ from bw_timex import TimexLCA
tlca = TimexLCA(
demand={("foreground", "A"): 1},
method=("our", "method"),
- database_dates=database_dates,
)
```
+The metadata is written by premise >= 2.4.9.2, or by you with
+`set_database_metadata` (see [Step 1](adding_temporal_information.md)).
+
+If your project holds several IAM scenarios, say which one you want - `bw_timex` lists
+what it found rather than guessing:
+
+```python
+tlca = TimexLCA(
+ demand={("foreground", "A"): 1},
+ method=("our", "method"),
+ scenario={"pathway": "SSP2-PkBudg500"},
+)
+```
+
+Any metadata key filters (`iam_model`, `pathway`, `system_model`, ...), and databases
+that don't carry it - your foreground, your own vintages - are kept. Comparing scenarios
+is the same script in a loop over filters.
+
+!!! tip "Mapping the databases by hand"
+
+ `database_dates` maps database names to dates yourself and replaces the metadata
+ entirely:
+
+ ```python
+ tlca = TimexLCA(demand, method, database_dates={
+ "background": datetime(2020, 1, 1),
+ "background_2030": datetime(2030, 1, 1),
+ "foreground": "dynamic",
+ })
+ ```
+
+ Handy to restrict a calculation to a subset of your project.
+
Using our new `tlca` object, we can now build the timeline of processes that leads to our functional unit "A". If not specified otherwise, it's assumed that the demand occurs in the current year. In our case, we're specifying the time of demand to the year 2024, with the attribute 'starting_datetime`.. Building the timeline is very simple:
```python
tlca.build_timeline(starting_datetime=datetime.strptime("2024-01-01", "%Y-%m-%d"))
diff --git a/docs/content/getting_started/quickstart.md b/docs/content/getting_started/quickstart.md
index 61e62ed9..c1b292d4 100644
--- a/docs/content/getting_started/quickstart.md
+++ b/docs/content/getting_started/quickstart.md
@@ -6,7 +6,7 @@ tags:
# Quick Start
-A condensed reference for using `bw_timex`. For a step-by-step introduction, see the [Walkthrough](index.md). For the underlying framework, see the [Theory](../theory.md) page. For more, see the [Examples](../examples/index.md) or the [API Reference](../../api/index.md).
+Condensed reference for `bw_timex`. For a step-by-step introduction, see the [Walkthrough](index.md). For the underlying framework, see the [Theory](../theory.md) page. For more, see the [Examples](../examples/index.md) or the [API Reference](../../api/index.md).
---
@@ -38,6 +38,7 @@ from bw_timex import (
TemporalDistribution,
TimexLCA,
add_temporal_distribution_to_exchange,
+ set_database_metadata,
)
# 1. Set up Brightway project
@@ -55,18 +56,15 @@ add_temporal_distribution_to_exchange(
output_database="foreground",
)
-# 3. Map your time-specific background databases to points in time
-database_dates = {
- "background": datetime.strptime("2020", "%Y"),
- "background_2030": datetime.strptime("2030", "%Y"),
- "foreground": "dynamic", # gets distributed over time
-}
+# 3. Say what your time-specific background databases represent
+# (databases from premise >= 2.4.9.2 already know - skip this for them)
+set_database_metadata("background", representative_time=datetime(2020, 1, 1))
+set_database_metadata("background_2030", representative_time=datetime(2030, 1, 1))
# 4. Create the TimexLCA object
tlca = TimexLCA(
demand={("foreground", "A"): 1},
method=("our", "method"),
- database_dates=database_dates,
)
# 5. Build the process timeline
@@ -93,7 +91,7 @@ tlca.plot_dynamic_characterized_inventory()
| What you want to express | How | Where |
|---|---|---|
| *When* an exchange happens | `temporal_distribution` on the exchange | any foreground exchange (and background ones, if you traverse the background) |
-| *How the background changes* over time | one database per point in time + `database_dates` | background databases |
+| *How the background changes* over time | one database per point in time, each with `representative_time` metadata | background databases |
| *How a foreground exchange changes* over time | `temporal_evolution_factors` / `temporal_evolution_amounts` on the exchange (`bw_timex>0.3.4`) | foreground exchanges |
```python
@@ -128,8 +126,11 @@ add_temporal_evolution_to_exchange(
Absolute dates (`dtype="datetime64[s]"`) are also allowed in a `TemporalDistribution`,
e.g. for the timing of the functional unit itself. Relative dates
(`dtype="timedelta64[Y]"`) are relative to the consuming process. Several databases may
-share the same date in `database_dates`, e.g. if you keep modified copies of background
-processes in their own database instead of writing them into the shared vintage.
+represent the same point in time, e.g. if you keep modified copies of background
+processes in their own database instead of writing them into the shared vintage. See
+[Step 1](adding_temporal_information.md) for the database metadata, and
+[Step 2](build_process_timeline.md) for scenario selection and for mapping databases
+explicitly with `database_dates`.
---
@@ -141,10 +142,16 @@ processes in their own database instead of writing them into the shared vintage.
TimexLCA(
demand={("foreground", "A"): 1}, # Node, (database, code) tuple, or int id
method=("our", "method"),
- database_dates=database_dates, # optional, but usually what you want
+ database_dates=None, # fallback: map the databases yourself, overriding metadata
+ scenario=None, # pick one scenario, when the project holds several
)
```
+Both are optional. `scenario` narrows down what `bw_timex` reads from the database
+metadata (written by premise >= 2.4.9.2, or by you with `set_database_metadata`);
+`database_dates` is the fallback for when you'd rather write the mapping out yourself,
+and it overrides the metadata entirely.
+
### `build_timeline()`
| Argument | Default | Description |
diff --git a/docs/superpowers/plans/2026-08-21-representative-time-metadata.md b/docs/superpowers/plans/2026-08-21-representative-time-metadata.md
new file mode 100644
index 00000000..e23a9643
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-21-representative-time-metadata.md
@@ -0,0 +1,1510 @@
+# Representative time as database metadata — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** `TimexLCA` learns the point in time each background database represents from that database's own Brightway metadata (`representative_time`, as written by premise), so `database_dates` becomes an optional explicit override instead of a required argument.
+
+**Architecture:** A new module `bw_timex/database_metadata.py` owns everything about database metadata: writing it (`set_database_metadata`) and resolving a `{database: datetime | "dynamic"}` mapping out of the project (`resolve_database_dates_from_metadata`), including scenario filtering and the ambiguity error. `TimexLCA.__init__` calls it in one place and is otherwise untouched: everything downstream still consumes `self.database_dates`.
+
+**Tech Stack:** Python 3.10+, `bw2data` (database metadata lives in `bd.databases[name]`, a JSON-serialized dict), `pydantic` (input validation, see `bw_timex/validation.py`), `loguru`, `pytest` with `bw2data.tests.bw2test` fixtures.
+
+**Spec:** `docs/superpowers/specs/2026-08-21-representative-time-metadata-design.md`
+
+## Global Constraints
+
+- Run everything with the project venv: `.venv/bin/python`, `.venv/bin/pytest`.
+- `database_dates` semantics do not change. When it is passed, it is the whole mapping and metadata is never read.
+- `bd.databases` is serialized to JSON. A `datetime` written into it breaks `bd.databases.flush()`. Every date stored in metadata is an ISO 8601 string.
+- Metadata keys, exactly as premise writes them: `representative_time`, `iam_model`, `pathway`, `system_model`, `ecoinvent_version`, `premise_version`, `external_scenarios`, `scenarios`.
+- Scenario identity keys (the ambiguity signature) are exactly: `("iam_model", "pathway", "system_model", "ecoinvent_version", "external_scenarios")`. `premise_version` is deliberately not one of them.
+- `notebooks/examples/paper_case_study.ipynb` must not be modified by any task.
+- Commit messages carry no AI attribution and no `Co-Authored-By` trailer.
+
+---
+
+### Task 1: `database_metadata` module — writing metadata
+
+**Files:**
+- Create: `bw_timex/database_metadata.py`
+- Modify: `bw_timex/validation.py` (append a `DatabaseMetadataInputs` model)
+- Modify: `bw_timex/__init__.py` (export `set_database_metadata`)
+- Create: `tests/test_database_metadata.py`
+
+**Interfaces:**
+- Consumes: nothing from earlier tasks.
+- Produces:
+ - `bw_timex.database_metadata.set_database_metadata(database: str | bd.Database, **metadata) -> dict`
+ - constants `REPRESENTATIVE_TIME: str = "representative_time"`, `SCENARIOS: str = "scenarios"`, `DYNAMIC: str = "dynamic"`, `SCENARIO_SIGNATURE_KEYS: tuple[str, ...]`, `BRIGHTWAY_METADATA_KEYS: frozenset[str]`
+ - `bw_timex.database_metadata._normalize_representative_time(value, database: str) -> datetime | str`
+
+- [ ] **Step 1: Write the failing tests**
+
+Create `tests/test_database_metadata.py`:
+
+```python
+"""Tests for reading and writing what a Brightway database represents."""
+
+from datetime import datetime
+
+import bw2data as bd
+import pytest
+
+from bw_timex import set_database_metadata
+
+# ─── Tests for set_database_metadata ───
+
+
+@pytest.mark.usefixtures("temporal_grouping_db_monthly")
+class TestSetDatabaseMetadata:
+
+ def test_datetime_is_stored_as_iso_string(self):
+ set_database_metadata("db_2022", representative_time=datetime(2022, 1, 1))
+ assert bd.databases["db_2022"]["representative_time"] == "2022-01-01T00:00:00"
+
+ def test_iso_string_is_stored_as_given(self):
+ set_database_metadata("db_2022", representative_time="2022-01-01")
+ assert bd.databases["db_2022"]["representative_time"] == "2022-01-01"
+
+ def test_dynamic_is_allowed(self):
+ set_database_metadata("foreground", representative_time="dynamic")
+ assert bd.databases["foreground"]["representative_time"] == "dynamic"
+
+ def test_scenario_fields_are_stored(self):
+ set_database_metadata(
+ "db_2022",
+ representative_time=datetime(2022, 1, 1),
+ iam_model="remind",
+ pathway="SSP2-PkBudg500",
+ )
+ assert bd.databases["db_2022"]["iam_model"] == "remind"
+ assert bd.databases["db_2022"]["pathway"] == "SSP2-PkBudg500"
+
+ def test_database_object_is_accepted(self):
+ set_database_metadata(
+ bd.Database("db_2022"), representative_time=datetime(2022, 1, 1)
+ )
+ assert bd.databases["db_2022"]["representative_time"] == "2022-01-01T00:00:00"
+
+ def test_existing_metadata_is_kept(self):
+ before = bd.databases["db_2022"]["backend"]
+ set_database_metadata("db_2022", representative_time=datetime(2022, 1, 1))
+ assert bd.databases["db_2022"]["backend"] == before
+
+ def test_survives_flush_and_reload(self):
+ set_database_metadata("db_2022", representative_time=datetime(2022, 1, 1))
+ bd.databases.__init__() # re-read from disk
+ assert bd.databases["db_2022"]["representative_time"] == "2022-01-01T00:00:00"
+
+ def test_unregistered_database_raises(self):
+ with pytest.raises(ValueError, match="not registered"):
+ set_database_metadata("no_such_db", representative_time=datetime(2022, 1, 1))
+
+ def test_unparseable_representative_time_raises(self):
+ with pytest.raises(ValueError, match="representative_time"):
+ set_database_metadata("db_2022", representative_time="whenever")
+
+ def test_non_serializable_value_raises(self):
+ with pytest.raises(ValueError, match="JSON"):
+ set_database_metadata("db_2022", pathway=object())
+
+ def test_no_metadata_raises(self):
+ with pytest.raises(ValueError, match="at least one"):
+ set_database_metadata("db_2022")
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `.venv/bin/pytest tests/test_database_metadata.py -v`
+Expected: FAIL — `ImportError: cannot import name 'set_database_metadata' from 'bw_timex'`
+
+- [ ] **Step 3: Write the module**
+
+Create `bw_timex/database_metadata.py`:
+
+```python
+"""Read and write what a Brightway database represents.
+
+`bw_timex` needs to know which point in time each background database stands
+for. That information is stored in the database's own Brightway metadata
+(`bw2data.databases[name]`), where premise also writes it when it exports a
+prospective database:
+
+```python
+{
+ "premise_version": "2.4.9.1",
+ "iam_model": "remind",
+ "pathway": "SSP2-PkBudg500",
+ "representative_time": "2050-01-01T00:00:00",
+ "ecoinvent_version": "3.10.1",
+ "system_model": "cutoff",
+}
+```
+
+Brightway stores this mapping as JSON, so dates are kept as ISO 8601 strings.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from typing import Any
+
+import bw2data as bd
+
+REPRESENTATIVE_TIME = "representative_time"
+SCENARIOS = "scenarios"
+DYNAMIC = "dynamic"
+
+#: Metadata keys that identify the scenario a database represents. Two
+#: databases differing in any of these represent different scenarios.
+#: `premise_version` is deliberately absent: re-running premise on the same
+#: pathway must not look like a second scenario.
+SCENARIO_SIGNATURE_KEYS = (
+ "iam_model",
+ "pathway",
+ "system_model",
+ "ecoinvent_version",
+ "external_scenarios",
+)
+
+#: Keys Brightway maintains itself, filtered out when reporting to the user
+#: which metadata a project's databases carry.
+BRIGHTWAY_METADATA_KEYS = frozenset(
+ {
+ "backend",
+ "depends",
+ "dirty",
+ "format",
+ "geocollections",
+ "modified",
+ "number",
+ "processed",
+ "searchable",
+ }
+)
+
+
+def _database_name(database: Any) -> str:
+ """The name of a database given either as a name or as a `bd.Database`."""
+ name = getattr(database, "name", database)
+ if not isinstance(name, str):
+ raise ValueError(
+ f"database must be a database name or a bw2data Database, got "
+ f"{type(database).__name__}."
+ )
+ return name
+
+
+def _normalize_representative_time(value: Any, database: str) -> datetime | str:
+ """Turn a stored `representative_time` into a datetime or `"dynamic"`."""
+ if isinstance(value, datetime):
+ return value
+ if isinstance(value, str):
+ if value == DYNAMIC:
+ return DYNAMIC
+ try:
+ return datetime.fromisoformat(value)
+ except ValueError:
+ raise ValueError(
+ f"Database '{database}' has an invalid `{REPRESENTATIVE_TIME}` "
+ f"metadata value: {value!r}. Expected an ISO 8601 datetime string "
+ f"(e.g. '2030-01-01'), a datetime, or '{DYNAMIC}'."
+ ) from None
+ raise ValueError(
+ f"Database '{database}' has an invalid `{REPRESENTATIVE_TIME}` metadata "
+ f"value of type {type(value).__name__}: {value!r}. Expected an ISO 8601 "
+ f"datetime string, a datetime, or '{DYNAMIC}'."
+ )
+
+
+def set_database_metadata(database: str | bd.Database, **metadata) -> dict:
+ """
+ Store what a database represents in its Brightway metadata.
+
+ Use this for databases that don't bring the metadata themselves, e.g.
+ databases you built yourself or that were exported by a premise version
+ older than the one writing scenario metadata. `TimexLCA` reads
+ `representative_time` from all databases of the project to map them to
+ points in time, so this replaces passing `database_dates`.
+
+ Parameters
+ ----------
+ database : str or bw2data.Database
+ Name of the database, or the database itself. Must be registered.
+ **metadata :
+ Metadata to store. `representative_time` accepts a `datetime`, an ISO
+ 8601 string, or `"dynamic"` and is always stored as a string, because
+ Brightway serializes database metadata to JSON. Any other key is stored
+ as given and must be JSON-serializable. Keys that premise writes, and
+ that `TimexLCA(scenario=...)` can select on, are `iam_model`,
+ `pathway`, `system_model`, `ecoinvent_version` and `premise_version`.
+
+ Returns
+ -------
+ dict
+ The database's metadata after the update.
+
+ Examples
+ --------
+ ```python
+ set_database_metadata("db_2030", representative_time=datetime(2030, 1, 1))
+ set_database_metadata(
+ "my_2050_variant",
+ representative_time="2050-01-01",
+ iam_model="remind",
+ pathway="SSP2-PkBudg500",
+ )
+ ```
+ """
+ from .validation import DatabaseMetadataInputs
+
+ name = _database_name(database)
+ DatabaseMetadataInputs(database=name, metadata=metadata)
+
+ if name not in bd.databases:
+ raise ValueError(
+ f"Database '{name}' is not registered in this Brightway project. "
+ f"Available databases: {sorted(bd.databases)}."
+ )
+
+ serialized = {}
+ for key, value in metadata.items():
+ if key == REPRESENTATIVE_TIME:
+ normalized = _normalize_representative_time(value, name)
+ serialized[key] = (
+ normalized if normalized == DYNAMIC else normalized.isoformat()
+ )
+ continue
+ try:
+ json.dumps(value)
+ except TypeError:
+ raise ValueError(
+ f"Metadata value for '{key}' is not JSON-serializable: {value!r}. "
+ f"Brightway stores database metadata as JSON."
+ ) from None
+ serialized[key] = value
+
+ bd.databases[name].update(serialized)
+ bd.databases.flush()
+ return bd.databases[name]
+```
+
+- [ ] **Step 4: Add the validation model**
+
+Append to `bw_timex/validation.py`:
+
+```python
+class DatabaseMetadataInputs(BaseModel):
+ """Validates inputs to set_database_metadata"""
+
+ model_config = {"arbitrary_types_allowed": True}
+
+ database: str
+ metadata: dict
+
+ @field_validator("metadata")
+ @classmethod
+ def validate_metadata(cls, v: dict) -> dict:
+ if not v:
+ raise ValueError(
+ "Provide at least one metadata field, e.g. "
+ "`representative_time=datetime(2030, 1, 1)`."
+ )
+ for key in v:
+ if not isinstance(key, str):
+ raise ValueError(
+ f"Metadata keys must be strings, got {type(key).__name__}: {key}."
+ )
+ return v
+```
+
+- [ ] **Step 5: Export it**
+
+In `bw_timex/__init__.py`, add the import next to the other helper imports and the name to `__all__` (in the `# utils` block, alphabetically after `plot_characterized_inventory_as_waterfall`):
+
+```python
+from .database_metadata import set_database_metadata
+```
+
+```python
+ "set_database_metadata",
+```
+
+- [ ] **Step 6: Run the tests to verify they pass**
+
+Run: `.venv/bin/pytest tests/test_database_metadata.py -v`
+Expected: PASS (12 tests)
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add bw_timex/database_metadata.py bw_timex/validation.py bw_timex/__init__.py tests/test_database_metadata.py
+git commit -m "feat: add set_database_metadata to store what a database represents"
+```
+
+---
+
+### Task 2: Resolve database dates from metadata
+
+**Files:**
+- Modify: `bw_timex/database_metadata.py`
+- Modify: `tests/test_database_metadata.py`
+
+**Interfaces:**
+- Consumes: `REPRESENTATIVE_TIME`, `SCENARIOS`, `DYNAMIC`, `_normalize_representative_time`, `set_database_metadata` from Task 1.
+- Produces: `resolve_database_dates_from_metadata(scenario: dict | None = None) -> dict[str, datetime | str]` — every registered database carrying `representative_time`, mapped to a `datetime` or `"dynamic"`. Multi-scenario databases are excluded. Scenario filtering and the ambiguity error come in Task 3; this task's version accepts the argument and ignores it.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `tests/test_database_metadata.py`:
+
+```python
+from bw_timex.database_metadata import resolve_database_dates_from_metadata
+
+# ─── Tests for resolving database dates from metadata ───
+
+
+@pytest.mark.usefixtures("temporal_grouping_db_monthly")
+class TestResolveFromMetadata:
+
+ def test_empty_project_metadata_resolves_to_nothing(self):
+ assert resolve_database_dates_from_metadata() == {}
+
+ def test_iso_strings_resolve_to_datetimes(self):
+ set_database_metadata("db_2022", representative_time="2022-01-01")
+ set_database_metadata("db_2024", representative_time="2024-01-01")
+ assert resolve_database_dates_from_metadata() == {
+ "db_2022": datetime(2022, 1, 1),
+ "db_2024": datetime(2024, 1, 1),
+ }
+
+ def test_dynamic_metadata_resolves_to_dynamic(self):
+ set_database_metadata("db_2022", representative_time="2022-01-01")
+ set_database_metadata("foreground", representative_time="dynamic")
+ resolved = resolve_database_dates_from_metadata()
+ assert resolved["foreground"] == "dynamic"
+ assert resolved["db_2022"] == datetime(2022, 1, 1)
+
+ def test_databases_without_metadata_are_ignored(self):
+ set_database_metadata("db_2022", representative_time="2022-01-01")
+ assert set(resolve_database_dates_from_metadata()) == {"db_2022"}
+
+ def test_multi_scenario_database_is_skipped(self):
+ set_database_metadata("db_2022", representative_time="2022-01-01")
+ set_database_metadata(
+ "db_2024",
+ representative_time="2024-01-01",
+ scenarios=[
+ {"pathway": "SSP2-Base", "representative_time": "2024-01-01"},
+ {"pathway": "SSP2-PkBudg500", "representative_time": "2024-01-01"},
+ ],
+ )
+ assert set(resolve_database_dates_from_metadata()) == {"db_2022"}
+
+ def test_invalid_metadata_value_raises_naming_the_database(self):
+ bd.databases["db_2022"]["representative_time"] = "whenever"
+ bd.databases.flush()
+ with pytest.raises(ValueError, match="db_2022"):
+ resolve_database_dates_from_metadata()
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `.venv/bin/pytest tests/test_database_metadata.py::TestResolveFromMetadata -v`
+Expected: FAIL — `ImportError: cannot import name 'resolve_database_dates_from_metadata'`
+
+- [ ] **Step 3: Implement discovery**
+
+Append to `bw_timex/database_metadata.py` (and add `from loguru import logger` to the imports):
+
+```python
+def _candidate_databases() -> dict[str, dict]:
+ """Registered databases that declare a `representative_time`.
+
+ Multi-scenario databases (superstructure and scenario-array exports, which
+ carry a `scenarios` list) are skipped: `bw_timex` needs one technosphere
+ per point in time and cannot pick a scenario out of such a database. They
+ can still be used by naming them in `database_dates`.
+ """
+ candidates = {}
+ for name in bd.databases:
+ metadata = bd.databases[name]
+ if REPRESENTATIVE_TIME not in metadata:
+ continue
+ if metadata.get(SCENARIOS):
+ logger.info(
+ f"Skipping database '{name}': it holds "
+ f"{len(metadata[SCENARIOS])} scenarios, so the point in time it "
+ f"represents is ambiguous. Map it explicitly with `database_dates` "
+ f"if you want to use it anyway."
+ )
+ continue
+ candidates[name] = metadata
+ return candidates
+
+
+def resolve_database_dates_from_metadata(
+ scenario: dict | None = None,
+) -> dict[str, datetime | str]:
+ """
+ Map the databases of the current project to the points in time they represent.
+
+ Reads the `representative_time` metadata of every registered database (see
+ [`set_database_metadata`][bw_timex.database_metadata.set_database_metadata]).
+
+ Parameters
+ ----------
+ scenario : dict, optional
+ Metadata a database must match to be included, e.g.
+ `{"iam_model": "remind", "pathway": "SSP2-PkBudg500"}`. Databases that
+ don't declare a filtered key at all are kept.
+
+ Returns
+ -------
+ dict
+ Mapping of database name to `datetime` or `"dynamic"`, ready to be used
+ as `TimexLCA.database_dates`.
+ """
+ candidates = _candidate_databases()
+ return {
+ name: _normalize_representative_time(metadata[REPRESENTATIVE_TIME], name)
+ for name, metadata in candidates.items()
+ }
+```
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `.venv/bin/pytest tests/test_database_metadata.py -v`
+Expected: PASS (18 tests)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add bw_timex/database_metadata.py tests/test_database_metadata.py
+git commit -m "feat: resolve database dates from representative_time metadata"
+```
+
+---
+
+### Task 3: Scenario filtering and the ambiguity error
+
+**Files:**
+- Modify: `bw_timex/database_metadata.py`
+- Modify: `tests/test_database_metadata.py`
+
+**Interfaces:**
+- Consumes: `resolve_database_dates_from_metadata`, `_candidate_databases`, `SCENARIO_SIGNATURE_KEYS`, `BRIGHTWAY_METADATA_KEYS` from Tasks 1–2.
+- Produces: `resolve_database_dates_from_metadata(scenario)` now filters, and raises `ValueError` on an unknown filter key or on several scenario sets. No new public names.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `tests/test_database_metadata.py`:
+
+```python
+# ─── Tests for scenario selection ───
+
+
+@pytest.mark.usefixtures("temporal_grouping_db_monthly")
+class TestScenarioSelection:
+
+ @pytest.fixture(autouse=True)
+ def two_scenarios(self):
+ """db_2022 and db_2024 hold the same year in two different pathways."""
+ set_database_metadata(
+ "db_2022",
+ representative_time="2022-01-01",
+ iam_model="remind",
+ pathway="SSP2-PkBudg500",
+ premise_version="2.4.9.1",
+ )
+ set_database_metadata(
+ "db_2024",
+ representative_time="2024-01-01",
+ iam_model="remind",
+ pathway="SSP2-Base",
+ premise_version="2.4.9.1",
+ )
+
+ def test_two_scenario_sets_without_selection_raises(self):
+ with pytest.raises(ValueError, match="Several background scenarios"):
+ resolve_database_dates_from_metadata()
+
+ def test_error_names_the_differing_key_and_values(self):
+ with pytest.raises(ValueError) as excinfo:
+ resolve_database_dates_from_metadata()
+ message = str(excinfo.value)
+ assert "pathway" in message
+ assert "SSP2-PkBudg500" in message
+ assert "SSP2-Base" in message
+ # iam_model is identical in both sets, so it isn't part of the report
+ assert "iam_model" not in message
+
+ def test_scenario_selects_one_set(self):
+ resolved = resolve_database_dates_from_metadata(
+ scenario={"pathway": "SSP2-Base"}
+ )
+ assert resolved == {"db_2024": datetime(2024, 1, 1)}
+
+ def test_databases_without_scenario_metadata_survive_the_filter(self):
+ set_database_metadata("foreground", representative_time="dynamic")
+ resolved = resolve_database_dates_from_metadata(
+ scenario={"pathway": "SSP2-Base"}
+ )
+ assert resolved == {
+ "db_2024": datetime(2024, 1, 1),
+ "foreground": "dynamic",
+ }
+
+ def test_several_filter_keys_are_combined(self):
+ resolved = resolve_database_dates_from_metadata(
+ scenario={"iam_model": "remind", "pathway": "SSP2-Base"}
+ )
+ assert set(resolved) == {"db_2024"}
+
+ def test_filter_matching_nothing_resolves_to_nothing(self):
+ assert resolve_database_dates_from_metadata(
+ scenario={"pathway": "SSP2-PkBudg1150"}
+ ) == {}
+
+ def test_unknown_filter_key_raises_listing_available_keys(self):
+ with pytest.raises(ValueError) as excinfo:
+ resolve_database_dates_from_metadata(scenario={"pathwya": "SSP2-Base"})
+ message = str(excinfo.value)
+ assert "pathwya" in message
+ assert "pathway" in message
+
+ def test_same_scenario_from_two_premise_versions_is_not_ambiguous(self):
+ set_database_metadata("db_2024", pathway="SSP2-PkBudg500")
+ set_database_metadata("db_2024", premise_version="2.4.9.2")
+ assert set(resolve_database_dates_from_metadata()) == {"db_2022", "db_2024"}
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `.venv/bin/pytest tests/test_database_metadata.py::TestScenarioSelection -v`
+Expected: FAIL — no error is raised, `resolve_database_dates_from_metadata` currently ignores `scenario`
+
+- [ ] **Step 3: Implement filtering and the ambiguity check**
+
+In `bw_timex/database_metadata.py`, add `from collections import defaultdict` to the imports and insert before `resolve_database_dates_from_metadata`:
+
+```python
+def _as_set(value: Any) -> set:
+ """Compare list-valued metadata (e.g. `external_scenarios`) order-insensitively."""
+ if isinstance(value, (list, tuple, set)):
+ return {str(item) for item in value}
+ return {str(value)}
+
+
+def _values_match(declared: Any, wanted: Any) -> bool:
+ if isinstance(declared, (list, tuple, set)) or isinstance(wanted, (list, tuple, set)):
+ return _as_set(declared) == _as_set(wanted)
+ return str(declared) == str(wanted)
+
+
+def _check_filter_keys(scenario: dict, candidates: dict[str, dict]) -> None:
+ """Reject filter keys no database declares, instead of silently matching nothing."""
+ declared = set()
+ for metadata in candidates.values():
+ declared.update(set(metadata) - BRIGHTWAY_METADATA_KEYS)
+ unknown = sorted(set(scenario) - declared)
+ if not unknown:
+ return
+ available = ", ".join(sorted(declared)) or "none"
+ raise ValueError(
+ f"No database in this project declares the metadata key(s) "
+ f"{unknown}. Keys declared by the databases of this project: {available}. "
+ f"Add the metadata with `bw_timex.set_database_metadata`, or check the "
+ f"spelling of your `scenario` filter."
+ )
+
+
+def _scenario_signature(metadata: dict) -> tuple:
+ return tuple(
+ (key, tuple(sorted(_as_set(metadata[key]))) if key in metadata else None)
+ for key in SCENARIO_SIGNATURE_KEYS
+ )
+
+
+def _format_scenario_sets(groups: dict[tuple, list[str]]) -> str:
+ """One line per scenario set, naming only the keys that actually differ."""
+ differing = [
+ key
+ for index, key in enumerate(SCENARIO_SIGNATURE_KEYS)
+ if len({signature[index][1] for signature in groups}) > 1
+ ]
+ lines = []
+ for signature, names in groups.items():
+ values = dict(signature)
+ description = ", ".join(
+ f"{key}={', '.join(values[key]) if values[key] else 'not set'}"
+ for key in differing
+ )
+ lines.append(f" {description}: {', '.join(sorted(names))}")
+ return "\n".join(lines)
+
+
+def _check_unambiguous(candidates: dict[str, dict]) -> None:
+ groups = defaultdict(list)
+ for name, metadata in candidates.items():
+ if any(key in metadata for key in SCENARIO_SIGNATURE_KEYS):
+ groups[_scenario_signature(metadata)].append(name)
+ if len(groups) <= 1:
+ return
+ raise ValueError(
+ f"Several background scenarios found in this project:\n"
+ f"{_format_scenario_sets(groups)}\n"
+ f"Select one, e.g. scenario={{'pathway': '...'}}, or map the databases "
+ f"explicitly with `database_dates`."
+ )
+```
+
+Then replace the body of `resolve_database_dates_from_metadata` with:
+
+```python
+ candidates = _candidate_databases()
+ if scenario:
+ _check_filter_keys(scenario, candidates)
+ candidates = {
+ name: metadata
+ for name, metadata in candidates.items()
+ if all(
+ key not in metadata or _values_match(metadata[key], wanted)
+ for key, wanted in scenario.items()
+ )
+ }
+ _check_unambiguous(candidates)
+ return {
+ name: _normalize_representative_time(metadata[REPRESENTATIVE_TIME], name)
+ for name, metadata in candidates.items()
+ }
+```
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `.venv/bin/pytest tests/test_database_metadata.py -v`
+Expected: PASS (26 tests)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add bw_timex/database_metadata.py tests/test_database_metadata.py
+git commit -m "feat: select background scenarios by database metadata"
+```
+
+---
+
+### Task 4: Wire it into `TimexLCA`
+
+**Files:**
+- Modify: `bw_timex/timex_lca.py` (imports, class docstring `Examples` block, `__init__` signature + docstring, the `database_dates` fallback block at `timex_lca.py:146-160`)
+- Modify: `bw_timex/validation.py` (`TimexLCAInputs`)
+- Modify: `tests/test_database_metadata.py`
+
+**Interfaces:**
+- Consumes: `resolve_database_dates_from_metadata(scenario)` from Task 3.
+- Produces: `TimexLCA(demand, method, database_dates=None, scenario=None, use_global_lci_cache=True)`; `TimexLCA.scenario` holds the filter that was used; `TimexLCA.database_dates` is the resolved mapping, exactly as before for callers who pass `database_dates`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `tests/test_database_metadata.py`:
+
+```python
+from bw_timex import TimexLCA
+
+# ─── Tests for TimexLCA using database metadata ───
+
+
+@pytest.mark.usefixtures("temporal_grouping_db_monthly")
+class TestTimexLCAFromMetadata:
+
+ @pytest.fixture
+ def fu(self):
+ return bd.get_node(database="foreground", code="A")
+
+ def test_no_arguments_uses_metadata(self, fu):
+ set_database_metadata("db_2022", representative_time="2022-01-01")
+ set_database_metadata("db_2024", representative_time="2024-01-01")
+ tlca = TimexLCA(demand={fu.key: 1}, method=("GWP", "example"))
+ assert tlca.database_dates == {
+ "db_2022": datetime(2022, 1, 1),
+ "db_2024": datetime(2024, 1, 1),
+ "foreground": "dynamic",
+ }
+
+ def test_demand_database_metadata_is_respected(self, fu):
+ set_database_metadata("db_2022", representative_time="2022-01-01")
+ set_database_metadata("foreground", representative_time="dynamic")
+ tlca = TimexLCA(demand={fu.key: 1}, method=("GWP", "example"))
+ assert tlca.database_dates["foreground"] == "dynamic"
+
+ def test_scenario_is_forwarded(self, fu):
+ set_database_metadata(
+ "db_2022", representative_time="2022-01-01", pathway="SSP2-Base"
+ )
+ set_database_metadata(
+ "db_2024", representative_time="2024-01-01", pathway="SSP2-PkBudg500"
+ )
+ tlca = TimexLCA(
+ demand={fu.key: 1},
+ method=("GWP", "example"),
+ scenario={"pathway": "SSP2-Base"},
+ )
+ assert tlca.database_dates == {
+ "db_2022": datetime(2022, 1, 1),
+ "foreground": "dynamic",
+ }
+
+ def test_database_dates_is_exclusive(self, fu):
+ set_database_metadata("db_2022", representative_time="2022-01-01")
+ set_database_metadata("db_2024", representative_time="2024-01-01")
+ tlca = TimexLCA(
+ demand={fu.key: 1},
+ method=("GWP", "example"),
+ database_dates={
+ "db_2024": datetime(2024, 1, 1),
+ "foreground": "dynamic",
+ },
+ )
+ assert tlca.database_dates == {
+ "db_2024": datetime(2024, 1, 1),
+ "foreground": "dynamic",
+ }
+
+ def test_database_dates_with_scenario_raises(self, fu):
+ with pytest.raises(ValueError, match="only applies when"):
+ TimexLCA(
+ demand={fu.key: 1},
+ method=("GWP", "example"),
+ database_dates={"foreground": "dynamic"},
+ scenario={"pathway": "SSP2-Base"},
+ )
+
+ def test_no_metadata_anywhere_falls_back_to_dynamic_demand(self, fu):
+ tlca = TimexLCA(demand={fu.key: 1}, method=("GWP", "example"))
+ assert tlca.database_dates == {"foreground": "dynamic"}
+
+ def test_metadata_and_database_dates_give_the_same_score(self, fu):
+ explicit = TimexLCA(
+ demand={fu.key: 1},
+ method=("GWP", "example"),
+ database_dates={
+ "db_2022": datetime(2022, 1, 1),
+ "db_2024": datetime(2024, 1, 1),
+ "foreground": "dynamic",
+ },
+ )
+ explicit.build_timeline(starting_datetime=datetime(2024, 1, 2))
+ explicit.lci()
+ explicit.static_lcia()
+
+ set_database_metadata("db_2022", representative_time="2022-01-01")
+ set_database_metadata("db_2024", representative_time="2024-01-01")
+ from_metadata = TimexLCA(demand={fu.key: 1}, method=("GWP", "example"))
+ from_metadata.build_timeline(starting_datetime=datetime(2024, 1, 2))
+ from_metadata.lci()
+ from_metadata.static_lcia()
+
+ assert from_metadata.static_score == pytest.approx(explicit.static_score)
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `.venv/bin/pytest tests/test_database_metadata.py::TestTimexLCAFromMetadata -v`
+Expected: FAIL — `TypeError: TimexLCA.__init__() got an unexpected keyword argument 'scenario'`, and `test_no_arguments_uses_metadata` fails because only the demand database is mapped
+
+- [ ] **Step 3: Change the signature and resolution**
+
+In `bw_timex/timex_lca.py`, add to the imports:
+
+```python
+from .database_metadata import resolve_database_dates_from_metadata
+```
+
+Change the signature:
+
+```python
+ def __init__(
+ self,
+ demand: dict,
+ method: tuple,
+ database_dates: dict = None,
+ scenario: dict = None,
+ use_global_lci_cache: bool = True,
+ ) -> None:
+```
+
+Replace the `database_dates` docstring entry and add one for `scenario`:
+
+```
+ database_dates : dict, optional
+ Dictionary mapping database names to the point in time they
+ represent, as a `datetime`, or to `"dynamic"` for databases whose
+ processes are distributed over time (typically the foreground).
+ Several databases may share the same date, e.g. to keep your own
+ modified copies of background processes in their own database
+ instead of writing them into the shared background database for
+ that vintage. If not given, the mapping is read from the
+ databases' own `representative_time` metadata (which premise
+ writes when exporting, and which you can set yourself with
+ `bw_timex.set_database_metadata`). Passing this argument replaces
+ the metadata entirely: only the databases listed here are used.
+ scenario : dict, optional
+ Metadata a background database must match to be used, e.g.
+ `{"iam_model": "remind", "pathway": "SSP2-PkBudg500"}`. Only
+ needed when the project holds several scenarios - `TimexLCA`
+ raises and lists them otherwise. Databases that don't declare the
+ filtered key (your foreground, a hand-built vintage) are always
+ kept. Cannot be combined with `database_dates`.
+```
+
+Replace the fallback block (`self.database_dates = database_dates` through the `if not self.database_dates:` block) with:
+
+```python
+ self.scenario = scenario
+ self.database_dates = self._resolve_database_dates(
+ demand=demand, database_dates=database_dates, scenario=scenario
+ )
+```
+
+Add the method right after `__init__`:
+
+```python
+ @staticmethod
+ def _resolve_database_dates(
+ demand: dict, database_dates: dict | None, scenario: dict | None
+ ) -> dict:
+ """Map databases to the points in time they represent.
+
+ Either from the explicit `database_dates` argument, which is then the
+ whole mapping, or from the databases' own `representative_time`
+ metadata. Databases holding the demand default to `"dynamic"`.
+ """
+ if database_dates:
+ if scenario:
+ raise ValueError(
+ "`scenario` selects background databases by their metadata and "
+ "only applies when `database_dates` is not given. Pass one or "
+ "the other."
+ )
+ return dict(database_dates)
+
+ resolved = resolve_database_dates_from_metadata(scenario)
+
+ if not resolved:
+ logger.info(
+ "No database_dates provided, and no database in this project carries "
+ "`representative_time` metadata. Treating the databases containing the "
+ "functional unit as dynamic. No remapping of inventories to time "
+ "explicit databases will be done."
+ )
+
+ for key in demand:
+ database = bd.get_node(id=get_id(key))["database"]
+ resolved.setdefault(database, "dynamic")
+
+ return resolved
+```
+
+- [ ] **Step 4: Accept `scenario` in the input validation**
+
+In `bw_timex/validation.py`, add the field and its validator to `TimexLCAInputs`:
+
+```python
+ scenario: Optional[dict] = None
+```
+
+```python
+ @field_validator("scenario")
+ @classmethod
+ def validate_scenario(cls, v: Optional[dict]) -> Optional[dict]:
+ if v is None:
+ return v
+ if not v:
+ raise ValueError("scenario must be a non-empty dictionary if provided.")
+ for key, value in v.items():
+ if not isinstance(key, str):
+ raise ValueError(
+ f"scenario keys must be strings (database metadata keys), got "
+ f"{type(key).__name__}."
+ )
+ if not isinstance(value, (str, int, float, bool, list, tuple)):
+ raise ValueError(
+ f"scenario values must be scalars or lists of scalars, got "
+ f"{type(value).__name__} for key '{key}'."
+ )
+ return v
+```
+
+And pass it in `timex_lca.py`, where `TimexLCAInputs` is instantiated:
+
+```python
+ TimexLCAInputs(
+ demand=self.demand,
+ method=self.method,
+ database_dates=self.database_dates,
+ scenario=self.scenario,
+ )
+```
+
+- [ ] **Step 5: Update the class docstring example**
+
+In the `Examples` block of the `TimexLCA` class docstring, put the metadata path first and keep the explicit mapping as the alternative:
+
+```python
+ from bw_timex import TimexLCA, set_database_metadata
+
+ demand = {("my_foreground_database", "my_process"): 1}
+ method = ("some_method_family", "some_category", "some_method")
+
+ # Databases exported by premise already know the point in time they
+ # represent. For your own databases, say so once:
+ set_database_metadata("my_background_database_one", representative_time=datetime(2020, 1, 1))
+ set_database_metadata("my_background_database_two", representative_time=datetime(2030, 1, 1))
+
+ tlca = TimexLCA(demand, method)
+
+ # ... or map the databases explicitly, which then replaces the metadata:
+ tlca = TimexLCA(
+ demand,
+ method,
+ database_dates={
+ "my_background_database_one": datetime(2020, 1, 1),
+ "my_background_database_two": datetime(2030, 1, 1),
+ # Several databases may share the same date, e.g. to keep your own
+ # modified copies of background processes in their own database:
+ "my_modified_background_2020": datetime(2020, 1, 1),
+ "my_foreground_database": "dynamic",
+ },
+ )
+
+ tlca.build_timeline() # has many optional arguments
+ tlca.lci()
+ tlca.static_lcia()
+ print(tlca.static_score)
+ # also available: "GWP", "pGWP", "pGTP", "prospective_radiative_forcing"
+ tlca.dynamic_lcia(metric="radiative_forcing")
+ print(tlca.dynamic_score)
+```
+
+- [ ] **Step 6: Run the new tests**
+
+Run: `.venv/bin/pytest tests/test_database_metadata.py -v`
+Expected: PASS (33 tests)
+
+- [ ] **Step 7: Run the whole suite to prove nothing regressed**
+
+Run: `.venv/bin/pytest -x -q`
+Expected: PASS, same count as on `main` plus the new tests. Every existing test passes `database_dates`, so the exclusive branch must keep them green.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add bw_timex/timex_lca.py bw_timex/validation.py tests/test_database_metadata.py
+git commit -m "feat: read database timing from metadata by default in TimexLCA"
+```
+
+---
+
+### Task 5: Documentation
+
+**Files:**
+- Create: `docs/content/background_database_metadata.md`
+- Create: `docs/api/database_metadata.md`
+- Modify: `zensical.toml` (User Guide nav, API nav)
+- Modify: `docs/content/getting_started/quickstart.md:58-70`, `:96`, `:128-132`
+- Modify: `docs/content/getting_started/adding_temporal_information.md:250-282`
+- Modify: `docs/content/getting_started/build_process_timeline.md:11-21`
+- Modify: `CHANGES.md`
+
+**Interfaces:**
+- Consumes: `set_database_metadata`, `TimexLCA(scenario=...)` from Tasks 1–4.
+- Produces: no code.
+
+- [ ] **Step 1: Write the new reference page**
+
+Create `docs/content/background_database_metadata.md`:
+
+````markdown
+---
+icon: lucide/calendar-clock
+tags:
+ - background databases
+---
+
+# What a database represents
+
+`bw_timex` needs to know which point in time each background database stands for.
+That information lives in the database's own Brightway metadata, so it only has to
+be recorded once - not in every script.
+
+```python
+import bw2data as bd
+
+bd.databases["ei_cutoff_3.10.1_remind_SSP2-PkBudg500_2050"]
+```
+
+```python
+{
+ # written by brightway
+ "format": "Ecoinvent XML", "backend": "sqlite", "number": 43648, ...,
+ # written by premise
+ "premise_version": "2.4.9.1",
+ "iam_model": "remind",
+ "pathway": "SSP2-PkBudg500",
+ "representative_time": "2050-01-01T00:00:00",
+ "ecoinvent_version": "3.10.1",
+ "system_model": "cutoff",
+}
+```
+
+Only `representative_time` is required. `TimexLCA` reads it from every database of
+your project, so a study on premise databases needs no timing argument at all:
+
+```python
+tlca = TimexLCA(demand={("foreground", "A"): 1}, method=("our", "method"))
+```
+
+!!! info "premise version"
+
+ premise writes this metadata from the version following 2.4.9.2 onwards. For
+ databases written by an earlier version, set it yourself as shown below - it is
+ a one-liner per database.
+
+## Setting it yourself
+
+For databases you built yourself, use
+[`set_database_metadata`][bw_timex.database_metadata.set_database_metadata]:
+
+```python
+from datetime import datetime
+from bw_timex import set_database_metadata
+
+set_database_metadata("background_2020", representative_time=datetime(2020, 1, 1))
+set_database_metadata("background_2030", representative_time=datetime(2030, 1, 1))
+```
+
+The value is stored as an ISO 8601 string, because Brightway keeps database
+metadata as JSON. You only do this once per database: it is stored in the project,
+not in your script.
+
+Your foreground doesn't represent a point in time - its processes get distributed
+over time. `TimexLCA` treats the databases holding your functional unit as
+`"dynamic"` automatically, but you can also say so explicitly:
+
+```python
+set_database_metadata("foreground", representative_time="dynamic")
+```
+
+## Several databases for the same point in time
+
+More than one database may carry the same date. This is useful when you modify
+background processes: keep the modified copies in your own database per point in
+time, instead of writing them into ecoinvent or premise.
+
+```python
+set_database_metadata("my_background_2020", representative_time=datetime(2020, 1, 1))
+set_database_metadata("my_background_2030", representative_time=datetime(2030, 1, 1))
+```
+
+For each process, `bw_timex` interpolates only between the databases that actually
+contain it, matched on `name`, `reference product` and `location`.
+
+## Choosing a scenario
+
+A project often holds more than one IAM scenario. `bw_timex` refuses to guess and
+tells you what it found:
+
+```
+Several background scenarios found in this project:
+ pathway=SSP2-PkBudg500: ei_..._2030, ei_..._2040, ei_..._2050
+ pathway=SSP2-Base: ei_..._2030, ei_..._2040, ei_..._2050
+Select one, e.g. scenario={'pathway': '...'}, or map the databases explicitly with
+`database_dates`.
+```
+
+Pick one with the `scenario` argument, which filters the databases on their
+metadata:
+
+```python
+tlca = TimexLCA(
+ demand={("foreground", "A"): 1},
+ method=("our", "method"),
+ scenario={"pathway": "SSP2-PkBudg500"},
+)
+```
+
+Any metadata key works - `iam_model`, `pathway`, `system_model`,
+`ecoinvent_version`, `premise_version`, or anything you set yourself. Databases
+that don't carry the key at all (your foreground, your own vintages) are never
+filtered out.
+
+Comparing scenarios is then a loop over filters:
+
+```python
+scores = {}
+for pathway in ("SSP2-Base", "SSP2-PkBudg500"):
+ tlca = TimexLCA(demand, method, scenario={"pathway": pathway})
+ tlca.build_timeline()
+ tlca.lci()
+ tlca.static_lcia()
+ scores[pathway] = tlca.static_score
+```
+
+!!! warning "Superstructure databases"
+
+ Databases holding several scenarios at once (premise superstructure or
+ scenario-array exports) are skipped: they have no single technosphere per point
+ in time. Use one database per scenario and year.
+
+## Mapping the databases explicitly
+
+`database_dates` still does what it always did, and takes over completely: when you
+pass it, metadata is not read at all and only the databases you list are used.
+
+```python
+tlca = TimexLCA(
+ demand={("foreground", "A"): 1},
+ method=("our", "method"),
+ database_dates={
+ "background": datetime(2020, 1, 1),
+ "background_2030": datetime(2030, 1, 1),
+ "foreground": "dynamic",
+ },
+)
+```
+
+Use it when you want to restrict a calculation to a subset of the databases in your
+project, or when a database's metadata is wrong and you don't want to change it.
+````
+
+- [ ] **Step 2: Add both pages to the nav**
+
+In `zensical.toml`, add the User Guide entry after the Walkthrough block (after the line `]},` that closes `Walkthrough`, before `{ "What LCA should I do?" ...`):
+
+```toml
+ { "What a database represents" = "content/background_database_metadata.md" },
+```
+
+And in the API nav block, next to the other API pages:
+
+```toml
+ { "Database metadata" = "api/database_metadata.md" },
+```
+
+Create `docs/api/database_metadata.md`, following `docs/api/utils.md`:
+
+```markdown
+---
+icon: lucide/calendar-clock
+tags:
+ - api
+---
+
+# Database metadata
+
+Reading and writing what a Brightway database represents: the point in time
+(`representative_time`) and, for prospective databases, the scenario it was built
+for.
+
+::: bw_timex.database_metadata
+```
+
+- [ ] **Step 3: Update the quickstart**
+
+In `docs/content/getting_started/quickstart.md`, replace step 3 and the `TimexLCA` call:
+
+```python
+# 3. Say what your time-specific background databases represent
+# (premise databases already know - skip this for them)
+set_database_metadata("background", representative_time=datetime(2020, 1, 1))
+set_database_metadata("background_2030", representative_time=datetime(2030, 1, 1))
+
+# 4. Create the TimexLCA object
+tlca = TimexLCA(
+ demand={("foreground", "A"): 1},
+ method=("our", "method"),
+)
+```
+
+Add `set_database_metadata` to the `from bw_timex import ...` line at the top of that
+code block. In the cheat sheet, change the background row to:
+
+```
+| *How the background changes* over time | one database per point in time, each with `representative_time` metadata | background databases |
+```
+
+And replace the trailing paragraph about `database_dates` (lines 128-132) with:
+
+```markdown
+Absolute dates (`dtype="datetime64[s]"`) are also allowed in a `TemporalDistribution`,
+e.g. for the timing of the functional unit itself. Relative dates
+(`dtype="timedelta64[Y]"`) are relative to the consuming process. Several databases may
+represent the same point in time, e.g. if you keep modified copies of background
+processes in their own database instead of writing them into the shared vintage. See
+[Time-specific background databases](../background_database_metadata.md) for scenario selection
+and for mapping databases explicitly with `database_dates`.
+```
+
+- [ ] **Step 4: Update walkthrough step 1**
+
+In `docs/content/getting_started/adding_temporal_information.md`, replace the paragraph and code block at lines 250-262 with:
+
+````markdown
+So, as you can see, the processes at specific time steps reside within a separate normal
+Brightway database. `bw_timex` picks these up automatically, as long as each database
+says which point in time it represents:
+
+```python
+from datetime import datetime
+from bw_timex import set_database_metadata
+
+set_database_metadata("background", representative_time=datetime(2020, 1, 1))
+set_database_metadata("background_2030", representative_time=datetime(2030, 1, 1))
+```
+
+You only do this once per database - it is stored in your Brightway project. Databases
+exported by [premise](https://premise.readthedocs.io/en/latest/introduction.html) bring
+this metadata with them, so there is nothing to do for those. The foreground doesn't
+represent a specific point in time and is distributed over time instead; `bw_timex`
+treats the databases holding your functional unit that way automatically.
+````
+
+Replace the code block in the "Several databases for the same point in time" section
+(lines 274-282) with:
+
+```python
+set_database_metadata("ecoinvent_2020", representative_time=datetime(2020, 1, 1))
+set_database_metadata("ecoinvent_2030", representative_time=datetime(2030, 1, 1))
+set_database_metadata("my_background_2020", representative_time=datetime(2020, 1, 1))
+set_database_metadata("my_background_2030", representative_time=datetime(2030, 1, 1))
+```
+
+- [ ] **Step 5: Update walkthrough step 2**
+
+In `docs/content/getting_started/build_process_timeline.md`, replace lines 11-21 with:
+
+````markdown
+With all the temporal information prepared, we can now instantiate our TimexLCA object.
+This is just like a normal Brightway LCA object - the timing of the background databases
+comes from their metadata:
+
+```python
+from bw_timex import TimexLCA
+
+tlca = TimexLCA(
+ demand={("foreground", "A"): 1},
+ method=("our", "method"),
+)
+```
+
+If your project holds several scenarios, select one with
+`scenario={"pathway": "SSP2-PkBudg500"}`; to map the databases by hand instead, pass
+`database_dates`. Both are covered in
+[Time-specific background databases](../background_database_metadata.md).
+````
+
+- [ ] **Step 6: Add the changelog entry**
+
+Under `## [Unreleased]` in `CHANGES.md`:
+
+```markdown
+* Added `representative_time` database metadata as the default timing source: `TimexLCA` now maps background databases to points in time by reading their Brightway metadata (as written by premise), making `database_dates` optional ([#217](https://github.com/brightway-lca/bw_timex/issues/217))
+* Added `set_database_metadata` to record Time-specific background databases (`representative_time`, and scenario fields such as `iam_model` or `pathway`) for databases that don't bring the metadata themselves
+* Added `TimexLCA(scenario={...})` to select one background scenario when a project holds several; `TimexLCA` raises and lists the scenarios it found if the choice is ambiguous
+```
+
+- [ ] **Step 7: Verify the docs build**
+
+Run: `.venv/bin/python -m zensical build 2>&1 | tail -20`
+Expected: build succeeds, no warning about `background_database_metadata.md` or `api/database_metadata.md` being missing from the nav. If `zensical` is not installed in the venv, run `.venv/bin/python -c "import tomllib, pathlib; tomllib.loads(pathlib.Path('zensical.toml').read_text())"` to at least prove the nav edit is valid TOML, and say in the commit that the build was not run.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add docs zensical.toml CHANGES.md
+git commit -m "docs: document representative_time database metadata"
+```
+
+---
+
+### Task 6: Tutorial notebooks
+
+**Files:**
+- Modify: `notebooks/tutorials/1_getting_started.ipynb`
+- Modify: `notebooks/tutorials/2_electric_vehicle_from_scratch.ipynb`
+- Modify: `notebooks/tutorials/3_dynamic_characterization.ipynb`
+- Modify: `notebooks/tutorials/4_import_model_from_excel.ipynb`
+
+**Interfaces:**
+- Consumes: `set_database_metadata`, `TimexLCA()` without `database_dates` from Tasks 1–4.
+- Produces: no code.
+
+These notebooks build their own small databases, so they can be re-executed.
+
+- [ ] **Step 1: Find every occurrence**
+
+Run: `grep -n "database_dates" notebooks/tutorials/*.ipynb`
+Note which cells build the mapping and which pass it to `TimexLCA`.
+
+- [ ] **Step 2: Edit the cells**
+
+In each notebook, use `NotebookEdit` to:
+1. Replace the cell that builds `database_dates` with `set_database_metadata` calls, one per background database, keeping the surrounding markdown explanation in sync (it must no longer say "we define a dictionary that maps databases to dates").
+2. Drop the `database_dates=database_dates` argument from the `TimexLCA(...)` call.
+3. Add `set_database_metadata` to the `from bw_timex import ...` cell.
+
+Pattern:
+
+```python
+# before
+database_dates = {
+ "db_2020": datetime.strptime("2020", "%Y"),
+ "db_2030": datetime.strptime("2030", "%Y"),
+ "foreground": "dynamic",
+}
+tlca = TimexLCA(demand={fu.key: 1}, method=method, database_dates=database_dates)
+
+# after
+set_database_metadata("db_2020", representative_time=datetime(2020, 1, 1))
+set_database_metadata("db_2030", representative_time=datetime(2030, 1, 1))
+tlca = TimexLCA(demand={fu.key: 1}, method=method)
+```
+
+- [ ] **Step 3: Re-execute each notebook**
+
+Run, one notebook at a time:
+
+```bash
+.venv/bin/jupyter nbconvert --to notebook --execute --inplace notebooks/tutorials/1_getting_started.ipynb
+```
+
+Expected: completes without error. If a notebook needs data that isn't in the repo, do
+not execute it — leave the stored outputs, and note that in the commit message.
+
+- [ ] **Step 4: Check the diff for accidental churn**
+
+Run: `git diff --stat notebooks/tutorials`
+Expected: only the edited cells plus their re-executed outputs. If execution rewrote
+every cell id or bumped unrelated metadata, restore and re-run with
+`--ClearMetadataPreprocessor.enabled=True` off, keeping the diff readable.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add notebooks/tutorials
+git commit -m "docs: use database metadata instead of database_dates in the tutorials"
+```
+
+---
+
+### Task 7: Remaining notebooks
+
+**Files:**
+- Modify: `notebooks/advanced/background_temporal_distributions.ipynb`
+- Modify: `notebooks/advanced/uncertainty_with_datapackages.ipynb`
+- Modify: `notebooks/advanced/background_temporal_distributions_premise.ipynb`
+- Modify: `notebooks/teaching/ev_walkthrough_premise.ipynb`
+- Modify: `notebooks/teaching/exercise_ev_vs_petrol_solutions.ipynb`
+- Modify: `notebooks/examples/electric_vehicle_premise.ipynb`
+- Modify: `notebooks/examples/electric_vehicle_premise_detailed.ipynb`
+- Modify: `notebooks/development/benchmarking.ipynb`
+- **Do not touch:** `notebooks/examples/paper_case_study.ipynb`
+
+**Interfaces:**
+- Consumes: `set_database_metadata`, `TimexLCA(scenario=...)` from Tasks 1–4.
+- Produces: no code.
+
+The first two build their own databases and can be re-executed. The rest need premise
+or ecoinvent databases that aren't in the repo: edit the cell sources only and leave
+the stored outputs alone.
+
+- [ ] **Step 1: Edit the two self-contained notebooks**
+
+`background_temporal_distributions.ipynb` and `uncertainty_with_datapackages.ipynb`:
+same replacement as Task 6 Step 2, then re-execute:
+
+```bash
+.venv/bin/jupyter nbconvert --to notebook --execute --inplace notebooks/advanced/background_temporal_distributions.ipynb
+.venv/bin/jupyter nbconvert --to notebook --execute --inplace notebooks/advanced/uncertainty_with_datapackages.ipynb
+```
+
+- [ ] **Step 2: Edit the premise/ecoinvent notebooks**
+
+For each of the six remaining notebooks, replace the `database_dates` cell. These use
+premise databases, which carry the metadata already, so the mapping usually
+disappears entirely:
+
+```python
+# before
+database_dates = {
+ "ei312_REMIND-EU_SSP2_NDC_2020": datetime.strptime("2020", "%Y"),
+ "ei312_REMIND-EU_SSP2_NDC_2030": datetime.strptime("2030", "%Y"),
+ "foreground": "dynamic",
+}
+tlca = TimexLCA(demand={fu.key: 1}, method=method, database_dates=database_dates)
+
+# after
+# The premise databases carry the point in time they represent in their
+# metadata, so bw_timex finds them by itself.
+tlca = TimexLCA(demand={fu.key: 1}, method=method)
+```
+
+Two things to get right per notebook:
+- If the notebook creates its own modified copies of background processes in extra
+ databases (the electric-vehicle notebooks do, e.g. `..., without EOL` copies), those
+ copies need `set_database_metadata(..., representative_time=...)` with the same date
+ as the vintage they were copied from, or they drop out of the mapping.
+- If the notebook's project could hold more than one pathway, show the `scenario`
+ argument in the markdown right below, e.g.
+ `scenario={"pathway": "SSP2-PkBudg500"}`.
+
+Update the surrounding markdown text wherever it explains `database_dates`.
+
+- [ ] **Step 3: Verify no notebook lost its outputs**
+
+Run: `git diff --stat notebooks`
+Expected: for the six premise notebooks, only source cells change - no `outputs` churn.
+
+- [ ] **Step 4: Confirm the paper case study is untouched**
+
+Run: `git status --porcelain notebooks/examples/paper_case_study.ipynb`
+Expected: no output.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add notebooks
+git commit -m "docs: use database metadata instead of database_dates in the notebooks"
+```
+
+---
+
+### Task 8: Final verification
+
+**Files:** none
+
+- [ ] **Step 1: Full test suite**
+
+Run: `.venv/bin/pytest -q`
+Expected: all pass.
+
+- [ ] **Step 2: Nothing still teaches the old default**
+
+Run: `grep -rn "database_dates" --include="*.md" --include="*.ipynb" docs notebooks | grep -v paper_case_study | grep -v superpowers`
+Expected: only the places that deliberately document `database_dates` as the explicit
+override — `background_database_metadata.md`, the quickstart's closing paragraph, and
+step 2's pointer. Anything else is a leftover.
+
+- [ ] **Step 3: Public API test still describes the namespace**
+
+Run: `.venv/bin/pytest tests/test_public_api.py -v`
+Expected: PASS. If it asserts an exact `__all__`, add `set_database_metadata` to it.
+
+- [ ] **Step 4: Commit any fixes and push the branch**
+
+```bash
+git add -A
+git commit -m "fix: address leftovers from the metadata migration"
+git push -u origin feat/representative-time-metadata
+```
diff --git a/docs/superpowers/specs/2026-08-21-representative-time-metadata-design.md b/docs/superpowers/specs/2026-08-21-representative-time-metadata-design.md
new file mode 100644
index 00000000..773202ed
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-21-representative-time-metadata-design.md
@@ -0,0 +1,284 @@
+# Representative time as database metadata
+
+## Problem
+
+`TimexLCA` learns what a background database represents in one way only: the
+`database_dates` argument the user hand-writes at every call site.
+
+```python
+database_dates = {
+ "ei310_remind_SSP2-PkBudg500_2030": datetime(2030, 1, 1),
+ "ei310_remind_SSP2-PkBudg500_2040": datetime(2040, 1, 1),
+ "ei310_remind_SSP2-PkBudg500_2050": datetime(2050, 1, 1),
+ "foreground": "dynamic",
+}
+```
+
+The information is already in the database — a premise export knows the year it was
+built for — but it lives only in the database *name*, so every study re-types it, and
+a typo either raises (`Database 'x' not available`) or, worse, silently maps a vintage
+to the wrong year.
+
+premise [PR #303](https://github.com/polca/premise/pull/303) (merged to `master`, not
+in 2.4.9.2) closes the gap on the producing side: exported Brightway databases now
+carry what they represent in their `bd.databases[name]` metadata.
+
+```python
+{
+ # written by brightway
+ "format": "Ecoinvent XML", "depends": [...], "backend": "sqlite",
+ "number": 43648, "modified": "...", "processed": "...",
+ # written by premise
+ "premise_version": "2.4.9.1",
+ "iam_model": "remind",
+ "pathway": "SSP2-PkBudg500",
+ "representative_time": "2050-01-01T00:00:00",
+ "ecoinvent_version": "3.10.1",
+ "system_model": "cutoff",
+}
+```
+
+Multi-scenario exports (superstructure, scenario arrays) instead carry a `scenarios`
+list of such mappings, and a top-level `representative_time` only when all their
+scenarios share a year. User (external) scenarios are listed under
+`external_scenarios`.
+
+## Goal
+
+`TimexLCA` reads the databases' own metadata by default, so the common case needs no
+timing argument at all:
+
+```python
+tlca = TimexLCA(demand={("foreground", "A"): 1}, method=("GWP", "example"))
+```
+
+A project holding several IAM scenarios stays unambiguous: `TimexLCA` refuses to guess
+and tells the user how to pick.
+
+```python
+tlca = TimexLCA(
+ demand={("foreground", "A"): 1},
+ method=("GWP", "example"),
+ scenario={"pathway": "SSP2-PkBudg500"},
+)
+```
+
+Databases that carry no metadata (hand-built vintages, the foreground) get it from a
+one-line helper instead of a repeated argument.
+
+## Non-goals
+
+- Removing or deprecating `database_dates`. It stays, unchanged in meaning, and
+ scripts that pass it behave exactly as they do today.
+- Reading anything from database *names*. No year parsing, no naming convention.
+- Making superstructure / scenario-array databases usable in `TimexLCA`. They are
+ recognised and skipped, not supported.
+- Writing metadata on import of ecoinvent or any other database. Only the explicit
+ helper writes.
+- Changing how a resolved `database_dates` mapping is used downstream. Everything
+ after resolution — timeline, temporal markets, matrix modification — is untouched.
+
+## Design
+
+### Public interface
+
+```python
+TimexLCA(
+ demand: dict,
+ method: tuple,
+ database_dates: dict = None,
+ scenario: dict = None,
+ use_global_lci_cache: bool = True,
+)
+```
+
+`scenario` is a mapping of database metadata key to required value. Any key that
+appears in database metadata is allowed — `iam_model`, `pathway`, `system_model`,
+`ecoinvent_version`, `premise_version`, and whatever premise adds later. It is a dict
+rather than a set of explicit keywords so that the signature stays closed (a
+misspelled `use_global_lci_cache` raises `TypeError` instead of being swallowed as a
+filter), the call site reads as background selection, and one dict can be reused
+across a comparison loop.
+
+```python
+from bw_timex import set_database_metadata
+
+set_database_metadata("db_2030", representative_time=datetime(2030, 1, 1))
+set_database_metadata(
+ "my_2050_variant",
+ representative_time="2050-01-01",
+ iam_model="remind",
+ pathway="SSP2-PkBudg500",
+)
+```
+
+### Resolution
+
+`TimexLCA.__init__` resolves `self.database_dates` before anything else, in
+`_resolve_database_dates`. Two mutually exclusive branches:
+
+**`database_dates` given.** It is the whole mapping. Metadata is not read, `scenario`
+must be `None` (passing both raises `ValueError`), and demand databases missing from
+it raise in validation as they do today. This keeps every existing script
+bit-for-bit unchanged: a legacy call in a project that also holds ten premise
+vintages must not silently pull those ten in.
+
+**`database_dates` not given.** Resolve from metadata:
+
+1. **Candidates.** Every database in `bd.databases` whose metadata has a
+ `representative_time`.
+2. **Skip multi-scenario databases.** A candidate that also has a non-empty
+ `scenarios` list is dropped with a `logger.info` naming it. `bw_timex` needs one
+ technosphere per point in time and cannot pick a scenario out of a superstructure
+ database. Such a database can still be used by naming it in `database_dates`.
+3. **Filter by `scenario`.** A candidate is dropped only if it *declares* a filtered
+ key with a different value. A candidate that does not declare the key at all is
+ kept — a hand-built 2020 database, an untouched ecoinvent, or the foreground has no
+ `pathway`, and filtering it out would break every mixed setup.
+ `external_scenarios` (a list) compares order-insensitively as a set; all other
+ values compare with `==` after `str` coercion of both sides.
+4. **Ambiguity check.** Over the surviving candidates that declare at least one
+ scenario key, build a signature from
+ `("iam_model", "pathway", "system_model", "ecoinvent_version", "external_scenarios")`
+ (missing key → `None`). Bookkeeping keys such as `premise_version` are deliberately
+ not part of the signature: re-running premise must not look like a second scenario.
+ More than one distinct signature raises `ValueError`, reporting only the keys whose
+ values actually differ:
+
+ ```
+ Several background scenarios found in this project:
+ pathway='SSP2-PkBudg500': ei310_remind_SSP2-PkBudg500_2030,
+ ei310_remind_SSP2-PkBudg500_2040,
+ ei310_remind_SSP2-PkBudg500_2050
+ pathway='SSP2-Base': ei310_remind_SSP2-Base_2030,
+ ei310_remind_SSP2-Base_2040,
+ ei310_remind_SSP2-Base_2050
+ Select one, e.g. scenario={'pathway': 'SSP2-PkBudg500'}, or map the databases
+ explicitly with database_dates.
+ ```
+
+ Databases that declare no scenario key at all never appear in this check and are
+ always kept.
+5. **Normalize values.** `datetime` passes through; a string parses with
+ `datetime.fromisoformat`; the literal `"dynamic"` passes through. Anything else
+ raises `ValueError` naming the database, the key and the offending value.
+6. **Demand databases.** Every database holding a demand key that is not already
+ mapped is added as `"dynamic"`.
+7. **Nothing found.** If no database carries `representative_time`, log the existing
+ "no remapping will be done" message and fall back to today's behaviour: demand
+ databases marked `"dynamic"`.
+
+An unknown filter key — one that no candidate database declares — raises rather than
+filtering everything away, listing the keys and values present in the project. That is
+what buys back the autocomplete a dict does not give.
+
+### Module layout
+
+Discovery, filtering and the setter live in a new module,
+`bw_timex/database_metadata.py`. `timex_lca.py` is already large and this is a
+self-contained responsibility with its own tests; `utils.py` holds exchange- and
+plot-level helpers. `TimexLCA` imports `resolve_database_dates_from_metadata` from it,
+and `set_database_metadata` is re-exported from the `bw_timex` top-level namespace.
+
+### Setter helper
+
+`bw_timex.database_metadata.set_database_metadata(database, **metadata)`, re-exported
+from `bw_timex`:
+
+- `database` may be a name or a `bd.Database`; unregistered → `ValueError`.
+- `representative_time` accepts a `datetime` (serialized with `.isoformat()`), an ISO
+ string (validated by round-tripping through `fromisoformat`), or `"dynamic"`.
+ Brightway metadata is stored as JSON, so a `datetime` object left in it breaks
+ `bd.databases.flush()`; converting is the point of the helper.
+- Any other key is written as given, after a JSON-serializability check.
+- Writes into `bd.databases[name]` and calls `bd.databases.flush()`, so the value
+ survives a project reload.
+- Returns the resulting metadata mapping.
+
+### Validation
+
+`TimexLCAInputs` gains `scenario: Optional[dict]`, validating that keys are strings
+and values are scalars or lists of scalars, and that `scenario` and `database_dates`
+are not both given. The metadata-side errors (unparseable value, ambiguity, unknown
+filter key) are raised in `_resolve_database_dates`, which owns the metadata, not in
+the pydantic model.
+
+`set_database_metadata` gets its own `DatabaseMetadataInputs` model in
+`validation.py`, matching how the other user-facing helpers validate.
+
+## Interactions and limits
+
+- **Several databases per date** ([#205](https://github.com/brightway-lca/bw_timex/pull/205))
+ still works: metadata discovery can map two databases to the same
+ `representative_time`, which is exactly the modified-copy case. Two full ecoinvent
+ copies of the same vintage (e.g. from two premise runs) collide on process identity
+ and raise there, as designed; the fix is a `scenario` filter on `premise_version` or
+ an explicit `database_dates`.
+- **Setup cost.** `TimexLCA.__init__` loads node metadata for every database in
+ `database_dates`, so auto-discovery costs one node-metadata load per matching
+ database. A project holding vintages from an unrelated study pays for them; the
+ escape hatches are `scenario` or `database_dates`.
+- **premise version.** The metadata is written by premise `master` (post-2.4.9.2).
+ Databases written by older premise carry nothing, and the docs say so; those users
+ either write metadata with the helper or keep using `database_dates`.
+
+## Documentation
+
+- `docs/content/getting_started/quickstart.md`: step 3 becomes "the databases already
+ know when they are"; `database_dates` shown once as the explicit alternative; the
+ cheat-sheet row for background timing updated.
+- `docs/content/getting_started/adding_temporal_information.md` and
+ `build_process_timeline.md`: update the passages that name `database_dates`.
+- New section in `docs/content/getting_started/` on what a database represents:
+ the metadata keys, `set_database_metadata`, scenario selection and its error, the
+ premise-version caveat, and `database_dates` as the explicit override.
+- New `docs/api/database_metadata.md` (`::: bw_timex.database_metadata`), added to the
+ API nav in `zensical.toml`.
+- `CHANGES.md`: entry under `[Unreleased]`.
+
+## Notebooks
+
+Every notebook that builds its own databases writes metadata with
+`set_database_metadata` and drops the `database_dates` argument; the premise notebooks
+rely on premise-written metadata and show `scenario` where a project holds more than
+one pathway.
+
+- `notebooks/tutorials/1_getting_started.ipynb`
+- `notebooks/tutorials/2_electric_vehicle_from_scratch.ipynb`
+- `notebooks/tutorials/3_dynamic_characterization.ipynb`
+- `notebooks/tutorials/4_import_model_from_excel.ipynb`
+- `notebooks/advanced/background_temporal_distributions.ipynb`
+- `notebooks/advanced/background_temporal_distributions_premise.ipynb`
+- `notebooks/advanced/uncertainty_with_datapackages.ipynb`
+- `notebooks/teaching/ev_walkthrough_premise.ipynb`
+- `notebooks/teaching/exercise_ev_vs_petrol_solutions.ipynb`
+- `notebooks/examples/electric_vehicle_premise.ipynb`
+- `notebooks/examples/electric_vehicle_premise_detailed.ipynb`
+- `notebooks/development/benchmarking.ipynb`
+
+`notebooks/examples/paper_case_study.ipynb` is **not** touched: it reproduces a
+published study and must keep its exact code.
+
+## Testing
+
+New `tests/test_database_metadata.py`, on the existing small fixtures:
+
+- Timing resolved from `representative_time` metadata with no `database_dates`.
+- ISO string and `datetime` metadata values both resolve; `"dynamic"` in metadata
+ marks a database dynamic; a garbage value raises naming the database.
+- Demand database defaults to `"dynamic"` when its metadata says nothing.
+- `database_dates` is exclusive: a project full of metadata-carrying databases plus an
+ explicit `database_dates` resolves to exactly that mapping.
+- `database_dates` together with `scenario` raises.
+- `scenario` filter selects one pathway out of two; databases without scenario
+ metadata survive the filter.
+- Two scenario sets and no `scenario` raises, and the message names the differing key
+ and both values.
+- Same scenario written by two premise versions does not raise (bookkeeping keys are
+ outside the signature).
+- A database carrying `scenarios` is skipped, and named in the log.
+- An unknown filter key raises listing the available keys.
+- `set_database_metadata` round-trips through `bd.databases.flush()` and a re-read;
+ a `datetime` lands as an ISO string; an unregistered database raises.
+- End-to-end: an existing scenario test rewritten to use metadata gives the same
+ score as the `database_dates` version.
diff --git a/notebooks/advanced/background_temporal_distributions.ipynb b/notebooks/advanced/background_temporal_distributions.ipynb
index acd8fee4..1614071e 100644
--- a/notebooks/advanced/background_temporal_distributions.ipynb
+++ b/notebooks/advanced/background_temporal_distributions.ipynb
@@ -57,10 +57,10 @@
"id": "942222ef",
"metadata": {
"execution": {
- "iopub.execute_input": "2026-06-22T08:08:47.650263Z",
- "iopub.status.busy": "2026-06-22T08:08:47.650130Z",
- "iopub.status.idle": "2026-06-22T08:08:48.990960Z",
- "shell.execute_reply": "2026-06-22T08:08:48.990545Z"
+ "iopub.execute_input": "2026-08-21T10:31:55.868733Z",
+ "iopub.status.busy": "2026-08-21T10:31:55.868550Z",
+ "iopub.status.idle": "2026-08-21T10:31:57.383744Z",
+ "shell.execute_reply": "2026-08-21T10:31:57.383219Z"
}
},
"outputs": [
@@ -77,21 +77,21 @@
"output_type": "stream",
"text": [
"\r",
- "100%|██████████| 1/1 [00:00<00:00, 10754.63it/s]"
+ "100%|██████████| 1/1 [00:00<00:00, 10951.19it/s]"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
- "\u001b[2m10:08:48+0200\u001b[0m [\u001b[32m\u001b[1minfo \u001b[0m] \u001b[1mVacuuming database \u001b[0m\n"
+ "\u001b[2m12:31:57+0200\u001b[0m [\u001b[32m\u001b[1minfo \u001b[0m] \u001b[1mVacuuming database \u001b[0m\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
- "\u001b[2m10:08:48+0200\u001b[0m [\u001b[33m\u001b[1mwarning \u001b[0m] \u001b[1mNot able to determine geocollections for all datasets. This database is not ready for regionalization.\u001b[0m\n"
+ "\u001b[2m12:31:57+0200\u001b[0m [\u001b[33m\u001b[1mwarning \u001b[0m] \u001b[1mNot able to determine geocollections for all datasets. This database is not ready for regionalization.\u001b[0m\n"
]
},
{
@@ -114,21 +114,21 @@
"output_type": "stream",
"text": [
"\r",
- "100%|██████████| 2/2 [00:00<00:00, 40920.04it/s]"
+ "100%|██████████| 2/2 [00:00<00:00, 34521.02it/s]"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
- "\u001b[2m10:08:48+0200\u001b[0m [\u001b[32m\u001b[1minfo \u001b[0m] \u001b[1mVacuuming database \u001b[0m\n"
+ "\u001b[2m12:31:57+0200\u001b[0m [\u001b[32m\u001b[1minfo \u001b[0m] \u001b[1mVacuuming database \u001b[0m\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
- "\u001b[2m10:08:48+0200\u001b[0m [\u001b[33m\u001b[1mwarning \u001b[0m] \u001b[1mNot able to determine geocollections for all datasets. This database is not ready for regionalization.\u001b[0m\n"
+ "\u001b[2m12:31:57+0200\u001b[0m [\u001b[33m\u001b[1mwarning \u001b[0m] \u001b[1mNot able to determine geocollections for all datasets. This database is not ready for regionalization.\u001b[0m\n"
]
},
{
@@ -151,14 +151,14 @@
"output_type": "stream",
"text": [
"\r",
- "100%|██████████| 1/1 [00:00<00:00, 10866.07it/s]"
+ "100%|██████████| 1/1 [00:00<00:00, 30615.36it/s]"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
- "\u001b[2m10:08:48+0200\u001b[0m [\u001b[32m\u001b[1minfo \u001b[0m] \u001b[1mVacuuming database \u001b[0m\n"
+ "\u001b[2m12:31:57+0200\u001b[0m [\u001b[32m\u001b[1minfo \u001b[0m] \u001b[1mVacuuming database \u001b[0m\n"
]
},
{
@@ -256,10 +256,10 @@
"id": "d2660de7",
"metadata": {
"execution": {
- "iopub.execute_input": "2026-06-22T08:08:48.992384Z",
- "iopub.status.busy": "2026-06-22T08:08:48.992289Z",
- "iopub.status.idle": "2026-06-22T08:08:49.032820Z",
- "shell.execute_reply": "2026-06-22T08:08:49.032374Z"
+ "iopub.execute_input": "2026-08-21T10:31:57.385045Z",
+ "iopub.status.busy": "2026-08-21T10:31:57.384951Z",
+ "iopub.status.idle": "2026-08-21T10:31:57.455766Z",
+ "shell.execute_reply": "2026-08-21T10:31:57.455229Z"
}
},
"outputs": [
@@ -267,7 +267,7 @@
"name": "stdout",
"output_type": "stream",
"text": [
- "\u001b[2m10:08:48+0200\u001b[0m [\u001b[33m\u001b[1mwarning \u001b[0m] \u001b[1mNot able to determine geocollections for all datasets. This database is not ready for regionalization.\u001b[0m\n"
+ "\u001b[2m12:31:57+0200\u001b[0m [\u001b[33m\u001b[1mwarning \u001b[0m] \u001b[1mNot able to determine geocollections for all datasets. This database is not ready for regionalization.\u001b[0m\n"
]
},
{
@@ -283,14 +283,14 @@
"output_type": "stream",
"text": [
"\r",
- "100%|██████████| 2/2 [00:00<00:00, 48489.06it/s]"
+ "100%|██████████| 2/2 [00:00<00:00, 60787.01it/s]"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
- "\u001b[2m10:08:48+0200\u001b[0m [\u001b[32m\u001b[1minfo \u001b[0m] \u001b[1mVacuuming database \u001b[0m\n"
+ "\u001b[2m12:31:57+0200\u001b[0m [\u001b[32m\u001b[1minfo \u001b[0m] \u001b[1mVacuuming database \u001b[0m\n"
]
},
{
@@ -334,7 +334,7 @@
"id": "c4d74bee",
"metadata": {},
"source": [
- "As in Getting Started, we record which background database represents which point in time:"
+ "As in [Getting Started](../tutorials/1_getting_started.ipynb), we record which point in time each background database represents, using `set_database_metadata` — `TimexLCA` will read it automatically:"
]
},
{
@@ -343,21 +343,39 @@
"id": "e21503fa",
"metadata": {
"execution": {
- "iopub.execute_input": "2026-06-22T08:08:49.034110Z",
- "iopub.status.busy": "2026-06-22T08:08:49.034022Z",
- "iopub.status.idle": "2026-06-22T08:08:49.036177Z",
- "shell.execute_reply": "2026-06-22T08:08:49.035812Z"
+ "iopub.execute_input": "2026-08-21T10:31:57.456900Z",
+ "iopub.status.busy": "2026-08-21T10:31:57.456834Z",
+ "iopub.status.idle": "2026-08-21T10:31:57.727620Z",
+ "shell.execute_reply": "2026-08-21T10:31:57.727191Z"
}
},
- "outputs": [],
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "{'depends': ['biosphere'],\n",
+ " 'backend': 'sqlite',\n",
+ " 'number': 2,\n",
+ " 'modified': '2026-08-21T12:31:57.386123',\n",
+ " 'geocollections': [],\n",
+ " 'searchable': True,\n",
+ " 'processed': '2026-08-21T12:31:57.451530',\n",
+ " 'dirty': False,\n",
+ " 'representative_time': '2040-01-01T00:00:00'}"
+ ]
+ },
+ "execution_count": 3,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
"source": [
"from datetime import datetime\n",
"\n",
- "database_dates = {\n",
- " \"background_2020\": datetime.strptime(\"2020\", \"%Y\"),\n",
- " \"background_2040\": datetime.strptime(\"2040\", \"%Y\"),\n",
- " \"foreground\": \"dynamic\",\n",
- "}"
+ "from bw_timex import set_database_metadata\n",
+ "\n",
+ "set_database_metadata(\"background_2020\", representative_time=datetime(2020, 1, 1))\n",
+ "set_database_metadata(\"background_2040\", representative_time=datetime(2040, 1, 1))"
]
},
{
@@ -398,10 +416,10 @@
"id": "ab591abf",
"metadata": {
"execution": {
- "iopub.execute_input": "2026-06-22T08:08:49.037461Z",
- "iopub.status.busy": "2026-06-22T08:08:49.037363Z",
- "iopub.status.idle": "2026-06-22T08:08:49.313368Z",
- "shell.execute_reply": "2026-06-22T08:08:49.313021Z"
+ "iopub.execute_input": "2026-08-21T10:31:57.728861Z",
+ "iopub.status.busy": "2026-08-21T10:31:57.728781Z",
+ "iopub.status.idle": "2026-08-21T10:31:57.737286Z",
+ "shell.execute_reply": "2026-08-21T10:31:57.736915Z"
}
},
"outputs": [
@@ -409,14 +427,14 @@
"name": "stderr",
"output_type": "stream",
"text": [
- "\u001b[32m2026-06-22 10:08:49.308\u001b[0m | \u001b[1mINFO \u001b[0m | \u001b[36mbw_timex.utils\u001b[0m:\u001b[36madd_temporal_distribution_to_exchange\u001b[0m:\u001b[36m604\u001b[0m - \u001b[1mAdded temporal distribution to exchange Exchange: 2 None 'C' (None, somewhere, None) to 'B' (None, somewhere, None).\u001b[0m\n"
+ "\u001b[32m2026-08-21 12:31:57.732\u001b[0m | \u001b[1mINFO \u001b[0m | \u001b[36mbw_timex.utils\u001b[0m:\u001b[36madd_temporal_distribution_to_exchange\u001b[0m:\u001b[36m670\u001b[0m - \u001b[1mAdded temporal distribution to exchange Exchange: 2 None 'C' (None, somewhere, None) to 'B' (None, somewhere, None).\u001b[0m\n"
]
},
{
"name": "stderr",
"output_type": "stream",
"text": [
- "\u001b[32m2026-06-22 10:08:49.311\u001b[0m | \u001b[1mINFO \u001b[0m | \u001b[36mbw_timex.utils\u001b[0m:\u001b[36madd_temporal_distribution_to_exchange\u001b[0m:\u001b[36m604\u001b[0m - \u001b[1mAdded temporal distribution to exchange Exchange: 2 None 'C' (None, somewhere, None) to 'B' (None, somewhere, None).\u001b[0m\n"
+ "\u001b[32m2026-08-21 12:31:57.735\u001b[0m | \u001b[1mINFO \u001b[0m | \u001b[36mbw_timex.utils\u001b[0m:\u001b[36madd_temporal_distribution_to_exchange\u001b[0m:\u001b[36m670\u001b[0m - \u001b[1mAdded temporal distribution to exchange Exchange: 2 None 'C' (None, somewhere, None) to 'B' (None, somewhere, None).\u001b[0m\n"
]
}
],
@@ -456,10 +474,10 @@
"id": "d44daabf",
"metadata": {
"execution": {
- "iopub.execute_input": "2026-06-22T08:08:49.314829Z",
- "iopub.status.busy": "2026-06-22T08:08:49.314709Z",
- "iopub.status.idle": "2026-06-22T08:08:49.352568Z",
- "shell.execute_reply": "2026-06-22T08:08:49.352155Z"
+ "iopub.execute_input": "2026-08-21T10:31:57.738406Z",
+ "iopub.status.busy": "2026-08-21T10:31:57.738335Z",
+ "iopub.status.idle": "2026-08-21T10:31:57.791869Z",
+ "shell.execute_reply": "2026-08-21T10:31:57.791482Z"
}
},
"outputs": [
@@ -467,49 +485,77 @@
"name": "stderr",
"output_type": "stream",
"text": [
- "\u001b[32m2026-06-22 10:08:49.315\u001b[0m | \u001b[1mINFO \u001b[0m | \u001b[36mbw_timex.timex_lca\u001b[0m:\u001b[36m__init__\u001b[0m:\u001b[36m136\u001b[0m - \u001b[1mInitializing TimexLCA object...\u001b[0m\n"
+ "\u001b[32m2026-08-21 12:31:57.738\u001b[0m | \u001b[1mINFO \u001b[0m | \u001b[36mbw_timex.timex_lca\u001b[0m:\u001b[36m__init__\u001b[0m:\u001b[36m174\u001b[0m - \u001b[1mInitializing TimexLCA object...\u001b[0m\n"
+ ]
+ },
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "\u001b[32m2026-08-21 12:31:57.740\u001b[0m | \u001b[1mINFO \u001b[0m | \u001b[36mbw_timex.timex_lca\u001b[0m:\u001b[36m__init__\u001b[0m:\u001b[36m194\u001b[0m - \u001b[1mCalculating base LCA...\u001b[0m\n"
]
},
{
"name": "stderr",
"output_type": "stream",
"text": [
- "\u001b[32m2026-06-22 10:08:49.316\u001b[0m | \u001b[1mINFO \u001b[0m | \u001b[36mbw_timex.timex_lca\u001b[0m:\u001b[36m__init__\u001b[0m:\u001b[36m153\u001b[0m - \u001b[1mCalculating base LCA...\u001b[0m\n"
+ "\u001b[32m2026-08-21 12:31:57.740\u001b[0m | \u001b[1mINFO \u001b[0m | \u001b[36mbw_timex.timex_lca\u001b[0m:\u001b[36mclean_databases\u001b[0m:\u001b[36m1355\u001b[0m - \u001b[1mReprocessing 2 modified database(s) before calculating: background_2020, background_2040. This can take a while for large databases.\u001b[0m\n"
]
},
{
"name": "stderr",
"output_type": "stream",
"text": [
- "\u001b[32m2026-06-22 10:08:49.331\u001b[0m | \u001b[1mINFO \u001b[0m | \u001b[36mbw_timex.timex_lca\u001b[0m:\u001b[36m__init__\u001b[0m:\u001b[36m170\u001b[0m - \u001b[1mCollecting node infos...\u001b[0m\n"
+ "\u001b[32m2026-08-21 12:31:57.747\u001b[0m | \u001b[1mINFO \u001b[0m | \u001b[36mbw_timex.timex_lca\u001b[0m:\u001b[36mclean_databases\u001b[0m:\u001b[36m1361\u001b[0m - \u001b[1mDone reprocessing modified databases.\u001b[0m\n"
]
},
{
"name": "stderr",
"output_type": "stream",
"text": [
- "\u001b[32m2026-06-22 10:08:49.332\u001b[0m | \u001b[1mINFO \u001b[0m | \u001b[36mbw_timex.timex_lca\u001b[0m:\u001b[36mbuild_timeline\u001b[0m:\u001b[36m336\u001b[0m - \u001b[1mNo edge filter function provided. Skipping all edges in background databases.\u001b[0m\n"
+ "\u001b[32m2026-08-21 12:31:57.758\u001b[0m | \u001b[1mINFO \u001b[0m | \u001b[36mbw_timex.timex_lca\u001b[0m:\u001b[36m__init__\u001b[0m:\u001b[36m211\u001b[0m - \u001b[1mCollecting node infos...\u001b[0m\n"
]
},
{
"name": "stderr",
"output_type": "stream",
"text": [
- "\u001b[32m2026-06-22 10:08:49.333\u001b[0m | \u001b[1mINFO \u001b[0m | \u001b[36mbw_timex.timex_lca\u001b[0m:\u001b[36mbuild_timeline\u001b[0m:\u001b[36m357\u001b[0m - \u001b[1mCreating activity time mapping...\u001b[0m\n"
+ "\u001b[32m2026-08-21 12:31:57.759\u001b[0m | \u001b[1mINFO \u001b[0m | \u001b[36mbw_timex.timex_lca\u001b[0m:\u001b[36m__init__\u001b[0m:\u001b[36m223\u001b[0m - \u001b[1mLoading node metadata from 3 database(s)...\u001b[0m\n"
]
},
{
"name": "stderr",
"output_type": "stream",
"text": [
- "\u001b[32m2026-06-22 10:08:49.333\u001b[0m | \u001b[1mINFO \u001b[0m | \u001b[36mbw_timex.timeline_builder\u001b[0m:\u001b[36m__init__\u001b[0m:\u001b[36m112\u001b[0m - \u001b[1mTraversing supply chain graph...\u001b[0m\n"
+ "\u001b[32m2026-08-21 12:31:57.760\u001b[0m | \u001b[1mINFO \u001b[0m | \u001b[36mbw_timex.timex_lca\u001b[0m:\u001b[36m__init__\u001b[0m:\u001b[36m260\u001b[0m - \u001b[1mTimexLCA initialized.\u001b[0m\n"
]
},
{
"name": "stderr",
"output_type": "stream",
"text": [
- "\u001b[32m2026-06-22 10:08:49.336\u001b[0m | \u001b[1mINFO \u001b[0m | \u001b[36mbw_timex.timeline_builder\u001b[0m:\u001b[36mbuild_timeline\u001b[0m:\u001b[36m186\u001b[0m - \u001b[1mBuilding timeline...\u001b[0m\n"
+ "\u001b[32m2026-08-21 12:31:57.761\u001b[0m | \u001b[1mINFO \u001b[0m | \u001b[36mbw_timex.timex_lca\u001b[0m:\u001b[36mbuild_timeline\u001b[0m:\u001b[36m453\u001b[0m - \u001b[1mNo edge filter function provided. Skipping all edges in background databases.\u001b[0m\n"
+ ]
+ },
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "\u001b[32m2026-08-21 12:31:57.761\u001b[0m | \u001b[1mINFO \u001b[0m | \u001b[36mbw_timex.timex_lca\u001b[0m:\u001b[36mbuild_timeline\u001b[0m:\u001b[36m474\u001b[0m - \u001b[1mCreating activity time mapping...\u001b[0m\n"
+ ]
+ },
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "\u001b[32m2026-08-21 12:31:57.762\u001b[0m | \u001b[1mINFO \u001b[0m | \u001b[36mbw_timex.timeline_builder\u001b[0m:\u001b[36m__init__\u001b[0m:\u001b[36m112\u001b[0m - \u001b[1mTraversing supply chain graph...\u001b[0m\n"
+ ]
+ },
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "\u001b[32m2026-08-21 12:31:57.767\u001b[0m | \u001b[1mINFO \u001b[0m | \u001b[36mbw_timex.timeline_builder\u001b[0m:\u001b[36mbuild_timeline\u001b[0m:\u001b[36m183\u001b[0m - \u001b[1mBuilding timeline...\u001b[0m\n"
]
},
{
@@ -517,7 +563,7 @@
"output_type": "stream",
"text": [
"Starting graph traversal\n",
- "Calculation count: 1\n"
+ "Calculation count: 2\n"
]
},
{
@@ -552,6 +598,7 @@
"