IAMC Data

class ixmp4.core.iamc.data.PlatformIamcData(backend: Backend)

IAMC data on a platform.

tabulate(*, join_runs: bool = True, join_run_id: bool = False, raw: bool = False, **kwargs: Unpack[FacadeDataPointFilter]) → DataFrame

Tabulates datapoints by specified criteria.

df = platform.iamc.tabulate()
#>   model   scenario  version  region  ...   year  value
# 0  Model  Scenario   1         World  ...  2020   36.5

Parameters:

**kwargs (any) – Filter parameters as specified in FacadeDataPointFilter.

Returns:

A data frame with the columns:

model
scenario
version
region
unit
variable
year
category
datetime
type

Return type:

pandas.DataFrame

class ixmp4.core.iamc.data.RunIamcData(backend: Backend, run: run.Run)

IAMC data linked to a ixmp4.core.run.Run.

import pandas as pd

input_df = pd.read_csv("my_iamc_data.csv")
run.iamc.add(input_df)

returned_df = run.iamc.tabulate()
print(returned_df)

run.iamc.remove(input_df.drop(columns=["value"]))

add(df: DataFrame, type: Type | str | None = None) → None

Adds IAMC data from a data frame to a run.

Requires an active run lock — use with run.transact("message"): to acquire one before calling this method.

import pandas as pd
from ixmp4.data.iamc.datapoint.type import Type

input_df = pd.DataFrame({
    "region": ["World"],
    "variable": ["Emissions|CO2"],
    "unit": ["MtCO2/yr"],
    "year": [2020],
    "value": [36.5],
})

with run.transact("add emissions data"):
    run.iamc.add(input_df, type=Type.ANNUAL)
    # or equivalently:
    run.iamc.add(input_df, type="ANNUAL")

Parameters:

df (pandas.DataFrame) –
A data frame with the columns:
- region
- variable
- unit
- value
Any combination of:
- step_year for ANNUAL data points
- step_year and step_category for CATEGORICAL data points
- step_datetime for DATETIME data points
You may optionally supply the type column for mixed data points:
- type
type (ixmp4.data.iamc.datapoint.type.Type or str, optional) – Will be set as the type for all provided data points. Accepted string values: "ANNUAL", "CATEGORICAL", "DATETIME" (case-insensitive).

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held. Acquire one with with run.transact("message"):.

remove(df: DataFrame, type: Type | str | None = None) → None

Removes IAMC data matching a data frame from a run.

Requires an active run lock — use with run.transact("message"): to acquire one before calling this method.

import pandas as pd

remove_df = pd.DataFrame({
    "region": ["World"],
    "variable": ["Emissions|CO2"],
    "unit": ["MtCO2/yr"],
    "year": [2020],
})

with run.transact("remove emissions data"):
    run.iamc.remove(remove_df, type="ANNUAL")

Parameters:

df (pandas.DataFrame) –
A data frame with the columns:
- region
- variable
- unit
Any combination of:
- step_year for ANNUAL data points
- step_year and step_category for CATEGORICAL data points
- step_datetime for DATETIME data points
You may optionally supply the type column for mixed data points:
- type
type (ixmp4.data.iamc.datapoint.type.Type or str, optional) – Will be set as the type for all provided data points. Accepted string values: "ANNUAL", "CATEGORICAL", "DATETIME" (case-insensitive).

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held. Acquire one with with run.transact("message"):.

tabulate(raw: bool = False, **kwargs: Unpack[FacadeDataPointFilter]) → DataFrame

Tabulates datapoints by specified criteria.

df = run.iamc.tabulate()
#>    region    unit       variable        year  value
# 0  World    MtCO2/yr   Emissions|CO2     2020  36.5

Parameters:

**kwargs (any) – Filter parameters as specified in FacadeDataPointFilter.

Returns:

A data frame with the columns:

region
unit
variable
year
category
datetime
type

Return type:

pandas.DataFrame

IAMC Variables

class ixmp4.core.iamc.variable.VariableServiceFacade(backend: Backend)

create(name: str) → Variable

Creates a variable.

platform.iamc.variables.create("Emissions|CO2")
#> <Variable 1 name='Emissions|CO2'>

Parameters:: name (str) – The name of the variable.
Raises:: VariableNotUnique – If the variable with name is not unique.
Returns:: The created variable.
Return type:: ixmp4.core.iamc.variable.Variable

delete(ref: Variable | int | str) → None

Deletes a variable.

platform.iamc.variables.delete("Emissions|CO2")

Parameters:

ref (Variable | int | str) – Variable object, variable id or variable name.

Raises:

VariableNotFound – If no variable matching ref exists.
VariableDeletionPrevented – If the variable matching ref is used in the database, preventing its deletion.

get_by_name(name: str) → Variable

Retrieves a variable by its name.

platform.iamc.variables.get_by_name("Emissions|CO2")
#> <Variable 1 name='Emissions|CO2'>

Parameters:: name (str) – The unique name of the variable.
Raises:: VariableNotFound – If the variable with name does not exist.
Returns:: The retrieved variable.
Return type:: ixmp4.core.iamc.variable.Variable

list(**kwargs: Unpack[FacadeVariableFilter]) → List[Variable]

Lists variables by specified criteria.

platform.iamc.variables.list()
#> [<Variable 1 name='Emissions|CO2'>]

Parameters:: **kwargs (any) – Filter parameters as specified in VariableFilter.
Returns:: List of variables.
Return type:: list[ixmp4.data.iamc.variable.dto.Variable]

tabulate(**kwargs: Unpack[FacadeVariableFilter]) → DataFrame

Tabulates variables by specified criteria.

platform.iamc.variables.tabulate()
#>     name  id
# 0  Emissions|CO2   1

Parameters:

**kwargs (any) – Filter parameters as specified in VariableFilter.

Returns:

A data frame with the columns:

id
name

Return type:

pandas.DataFrame

class ixmp4.core.iamc.variable.Variable(backend: Backend, dto: DtoT)

Filter: alias of FacadeVariableFilter

NotFound: alias of VariableNotFound

NotUnique: alias of VariableNotUnique

DeletionPrevented: alias of VariableDeletionPrevented

docs: DocsDescriptor[VariableService, Variable]: IAMC Variable docs.

property id: int: Unique id.

property name: str: Variable name.

delete() → None: Deletes the variable from the database.

IAMC Data Points

class ixmp4.core.iamc.datapoint.DataPoint

class Type(*values)

Filter: alias of FacadeDataPointFilter

NotFound: alias of DataPointNotFound

NotUnique: alias of DataPointNotUnique

DeletionPrevented: alias of DataPointDeletionPrevented