Read background database timing from database metadata

[TimoDiepers]

Closes #217. Supersedes #218.

TimexLCA used to learn what a background database represents in one way only: the database_dates mapping, hand-written at every call site. The information already exists in the database — a premise export knows the year it was built for — but it lived only in the database name, so every study re-typed it, and a typo either raised or, worse, mapped a vintage to the wrong year.

premise PR #303 (on master, released after 2.4.9.2) closes the gap on the producing side: exported databases now carry what they represent in their Brightway metadata. This PR makes bw_timex read it.

tlca = TimexLCA(demand={("foreground", "A"): 1}, method=("GWP", "example"))

What changed

Timing is read from database metadata by default. Every registered database carrying representative_time is mapped to its point in time. ISO strings, datetimes and "dynamic" are all accepted; databases holding the functional unit default to "dynamic".

set_database_metadata records it for databases that don't bring it themselves:

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")

Dates are stored as ISO strings, since Brightway serializes database metadata to JSON.

TimexLCA(scenario={...}) selects one scenario when a project holds several. Any metadata key works — iam_model, pathway, system_model, ecoinvent_version, premise_version, or one you set yourself. Databases that don't declare the filtered key (your foreground, a hand-built vintage) are never filtered out.

A project holding several scenarios stays unambiguous — bw_timex refuses to guess, and names only the keys that actually differ:

Several background scenarios found in this project:
  pathway=SSP2-PkBudg500: ei310_remind_SSP2-PkBudg500_2030, ..._2040, ..._2050
  pathway=SSP2-Base: ei310_remind_SSP2-Base_2030, ..._2040, ..._2050
Select one, e.g. scenario={'pathway': '...'}, or map the databases explicitly with `database_dates`.

A filter key no database declares, and a filter that matches nothing, are errors too — never a silent non-time-explicit run.

database_dates is unchanged and exclusive. When passed, it is the whole mapping and metadata is not read at all, so existing scripts behave exactly as before — a legacy call in a project that also holds ten premise vintages must not silently pull those ten in.

Multi-scenario databases (premise superstructure and scenario-array exports) are recognised and skipped: there is no single technosphere per point in time to pick. They remain usable by naming them in database_dates.

Also in here

Three user-facing error messages named database_dates when the timing may now have come from metadata (validation.py, timeline_builder.py, edge_extractor.py); they now name both sources.

Docs and notebooks

New page What a database represents covering the metadata, the setter, scenario selection, and database_dates as the explicit override — including the note that metadata resolution pulls in every registered database carrying representative_time, which costs setup time and lets those databases take part in temporal-market interpolation. The quickstart and walkthrough steps 1–2 teach the new default. All twelve notebooks are updated; paper_case_study.ipynb is deliberately untouched.

Testing

338 passed, 0 failed. tests/test_database_metadata.py covers resolution, ISO/datetime/"dynamic" values, database_dates exclusivity, scenario filtering, the ambiguity and empty-filter errors, the multi-scenario skip, and set_database_metadata round-tripping through bd.databases.flush(), plus an end-to-end check that the metadata path and the database_dates path give the same score.

Note for reviewers

The design and implementation plan are committed under docs/superpowers/. One deliberate compatibility wrinkle: scenario sits at positional slot 4, ahead of use_global_lci_cache, so TimexLCA(demand, method, dates, False) now raises rather than disabling the cache. It fails loudly, never silently.

[codecov]

Codecov Report

❌ Patch coverage is 97.70115% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.78%. Comparing base (f67e3ef) to head (107b047).

Files with missing lines	Patch %	Lines
bw_timex/database_metadata.py	98.05%	2 Missing ⚠️
bw_timex/validation.py	92.59%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #219      +/-   ##
==========================================
+ Coverage   78.51%   79.78%   +1.26%     
==========================================
  Files          10       12       +2     
  Lines        2472     2642     +170     
==========================================
+ Hits         1941     2108     +167     
- Misses        531      534       +3     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.