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: Any, **kwargs: Any)

Bases: Enumerator, BulkUpserter, BulkDeleter, Protocol

bulk_delete(df: DataFrame) → 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) → 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, join_runs: bool = False, **kwargs: Unpack[EnumerateKwargs]) → 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 list will include parameter columns from the associated ixmp4.data.abstract.iamc.timeseries.TimeSeries.

join_runsbool

If set to True the resulting list 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

Iterable[ixmp4.data.abstract.iamc.datapoint.DataPoint]:

List of data points.

tabulate(*, join_parameters: bool | None = False, join_runs: bool = False, **kwargs: Unpack[EnumerateKwargs]) → 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.iamc.timeseries.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

class ixmp4.data.abstract.iamc.datapoint.EnumerateKwargs

Bases: TypedDict

model: dict[str, str | Iterable[str]] | None

region: dict[str, str | Iterable[str]] | None

run: dict[str, bool | int | Iterable[int]]

scenario: dict[str, str | Iterable[str]] | None

step_year: int | None

step_year__gt: int

step_year__gte: int

step_year__in: Iterable[int]

step_year__lt: int

step_year__lte: int

time_series__id: int | None

time_series__id__gt: int

time_series__id__gte: int

time_series__id__in: Iterable[int]

time_series__id__lt: int

time_series__id__lte: int

time_series_id: int | None

time_series_id__gt: int

time_series_id__gte: int

time_series_id__in: Iterable[int]

time_series_id__lt: int

time_series_id__lte: int

unit: dict[str, str | Iterable[str]] | None

variable: dict[str, str | Iterable[str]] | None

year: int | None

year__gt: int

year__gte: int

year__in: Iterable[int]

year__lt: int

year__lte: int

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[Unit]

Associated unit.

unit__id: Mapped[int]

Foreign unique integer id of a unit.

variable: Mapped[Variable]

Associated variable.

variable__id: Mapped[int]

Foreign unique integer id of a variable.

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

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.EnumerateKwargs

Bases: HasIdFilter

id: int

id__in: Iterable[int]

region: HasRegionFilter

run: HasRunFilter

unit: HasUnitFilter

variable: HasVariableFilter

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[str, Any]

A set of parameter values for the time series.

run__id: Mapped[int]

Unique run id.

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

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(**kwargs: Unpack[CreateKwargs]) → ModelType

Retrieves a time series.

Parameters

run__idint

Unique run id.

parametersMapping[str, Any]

A set of parameter values for the time series.

Raises

ixmp4.data.abstract.iamc.timeseries.TimeSeries.NotUnique.

Returns

ixmp4.data.abstract.iamc.timeseries.TimeSeries:

The retrieved time series.

get(run_id: int, parameters: Mapping[str, Any]) → ModelType

Retrieves a time series.

Parameters

run_idint

Unique run id.

parametersMapping[str, Any]

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[str, Any]) → ModelType

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

Parameters

run_idint

Unique run id.

parametersMapping[str, Any]

A set of parameter values for the time series.

Returns

ixmp4.data.base.TimeSeries:

The retrieved or created time series.

list(**kwargs: Unpack[EnumerateKwargs]) → 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: Unpack[EnumerateKwargs]) → 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.EnumerateKwargs

Bases: HasIdFilter, HasNameFilter

id: int

id__in: Iterable[int]

name: str | None

name__ilike: str

name__in: Iterable[str]

name__like: str

name__notilike: str

name__notlike: str

region: HasRegionFilter

run: HasRunFilter

unit: HasUnitFilter

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: Any, **kwargs: Any)

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(**kwargs: Unpack[EnumerateKwargs]) → list[Variable]

Lists variables by specified criteria.

Parameters

**kwargs: any

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

Returns

Iterable[ixmp4.data.abstract.Variable]:

List of variables.

tabulate(**kwargs: Unpack[EnumerateKwargs]) → DataFrame

Tabulate variables by specified criteria.

Parameters

**kwargs: any

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

Returns

pandas.DataFrame:

A data frame with the columns:

• id

• name

Module contents