API reference¶
Top-level classes and functions¶
|
Configure |
|
Class for describing and executing computations. |
|
A hashable key for a quantity that includes its dimensionality. |
|
- genno.configure(path: Optional[Union[pathlib.Path, str]] = None, **config)[source]
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.
- class genno.Computer(**kwargs)[source]¶
Class for describing and executing computations.
- Parameters
kwargs – Passed to
configure()
.
A Computer is used to describe (
add()
and related methods) and then execute (get()
and related methods) tasks stored in agraph
. Advanced users may manipulate the graph directly; but common reporting tasks can be handled by using Computer methods.Instance attributes:
The default key to
get()
with no argument.keys
()Return the keys of
graph
.List of modules containing pre-defined computations.
The
pint.UnitRegistry()
used by the Computer.General-purpose methods for describing tasks and preparing computations:
add
(data, *args, **kwargs)General-purpose method to add computations.
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.
apply
(generator, *keys, **kwargs)Add computations by applying generator to keys.
cache
(func)Return a decorator to cache data.
describe
([key, quiet])Return a string describing the computations that produce key.
visualize
(filename, **kwargs)Generate an image describing the Computer structure.
Helper methods to simplify adding specific computations:
add_file
(path[, key])Add exogenous quantities from path.
add_product
(key, *quantities[, sums])Add a computation that takes the product of quantities.
aggregate
(qty, tag, dims_or_groups[, …])Add a computation that aggregates qty.
convert_pyam
(quantities[, tag])Add conversion of one or more quantities to IAMC format.
disaggregate
(qty, new_dim[, method, args])Add a computation that disaggregates qty using method.
Exectuing tasks:
get
([key])Execute and return the result of the computation key.
write
(key, path)Write the result of key to the file path.
Utility and configuration methods:
check_keys
(*keys[, action, _permute])Check that keys are in the Computer.
configure
([path, fail])Configure the Computer.
full_key
(name_or_key)Return the full-dimensionality key for name_or_key.
get_comp
(name)Return a computation function.
infer_keys
(key_or_keys[, dims])Infer complete key_or_keys.
require_compat
(pkg)Load computations from
genno.compat.{pkg}
for use withget_comp()
.- graph: Dict[str, Any] = {'config': {}}¶
A dask-format graph (see 1, 2).
Dictionary keys are either
Key
,str
, or any other hashable value.Dictionary values are computations, one of:
Any other, existing key in the Computer. This functions as an alias.
Any other literal value or constant, to be returned directly.
A task
tuple
: a callable (e.g. function), followed by zero or more computations, e.g. keys for other tasks.A
list
containing zero or more of (1), (2), and/or (3).
genno
reserves some keys for special usage:"config"
A
dict
storing configuration settings. See Configuration. Because this information is stored in thegraph
, it can be used as one input to other computations.
Some inputs to tasks may be confused for (1) or (4), above. The recommended way to protect these is:
Literal
str
inputs to tasks: usefunctools.partial()
on the function that is the first element of the task tuple.
- add(data, *args, **kwargs)[source]¶
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
The data argument may be:
list
A list of computations, like
[(list(args1), dict(kwargs1)), (list(args2), dict(kwargs2)), ...]
→ passed toadd_queue()
.str
naming a computatione.g. “select”, retrievable with
get_comp()
.add_single()
is called with(key=args[0], data, *args[1], **kwargs
, i.e. applying the named computation. to the other parameters.str
naming another Computer methode.g.
add_file()
→ the named method is called with the args and kwargs.Key
or otherstr
:Passed to
add_single()
.
add()
may be used to:Provide an alias from one key to another:
>>> from genno import Computer >>> rep = Computer() # Create a new Computer object >>> rep.add('aliased name', 'original name')
Define an arbitrarily complex computation in a Python function that operates directly on the
ixmp.Scenario
:>>> def my_report(scenario): >>> # many lines of code >>> return 'foo' >>> rep.add('my report', (my_report, 'scenario')) >>> rep.finalize(scenario) >>> rep.get('my report') foo
- apply(generator, *keys, **kwargs)[source]¶
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.
The generator may have a type annotation for Computer on its first positional argument. In this case, a reference to the Computer is supplied, and generator can use the Computer methods to add many keys and computations:
def my_gen0(c: genno.Computer, **kwargs): c.load_file("file0.txt", **kwargs) c.load_file("file1.txt", **kwargs) # Use the generator to add several computations rep.apply(my_gen0, units="kg")
Or, generator may
yield
a sequence (0 or more) of (key, computation), which are added to thegraph
:def my_gen1(**kwargs): op = partial(computations.load_file, **kwargs) yield from (f"file:{i}", (op, "file{i}.txt")) for i in range(2) rep.apply(my_gen1, units="kg")
- cache(func)[source]¶
Return a decorator to cache data.
Use this function to decorate another function to be added as the computation/callable in a task:
c = Computer(cache_path=Path("/some/directory")) @c.cache def myfunction(*args, **kwargs): # Expensive operations, e.g. loading large files return data c.add("myvar", (myfunction,)) # Data is cached in /some/directory/myfunction-*.pkl
On the first call of
get()
that invokes func, the data requested is returned, but also cached in the cache directory (see Configuration → Caching).On subsequent calls, if the cache exists, it is used instead of calling the (possibly slow) func.
If the
"cache_skip"
configuration option isTrue
, func is always called.
- convert_pyam(quantities, tag='iamc', **kwargs)[source]¶
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
The IAMC data format includes columns named ‘Model’, ‘Scenario’, ‘Region’, ‘Variable’, ‘Unit’; one of ‘Year’ or ‘Time’; and ‘value’.
Using
convert_pyam()
:‘Model’ and ‘Scenario’ are populated from the attributes of the object returned by the Reporter key
scenario
;‘Variable’ contains the name(s) of the quantities;
‘Unit’ contains the units associated with the quantities; and
‘Year’ or ‘Time’ is created according to year_time_dim.
A callback function (collapse) can be supplied that modifies the data before it is converted to an
IamDataFrame
; for instance, to concatenate extra dimensions into the ‘Variable’ column. Other dimensions can simply be dropped (with drop). Dimensions that are not collapsed or dropped will appear as additional columns in the resultingIamDataFrame
; this is valid, but non-standard IAMC data.For example, here the values for the MESSAGEix
technology
andmode
dimensions are appended to the ‘Variable’ column:def m_t(df): """Callback for collapsing ACT columns.""" # .pop() removes the named column from the returned row df['variable'] = 'Activity|' + df['t'] + '|' + df['m'] return df ACT = rep.full_key('ACT') keys = rep.convert_pyam(ACT, 'ya', collapse=m_t, drop=['t', 'm'])
- add_aggregate(qty, tag, dims_or_groups, weights=None, keep=True, sums=False)¶
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
.
- Returns
The key of the newly-added node.
- Return type
- add_file(path, key=None, **kwargs)[source]¶
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
See also
- add_product(key, *quantities, sums=True)[source]¶
Add a computation that takes the product of quantities.
- Parameters
- Returns
The full key of the new quantity.
- Return type
- add_queue(queue: Iterable[Tuple[Tuple, Mapping]], max_tries: int = 1, fail: Union[str, int] = 'raise') → Tuple[Union[genno.core.key.Key, Hashable], ...][source]¶
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)[source]¶
Add a single computation at key.
- Parameters
key (str or Key or hashable) – A string, Key, or other value identifying the output of computation.
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
- aggregate(qty, tag, dims_or_groups, weights=None, keep=True, sums=False)[source]¶
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
.
- Returns
The key of the newly-added node.
- Return type
- check_keys(*keys: Union[str, genno.core.key.Key], action='raise', _permute=True) → Optional[List[Union[str, genno.core.key.Key]]][source]¶
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)[source]¶
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.
- describe(key=None, quiet=True)[source]¶
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=[])[source]¶
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
- full_key(name_or_key)[source]¶
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.
- get(key=None)[source]¶
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][source]¶
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, dims=[])[source]¶
Infer complete key_or_keys.
- Parameters
dims (list of str, optional) – Drop all but these dimensions from the returned key(s).
- modules: Sequence[module] = [<module 'genno.computations' from '/home/docs/checkouts/readthedocs.org/user_builds/genno/envs/v1.6.0/lib/python3.8/site-packages/genno/computations.py'>]¶
List of modules containing pre-defined computations.
By default, this includes the
genno
built-in computations ingenno.computations
.require_compat()
appends additional modules, e.g. #:compat.pyam.computations
, to this list. User code may also add modules to this list.
- require_compat(pkg: str)[source]¶
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
- property unit_registry¶
The
pint.UnitRegistry()
used by the Computer.
- class genno.Key(name: str, dims: Iterable[str] = [], tag: Optional[str] = None)[source]¶
A hashable key for a quantity that includes its dimensionality.
Quantities are indexed by 0 or more dimensions. A Key refers to a quantity using three components:
For example, for a \(\text{foo}\) with with three dimensions \(a, b, c\):
\[\text{foo}^{abc}\]Key allows a specific, explicit reference to various forms of “foo”:
in its full resolution, i.e. indexed by a, b, and c:
>>> k1 = Key("foo", ["a", "b", "c"]) >>> k1 <foo:a-b-c>
in a partial sum over one dimension, e.g. summed across dimension c, with remaining dimensions a and b:
>>> k2 = k1.drop('c') >>> k2 == 'foo:a-b' True
in a partial sum over multiple dimensions, etc.:
>>> k1.drop('a', 'c') == k2.drop('a') == 'foo:b' True
after it has been manipulated by other computations, e.g.
>>> k3 = k1.add_tag('normalized') >>> k3 <foo:a-b-c:normalized> >>> k4 = k3.add_tag('rescaled') >>> k4 <foo:a-b-c:normalized+rescaled>
Notes:
A Key has the same hash, and compares equal to its
str
representation. A Key also compares equal to another key orstr
with the same dimensions in any other order.repr(key)
prints the Key in angle brackets (‘<>’) to signify that it is a Key object.>>> str(k1) 'foo:a-b-c' >>> repr(k1) '<foo:a-b-c>' >>> hash(k1) == hash("foo:a-b-c") True >>> k1 == "foo:c-b-a" True
Keys are immutable: the properties
name
,dims
, andtag
are read-only, and the methodsappend()
,drop()
, andadd_tag()
return new Key objects.Keys may be generated concisely by defining a convenience method:
>>> def foo(dims): >>> return Key('foo', dims.split()) >>> foo('a b c') <foo:a-b-c>
- classmethod from_str_or_key(value: Union[str, genno.core.key.Key], drop: Union[Iterable[str], bool] = [], append: Iterable[str] = [], tag: Optional[str] = None)[source]¶
Return a new Key from value.
- Parameters
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()
.
- Returns
- Return type
- iter_sums() → Generator[Tuple[genno.core.key.Key, Callable, genno.core.key.Key], None, None][source]¶
Generate (key, task) for all possible partial sums of the Key.
- permute_dims() → Generator[genno.core.key.Key, None, None][source]¶
Generate variants of the Key with dimensions in all possible orders.
Examples
>>> k = Key("A", "xyz") >>> list(k.permute_dims()) [<A:x-y-z>, <A:x-z-y>, <A:y-x-z>, <A:y-z-x>, <A:z-x-y>, <A:z-y-x>]
- classmethod product(new_name: str, *keys, tag: Optional[str] = None) → genno.core.key.Key[source]¶
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.
- class genno.Quantity(*args, **kwargs)[source]¶
- classmethod from_series(series, sparse=True)[source]¶
Convert series to the Quantity class given by
CLASS
.
The Quantity
constructor converts its arguments to an internal, xarray.DataArray
-like data format:
# Existing data
data = pd.Series(...)
# Convert to a Quantity for use in reporting calculations
qty = Quantity(data, name="Quantity name", units="kg")
rep.add("new_qty", qty)
Common genno
usage, e.g. in message_ix
, creates large, sparse data frames (billions of possible elements, but <1% populated); DataArray
’s default, ‘dense’ storage format would be too large for available memory.
Currently, Quantity is
AttrSeries
, a wrappedpandas.Series
that behaves like aDataArray
.In the future,
genno
will useSparseDataArray
, and eventuallyDataArray
backed by sparse data, directly.
The goal is that all genno
-based code, including built-in and user computations, can treat quantity arguments as if they were DataArray
.
Computations¶
Elementary computations for genno.
Unless otherwise specified, these methods accept and return Quantity
objects for data arguments/return values.
Genno’s compatibility modules each provide additional computations.
Calculations:
|
Sum across multiple quantities. |
|
Aggregate quantity by groups. |
|
Simply apply units to qty. |
|
Broadcast quantity using a map. |
|
Sum distinct quantities by weights. |
|
Disaggregate quantity by shares. |
|
Group by dimension group, then sum across dimension sum. |
|
Compute a raised to the power of b. |
|
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. |
Input and output:
|
Read the file at path and return its contents as a |
|
Write a quantity to a file. |
Data manipulation:
|
Concatenate Quantity objs. |
- genno.computations.add(*quantities, fill_value=0.0)[source]¶
Sum across multiple quantities.
- Raises
ValueError – if any of the quantities have incompatible units.
- Returns
Units are the same as the first of quantities.
- Return type
- genno.computations.aggregate(quantity, groups, keep)[source]¶
Aggregate quantity by groups.
- Parameters
quantity (
Quantity
) –groups (dict of dict) – Top-level keys are the names of dimensions in quantity. Second-level keys are group names; second-level values are lists of labels along the dimension to sum into a group.
keep (bool) – If True, the members that are aggregated into a group are returned with the group sums. If False, they are discarded.
- Returns
Same dimensionality as quantity.
- Return type
Quantity
- genno.computations.apply_units(qty, units, quiet=False)[source]¶
Simply apply units to qty.
Logs on level
WARNING
if qty already has existing units.
- genno.computations.broadcast_map(quantity, map, rename={}, strict=False)[source]¶
Broadcast quantity using a map.
The map must be a 2-dimensional Quantity with dimensions (
d1
,d2
), such as returned bymap_as_qty()
. quantity must also have a dimensiond1
. Typicallylen(d2) > len(d1)
.quantity is ‘broadcast’ by multiplying it with map, and then summing on the common dimension
d1
. The result has the dimensions of quantity, but withd2
in place ofd1
.
- genno.computations.combine(*quantities, select=None, weights=None)[source]¶
Sum distinct quantities by weights.
- Parameters
*quantities (Quantity) – The quantities to be added.
select (list of dict) – Elements to be selected from each quantity. Must have the same number of elements as quantities.
weights (list of float) – Weight applied to each quantity. Must have the same number of elements as quantities.
- Raises
ValueError – If the quantities have mismatched units.
- genno.computations.concat(*objs, **kwargs)[source]¶
Concatenate Quantity objs.
Any strings included amongst objs are discarded, with a logged warning; these usually indicate that a quantity is referenced which is not in the Computer.
Disaggregate quantity by shares.
- genno.computations.group_sum(qty, group, sum)[source]¶
Group by dimension group, then sum across dimension sum.
The result drops the latter dimension.
- genno.computations.load_file(path, dims={}, units=None, name=None)[source]¶
Read the file at path and return its contents as a
Quantity
.Some file formats are automatically converted into objects for direct use in genno computations:
.csv
:Converted to
Quantity
. CSV files must have a ‘value’ column; all others are treated as indices, except as given by dims. Lines beginning with ‘#’ are ignored.
- Parameters
path (pathlib.Path) – Path to the file to read.
dims (collections.abc.Collection or collections.abc.Mapping, optional) – If a collection of names, other columns besides these and ‘value’ are discarded. If a mapping, the keys are the column labels in path, and the values are the target dimension names.
units (str or pint.Unit) – Units to apply to the loaded Quantity.
name (str) – Name for the loaded Quantity.
- genno.computations.pow(a, b)[source]¶
Compute a raised to the power of b.
Todo
Provide units on the result in the special case where b is a Quantity but all its values are the same
int
.
- genno.computations.ratio(numerator, denominator)[source]¶
Compute the ratio numerator / denominator.
Internal format for quantities¶
- genno.core.quantity.assert_quantity(*args)[source]¶
Assert that each of args is a Quantity object.
- Raises
TypeError – with a indicative message.
- class genno.core.attrseries.AttrSeries(*args, **kwargs)[source]¶
pandas.Series
subclass imitatingxarray.DataArray
.The AttrSeries class provides similar methods and behaviour to
xarray.DataArray
, so thatgenno.computations
functions and user code can use xarray-like syntax. In particular, this allows such code to be agnostic about the order of dimensions.- Parameters
- align_levels(other)[source]¶
Work around https://github.com/pandas-dev/pandas/issues/25760.
Return a copy of self with common levels in the same order as other.
- bfill(dim: Hashable, limit: Optional[int] = None)[source]¶
Like
xarray.DataArray.bfill()
.
- property coords¶
Like
xarray.DataArray.coords
. Read-only.
- property dims¶
Like
xarray.DataArray.dims
.
- drop(label)[source]¶
Like
xarray.DataArray.drop()
.
- ffill(dim: Hashable, limit: Optional[int] = None)[source]¶
Like
xarray.DataArray.ffill()
.
- item(*args)[source]¶
Like
xarray.DataArray.item()
.
- sel(indexers=None, drop=False, **indexers_kwargs)[source]¶
Like
xarray.DataArray.sel()
.
- shift(shifts: Optional[Mapping[Hashable, int]] = None, fill_value: Optional[Any] = None, **shifts_kwargs: int)[source]¶
Like
xarray.DataArray.shift()
.
- sum(*args, **kwargs)[source]¶
Like
xarray.DataArray.sum()
.
- class genno.core.sparsedataarray.SparseAccessor(obj)[source]¶
xarray
accessor to helpSparseDataArray
.See the xarray accessor documentation, e.g.
register_dataarray_accessor()
.- convert()[source]¶
Return a
SparseDataArray
instance.
- property dense¶
Return a copy with dense (
ndarray
) data.
- property dense_super¶
Return a proxy to a
ndarray
-backedDataArray
.
- class genno.core.sparsedataarray.SparseDataArray(*args, **kwargs)[source]¶
DataArray
with sparse data.SparseDataArray uses
sparse.COO
for storage withnumpy.nan
as itssparse.COO.fill_value
. Some methods ofDataArray
are overridden to ensure data is in sparse, or dense, format as necessary, to provide expected functionality not currently supported bysparse
, and to avoid exhausting memory for some operations that require dense data.- sel(indexers=None, method=None, tolerance=None, drop=False, **indexers_kwargs) → genno.core.sparsedataarray.SparseDataArray[source]¶
Return a new array by selecting labels along the specified dim(s).
Overrides
sel()
to handle >1-D indexers with sparse data.
- to_dataframe(name=None)[source]¶
Convert this array and its coords into a
DataFrame
.Overrides
to_dataframe()
.
- to_series() → pandas.core.series.Series[source]¶
Convert this array into a
Series
.Overrides
to_series()
to create the series without first converting to a potentially very largenumpy.ndarray
.
Utilities¶
- genno.util.REPLACE_UNITS = {'%': 'percent'}¶
Replacements to apply to Quantity units before parsing by pint. Mapping from original unit -> preferred unit.
The default values include:
The ‘%’ symbol cannot be supported by pint, because it is a Python operator; it is replaced with “percent”.
Additional values can be added with
configure()
; see units:.
- genno.util.clean_units(input_string)[source]¶
Tolerate messy strings for units.
Dimensions enclosed in “[]” have these characters stripped.
Replacements from
REPLACE_UNITS
are applied.
- genno.util.filter_concat_args(args)[source]¶
Filter out str and Key from args.
A warning is logged for each element removed.
- genno.util.parse_units(data: Iterable, registry=None) → pint.unit.Unit[source]¶
Return a
pint.Unit
for an iterable of strings.Valid unit expressions not already present in the registry are defined, e.g.:
u = parse_units(["foo/bar", "foo/bar"], reg)
…results in the addition of unit definitions equivalent to:
reg.define("foo = [foo]") reg.define("bar = [bar]") u = reg.foo / reg.bar
- Raises
ValueError – if data contains more than 1 unit expression, or the unit expression contains characters not parseable by
pint
, e.g.-?$
.
- genno.util.partial_split(func, kwargs)[source]¶
Forgiving version of
functools.partial()
.Returns a partial object and leftover kwargs not applicable to func.
- class genno.caching.PathEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]¶
JSON encoder that handles
pathlib.Path
.Used by
arg_hash()
.- default(o)[source]¶
Implement this method in a subclass such that it returns a serializable object for
o
, or calls the base implementation (to raise aTypeError
).For example, to support arbitrary iterators, you could implement default like this:
def default(self, o): try: iterable = iter(o) except TypeError: pass else: return list(iterable) # Let the base class default method raise the TypeError return JSONEncoder.default(self, o)
- genno.caching.arg_hash(*args, **kwargs)[source]¶
Return a unique hash for args and kwargs.
Used by
make_cache_decorator()
.
- genno.caching.make_cache_decorator(computer, func)[source]¶
Helper for
Computer.cache()
.