@@ -30,70 +30,76 @@ Exogenous data (:mod:`.tools.exo_data`)
3030 :members:
3131 :exclude-members: ExoDataSource, prepare_computer
3232
33+ The tools in this module support use of data from arbitrary sources and formats in model-building code.
34+ For each source/format, a subclass of :class: `.ExoDataSource ` adds tasks to a :class: `genno.Computer `
35+ that retrieve/load and transform the source data into :class: `genno.Quantity `.
36+
37+ An example using one such class, :class: `message_ix_models.project.advance.data.ADVANCE `.
38+
39+ .. code-block :: python
40+
41+ from genno import Computer
42+
43+ from message_ix_models.project.advance.data import ADVANCE
44+
45+ # Keyword arguments corresponding to ADVANCE.Options
46+ kw = dict (
47+ measure = " Transport|Service demand|Road|Passenger|LDV"
48+ model = " MESSAGE"
49+ scenario = " ADV3TRAr2_Base"
50+ )
51+
52+ # Add tasks to retrieve and transform data
53+ c = Computer()
54+ keys = c.apply(ADVANCE , context = context, ** kw)
55+
56+ # Retrieve some of the data
57+ q_result = c.get(keys[0 ])
58+
59+ # Pass the data into further calculations
60+ c.add(" derived" " mul" 1 ], k_other)
61+
3362autosummary ::
3463
3564 MEASURES
3665 SOURCES
66+ BaseOptions
3767 DemoSource
3868 ExoDataSource
69+ add_structure
3970 iamc_like_data_for_query
4071 prepare_computer
4172 register_source
4273
43- .. autofunction :: prepare_computer
44-
45- The first returned key, like ``{measure}:n-y ``, triggers the following computations:
46-
47- 1. Load data by invoking a :class: `ExoDataSource `.
48- 2. Aggregate on the |n | (node) dimension according to :attr: `.Config.regions `.
49- 3. Interpolate on the |y | (year) dimension according to :attr: `.Config.years `.
50-
51- Additional key(s) include:
52-
53- - ``{measure}:n-y:y0 indexed ``: same as ``{measure}:n-y ``, indexed to values as of |y0 | (the first model year).
54-
55- See particular data source classes, like :class: `.SSPOriginal `, for particular examples of usage.
56-
57- .. todo :: Extend to also prepare to compute values indexed to a particular |n|.
58-
5974.. autoclass :: ExoDataSource
6075 :members:
6176 :private-members: _where
62- :special-members: __init__, __call__
63-
64- .. currentmodule :: message_ix_models.tools.advance
77+ :special-members: __init__
6578
66- ADVANCE data (:mod: `.tools.advance `)
67- ====================================
68-
69- .. deprecated :: 2023.11
70- Use :mod: `.project.advance ` instead.
71-
72- .. autosummary ::
73- get_advance_data
74- advance_data
79+ As an abstract class ExoDataSource **must ** be subclassed to be used.
80+ Concrete subclasses **must ** implement at least the :meth: `~ExoDataSource.get ` method
81+ that performs the loading of the raw data when executed,
82+ and **may ** override others, as described below.
7583
76- .. autodata :: LOCATION
84+ The class method :meth: `.ExoDataSource.add_tasks ` adds tasks to a :class: `genno.Computer `.
85+ It returns a :class: `genno.Key ` that refers to the loaded and transformed data.
86+ This method usually **should not ** be modified for subclasses.
7787
78- This is a location relative to a parent directory.
79- The specific parent directory depends on whether :mod: `message_data ` is available:
88+ The behaviour of a subclass can be customized in these ways:
8089
81- Without :mod: `message_data `:
82- The code finds the data within :ref: `local-data ` (see discussion there for how to configure this location).
83- Users should:
90+ 1. Create a subclass of :class: `.BaseOptions `
91+ and set it as the :attr: `~.ExoDataSource.Options ` class attribute.
92+ 2. Override :meth: `~.ExoDataSource.__init__ `,
93+ which receives keyword arguments via :meth: `.add_tasks `.
94+ 3. Override :meth: `~.ExoDataSource.transform `,
95+ which is called to add further tasks which will transform the data.
8496
85- 1. Visit https://tntcat.iiasa.ac.at/ADVANCEWP2DB/dsd?Action=htmlpage&page=about and register for access to the data.
86- 2. Log in.
87- 3. Download the snapshot with the file name given in :data: `LOCATION ` to a subdirectory :file: `advance/ ` within their local data directory.
97+ See the documentation for these methods and attributes for further details.
8898
89- With :mod: `message_data `:
90- The code finds the data within :ref: `private-data `.
91- The snapshot is stored directly in the repository using Git LFS.
99+ .. autofunction :: prepare_computer
92100
93- .. automodule :: message_ix_models.tools.advance
94- :members:
95- :exclude-members: LOCATION
96- :private-members:
101+ .. deprecated :: 2025-06-06
102+ Use :py: `c.apply(SOURCE.add_tasks, …) ` as shown above.
97103
98104.. currentmodule :: message_ix_models.tools.iamc
99105
@@ -103,6 +109,14 @@ IAMC data structures (:mod:`.tools.iamc`)
103109.. automodule :: message_ix_models.tools.iamc
104110 :members:
105111
112+ .. currentmodule :: message_ix_models.tools.policy
113+
114+ Policies (:mod: `.tools.policy `)
115+ ===============================
116+
117+ .. automodule :: message_ix_models.tools.policy
118+ :members:
119+
106120.. _tools-wb :
107121
108122World Bank structures (:mod: `.tools.wb `)
0 commit comments