Abstract IAMC Data Interface

Submodules

ixmp4.data.abstract.iamc.datapoint module

class ixmp4.data.abstract.iamc.datapoint.DataPoint(*args, **kwargs)

Bases: BaseModel, Protocol

Data point data model.

DeletionPrevented

alias of DataPointDeletionPrevented

NotFound

alias of DataPointNotFound

NotUnique

alias of DataPointNotUnique

class Type(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

ANNUAL = 'ANNUAL'

BASE = 'BASE'

CATEGORICAL = 'CATEGORICAL'

DATETIME = 'DATETIME'

step_category: Mapped[str] | None

A string category required by data points of type CATEGORICAL.

step_datetime: Mapped[datetime] | None

A datetime object required by data points of type DATETIME.

step_year: Mapped[int] | None

An integer time step required by data points of type ANNUAL or CATEGORICAL.

time_series__id: Mapped[int]

Foreign unique integer id of the associated time series.

type: Mapped[str]

Type of data point either ANNUAL, CATEGORICAL or DATETIME.

value: Mapped[float]

Value of the data point.

class ixmp4.data.abstract.iamc.datapoint.DataPointRepository(*args, **kwargs)

Bases: Enumerator, BulkUpserter, BulkDeleter, Protocol

bulk_delete(df: DataFrame, **kwargs) → None

Deletes data points which match criteria in the supplied data frame.

Parameters

dfpandas.DataFrame

A data frame with the columns:

• time_series__id

• type

• step_year

  if it contains data points of type ANNUAL or CATEGORICAL

• step_category

  if it contains data points of type CATEGORICAL

• step_datetime

  if it contains data points of type DATETIME

bulk_upsert(df: DataFrame, **kwargs) → None

Looks which data points in the supplied data frame already exists, updates those that have changed and inserts new ones.

Parameters

dfpandas.DataFrame

A data frame with the columns:

• time_series__id

• value

• type

• step_year

  if it contains data points of type ANNUAL or CATEGORICAL

• step_category

  if it contains data points of type CATEGORICAL

• step_datetime

  if it contains data points of type DATETIME

list(*, join_parameters: bool | None = False, **kwargs) → list[DataPoint]

Lists data points by specified criteria. This method incurrs mentionable overhead compared to tabulate().

Parameters

join_parametersbool | None

If set to True the resulting data frame will include parameter columns from the associated ixmp4.data.base.TimeSeries.

kwargsAny

Additional key word arguments. Any left over kwargs will be used as filters.

Returns

Iterable[ixmp4.data.base.DataPoint]:

List of data points.

tabulate(*, join_parameters: bool | None = False, join_runs: bool = False, **kwargs) → DataFrame

Tabulates data points by specified criteria.

Parameters

join_parametersbool | None

If set to True the resulting data frame will include parameter columns from the associated ixmp4.data.abstract.TimeSeries.

join_runsbool

If set to True the resulting data frame will include model & scenario name and version id of the associated Run.

kwargsAny

Additional key word arguments. Any left over kwargs will be used as filters.

Returns

pandas.DataFrame:

A data frame with the columns:

• id

• time_series__id

• value

• type

• step_year

  if it contains data points of type ANNUAL or CATEGORICAL

• step_category

  if it contains data points of type CATEGORICAL

• step_datetime

  if it contains data points of type DATETIME

• … misc parameter columns if join_parameters is set to True

ixmp4.data.abstract.iamc.measurand module

class ixmp4.data.abstract.iamc.measurand.Measurand(*args, **kwargs)

Bases: BaseModel, Protocol

Measurand data model.

DeletionPrevented

alias of MeasurandDeletionPrevented

NotFound

alias of MeasurandNotFound

NotUnique

alias of MeasurandNotUnique

unit: Mapped

Associated unit.

unit__id: Mapped[int]

Foreign unique integer id of a unit.

variable: Mapped

Associated variable.

variable__id: Mapped[int]

Foreign unique integer id of a variable.

class ixmp4.data.abstract.iamc.measurand.MeasurandRepository(*args, **kwargs)

Bases: Creator, Retriever, Enumerator, Protocol

create(variable_name: str, unit__id: int) → Measurand

get(variable_name: str, unit__id: int) → Measurand

get_or_create(variable_name: str, unit__id: int) → Measurand

list() → list[Measurand]

tabulate() → DataFrame

ixmp4.data.abstract.iamc.timeseries module

class ixmp4.data.abstract.iamc.timeseries.TimeSeries(*args, **kwargs)

Bases: BaseModel, Protocol

Time series data model.

DeletionPrevented

alias of TimeSeriesDeletionPrevented

NotFound

alias of TimeSeriesNotFound

NotUnique

alias of TimeSeriesNotUnique

parameters: Mapping

A set of parameter values for the time series.

run__id: Mapped[int]

Unique run id.

class ixmp4.data.abstract.iamc.timeseries.TimeSeriesRepository(*args, **kwargs)

Bases: Creator, Retriever, Enumerator, BulkUpserter, Protocol, Generic[ModelType]

bulk_upsert(df: DataFrame, create_related: bool | None = False) → None

Looks which time series in the supplied data frame already exist, and inserts new ones.

Parameters

dfpandas.DataFrame

A data frame with the columns:

• id

• run__id

if create_related = False:

• … parameter id columns

else:

• … parameter value columns (i.e region column with value “World” instead of region__id column with value “1”.)

create_relatedbool

Creates related database entries with value data supplied in df.

create(run_id: int, parameters: Mapping) → ModelType

Retrieves a time series.

Parameters

run_idint

Unique run id.

parametersMapping

A set of parameter values for the time series.

Raises

ixmp4.data.abstract.TimeSeries.NotUnique.

Returns

ixmp4.data.base.TimeSeries:

The retrieved time series.

get(run_id: int, parameters: Mapping) → ModelType

Retrieves a time series.

Parameters

run_idint

Unique run id.

parametersMapping

A set of parameter values for the time series.

Raises

ixmp4.data.abstract.TimeSeries.NotFound.

If the time series with run_id and parameters does not exist.

Returns

ixmp4.data.base.TimeSeries:

The retrieved time series.

get_by_id(id: int) → ModelType

Retrieves a time series by it’s id.

Parameters

idint

Unique integer id.

Raises

ixmp4.data.abstract.TimeSeries.NotFound.

If the time series with id does not exist.

Returns

ixmp4.data.base.TimeSeries:

The retrieved time series.

get_or_create(run_id: int, parameters: Mapping) → ModelType

Tries to retrieve a time series and creates it if it was not found.

Parameters

run_idint

Unique run id.

parametersMapping

A set of parameter values for the time series.

Returns

ixmp4.data.base.TimeSeries:

The retrieved or created time series.

list(**kwargs) → list[ModelType]

Lists time series by specified criteria.

Parameters

**kwargs: any Filter parameters as specified in ixmp4.data.db.iamc.timeseries.filter.TimeSeriesFilter.

Returns

Iterable[ixmp4.data.base.TimeSeries]:

List of time series.

tabulate(*, join_parameters: bool | None = False, **kwargs) → DataFrame

Tabulate time series by specified criteria.

Parameters

join_parametersbool | None

If set to True the resulting data frame will include parameter columns as values instead of foreign key id’s.

**kwargs: any

Filter parameters as specified in ixmp4.data.db.iamc.timeseries.filter.TimeSeriesFilter.

Returns

pandas.DataFrame:

A data frame with the columns:

• id

• run__id

• … parameter id columns Or:

• … parameter value columns

ixmp4.data.abstract.iamc.variable module

class ixmp4.data.abstract.iamc.variable.Variable(*args, **kwargs)

Bases: BaseModel, Protocol

Variable data model.

DeletionPrevented

alias of VariableDeletionPrevented

NotFound

alias of VariableNotFound

NotUnique

alias of VariableNotUnique

created_at: Mapped[datetime]

Creation date/time. TODO

created_by: Mapped[str]

Creator. TODO

name: Mapped[str]

Unique name of the variable.

class ixmp4.data.abstract.iamc.variable.VariableRepository(*args, **kwargs)

Bases: Creator, Retriever, Enumerator, Protocol

create(name: str) → Variable

Creates a variable.

Parameters

namestr

The name of the variable.

Raises

ixmp4.data.abstract.Variable.NotUnique:

If the variable with name is not unique.

Returns

ixmp4.data.abstract.Variable:

The created variable.

docs: DocsRepository

get(name: str) → Variable

Retrieves a variable.

Parameters

namestr

The unique name of the variable.

Raises

ixmp4.data.abstract.Variable.NotFound:

If the variable with name does not exist.

Returns

ixmp4.data.abstract.Variable:

The retrieved variable.

list(*, name: str | None = None, **kwargs) → list[Variable]

Lists variables by specified criteria.

Parameters

namestr

The name of a variable. If supplied only one result will be returned.

**kwargs: any

More filter parameters as specified in ixmp4.data.db.iamc.variable.filters.VariableFilter.

Returns

Iterable[ixmp4.data.abstract.Variable]:

List of variables.

tabulate(*, name: str | None = None, **kwargs) → DataFrame

Tabulate variables by specified criteria.

Parameters

namestr

The name of a variable. If supplied only one result will be returned.

**kwargs: any

More filter parameters as specified in ixmp4.data.db.iamc.variable.filters.VariableFilter.

Returns

pandas.DataFrame:

A data frame with the columns:

• id

• name

Module contents