Abstract Interface

Subpackages

Submodules

ixmp4.data.abstract.base module

class ixmp4.data.abstract.base.BaseMeta(name, bases, namespace, /, **kwargs)

Bases: _ProtocolMeta

class ixmp4.data.abstract.base.BaseModel(*args, **kwargs)

Bases: Protocol

DeletionPrevented

alias of BaseModelDeletionPrevented

NotFound

alias of BaseModelNotFound

NotUnique

alias of BaseModelNotUnique

id: Mapped[int]

Unique integer id.

class ixmp4.data.abstract.base.BaseRepository(*args, **kwargs)

Bases: Protocol

class ixmp4.data.abstract.base.BulkDeleter(*args, **kwargs)

Bases: BaseRepository, Protocol

bulk_delete(*args, **kwargs) → None
class ixmp4.data.abstract.base.BulkUpserter(*args, **kwargs)

Bases: BaseRepository, Protocol

bulk_upsert(*args, **kwargs) → None
class ixmp4.data.abstract.base.Creator(*args, **kwargs)

Bases: BaseRepository, Protocol

create(*args, **kwargs) → BaseModel
class ixmp4.data.abstract.base.Deleter(*args, **kwargs)

Bases: BaseRepository, Protocol

delete(*args, **kwargs) → None
class ixmp4.data.abstract.base.Enumerator(*args, **kwargs)

Bases: Lister, Tabulator, Protocol

enumerate(*args, table: bool = False, **kwargs) → list | DataFrame
class ixmp4.data.abstract.base.Lister(*args, **kwargs)

Bases: BaseRepository, Protocol

list(*args, **kwargs) → list
class ixmp4.data.abstract.base.Retriever(*args, **kwargs)

Bases: BaseRepository, Protocol

get(*args, **kwargs) → BaseModel
class ixmp4.data.abstract.base.Tabulator(*args, **kwargs)

Bases: BaseRepository, Protocol

tabulate(*args, **kwargs) → DataFrame

ixmp4.data.abstract.meta module

class ixmp4.data.abstract.meta.RunMetaEntry(*args, **kwargs)

Bases: BaseModel, Protocol

Run meta entry model.

DeletionPrevented

alias of RunMetaEntryDeletionPrevented

NotFound

alias of RunMetaEntryNotFound

NotUnique

alias of RunMetaEntryNotUnique

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

Bases: str, Enum

BOOL = 'BOOL'
FLOAT = 'FLOAT'
INT = 'INT'
STR = 'STR'
classmethod from_pytype(type_)
key: Mapped[str]

Key for the entry. Unique for each run__id.

run__id: Mapped[int]

Foreign unique integer id of a run.

type: Mapped[str]

Datatype of the entry’s value.

value: Mapped[int] | Mapped[float] | Mapped[bool]

Value of the entry.

class ixmp4.data.abstract.meta.RunMetaEntryRepository(*args, **kwargs)

Bases: Creator, Retriever, Deleter, Enumerator, BulkUpserter, BulkDeleter, Protocol

bulk_delete(df: DataFrame) → None

Deletes run meta indicator entries as specified per dataframe. Warning: No recovery of deleted data shall be possible via ixmp after the execution of this function.

Parameters

dfpandas.DataFrame
A data frame with the columns:

  • run__id

  • key

bulk_upsert(df: DataFrame) → None

Upserts a dataframe of run meta indicator entries.

Parameters

dfpandas.DataFrame
A data frame with the columns:

  • run__id

  • key

  • value

  • type

create(run__id: int, key: str, value: bool | int | float | str) → RunMetaEntry

Creates a meta indicator entry for a run.

Parameters

run__idstr

The unique integer id of a run.

keystr

The key of the entry.

valuestr, int, bool or float

The value of the entry.

Raises

ixmp4.core.exceptions.RunMetaEntryNotUnique:

If the entry with run__id and key is not unique.

Returns

ixmp4.data.base.RunMetaEntry:

The created entry.

delete(id: int) → None

Deletes a run’s meta indicator entry. Warning: No recovery of deleted data shall be possible via ixmp after the execution of this function.

Parameters

idint

The unique integer ids of entries to delete.

Raises

ixmp4.data.abstract.RunMetaEntry.NotFound:

If the entry with id does not exist.

get(run__id: int, key: str) → RunMetaEntry

Retrieves a run’s meta indicator entry.

Parameters

run__idstr

The unique integer id of a run.

keystr

The key of the entry.

Raises

ixmp4.data.abstract.RunMetaEntry.NotFound:

If the entry with run__id and key does not exist.

Returns

ixmp4.data.base.Run:

The retrieved entry.

list(**kwargs) → list[RunMetaEntry]

Lists run’s meta indicator entries by specified criteria.

Parameters

**kwargs: any

Filter parameters as specified in ixmp4.data.db.meta.filter.RunMetaEntryFilter.

Returns

Iterable[ixmp4.data.abstract.RunMetaEntry]:

List of run meta indicator entries.

tabulate(join_run_index: bool = False, **kwargs) → DataFrame

Tabulates run’s meta indicator entries by specified criteria.

Parameters

**kwargs: any

Filter parameters as specified in ixmp4.data.db.meta.filter.RunMetaEntryFilter.

Returns

pandas.DataFrame:
A data frame with the columns:

  • id

  • run__id

  • key

  • type

  • value

ixmp4.data.abstract.model module

class ixmp4.data.abstract.model.Model(*args, **kwargs)

Bases: BaseModel, Protocol

Data model of an assement modeling “model”. Unfortunately two naming conventions clash here.

DeletionPrevented

alias of ModelDeletionPrevented

NotFound

alias of ModelNotFound

NotUnique

alias of ModelNotUnique

created_at: Mapped[datetime]

Creation date/time. TODO

created_by: Mapped[str]

Creator. TODO

name: Mapped[str]

Unique name of the model.

class ixmp4.data.abstract.model.ModelRepository(*args, **kwargs)

Bases: Creator, Retriever, Enumerator, Protocol

create(name: str) → Model

Creates a model.

Parameters

namestr

The name of the model.

Raises

ixmp4.core.exceptions.ModelNotUnique:

If the model with name is not unique.

Returns

ixmp4.data.abstract.Model:

The created model.

docs: DocsRepository
get(name: str) → Model

Retrieves a model.

Parameters

namestr

The unique name of the model.

Raises

ixmp4.data.abstract.Model.NotFound:

If the model with name does not exist.

Returns

ixmp4.data.abstract.Model:

The retrieved model.

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

Lists models by specified criteria.

Parameters

namestr

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

Returns

Iterable[ixmp4.data.abstract.Model]:

List of Model.

map(*args, **kwargs) → dict

Return a mapping of model-id to model-name.

Returns

dict:

A dictionary id -> name

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

Tabulate models by specified criteria.

Parameters

namestr

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

Returns

pandas.DataFrame:
A data frame with the columns:

  • id

  • name

ixmp4.data.abstract.region module

class ixmp4.data.abstract.region.Region(*args, **kwargs)

Bases: BaseModel, Protocol

Region data model.

DeletionPrevented

alias of RegionDeletionPrevented

NotFound

alias of RegionNotFound

NotUnique

alias of RegionNotUnique

created_at: Mapped[datetime]

Creation date/time. TODO

created_by: Mapped[str]

Creator. TODO

hierarchy: Mapped[str]

Region hierarchy.

name: Mapped[str]

Unique name of the region.

class ixmp4.data.abstract.region.RegionRepository(*args, **kwargs)

Bases: Creator, Deleter, Retriever, Enumerator, Protocol

create(name: str, hierarchy: str) → Region

Creates a region.

Parameters

namestr

The name of the region.

hierarchystr

The hierarchy this region is assigned to.

Raises

ixmp4.data.abstract.Region.NotUnique:

If the region with name is not unique.

Returns

ixmp4.ata.base.iamc.Region:

The created region.

delete(id: int)

Deletes a region.

Parameters

idint

The unique integer id of the region.

Raises

ixmp4.data.abstract.Region.NotFound:

If the region with id does not exist.

ixmp4.data.abstract.Region.DeletionPrevented:

If the region with id is used in the database, preventing it’s deletion.

docs: DocsRepository
get(name: str) → Region

Retrieves a region.

Parameters

namestr

The unique name of the region.

Raises

ixmp4.data.abstract.Region.NotFound:

If the region with name does not exist.

Returns

ixmp4.data.base.iamc.Region:

The retrieved region.

get_or_create(name: str, hierarchy: str | None = None) → Region
list(*, name: str | None = None, hierarchy: str | None = None, **kwargs) → list[Region]

Lists regions by specified criteria.

Parameters

namestr

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

hierarchystr

The hierarchy of a region.

**kwargs: any

More filter parameters as specified in ixmp4.data.db.region.filters.RegionFilter.

Returns

Iterable[ixmp4.data.abstract.Region]:

List of regions.

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

Tabulate regions by specified criteria.

Parameters

namestr

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

hierarchystr

The hierarchy of a region.

**kwargs: any

More filter parameters as specified in ixmp4.data.db.region.filters.RegionFilter.

Returns

pandas.DataFrame:
A data frame with the columns:

  • id

  • name

ixmp4.data.abstract.run module

class ixmp4.data.abstract.run.Run(*args, **kwargs)

Bases: BaseModel, Protocol

Model run data model.

DeletionPrevented

alias of RunDeletionPrevented

NoDefaultVersion

alias of NoDefaultRunVersion

NotFound

alias of RunNotFound

NotUnique

alias of RunNotUnique

is_default: Mapped[bool]

True if this is the default run version.

model: Mapped

Associated model.

model__id: Mapped[int]

Foreign unique integer id of the model.

scenario: Mapped

Associated scenario.

scenario__id: Mapped[int]

Foreign unique integer id of the scenario.

version: Mapped[int]

Run version.

class ixmp4.data.abstract.run.RunRepository(*args, **kwargs)

Bases: Creator, Retriever, Enumerator, Protocol

create(model_name: str, scenario_name: str) → Run

Creates a run with an incremented version number or version=1 if no versions exist. Will automatically create the models and scenarios if they don’t exist yet.

Parameters

model_namestr

The name of a model.

scenario_namestr

The name of a scenario.

Returns

ixmp4.data.abstract.Run:

The created run.

get(model_name: str, scenario_name: str, version: int) → Run

Retrieves a run.

Parameters

model_namestr

The name of a model.

scenario_namestr

The name of a scenario.

versionint

The version number of this run.

Raises

ixmp4.data.abstract.Run.NotFound:

If the run with model_name, scenario_name and version does not exist.

Returns

ixmp4.data.abstract.Run:

The retrieved run.

get_default_version(model_name: str, scenario_name: str) → Run

Retrieves a run’s default version.

Parameters

model_namestr

The name of a model.

scenario_namestr

The name of a scenario.

Raises

ixmp4.core.exceptions.NoDefaultRunVersion:

If no runs with model_name, scenario_name and is_default=True exist.

Returns

ixmp4.data.abstract.Run:

The retrieved run.

get_or_create(model_name: str, scenario_name: str) → Run

Tries to retrieve a run’s default version and creates it if it was not found.

Parameters

model_namestr

The name of a model.

scenario_namestr

The name of a scenario.

Returns

ixmp4.data.abstract.Run:

The retrieved or created run.

list(*, version: int | None = None, **kwargs) → list[Run]

Lists runs by specified criteria.

Parameters

versionint

The run’s version.

default_onlybool

True by default. This function will return default runs only if true.

**kwargs: any

More filter parameters as specified in ixmp4.data.db.run.filters.RunFilter.

Returns

Iterable[ixmp4.data.abstract.Run]:

List of runs.

set_as_default_version(id: int) → None

Sets a run as the default version for a (model, scenario) combination.

Parameters

idint

Unique integer id.

Raises

ixmp4.data.abstract.Run.NotFound:

If no run with the id exists.

tabulate(*, version: int | None = None, **kwargs) → DataFrame

Tabulate runs by specified criteria.

Parameters

versionint

The run’s version.

default_onlybool

True by default. This function will return default runs only if true.

**kwargs: any

More filter parameters as specified in ixmp4.data.db.run.filters.RunFilter.

Returns

pandas.DataFrame:
A data frame with the columns:

  • id

  • model__id

  • scenario__id

unset_as_default_version(id: int) → None

Unsets a run as the default version leaving no default version for a (model, scenario) combination.

Parameters

idint

Unique integer id.

Raises

ixmp4.data.abstract.Run.NotFound:

If no run with the id exists.

ixmp4.core.exceptions.IxmpError:

If the run is not set as a default version.

ixmp4.data.abstract.scenario module

class ixmp4.data.abstract.scenario.Scenario(*args, **kwargs)

Bases: BaseModel, Protocol

Modeling scenario data model.

DeletionPrevented

alias of ScenarioDeletionPrevented

NotFound

alias of ScenarioNotFound

NotUnique

alias of ScenarioNotUnique

created_at: Mapped[datetime]

Creation date/time. TODO

created_by: Mapped[str]

Creator. TODO

name: Mapped[str]

Unique name of the scenario.

class ixmp4.data.abstract.scenario.ScenarioRepository(*args, **kwargs)

Bases: Creator, Retriever, Enumerator, Protocol

create(name: str) → Scenario

Creates a scenario.

Parameters

namestr

The name of the scenario.

Raises

ixmp4.core.exceptions.ScenarioNotUnique:

If the scenario with name is not unique.

Returns

ixmp4.data.abstract.Scenario:

The created scenario.

docs: DocsRepository
get(name: str) → Scenario

Retrieves a scenario.

Parameters

namestr

The unique name of the scenario.

Raises

ixmp4.data.abstract.Scenario.NotFound:

If the scenario with name does not exist.

Returns

ixmp4.data.abstract.Scenario:

The retrieved scenario.

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

Lists scenarios by specified criteria.

Parameters

namestr

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

Returns

Iterable[ixmp4.data.abstract.Scenario]:

List of scenarios.

map(*args, **kwargs) → dict

Return a mapping of scenario-id to scenario-name.

Returns

dict

A dictionary id -> name

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

Tabulate scenarios by specified criteria.

Parameters

namestr

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

Returns

pandas.DataFrame:
A data frame with the columns:

  • id

  • name

ixmp4.data.abstract.unit module

class ixmp4.data.abstract.unit.Unit(*args, **kwargs)

Bases: BaseModel, Protocol

Unit data model.

DeletionPrevented

alias of UnitDeletionPrevented

NotFound

alias of UnitNotFound

NotUnique

alias of UnitNotUnique

created_at: Mapped[datetime]

Creation date/time. TODO

created_by: Mapped[str]

Creator. TODO

name: Mapped[str]

Unique name of the unit.

class ixmp4.data.abstract.unit.UnitRepository(*args, **kwargs)

Bases: Creator, Deleter, Retriever, Enumerator, Protocol

create(name: str) → Unit

Creates a unit.

Parameters

namestr

The name of the model.

Raises

ixmp4.core.exceptions.UnitNotUnique:

If the unit with name is not unique.

Returns

ixmp4.data.abstract.Unit:

The created unit.

delete(id: int)

Deletes a unit.

Parameters

idint

The unique integer id of the unit.

Raises

ixmp4.data.abstract.Unit.NotFound:

If the unit with id does not exist.

ixmp4.data.abstract.Unit.DeletionPrevented:

If the unit with id is used in the database, preventing it’s deletion.

docs: DocsRepository
get(name: str) → Unit

Retrieves a unit.

Parameters

namestr

The unique name of the unit.

Raises

ixmp4.data.abstract.Unit.NotFound:

If the unit with name does not exist.

Returns

ixmp4.data.abstract.Unit:

The retrieved unit.

get_by_id(id: int) → Unit

Retrieves a Unit by it’s id.

Parameters

idint

Unique integer id.

Raises

ixmp4.data.abstract.Unit.NotFound.

If the Unit with id does not exist.

Returns

ixmp4.data.abstract.Unit:

The retrieved Unit.

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

Lists units by specified criteria.

Parameters

namestr

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

**kwargs: any

More filter parameters as specified in ixmp4.data.db.unit.filters.UnitFilter.

Returns

Iterable[ixmp4.data.base.iamc.Unit]:

List of units.

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

Tabulate units by specified criteria.

Parameters

namestr

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

**kwargs: any

More filter parameters as specified in ixmp4.data.db.unit.filters.UnitFilter.

Returns

pandas.DataFrame:
A data frame with the columns:pass

  • id

  • name

Module contents

This module holds a shared datastructure and interface for normalization between the database and api data models and repositories.