bw2data.parameters

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

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

Module Contents

class bw2data.parameters.ActivityParameter

Bases: ParameterBase

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

constraints

indexes = [(('group', 'name'), True)]

static _static_dependencies(group)

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

static dependency_chain(group, include_self=False)

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)

Return boolean - is this group expired?

static insert_dummy(group, activity)

is_deletable()

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

static is_dependency_within_group(name, group, include_order=False)

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)

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

static load(group)

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

static recalculate(group)

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

static recalculate_exchanges(group)

Recalculate formulas for all parameterized exchanges in group group.

save(*args, **kwargs)

Save this model instance

static static(group, only=None, full=False)

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)

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)

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)

Performs an update of the formula of relevant parameters.

This method specifically targets project parameters used in activity formulas

_db_table = 'activityparameter'

_new_name = 'NEW."group"'

_old_name = 'OLD."group"'

amount

code

data

database

property dict

Parameter data as a standardized dictionary

formula

group

name

class bw2data.parameters.DatabaseParameter

Bases: ParameterBase

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

constraints

indexes = ((('database', 'name'), True),)

static dependency_chain(group, include_self=False)

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)

Return boolean - is this group expired?

is_deletable()

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

static is_dependency_within_group(name, database)

static is_dependent_on(name)

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

static load(database)

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

static recalculate(database)

Recalculate all database parameters for database, if expired.

save(*args, **kwargs)

Save this model instance

static static(database, only=None)

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

classmethod update_formula_database_parameter_name(old, new)

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)

Performs an update of the formula of relevant parameters.

This method specifically targets project parameters used in database formulas

_db_table = 'databaseparameter'

_new_name = 'NEW.database'

_old_name = 'OLD.database'

amount

data

database

property dict

Parameter data as a standardized dictionary

formula

name

class bw2data.parameters.Group

Bases: peewee.Model

class Meta

table_name = 'group_table'

expire()

Set fresh to False

freshen()

Set fresh to True

purge_order()

save(*args, **kwargs)

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

fresh

name

order

updated

class bw2data.parameters.GroupDependency

Bases: peewee.Model

class Meta

constraints

indexes = ((('group', 'depends'), True),)

classmethod create_table()

save(*args, **kwargs)

depends

group

class bw2data.parameters.ParameterBase

Bases: peewee.Model

classmethod create_table()

static expire_downstream(group)

Expire any activity parameters that depend on this group

class bw2data.parameters.ParameterManager

Bases: object

add_exchanges_to_group(group, activity)

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)

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)

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)

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)

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

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

remove_exchanges_from_group(group, activity, restore_original=True)

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)

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)

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)

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)

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.

db

class bw2data.parameters.ParameterizedExchange

Bases: peewee.Model

classmethod create_table()

static load(group)

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

static recalculate(group)

Shortcut for ActivityParameter.recalculate_exchanges.

save(*args, **kwargs)

exchange

formula

group

class bw2data.parameters.ProjectParameter

Bases: ParameterBase

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.

static dependency_chain()

Determine if `ProjectParameter parameters have dependencies within the group.

Returns:

[
    {
        'kind': 'project',
        'group': 'project',
        'names': set of variables names
    }
]

static expired()

Return boolean - is this group expired?

is_deletable()

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

static is_dependency_within_group(name)

static load(group=None)

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

static recalculate(ignored=None)

Recalculate all parameters.

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

save(*args, **kwargs)

static static(ignored='project', only=None)

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)

Performs an update of the formula of relevant parameters.

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

_db_table = 'projectparameter'

_new_name = "'project'"

_old_name = "'project'"

amount

data

property dict

Parameter data as a standardized dictionary

formula

name

bw2data.parameters.alter_parameter_formula(parameter, old, new)

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

bw2data.parameters.get_new_symbols(data, context=None)

bw2data.parameters.AUTOUPDATE_TRIGGER = Multiline-String

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

bw2data.parameters.CROSSDATASE_UPDATE_TRIGGER

Activities can’t be in multiple activity parameter groups

bw2data.parameters.CROSSGROUP_INSERT_TRIGGER

bw2data.parameters.CROSSGROUP_UPDATE_TRIGGER

No circular dependences in activity parameter group dependencies

bw2data.parameters.GD_INSERT_TRIGGER

bw2data.parameters.GD_UPDATE_TRIGGER

Parameterized exchange groups must be in activityparameters table

bw2data.parameters.PE_INSERT_TRIGGER

bw2data.parameters.PE_UPDATE_TRIGGER

bw2data.parameters._CLOSURE_TEMPLATE = Multiline-String

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

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

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

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

bw2data.parameters.nonempty

Autoupdate updated field in Group when parameters change

bw2data.parameters.parameters