REGISTER NOW: Brightway Spring School! 🇨🇦 Québec City (Canada) 🗓️ 20.-24. May 2024

bw2data.parameters#

Module Contents#

Classes#

ActivityParameter

Parameter set for a group of activities.

DatabaseParameter

Parameter set for a database. Group name is the name of the database.

Group

GroupDependency

ParameterBase

ParameterManager

ParameterizedExchange

ProjectParameter

Parameter set for a project. Group name is 'project'.

Functions#

alter_parameter_formula(parameter, old, new)

Replace the old part with new in the formula field and return

get_new_symbols(data[, context])

Attributes#

AUTOUPDATE_TRIGGER

Activity parameter groups can't cross databases

CROSSDATASE_INSERT_TRIGGER

CROSSDATASE_UPDATE_TRIGGER

Activities can't be in multiple activity parameter groups

CROSSGROUP_INSERT_TRIGGER

CROSSGROUP_UPDATE_TRIGGER

No circular dependences in activity parameter group dependencies

GD_INSERT_TRIGGER

GD_UPDATE_TRIGGER

Parameterized exchange groups must be in activityparameters table

PE_INSERT_TRIGGER

PE_UPDATE_TRIGGER

_CLOSURE_TEMPLATE

_CROSSDATABASE_TEMPLATE

_CROSSGROUP_TEMPLATE

_PE_GROUP_TEMPLATE

clean

nonempty

Autoupdate updated field in Group when parameters change

parameters

class bw2data.parameters.ActivityParameter[source]#

Bases: ParameterBase

Inheritance diagram of bw2data.parameters.ActivityParameter

Parameter set for a group of activities.

Columns:

  • group: str

  • database: str

  • code: str. Code and database define the linked activity for this parameter.

  • name: str, unique within a group

  • formula: str, optional

  • amount: float, optional

  • data: object, optional. Used for any other metadata.

Activities can only have parameters in one group. Group names cannot be ‘project’ or the name of any existing database.

Activity parameter groups can depend on other activity parameter groups, so that a formula in group “a” can depend on a variable in group “b”. This dependency information is stored in Group.order - in our small example, we could define the following:

a = Group.get(name="a")
a.order = ["b", "c"]
a.save()

In this case, a variable not found in “a” would be searched for in “b” and then “c”, in that order. Database and then project parameters are also implicitly included at the end of Group.order.

Note that there is no magic for reading and writing to data (unlike Activity objects) - it must be used directly.

class Meta[source]#
constraints[source]#
indexes = [(('group', 'name'), True)][source]#
property dict[source]#

Parameter data as a standardized dictionary

_db_table = 'activityparameter'[source]#
_new_name = 'NEW."group"'[source]#
_old_name = 'OLD."group"'[source]#
amount[source]#
code[source]#
data[source]#
database[source]#
formula[source]#
group[source]#
name[source]#
static _static_dependencies(group)[source]#

Get dictionary of {name: amount} for all variables defined in dependency chain.

Be careful! This could have variables which overlap with local variable names. Designed for internal use.

classmethod create_table()[source]#
static dependency_chain(group, include_self=False)[source]#

Find where each missing variable is defined in dependency chain.

Will also load in all parameters needed to resolve the ParameterizedExchanges for this group.

If include_self is True will include parameters within the group as possible dependencies

Returns:

[
    {
        'kind': one of 'project', 'database', 'activity',
        'group': group name,
        'names': set of variables names
    }
]
static expired(group)[source]#

Return boolean - is this group expired?

static insert_dummy(group, activity)[source]#
is_deletable()[source]#

Perform a test to see if the current parameter can be deleted.

static is_dependency_within_group(name, group, include_order=False)[source]#

Determine if the given parameter name is a dependency within the given activity group.

The optional include_order parameter will include dependencies from groups found in the the Group.`order` field.

static is_dependent_on(name, group)[source]#

Test if any activity parameters are dependent on the given parameter name from the given group.

static load(group)[source]#

Return dictionary of parameter data with names as keys and .dict() as values.

static recalculate(group)[source]#

Recalculate all values for activity parameters in this group, and update their underlying Activity and Exchange values.

static recalculate_exchanges(group)[source]#

Recalculate formulas for all parameterized exchanges in group group.

save(*args, **kwargs)[source]#

Save this model instance

static static(group, only=None, full=False)[source]#

Get dictionary of {name: amount} for parameters defined in group.

only restricts returned names to ones found in only. full returns all names, including those found in the dependency chain.

classmethod update_formula_activity_parameter_name(old, new, include_order=False)[source]#

Performs an update of the formula of relevant parameters.

This method specifically targets activity parameters used in activity formulas

classmethod update_formula_database_parameter_name(old, new)[source]#

Performs an update of the formula of relevant parameters.

This method specifically targets database parameters used in activity formulas

classmethod update_formula_project_parameter_name(old, new)[source]#

Performs an update of the formula of relevant parameters.

This method specifically targets project parameters used in activity formulas

class bw2data.parameters.DatabaseParameter[source]#

Bases: ParameterBase

Inheritance diagram of bw2data.parameters.DatabaseParameter

Parameter set for a database. Group name is the name of the database.

Columns:

  • database: str

  • name: str, unique within a database

  • formula: str, optional

  • amount: float, optional

  • data: object, optional. Used for any other metadata.

Note that there is no magic for reading and writing to data (unlike Activity objects) - it must be used directly.

class Meta[source]#
constraints[source]#
indexes = ((('database', 'name'), True),)[source]#
property dict[source]#

Parameter data as a standardized dictionary

_db_table = 'databaseparameter'[source]#
_new_name = 'NEW.database'[source]#
_old_name = 'OLD.database'[source]#
amount[source]#
data[source]#
database[source]#
formula[source]#
name[source]#
static dependency_chain(group, include_self=False)[source]#

Find where each missing variable is defined in dependency chain.

If include_self is True will include parameters within the group as possible dependencies

Returns:

[
    {
        'kind': one of 'project', 'database', 'activity',
        'group': group name,
        'names': set of variables names
    }
]
static expired(database)[source]#

Return boolean - is this group expired?

is_deletable()[source]#

Perform a test to see if the current parameter can be deleted.

static is_dependency_within_group(name, database)[source]#
static is_dependent_on(name)[source]#

Test if any database parameters are dependent on the given project parameter name.

static load(database)[source]#

Return dictionary of parameter data with names as keys and .dict() as values.

static recalculate(database)[source]#

Recalculate all database parameters for database, if expired.

save(*args, **kwargs)[source]#

Save this model instance

static static(database, only=None)[source]#

Return dictionary of {name: amount} for database group.

classmethod update_formula_database_parameter_name(old, new)[source]#

Performs an update of the formula of relevant parameters.

This method specifically targets database parameters used in database formulas

classmethod update_formula_project_parameter_name(old, new)[source]#

Performs an update of the formula of relevant parameters.

This method specifically targets project parameters used in database formulas

class bw2data.parameters.Group[source]#

Bases: peewee.Model

Inheritance diagram of bw2data.parameters.Group
class Meta[source]#
table_name = 'group_table'[source]#
fresh[source]#
name[source]#
order[source]#
updated[source]#
expire()[source]#

Set fresh to False

freshen()[source]#

Set fresh to True

purge_order()[source]#
save(*args, **kwargs)[source]#

Save this model instance. Will remove ‘project’ and database names from order.

class bw2data.parameters.GroupDependency[source]#

Bases: peewee.Model

Inheritance diagram of bw2data.parameters.GroupDependency
class Meta[source]#
constraints[source]#
indexes = ((('group', 'depends'), True),)[source]#
depends[source]#
group[source]#
classmethod create_table()[source]#
save(*args, **kwargs)[source]#
class bw2data.parameters.ParameterBase[source]#

Bases: peewee.Model

Inheritance diagram of bw2data.parameters.ParameterBase
classmethod create_table()[source]#
static expire_downstream(group)[source]#

Expire any activity parameters that depend on this group

class bw2data.parameters.ParameterManager[source]#
add_exchanges_to_group(group, activity)[source]#

Add exchanges with formulas from activity to group.

Every exchange with a formula field will have its original amount value stored as original_amount. This original value can be restored when parameterization is removed from the activity with remove_from_group.

add_to_group(group, activity)[source]#

Add activity to group.

Creates group if needed.

Will delete any existing ActivityParameter for this activity.

Deletes parameters key from Activity.

new_activity_parameters(data, group, overwrite=True)[source]#

Efficiently and correctly enter multiple parameters. Deletes all existing activity parameters for this group.

Will overwrite existing parameters in the same group with the same name, unless overwrite is false, in which case a ValueError is raised.

Input parameters must refer to a single, existing database.

group is the group name; will be autocreated if necessary. data should be a list of dictionaries:

[{
    'name': name of variable (unique),
    'database': activity database,
    'code': activity code,
    'amount': numeric value of variable (optional),
    'formula': formula in Python as string (optional),
    optional keys like uncertainty, etc. (no limitations)
}]
new_database_parameters(data, database, overwrite=True)[source]#

Efficiently and correctly enter multiple parameters. Deletes all existing database parameters for this database.

Will overwrite existing database parameters with the same name, unless overwrite is false, in which case a ValueError is raised.

database should be an existing database. data should be a list of dictionaries:

[{
    'name': name of variable (unique),
    'amount': numeric value of variable (optional),
    'formula': formula in Python as string (optional),
    optional keys like uncertainty, etc. (no limitations)
}]
new_project_parameters(data, overwrite=True)[source]#

Efficiently and correctly enter multiple parameters.

Will overwrite existing project parameters with the same name, unless overwrite is false, in which case a ValueError is raised.

data should be a list of dictionaries:

[{
    'name': name of variable (unique),
    'amount': numeric value of variable (optional),
    'formula': formula in Python as string (optional),
    optional keys like uncertainty, etc. (no limitations)
}]
recalculate()[source]#

Recalculate all expired project, database, and activity parameters, as well as exchanges.

remove_exchanges_from_group(group, activity, restore_original=True)[source]#

Takes a group and activity and removes all ParameterizedExchange objects from the group.

The restore_original parameter determines if the original amount values will be restored to those exchanges where a formula was used to alter the amount.

remove_from_group(group, activity, restore_amounts=True)[source]#

Remove activity from group.

Will delete any existing ActivityParameter and ParameterizedExchange for this activity.

Restores parameters key to this Activity. By default, restores amount value of each parameterized exchange of the Activity to the original value. This can be avoided by using the restore_amounts parameter.

rename_activity_parameter(parameter, new_name, update_dependencies=False)[source]#

Given a parameter and a new name, safely update the parameter.

Will raise a TypeError if the given parameter is of the incorrect type. Will raise a ValueError if other parameters depend on the given one and update_dependencies is False.

rename_database_parameter(parameter, new_name, update_dependencies=False)[source]#

Given a parameter and a new name, safely update the parameter.

Will raise a TypeError if the given parameter is of the incorrect type. Will raise a ValueError if other parameters depend on the given one and update_dependencies is False.

rename_project_parameter(parameter, new_name, update_dependencies=False)[source]#

Given a parameter and a new name, safely update the parameter.

Will raise a TypeError if the given parameter is of the incorrect type. Will raise a ValueError if other parameters depend on the given one and update_dependencies is False.

class bw2data.parameters.ParameterizedExchange[source]#

Bases: peewee.Model

Inheritance diagram of bw2data.parameters.ParameterizedExchange
exchange[source]#
formula[source]#
group[source]#
classmethod create_table()[source]#
static load(group)[source]#

Return dictionary of parameter data with names as keys and .dict() as values.

static recalculate(group)[source]#

Shortcut for ActivityParameter.recalculate_exchanges.

save(*args, **kwargs)[source]#
class bw2data.parameters.ProjectParameter[source]#

Bases: ParameterBase

Inheritance diagram of bw2data.parameters.ProjectParameter

Parameter set for a project. Group name is ‘project’.

Columns:

  • name: str, unique

  • formula: str, optional

  • amount: float, optional

  • data: object, optional. Used for any other metadata.

Note that there is no magic for reading and writing to data (unlike Activity objects) - it must be used directly.

property dict[source]#

Parameter data as a standardized dictionary

_db_table = 'projectparameter'[source]#
_new_name = "'project'"[source]#
_old_name = "'project'"[source]#
amount[source]#
data[source]#
formula[source]#
name[source]#
static dependency_chain()[source]#

Determine if `ProjectParameter parameters have dependencies within the group.

Returns:

[
    {
        'kind': 'project',
        'group': 'project',
        'names': set of variables names
    }
]
static expired()[source]#

Return boolean - is this group expired?

is_deletable()[source]#

Perform a test to see if the current parameter can be deleted.

static is_dependency_within_group(name)[source]#
static load(group=None)[source]#

Return dictionary of parameter data with names as keys and .dict() as values.

static recalculate(ignored=None)[source]#

Recalculate all parameters.

ignored included for API compatibility with other recalculate methods - it will really be ignored.

save(*args, **kwargs)[source]#
static static(ignored='project', only=None)[source]#

Get dictionary of {name: amount} for all project parameters.

only restricts returned names to ones found in only. ignored included for API compatibility with other recalculate methods.

classmethod update_formula_parameter_name(old, new)[source]#

Performs an update of the formula of relevant parameters.

NOTE: Make sure to wrap this in an .atomic() statement!

bw2data.parameters.alter_parameter_formula(parameter, old, new)[source]#

Replace the old part with new in the formula field and return the parameter itself.

bw2data.parameters.get_new_symbols(data, context=None)[source]#
bw2data.parameters.AUTOUPDATE_TRIGGER = Multiline-String[source]#
Show Value
"""CREATE TRIGGER IF NOT EXISTS {table}_{action}_trigger AFTER {action} ON {table} BEGIN
    UPDATE group_table SET updated = datetime('now') WHERE name = {name};
END;"""

Activity parameter groups can’t cross databases

bw2data.parameters.CROSSDATASE_INSERT_TRIGGER[source]#
bw2data.parameters.CROSSDATASE_UPDATE_TRIGGER[source]#

Activities can’t be in multiple activity parameter groups

bw2data.parameters.CROSSGROUP_INSERT_TRIGGER[source]#
bw2data.parameters.CROSSGROUP_UPDATE_TRIGGER[source]#

No circular dependences in activity parameter group dependencies

bw2data.parameters.GD_INSERT_TRIGGER[source]#
bw2data.parameters.GD_UPDATE_TRIGGER[source]#

Parameterized exchange groups must be in activityparameters table

bw2data.parameters.PE_INSERT_TRIGGER[source]#
bw2data.parameters.PE_UPDATE_TRIGGER[source]#
bw2data.parameters._CLOSURE_TEMPLATE = Multiline-String[source]#
Show Value
"""CREATE TRIGGER IF NOT EXISTS gd_circular_{action} BEFORE {action} ON groupdependency BEGIN
    SELECT CASE WHEN EXISTS (SELECT * FROM groupdependency AS g WHERE g."group" = NEW.depends AND g.depends = NEW."group")
    THEN RAISE(ABORT,'Circular dependency')
    END;
END;
"""
bw2data.parameters._CROSSDATABASE_TEMPLATE = Multiline-String[source]#
Show Value
"""CREATE TRIGGER IF NOT EXISTS ap_crossdatabase_{action} BEFORE {action} ON activityparameter BEGIN
    SELECT CASE WHEN
        ((SELECT COUNT(*) FROM activityparameter WHERE "group" = NEW."group") > 0)
    AND (NEW.database NOT IN (SELECT DISTINCT "database" FROM activityparameter where "group" = NEW."group"))
    THEN RAISE(ABORT,'Cross database group')
    END;
END;"""
bw2data.parameters._CROSSGROUP_TEMPLATE = Multiline-String[source]#
Show Value
"""CREATE TRIGGER IF NOT EXISTS ap_crossgroup_{action} BEFORE {action} ON activityparameter BEGIN
    SELECT CASE WHEN EXISTS (SELECT * FROM activityparameter AS a WHERE
            a.database = NEW.database AND
            a.code = NEW.code AND
            a."group" != NEW."group")
    THEN RAISE(ABORT,'Cross group activity')
    END;
END;"""
bw2data.parameters._PE_GROUP_TEMPLATE = Multiline-String[source]#
Show Value
"""CREATE TRIGGER IF NOT EXISTS pe_group_{action} BEFORE {action} ON parameterizedexchange BEGIN
    SELECT CASE WHEN
        ((SELECT COUNT(*) FROM activityparameter WHERE "group" = NEW."group") < 1)
    THEN RAISE(ABORT,'Missing activity parameter group')
    END;
END;
"""
bw2data.parameters.clean[source]#
bw2data.parameters.nonempty[source]#

Autoupdate updated field in Group when parameters change

bw2data.parameters.parameters[source]#