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

Bases: Protocol

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

Bases: BaseRepository, Protocol

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

Bases: BaseRepository, Protocol

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

Bases: BaseRepository, Protocol

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

Bases: BaseRepository, Protocol

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

Bases: Lister, Tabulator, Protocol

enumerate(table: bool = False, **kwargs: Unpack[EnumerateKwargs]) → Sequence[BaseModel] | DataFrame
class ixmp4.data.abstract.base.Lister(*args: Any, **kwargs: Any)

Bases: BaseRepository, Protocol

list(*args: Any, **kwargs: Any) → Sequence[BaseModel]
class ixmp4.data.abstract.base.Retriever(*args: Any, **kwargs: Any)

Bases: BaseRepository, Protocol

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

Bases: BaseRepository, Protocol

tabulate(*args: Any, **kwargs: Any) → DataFrame

ixmp4.data.abstract.meta module

class ixmp4.data.abstract.meta.EnumerateKwargs

Bases: HasIdFilter, HasRunIdFilter

dtype: str
dtype__ilike: str
dtype__in: Iterable[str]
dtype__like: str
dtype__notilike: str
dtype__notlike: str
id: int
id__in: Iterable[int]
key: str
key__ilike: str
key__in: Iterable[str]
key__like: str
key__notilike: str
key__notlike: str
run: HasRunFilter
run__id: int | None
run__id__gt: int
run__id__gte: int
run__id__in: Iterable[int]
run__id__lt: int
run__id__lte: int
run_id: int | None
run_id__gt: int
run_id__gte: int
run_id__in: Iterable[int]
run_id__lt: int
run_id__lte: int
value_bool: bool
value_float: float
value_float_id__gt: float
value_float_id__gte: float
value_float_id__in: Iterable[float]
value_float_id__lt: float
value_float_id__lte: float
value_int: int
value_int_id__gt: int
value_int_id__gte: int
value_int_id__in: Iterable[int]
value_int_id__lt: int
value_int_id__lte: int
value_str: str
value_str__ilike: str
value_str__in: Iterable[str]
value_str__like: str
value_str__notilike: str
value_str__notlike: str
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_: type) → str
dtype: Mapped[str]

Datatype of the entry’s value.

key: Mapped[str]

Key for the entry. Unique for each run__id.

run__id: Mapped[int]

Foreign unique integer id of a run.

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

Value of the entry.

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

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(join_run_index: bool = False, **kwargs: Unpack[EnumerateKwargs]) → list[RunMetaEntry]

Lists run’s meta indicator entries by specified criteria.

Parameters

join_run_index: bool, optional

Default False.

**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: Unpack[EnumerateKwargs]) → DataFrame

Tabulates run’s meta indicator entries by specified criteria.

Parameters

join_run_index: bool, optional

Default False.

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

Bases: HasIdFilter, HasNameFilter

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

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

Lists models by specified criteria.

Parameters

**kwargs: any

Any filter parameters as specified in ixmp4.data.db.model.filter.ModelFilter.

Returns

Iterable[ixmp4.data.abstract.Model]:

List of Model.

map(**kwargs: Unpack[EnumerateKwargs]) → dict[int, str]

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

Returns

dict:

A dictionary id -> name

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

Tabulate models by specified criteria.

Parameters

**kwargs: any

Any filter parameters as specified in ixmp4.data.db.model.filter.ModelFilter.

Returns

pandas.DataFrame:
A data frame with the columns:

  • id

  • name

ixmp4.data.abstract.region module

class ixmp4.data.abstract.region.EnumerateKwargs

Bases: HasHierarchyFilter, HasIdFilter, HasNameFilter

hierarchy: str | None
hierarchy__ilike: str
hierarchy__in: Iterable[str]
hierarchy__like: str
hierarchy__notilike: str
hierarchy__notlike: str
iamc: IamcRegionFilter | bool | None
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
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: Any, **kwargs: Any)

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) → None

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

Lists regions by specified criteria.

Parameters

**kwargs: any

Any filter parameters as specified in ixmp4.data.db.region.filter.RegionFilter.

Returns

Iterable[ixmp4.data.abstract.Region]:

List of regions.

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

Tabulate regions by specified criteria.

Parameters

**kwargs: any

Any filter parameters as specified in ixmp4.data.db.region.filter.RegionFilter.

Returns

pandas.DataFrame:
A data frame with the columns:

  • id

  • name

ixmp4.data.abstract.run module

class ixmp4.data.abstract.run.EnumerateKwargs

Bases: HasRunFilter

default_only: bool
iamc: IamcRunFilter | bool | None
id: int
id__in: Iterable[int]
is_default: bool | None
model: HasModelFilter | None
scenario: HasScenarioFilter | None
version: int | None
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[Model]

Associated model.

model__id: Mapped[int]

Foreign unique integer id of the model.

scenario: Mapped[Scenario]

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

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

Lists runs by specified criteria.

Parameters

**kwargs: any

Any filter parameters as specified in ixmp4.data.db.run.filter.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(**kwargs: Unpack[EnumerateKwargs]) → DataFrame

Tabulate runs by specified criteria.

Parameters

**kwargs: any

Any filter parameters as specified in ixmp4.data.db.run.filter.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.EnumerateKwargs

Bases: HasIdFilter, HasNameFilter

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

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

Lists scenarios by specified criteria.

Parameters

**kwargs: any

Any filter parameters as specified in ixmp4.data.db.scenario.filter.ScenarioFilter.

Returns

Iterable[ixmp4.data.abstract.Scenario]:

List of scenarios.

map(**kwargs: Unpack[EnumerateKwargs]) → dict[int, str]

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

Returns

dict

A dictionary id -> name

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

Tabulate scenarios by specified criteria.

Parameters

**kwargs: any

Any filter parameters as specified in ixmp4.data.db.scenario.filter.ScenarioFilter.

Returns

pandas.DataFrame:
A data frame with the columns:

  • id

  • name

ixmp4.data.abstract.unit module

class ixmp4.data.abstract.unit.EnumerateKwargs

Bases: HasIdFilter, HasNameFilter

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

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) → None

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

Lists units by specified criteria.

Parameters

**kwargs: any

Any filter parameters as specified in ixmp4.data.db.unit.filter.UnitFilter.

Returns

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

List of units.

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

Tabulate units by specified criteria.

Parameters

**kwargs: any

Any filter parameters as specified in ixmp4.data.db.unit.filter.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.