Postprocessing and reporting
The MESSAGEix framework provides zero-configuration reporting of models built on the framework.
The word “reporting” refers to calculations and other post-processing performed after a Scenario
has been solved by the associated optimization model: first the model solution is obtained, and then things are “reported” based on that solution.
message_ix.reporting
is developed on the basis of ixmp.reporting
and genno
.
It provides a basis for other code and packages—such as message_ix_models
—that perform reporting calculations tailored to specific model structures.
Each layer of this “stack” builds on the features in the level below:
Package |
Role |
Core features |
Reporting features |
---|---|---|---|
|
MESSAGEix-GLOBIOM models |
Specific model structure ( |
Calculations for specific technologies |
|
Energy model framework |
Common sets/parameters ( |
Derived quantities ( |
|
Optimization models & data |
|
|
|
Structured calculations |
— |
These features are accessible through Reporter
, which can produce multiple reports from one or more Scenarios.
A report is identified by a key (usually a string), and may…
perform arbitrarily complex calculations while intelligently handling units;
read and make use of data that is ‘exogenous’ to (not included in) a Scenario;
produce output as Python or R objects (in code), or to files or databases;
calculate only a requested subset of quantities; and
much, much more!
Contents:
Concepts
See Concepts and usage in the genno documentation for an introduction to concepts including quantity, key, computation, task, and graph.
In message_ix.reporting
:
The
message_ix.Reporter
class is an extended version of thegenno.Computer
class.ixmp
parameters, scalars, equations, and time-series data all become quantities for the purpose of reporting.For example, the MESSAGEix parameter
resource_cost
, defined with the dimensions (node n, commodity c, grade g, year y) is identified by the keyresource_cost:n-c-g-y
. When summed across the grade/g dimension, it has dimensions n, c, y and is identified by the keyresource_cost:n-c-y
.Reporter.from_scenario()
automatically sets up keys and tasks (such asresource_cost:n-c-g-y
) that simply retrieve raw/unprocessed data from aScenario
and return it as agenno.Quantity
.Computations are defined as functions in modules including:
message_ix.reporting.computations
,ixmp.reporting.computations
, andgenno.computations
. These are documented below.
Usage
A MESSAGEix reporting workflow has the following steps:
Obtain a
Scenario
object from anPlatform
.Use
Reporter.from_scenario()
to prepare a Reporter object with many calculations automatically prepared.(optionally) Use the built-in features of
Reporter
to describe additional calculations.Use
get()
1 or more times to execute tasks, including all the calculations on which they depend:
from ixmp import Platform
from message_ix import Scenario, Reporter
mp = Platform()
scen = Scenario(scen)
rep = Reporter.from_scenario(scen)
rep.get("all")
Note that keys and tasks are described in steps (2–3), but they are not executed until get()
is called—or the results of one task are required by another.
This design allows the Reporter to skip unneeded (and potentially slow) computations and deliver good performance.
The Reporter’s Computer.graph
may contain thousands of tasks for retrieving model quantities and calculating derived quantities, but a particular call to get()
may only execute a few of these.
Customization
A Reporter prepared with from_scenario()
always contains a key
scenario
, referring to the Scenario to be reported.
The method Reporter.add()
can be used to add arbitrary Python code that operates directly on the Scenario object:
def my_custom_report(scenario):
"""Function with custom code that manipulates the `scenario`."""
print("Model name:", scenario.model)
# Add a task at the key "custom". The task executes my_custom_report().
# The key "scenario" means that the Scenario object is retrieved and
# passed as an argument to the function.
rep.add("custom", (my_custom_report, "scenario"))
rep.get("custom")
In this example, the function my_custom_report()
could run to thousands of lines; read to and write from multiple files; invoke other programs or Python scripts; etc.
In order to take advantage of the performance-optimizing features of the Reporter, such calculations can instead be composed from atomic (i.e. small, indivisible) computations.
See the genno
documentation for more.
API reference
Top-level classes and functions
message_ix.reporting
provides:
|
MESSAGEix Reporter. |
The following objects from genno
may also be imported from message_ix.reporting
.
Their documentation is repeated below for convenience.
|
Wrapper to print intelligible exception information for |
|
A hashable key for a quantity that includes its dimensionality. |
|
Raised by |
|
Raised by |
|
A sparse data structure that behaves like |
|
Configure |
ixmp.Reporter.from_scenario
automatically adds keys based on the contents of the Scenario
argument.
message_ix.Reporter.from_scenario
extends this to add additional keys for derived quantities specific to the MESSAGEix model framework.
These include:
out
-output
×ACT
; that is, the product ofoutput
(output efficiency) andACT
(activity)out_hist
=output
×ref_activity
(historical reference activity)in
=input
×ACT
in_hist
=input
×ref_activity
emi
=emission_factor
×ACT
emi_hist
=emission_factor
×ref_activity
inv
=inv_cost
×CAP_NEW
inv_hist
=inv_cost
×ref_new_capacity
fom
=fix_cost
×CAP
fom_hist
=fix_cost
×ref_capacity
vom
=var_cost
×ACT
vom_hist
=var_cost
×ref_activity
tom
=fom
+vom
land_out
=land_output
×LAND
land_use_qty
=land_use
×LAND
land_emi
=land_emission
×LAND
addon conversion
, the model parameteraddon_conversion
(note space versus underscore), except broadcast across individual add-on technologies (ta) rather than add-on types (type_addon).addon up
, which isaddon_up
similarly broadcast.addon ACT
=addon conversion
×ACT
addon in
=input
×addon ACT
addon out
=output
×addon ACT
addon potential
=addon up
×addon ACT
, the maximum potential activity by add-on technology.price emission
, the model variablePRICE_EMISSION
broadcast across emission species (e) and technologies (t) rather than types (type_emission, type_tec).
Tip
Use full_key()
to retrieve the full-dimensionality Key
for any of these quantities.
Other added keys include:
message_ix
adds the standard short symbols for MESSAGEix dimensions (sets) based onDIMS
. Each of these is also available in a Reporter: for examplerep.get("n")
returns a list with the elements of the MESSAGEix set named “node”. These keys can be used as inputComputations to convert internal
Quantity()
data format to the IAMC data format, i.e. aspyam.IamDataFrame
objects. These include:<name>:pyam
for most of the above derived quantities.CAP:pyam
(fromCAP
)CAP_NEW:pyam
(fromCAP_NEW
)
map_<name>
as “one-hot” or indicator quantities for the respective MESSAGEix mapping setscat_<name>
.Standard reports
message:system
,message:costs
, andmessage:emissions
perREPORTS
.The report
message:default
, collecting all of the above reports.
These automatic contents are prepared using:
Automatic quantities derived by other calculations. |
|
Short names for dimensions (sets) in the MESSAGEix framework. |
|
MESSAGE mapping sets, converted to reporting quantities via |
|
Automatic quantities that are the |
|
Quantities to automatically convert to IAMC format using |
|
Automatic reports that |
- class message_ix.reporting.Reporter(**kwargs)
Bases:
ixmp.reporting.reporter.Reporter
MESSAGEix Reporter.
add
(data, *args, **kwargs)General-purpose method to add computations.
add_file
(path[, key])Add exogenous quantities from path.
add_product
(key, *quantities[, sums])Add a computation that takes the product of quantities.
add_queue
(queue[, max_tries, fail])Add tasks from a list or queue.
add_single
(key, *computation[, strict, index])Add a single computation at key.
aggregate
(qty, tag, dims_or_groups[, ...])Add a computation that aggregates qty.
apply
(generator, *keys, **kwargs)Add computations by applying generator to keys.
check_keys
(*keys[, action])Check that keys are in the Computer.
configure
([path, fail])Configure the Computer.
convert_pyam
(quantities[, tag])Add conversion of one or more quantities to IAMC format.
describe
([key, quiet])Return a string describing the computations that produce key.
disaggregate
(qty, new_dim[, method, args])Add a computation that disaggregates qty using method.
finalize
(scenario)Prepare the Reporter to act on scenario.
from_scenario
(scenario, **kwargs)Create a Reporter by introspecting scenario.
full_key
(name_or_key)Return the full-dimensionality key for name_or_key.
get
([key])Execute and return the result of the computation key.
infer_keys
(key_or_keys[, dims])Infer complete key_or_keys.
keys
()Return the keys of
graph
.set_filters
(**filters)Apply filters ex ante (before computations occur).
visualize
(filename, **kwargs)Generate an image describing the Computer structure.
write
(key, path)Write the result of key to the file path.
- add(data, *args, **kwargs)
General-purpose method to add computations.
add()
can be called in several ways; its behaviour depends on data; see below. It chains to methods such asadd_single()
,add_queue()
, and/orapply()
; each can also be called directly.- Returns
Some or all of the keys added to the Computer.
- Return type
list of Key-like
See also
- add_aggregate(qty: Union[genno.core.key.Key, Hashable], tag: str, dims_or_groups: Union[Mapping, str, Sequence[str]], weights: Optional[xarray.core.dataarray.DataArray] = None, keep: bool = True, sums: bool = False, fail: Optional[Union[str, int]] = None)
Add a computation that aggregates qty.
- Parameters
qty (
Key
or str) – Key of the quantity to be aggregated.tag (str) – Additional string to add to the end the key for the aggregated quantity.
dims_or_groups (str or iterable of str or dict) – Name(s) of the dimension(s) to sum over, or nested dict.
weights (
xarray.DataArray
, optional) – Weights for weighted aggregation.keep (bool, optional) – Passed to
computations.aggregate
.fail (str or int, optional) – Passed to
add_queue()
viaadd()
.
- Returns
The key of the newly-added node.
- Return type
Key
- add_as_pyam(quantities, tag='iamc', **kwargs)
Add conversion of one or more quantities to IAMC format.
- Parameters
- Returns
Each task converts a
Quantity
into apyam.IamDataFrame
.- Return type
list of Key
See also
as_pyam
- add_file(path, key=None, **kwargs)
Add exogenous quantities from path.
Computing the key or using it in other computations causes path to be loaded and converted to
Quantity
.- Parameters
path (os.PathLike) – Path to the file, e.g. ‘/path/to/foo.ext’.
key (str or .Key, optional) – Key for the quantity read from the file.
dims (dict or list or set) – Either a collection of names for dimensions of the quantity, or a mapping from names appearing in the input to dimensions.
units (str or pint.Unit) – Units to apply to the loaded Quantity.
- Returns
Either key (if given) or e.g.
file:foo.ext
based on the path name, without directory components.- Return type
.Key
See also
- add_load_file(path, key=None, **kwargs)
Add exogenous quantities from path.
Computing the key or using it in other computations causes path to be loaded and converted to
Quantity
.- Parameters
path (os.PathLike) – Path to the file, e.g. ‘/path/to/foo.ext’.
key (str or .Key, optional) – Key for the quantity read from the file.
dims (dict or list or set) – Either a collection of names for dimensions of the quantity, or a mapping from names appearing in the input to dimensions.
units (str or pint.Unit) – Units to apply to the loaded Quantity.
- Returns
Either key (if given) or e.g.
file:foo.ext
based on the path name, without directory components.- Return type
.Key
See also
- add_product(key, *quantities, sums=True)
Add a computation that takes the product of quantities.
- Parameters
- Returns
The full key of the new quantity.
- Return type
Key
- add_queue(queue: Iterable[Tuple[Tuple, Mapping]], max_tries: int = 1, fail: Optional[Union[int, str]] = None) Tuple[Union[genno.core.key.Key, Hashable], ...]
Add tasks from a list or queue.
- Parameters
queue (iterable of 2-
tuple
) – The members of each tuple are the arguments (e.g.list
or tuple) and keyword arguments (e.gdict
) toadd()
.max_tries (int, optional) – Retry adding elements up to this many times.
fail (“raise” or str or
logging
level, optional) – Action to take when a computation from queue cannot be added after max_tries: “raise” an exception, or log messages on the indicated level and continue.
- add_single(key, *computation, strict=False, index=False)
Add a single computation at key.
- Parameters
key (str or Key or hashable) – A string, Key, or other value identifying the output of computation.
computation (object) – Any computation. See
graph
.strict (bool, optional) – If True, key must not already exist in the Computer, and any keys referred to by computation must exist.
index (bool, optional) – If True, key is added to the index as a full-resolution key, so it can be later retrieved with
full_key()
.
- Raises
- add_tasks(fail_action: Union[int, str] = 'raise') None
Add the pre-defined MESSAGEix reporting tasks to the Reporter.
- Parameters
fail_action (“raise” or logging level) – Passed to the fail argument of
Reporter.add_queue()
.
- aggregate(qty: Union[genno.core.key.Key, Hashable], tag: str, dims_or_groups: Union[Mapping, str, Sequence[str]], weights: Optional[xarray.core.dataarray.DataArray] = None, keep: bool = True, sums: bool = False, fail: Optional[Union[str, int]] = None)
Add a computation that aggregates qty.
- Parameters
qty (
Key
or str) – Key of the quantity to be aggregated.tag (str) – Additional string to add to the end the key for the aggregated quantity.
dims_or_groups (str or iterable of str or dict) – Name(s) of the dimension(s) to sum over, or nested dict.
weights (
xarray.DataArray
, optional) – Weights for weighted aggregation.keep (bool, optional) – Passed to
computations.aggregate
.fail (str or int, optional) – Passed to
add_queue()
viaadd()
.
- Returns
The key of the newly-added node.
- Return type
Key
- apply(generator, *keys, **kwargs)
Add computations by applying generator to keys.
- Parameters
generator (callable) – Function to apply to keys.
keys (hashable) – The starting key(s).
kwargs – Keyword arguments to generator.
- check_keys(*keys: Union[str, genno.core.key.Key], action='raise') Optional[List[Union[str, genno.core.key.Key]]]
Check that keys are in the Computer.
If any of keys is not in the Computer and action is “raise” (the default)
KeyError
is raised. Otherwise, a list is returned with either the key from keys, or the correspondingfull_key()
.If action is “return” (or any other value),
None
is returned on missing keys.
- configure(path: Optional[Union[pathlib.Path, str]] = None, fail: Union[str, int] = 'raise', **config)
Configure the Computer.
Accepts a path to a configuration file and/or keyword arguments. Configuration keys loaded from file are superseded by keyword arguments. Messages are logged at level
logging.INFO
if config contains unhandled sections.See Configuration for a list of all configuration sections and keys, and details of the configuration file format.
- Parameters
path (.Path, optional) – Path to a configuration file in JSON or YAML format.
fail (“raise” or str or
logging
level, optional) – Passed toadd_queue()
. If not “raise”, then log messages are generated for config handlers that fail. The Computer may be only partially configured.**config – Configuration keys/sections and values.
- convert_pyam(quantities, tag='iamc', **kwargs)
Add conversion of one or more quantities to IAMC format.
- Parameters
- Returns
Each task converts a
Quantity
into apyam.IamDataFrame
.- Return type
list of Key
See also
as_pyam
- describe(key=None, quiet=True)
Return a string describing the computations that produce key.
If key is not provided, all keys in the Computer are described.
Unless quiet, the string is also printed to the console.
- Returns
Description of computations.
- Return type
- disaggregate(qty, new_dim, method='shares', args=[])
Add a computation that disaggregates qty using method.
- Parameters
qty (hashable) – Key of the quantity to be disaggregated.
new_dim (str) – Name of the new dimension of the disaggregated variable.
method (callable or str) – Disaggregation method. If a callable, then it is applied to var with any extra args. If a string, then a method named ‘disaggregate_{method}’ is used.
args (list, optional) – Additional arguments to the method. The first element should be the key for a quantity giving shares for disaggregation.
- Returns
The key of the newly-added node.
- Return type
Key
- finalize(scenario: ixmp.core.scenario.Scenario) None
Prepare the Reporter to act on scenario.
The
TimeSeries
(i.e. includingixmp.Scenario
andmessage_ix.Scenario
) object scenario is stored with the key'scenario'
. All subsequent processing will act on data from this Scenario.
- classmethod from_scenario(scenario, **kwargs) message_ix.reporting.Reporter
Create a Reporter by introspecting scenario.
Warnings are logged if scenario does not have a solution. In this case, any keys/computations based on model output (ixmp variables and equations) may return an empty Quantity, fail, or behave unpredictably. Keys/computations based only on model input (ixmp sets and parameters) should function normally.
- Returns
A reporter for scenario.
- Return type
- full_key(name_or_key: Union[genno.core.key.Key, Hashable]) Union[genno.core.key.Key, Hashable]
Return the full-dimensionality key for name_or_key.
An quantity ‘foo’ with dimensions (a, c, n, q, x) is available in the Computer as
'foo:a-c-n-q-x'
. ThisKey
can be retrieved with:c.full_key("foo") c.full_key("foo:c") # etc.
- Raises
KeyError – if name_or_key is not in the graph.
- get(key=None)
Execute and return the result of the computation key.
Only key and its dependencies are computed.
- Parameters
key (str, optional) – If not provided,
default_key
is used.- Raises
ValueError – If key and
default_key
are bothNone
.
- get_comp(name) Optional[Callable]
Return a computation function.
get_comp()
checks each of themodules
for a function or callable with the given name. Modules at the end of the list take precedence over those earlier in the lists.- Returns
.callable
None – If there is no computation with the given name in any of
modules
.
- infer_keys(key_or_keys: Union[genno.core.key.Key, Hashable, Iterable[Union[genno.core.key.Key, Hashable]]], dims: Iterable[str] = [])
Infer complete key_or_keys.
Each return value is one of:
a
Key
with eitherdimensions dims, if any are given, otherwise
its full dimensionality (cf.
full_key()
)
str
, the same as input, if the key is not defined in the Computer.
- Parameters
key_or_keys (str or Key or list of str or Key) –
dims (list of str, optional) – Drop all but these dimensions from the returned key(s).
- Returns
str or Key – If key_or_keys is a single
KeyLike
.list of str or Key – If key_or_keys is an iterable of
KeyLike
.
- keys()
Return the keys of
graph
.
- require_compat(pkg: str)
Load computations from
genno.compat.{pkg}
for use withget_comp()
.The specified module is appended to
modules
.- Raises
ModuleNotFoundError – If the required packages are missing.
See also
- set_filters(**filters) None
Apply filters ex ante (before computations occur).
See the description of
filters()
under Configuration.
- property unit_registry
The
pint.UnitRegistry()
used by the Computer.
- visualize(filename, **kwargs)
Generate an image describing the Computer structure.
This is a shorthand for
dask.visualize()
. Requires graphviz.
- write(key, path)
Write the result of key to the file path.
- message_ix.reporting.DERIVED = [('tom:nl-t-yv-ya', (<function add>, 'fom:nl-t-yv-ya', 'vom:nl-t-yv-ya')), ('addon conversion:nl-t-yv-ya-m-h-ta', (functools.partial(<function broadcast_map>, rename={'n': 'nl'}), 'addon_conversion:n-t-yv-ya-m-h-type_addon', 'map_addon')), ('addon up:nl-t-ya-m-h-ta', (functools.partial(<function broadcast_map>, rename={'n': 'nl'}), 'addon_up:n-t-ya-m-h-type_addon', 'map_addon')), ('price emission:n-e-t-y', (<function broadcast_map>, (<function broadcast_map>, 'PRICE_EMISSION:n-type_emission-type_tec-y', 'map_emission'), 'map_tec'))]
Automatic quantities derived by other calculations.
- message_ix.reporting.DIMS = {'commodity': 'c', 'emission': 'e', 'grade': 'g', 'land_scenario': 's', 'land_type': 'u', 'level': 'l', 'mode': 'm', 'node': 'n', 'node_dest': 'nd', 'node_loc': 'nl', 'node_origin': 'no', 'node_rel': 'nr', 'node_share': 'ns', 'rating': 'q', 'relation': 'r', 'technology': 't', 'technology_addon': 'ta', 'technology_primary': 'tp', 'time': 'h', 'time_dest': 'hd', 'time_origin': 'ho', 'year': 'y', 'year_act': 'ya', 'year_rel': 'yr', 'year_vtg': 'yv'}
Short names for dimensions (sets) in the MESSAGEix framework.
- message_ix.reporting.MAPPING_SETS = [('addon', 't'), ('emission', 'e'), ('tec', 't'), ('year', 'y')]
MESSAGE mapping sets, converted to reporting quantities via
map_as_qty()
.For instance, the mapping set
cat_addon
is available at the reporting keymap_addon
, which produces aQuantity
with the two dimensionstype_addon
andta
(short form oftechnology_addon
). This Quantity contains the value 1 at every valid (type_addon, ta) location, and 0 elsewhere.
- message_ix.reporting.PRODUCTS = (('out', ('output', 'ACT')), ('in', ('input', 'ACT')), ('rel', ('relation_activity', 'ACT')), ('emi', ('emission_factor', 'ACT')), ('inv', ('inv_cost', 'CAP_NEW')), ('fom', ('fix_cost', 'CAP')), ('vom', ('var_cost', 'ACT')), ('land_out', ('land_output', 'LAND')), ('land_use_qty', ('land_use', 'LAND')), ('land_emi', ('land_emission', 'LAND')), ('addon ACT', ('addon conversion', 'ACT')), ('addon in', ('input', 'addon ACT')), ('addon out', ('output', 'addon ACT')), ('addon potential', ('addon up', 'addon ACT')))
Automatic quantities that are the
product()
of two others.
- message_ix.reporting.PYAM_CONVERT = [('out:nl-t-ya-m-nd-c-l', 'ya', {'kind': 'ene', 'var': 'out'}), ('in:nl-t-ya-m-no-c-l', 'ya', {'kind': 'ene', 'var': 'in'}), ('CAP:nl-t-ya', 'ya', {'var': 'capacity'}), ('CAP_NEW:nl-t-yv', 'yv', {'var': 'new capacity'}), ('inv:nl-t-yv', 'yv', {'var': 'inv cost'}), ('fom:nl-t-ya', 'ya', {'var': 'fom cost'}), ('vom:nl-t-ya', 'ya', {'var': 'vom cost'}), ('tom:nl-t-ya', 'ya', {'var': 'total om cost'}), ('emi:nl-t-ya-m-e', 'ya', {'kind': 'emi', 'var': 'emis'})]
Quantities to automatically convert to IAMC format using
as_pyam()
.
- message_ix.reporting.REPORTS = {'message:costs': ['inv:pyam', 'fom:pyam', 'vom:pyam', 'tom:pyam'], 'message:emissions': ['emi:pyam'], 'message:system': ['out:pyam', 'in:pyam', 'CAP:pyam', 'CAP_NEW:pyam']}
Automatic reports that
concat()
quantities converted to IAMC format.
- exception message_ix.reporting.ComputationError(exc)
Wrapper to print intelligible exception information for
Computer.get()
.In order to aid in debugging, this helper:
Omits the parts of the stack trace that are internal to
dask
, andGives the key in the
Computer.graph
and the computation/task that caused the exception.
- class message_ix.reporting.Key(name: str, dims: Iterable[str] = [], tag: Optional[str] = None)
A hashable key for a quantity that includes its dimensionality.
- add_tag(tag)
Return a new Key with tag appended.
- append(*dims: str)
Return a new Key with additional dimensions dims.
- classmethod bare_name(value) Optional[str]
If value is a bare name (no dims or tags), return it; else
None
.
- classmethod from_str_or_key(value: Union[genno.core.key.Key, Hashable], drop: Union[Iterable[str], bool] = [], append: Iterable[str] = [], tag: Optional[str] = None) genno.core.key.Key
Return a new Key from value.
- Parameters
value (str or Key) – Value to use to generate a new Key.
drop (list of str or
True
, optional) – Existing dimensions of value to drop. Seedrop()
.append (list of str, optional.) – New dimensions to append to the returned Key. See
append()
.tag (str, optional) – Tag for returned Key. If value has a tag, the two are joined using a ‘+’ character. See
add_tag()
.
- Return type
Key
- iter_sums() Generator[Tuple[genno.core.key.Key, Callable, genno.core.key.Key], None, None]
Generate (key, task) for all possible partial sums of the Key.
- classmethod product(new_name: str, *keys, tag: Optional[str] = None) genno.core.key.Key
Return a new Key that has the union of dimensions on keys.
Dimensions are ordered by their first appearance:
First, the dimensions of the first of the keys.
Next, any additional dimensions in the second of the keys that were not already added in step 1.
etc.
- Parameters
new_name (str) – Name for the new Key. The names of keys are discarded.
- property sorted: genno.core.key.Key
A version of the Key with its
dims
sorted alphabetically.
- exception message_ix.reporting.KeyExistsError
Raised by
Computer.add()
when the target key exists.
- exception message_ix.reporting.MissingKeyError
Raised by
Computer.add()
when a required input key is missing.
- class message_ix.reporting.Quantity(*args, **kwargs)
A sparse data structure that behaves like
xarray.DataArray
.Depending on the value of
CLASS
, Quantity is eitherAttrSeries
orSparseDataArray
.- classmethod from_series(series, sparse=True)
Convert series to the Quantity class given by
CLASS
.
- to_series() pandas.core.series.Series
Like
xarray.DataArray.to_series()
.
- property units
Retrieve or set the units of the Quantity.
Examples
Create a quantity without units:
>>> qty = Quantity(...)
Set using a string; automatically converted to pint.Unit:
>>> qty.units = "kg" >>> qty.units <Unit('kilogram')>
- message_ix.reporting.configure(path: Optional[Union[pathlib.Path, str]] = None, **config)
Configure
genno
globally.Modifies global variables that affect the behaviour of all Computers and computations. Configuration keys loaded from file are superseded by keyword arguments. Messages are logged at level
logging.INFO
if config contains unhandled sections.- Parameters
path (Path, optional) – Path to a configuration file in JSON or YAML format.
**config – Configuration keys/sections and values.
Computations
message_ix.reporting
only provides two computations, which are currently only used in the tutorials to produce simple plots.
For custom plotting, genno.compat.plotnine
is recommended.
|
Plot a supply curve. |
|
Plot qty as a stacked bar chart. |
Other computations are provided by ixmp.reporting
:
|
Retrieve data from scenario. |
|
Convert set_df to a |
|
Update scenario with computed data from reporting quantities. |
…and by genno.computation
and its compatibility modules. See the package documentation for details.
|
Class for plotting using |
|
Sum across multiple quantities. |
|
Aggregate quantity by groups. |
|
Simply apply units to qty. |
|
Return a |
|
Broadcast quantity using a map. |
|
Sum distinct quantities by weights. |
|
Concatenate Quantity objs. |
|
Disaggregate quantity by shares. |
|
Group by dimension group, then sum across dimension sum. |
|
Read the file at path and return its contents as a |
|
Compute the product of any number of quantities. |
|
Compute the ratio numerator / denominator. |
|
Select from qty based on indexers. |
|
Sum quantity over dimensions, with optional weights. |
|
Write a quantity to a file. |
- message_ix.reporting.computations.plot_cumulative(x, y, labels)
Plot a supply curve.
x and y must share the first two dimensions.
The first dimension must contain unique values.
One rectangle is plotted for each unique value in the second dimension.
- Parameters
x (Quantity) – e.g.
<resource_volume:n-g>
.y (Quantity) – e.g.
<resource_cost:n-g-y>
. Themean()
is taken across the third dimension.
- message_ix.reporting.computations.stacked_bar(qty, dims=['nl', 't', 'ya'], units='', title='', cf=1.0, stacked=True)
Plot qty as a stacked bar chart.
- Parameters
qty (ixmp.reporting.Quantity) – Data to plot.
dims (3-tuple of str) –
Dimensions for, respectively:
The node/region.
Dimension to stack.
The ordinate (x-axis).
units (str) – Units to display on the plot.
title (str) – Title fragment; the plot title is “{node} {title}”.
cf (float, optional) – Conversion factor to apply to data.
Utilities
- message_ix.reporting.pyam.collapse_message_cols(df: pandas.core.frame.DataFrame, var: Optional[str] = None, kind: Optional[str] = None, var_cols=[]) Callable
as_pyam()
collapse=… callback for MESSAGEix quantities.Wraps
collapse()
with arguments particular to MESSAGEix.- Parameters
var (str) – Name for ‘variable’ column.
kind (None or 'ene' or 'emi', optional) –
Determines which other columns are combined into the ‘region’ and ‘variable’ columns:
’ene’: ‘variable’ is
'<var>|<level>|<commodity>|<technology>|<mode>'
and ‘region’ is'<region>|<node_dest>'
(if var=’out’) or'<region>|<node_origin>'
(if ‘var=’in’).’emi’: ‘variable’ is
'<var>|<emission>|<technology>|<mode>'
.Otherwise: ‘variable’ is
'<var>|<technology>'
.