Common Data Interface

Runs (ixmp4.data.run)

Data Transfer Object

class ixmp4.data.run.dto.Run(*, updated_at: datetime | None, updated_by: str | None, created_at: datetime | None, created_by: str | None, id: int, model__id: int, model: Model, scenario__id: int, scenario: Scenario, version: int, is_default: bool, lock_transaction: int | None)

Bases: BaseModel, HasCreationInfo, HasUpdateInfo

Model run data model.

model__id: int: Foreign unique integer id of the model.

model: Model: Associated model.

scenario__id: int: Foreign unique integer id of the scenario.

scenario: Scenario: Associated scenario.

model_config = {'from_attributes': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

version: int: Run version.

is_default: bool: True if this is the default run version.

lock_transaction: int | None

Service

class ixmp4.data.run.service.RunService(transport: Transport)

Bases: GetByIdService

router_prefix: ClassVar[str] = '/runs'

router_tags: ClassVar[Sequence[str]] = ['runs']

http_controller: alias of EnumerationCompatibilityController

executor: SessionExecutor

items: ItemRepository

pandas: PandasRepository

versions: VersionRepository

models: ItemRepository

scenarios: ItemRepository

transactions: TransactionRepository

meta: PandasRepository

meta_versions: VersionRepository

default_filter: RunFilter = {'default_only': True}

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_name (str) – The name of a model.
scenario_name (str) – The name of a scenario.

Returns:

The created run.

Return type:

ixmp4.data.run.dto.Run

create_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol, model_name: str, scenario_name: str) → None

delete_by_id(id: int) → None

Deletes a run and all associated iamc, optimization and meta data.

Parameters:: id (int) – The unique integer id of the run.
Raises:: RunNotFound – If the run with id does not exist.

delete_by_id_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

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

Retrieves a run.

Parameters:

model_name (str) – The name of a model.
scenario_name (str) – The name of a scenario.
version (int) – The version number of this run.

Raises:

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

Returns:

The retrieved run.

Return type:

ixmp4.data.run.dto.Run

get_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol, model_name: str, scenario_name: str, version: int) → None

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_name (str) – The name of a model.
scenario_name (str) – The name of a scenario.

Returns:

The retrieved or created run.

Return type:

ixmp4.data.run.dto.Run

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

Retrieves a run’s default version.

Parameters:

model_name (str) – The name of a model.
scenario_name (str) – The name of a scenario.

Raises:

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

Returns:

The retrieved run.

Return type:

ixmp4.data.run.dto.Run

get_default_version_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol, model_name: str, scenario_name: str) → None

get_by_id(id: int) → Run

Retrieves a Run by its id.

Parameters:: id (int) – Unique integer id.
Raises:: RunNotFound – If the Run with id does not exist.
Returns:: The retrieved Run.
Return type:: ixmp4.data.run.dto.Run

get_by_id_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

list(**kwargs: Unpack[RunFilter]) → List[Run]

Lists runs by specified criteria.

Parameters:: **kwargs (any) – Any filter parameters as specified in RunFilter.
Returns:: List of runs.
Return type:: list[ixmp4.data.run.dto.Run]

list_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

paginated_list(pagination: Pagination, **kwargs: Unpack[RunFilter]) → PaginatedResult[List[Run]]

get_columns(*, include_audit_info: bool, include_internal_columns: bool) → List[str]

tabulate(include_audit_info: bool = False, include_internal_columns: bool = False, **kwargs: Unpack[RunFilter]) → WithJsonSchema(json_schema={'properties': {'index': {'anyOf': [{'items': {'type': 'integer'}, 'type': 'array'}, {'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Index'}, 'columns': {'anyOf': [{'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Columns'}, 'dtypes': {'anyOf': [{'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Dtypes'}, 'data': {'anyOf': [{'items': {'items': {'anyOf': [{'type': 'boolean'}, {'type': 'integer'}, {'type': 'number'}, {'type': 'string'}, {'additionalProperties': True, 'type': 'object'}, {'items': {'type': 'number'}, 'type': 'array'}, {'items': {'type': 'integer'}, 'type': 'array'}, {'items': {'type': 'string'}, 'type': 'array'}, {'format': 'date-time', 'type': 'string'}, {'type': 'null'}]}, 'type': 'array'}, 'type': 'array'}, {'type': 'null'}], 'title': 'Data'}}, 'required': ['data'], 'title': 'DataFrameTypeAdapter', 'type': 'object'}, mode=serialization)]

Tabulate runs by specified criteria.

Parameters:

include_audit_info (bool) – Whether or not to include audit info columns in the data frame. Default: False
include_internal_columns (bool) – Whether or not to include internal database columns (model__id, scenario__id, lock_transaction). Default: False
**kwargs (any) – Any filter parameters as specified in RunFilter.

Returns:

A data frame with the columns:

id
model
scenario
version
is_default

and if include_internal_columns is True:

model__id
scenario__id
lock_transaction

and if include_audit_info is True:

created_by
created_at
updated_by
updated_at

Return type:

pandas.DataFrame

tabulate_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

paginated_tabulate(pagination: Pagination, include_audit_info: bool = False, include_internal_columns: bool = False, **kwargs: Unpack[RunFilter]) → PaginatedResult[Annotated[DataFrame, PlainValidator, PlainSerializer, WithJsonSchema]]

set_as_default_version(id: int) → None

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

Parameters:: id (int) – Unique integer id.
Raises:: RunNotFound – If no run with the id exists.

set_as_default_version_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol, id: int) → None

unset_as_default_version(id: int) → None

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

Parameters:: id (int) – Unique integer id.
Raises:: RunNotFound – If no run with the id exists.

unset_as_default_version_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol, id: int) → None

revert(id: int, transaction__id: int, revert_platform: bool = False) → None

Reverts run data to a specific transaction__id.

Parameters:

id (int) – Unique integer id.
transaction__id (int) – Id of the transaction to revert to.
revert_platform (bool, optional) – Whether to revert the units defined on the platform, too. Default False.

Raises:

RunNotFound – If no run with the id exists.

revert_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol, id: int, transaction__id: int, revert_platform: bool = False) → None

lock(id: int) → Run

Locks a run at the current transaction (via transaction__id).

Parameters:

id (int) – Unique integer id.

Raises:

RunNotFound – If no run with the id exists.
RunIsLocked – If the run is already locked.

lock_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol, id: int) → None

unlock(id: int) → Run

Locks a run at the current transaction (via transaction__id).

Parameters:: id (int) – Unique integer id.
Raises:: RunNotFound – If no run with the id exists.

unlock_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol, id: int) → None

Filters

class ixmp4.data.run.filter.IamcRunFilter

Bases: TypedDict

variable: InstrumentedAttribute object at 0x79d92787b380>)]

unit: InstrumentedAttribute object at 0x79d927827d80>)]

region: InstrumentedAttribute object at 0x79d927827ba0>)]

ixmp4.data.run.filter.filter_by_iamc(exc: Select | Update | Delete, value: dict[str, Any] | bool | None, *, schema: type[Any], repo: BaseRepository[Any]) → Select | Update | Delete

class ixmp4.data.run.filter.RunFilter

Bases: RunFilter

model: InstrumentedAttribute object at 0x79d927323420>]

scenario: InstrumentedAttribute object at 0x79d9273234c0>]

iamc: IamcRunFilter | bool | None, <function filter_by_iamc at 0x79d926f420c0>]

id: int

id__in: list[int]

version: int

version__in: list[int]

is_default: bool

default_only: Annotated[bool, <function filter_by_default_only at 0x79d926f42e80>]

class ixmp4.data.run.filter.FacadeRunFilter

Bases: RunFilter

model: ModelFilter | str | Iterable[str]

scenario: ScenarioFilter | str | Iterable[str]

iamc: IamcRunFilter | bool | None

id: int

id__in: list[int]

version: int

version__in: list[int]

is_default: bool

default_only: Annotated[bool, <function filter_by_default_only at 0x79d926f42e80>]

ixmp4.data.run.filter.facade_to_data_filter(filter_values: Mapping[str, Any]) → RunFilter

Models (ixmp4.data.model)

Data Transfer Object

class ixmp4.data.model.dto.Model(*, created_at: datetime | None, created_by: str | None, id: int, name: str)

Bases: BaseModel, HasCreationInfo

The model.

name: str: Unique name of the model.

model_config = {'from_attributes': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Service

class ixmp4.data.model.service.ModelService(transport: Transport)

Bases: DocsService, GetByIdService

router_prefix: ClassVar[str] = '/models'

router_tags: ClassVar[Sequence[str]] = ['models']

http_controller: alias of EnumerationCompatibilityController

executor: SessionExecutor

items: ItemRepository

pandas: PandasRepository

versions: VersionRepository

create(name: str) → Model

Creates a model.

Parameters:: name (str) – The name of the model.
Raises:: ModelNotUnique – If the model with name is not unique.
Returns:: The created model.
Return type:: Model

create_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

delete_by_id(id: int) → None

Deletes a model.

Parameters:

id (int) – The unique integer id of the model.

Raises:

ModelNotFound – If the model with id does not exist.
ModelDeletionPrevented – If the model with id is used in the database, preventing it’s deletion.
Unauthorized – If the current user is not authorized to perform this action.

delete_by_id_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

get_by_name(name: str) → Model

Retrieves a model by its name.

Parameters:: name (str) – The unique name of the model.
Raises:: ModelNotFound – If the model with name does not exist.
Returns:: The retrieved model.
Return type:: ixmp4.data.model.dto.Model

get_by_name_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

get_by_id(id: int) → Model

Retrieves a model by its id.

Parameters:: id (int) – The integer id of the model.
Raises:: ixmp4.data.abstract.Model.NotFound – If the model with id does not exist.
Returns:: The retrieved model.
Return type:: ixmp4.data.model.dto.Model

get_by_id_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

list(**kwargs: Unpack[ModelFilter]) → List[Model]

Lists models by specified criteria.

Parameters:: **kwargs (any) – Filter parameters as specified in ModelFilter.
Returns:: List of models.
Return type:: list[ixmp4.data.model.dto.Model]

list_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

paginated_list(pagination: Pagination, **kwargs: Unpack[ModelFilter]) → PaginatedResult[List[Model]]

tabulate(**kwargs: Unpack[ModelFilter]) → WithJsonSchema(json_schema={'properties': {'index': {'anyOf': [{'items': {'type': 'integer'}, 'type': 'array'}, {'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Index'}, 'columns': {'anyOf': [{'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Columns'}, 'dtypes': {'anyOf': [{'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Dtypes'}, 'data': {'anyOf': [{'items': {'items': {'anyOf': [{'type': 'boolean'}, {'type': 'integer'}, {'type': 'number'}, {'type': 'string'}, {'additionalProperties': True, 'type': 'object'}, {'items': {'type': 'number'}, 'type': 'array'}, {'items': {'type': 'integer'}, 'type': 'array'}, {'items': {'type': 'string'}, 'type': 'array'}, {'format': 'date-time', 'type': 'string'}, {'type': 'null'}]}, 'type': 'array'}, 'type': 'array'}, {'type': 'null'}], 'title': 'Data'}}, 'required': ['data'], 'title': 'DataFrameTypeAdapter', 'type': 'object'}, mode=serialization)]

Tabulates models by specified criteria.

Parameters:

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

Returns:

A data frame with the columns:

id
name

Return type:

pandas.DataFrame

tabulate_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

paginated_tabulate(pagination: Pagination, **kwargs: Unpack[ModelFilter]) → PaginatedResult[Annotated[DataFrame, PlainValidator, PlainSerializer, WithJsonSchema]]

Filters

class ixmp4.data.model.filter.IamcModelFilter

Bases: ModelFilter

variable: InstrumentedAttribute object at 0x79d927827ce0>)]

unit: InstrumentedAttribute object at 0x79d927827d80>)]

region: InstrumentedAttribute object at 0x79d927827ba0>)]

run: InstrumentedAttribute object at 0x79d927827b00>)]

id: int

id__in: list[int]

name: str

name__in: list[str]

name__like: str

name__ilike: str

name__notlike: str

name__notilike: str

ixmp4.data.model.filter.filter_by_iamc(exc: Select | Update | Delete, value: dict[str, Any] | bool | None, *, schema: type[Any], repo: BaseRepository[Any]) → Select | Update | Delete

class ixmp4.data.model.filter.ModelFilter

Bases: ModelFilter

iamc: IamcModelFilter | bool | None, <function filter_by_iamc at 0x79d925afeca0>]

id: int

id__in: list[int]

name: str

name__in: list[str]

name__like: str

name__ilike: str

name__notlike: str

name__notilike: str

class ixmp4.data.model.filter.FacadeIamcModelFilter

Bases: ModelFilter

variable: VariableFilter

unit: UnitFilter

region: RegionFilter

run: FacadeRunFilter

id: int

id__in: list[int]

name: str

name__in: list[str]

name__like: str

name__ilike: str

name__notlike: str

name__notilike: str

ixmp4.data.model.filter.iamc_facade_to_data_filter(filter_values: Mapping[str, Any]) → IamcModelFilter

class ixmp4.data.model.filter.FacadeModelFilter

Bases: ModelFilter

iamc: FacadeIamcModelFilter | bool | None

id: int

id__in: list[int]

name: str

name__in: list[str]

name__like: str

name__ilike: str

name__notlike: str

name__notilike: str

ixmp4.data.model.filter.facade_to_data_filter(filter_values: Mapping[str, Any]) → ModelFilter

Scenarios (ixmp4.data.scenario)

Data Transfer Object

class ixmp4.data.scenario.dto.Scenario(*, created_at: datetime | None, created_by: str | None, id: int, name: str)

Bases: BaseModel, HasCreationInfo

Modeling scenario data model.

name: str: Unique name of the scenario.

model_config = {'from_attributes': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Service

class ixmp4.data.scenario.service.ScenarioService(transport: Transport)

Bases: DocsService, GetByIdService

router_prefix: ClassVar[str] = '/scenarios'

router_tags: ClassVar[Sequence[str]] = ['scenarios']

http_controller: alias of EnumerationCompatibilityController

executor: SessionExecutor

items: ItemRepository

pandas: PandasRepository

versions: VersionRepository

create(name: str) → Scenario

Creates a scenario.

Parameters:: name (str) – The name of the scenario.
Raises:: ScenarioNotUnique – If the scenario with name is not unique.
Returns:: The created scenario.
Return type:: Scenario

create_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol, name: str) → None

delete_by_id(id: int) → None

Deletes a scenario.

Parameters:

id (int) – The unique integer id of the scenario.

Raises:

ScenarioNotFound – If the scenario with id does not exist.
ScenarioDeletionPrevented – If the scenario with id is used in the database, preventing it’s deletion.
Unauthorized – If the current user is not authorized to perform this action.

delete_by_id_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

get_by_name(name: str) → Scenario

Retrieves a scenario by its name.

Parameters:: name (str) – The unique name of the scenario.
Raises:: ScenarioNotFound – If the scenario with name does not exist.
Returns:: The retrieved scenario.
Return type:: ixmp4.data.base.iamc.Scenario

get_by_name_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol, name: str) → None

get_by_id(id: int) → Scenario

Retrieves a scenario by its id.

Parameters:: id (int) – The integer id of the scenario.
Raises:: ixmp4.data.abstract.Scenario.NotFound – If the scenario with id does not exist.
Returns:: The retrieved scenario.
Return type:: ixmp4.data.base.iamc.Scenario

get_by_id_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol, id: int) → None

list(**kwargs: Unpack[ScenarioFilter]) → List[Scenario]

Lists scenarios by specified criteria.

Parameters:: **kwargs (any) – Filter parameters as specified in ScenarioFilter.
Returns:: List of scenarios.
Return type:: list[ixmp4.data.scenario.dto.Scenario]

list_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

paginated_list(pagination: Pagination, **kwargs: Unpack[ScenarioFilter]) → PaginatedResult[List[Scenario]]

tabulate(**kwargs: Unpack[ScenarioFilter]) → WithJsonSchema(json_schema={'properties': {'index': {'anyOf': [{'items': {'type': 'integer'}, 'type': 'array'}, {'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Index'}, 'columns': {'anyOf': [{'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Columns'}, 'dtypes': {'anyOf': [{'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Dtypes'}, 'data': {'anyOf': [{'items': {'items': {'anyOf': [{'type': 'boolean'}, {'type': 'integer'}, {'type': 'number'}, {'type': 'string'}, {'additionalProperties': True, 'type': 'object'}, {'items': {'type': 'number'}, 'type': 'array'}, {'items': {'type': 'integer'}, 'type': 'array'}, {'items': {'type': 'string'}, 'type': 'array'}, {'format': 'date-time', 'type': 'string'}, {'type': 'null'}]}, 'type': 'array'}, 'type': 'array'}, {'type': 'null'}], 'title': 'Data'}}, 'required': ['data'], 'title': 'DataFrameTypeAdapter', 'type': 'object'}, mode=serialization)]

Tabulates scenarios by specified criteria.

Parameters:

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

Returns:

A data frame with the columns:

id
name

Return type:

pandas.DataFrame

tabulate_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

paginated_tabulate(pagination: Pagination, **kwargs: Unpack[ScenarioFilter]) → PaginatedResult[Annotated[DataFrame, PlainValidator, PlainSerializer, WithJsonSchema]]

Filters

class ixmp4.data.scenario.filter.IamcScenarioFilter

Bases: ScenarioFilter

variable: InstrumentedAttribute object at 0x79d927827ce0>)]

unit: InstrumentedAttribute object at 0x79d927827d80>)]

region: InstrumentedAttribute object at 0x79d927827ba0>)]

run: InstrumentedAttribute object at 0x79d927827b00>)]

id: int

id__in: list[int]

name: str

name__in: list[str]

name__like: str

name__ilike: str

name__notlike: str

name__notilike: str

ixmp4.data.scenario.filter.filter_by_iamc(exc: Select | Update | Delete, value: dict[str, Any] | bool | None, *, schema: type[Any], repo: BaseRepository[Any]) → Select | Update | Delete

class ixmp4.data.scenario.filter.ScenarioFilter

Bases: ScenarioFilter

iamc: IamcScenarioFilter | bool | None, <function filter_by_iamc at 0x79d9259ea8e0>]

id: int

id__in: list[int]

name: str

name__in: list[str]

name__like: str

name__ilike: str

name__notlike: str

name__notilike: str

class ixmp4.data.scenario.filter.FacadeIamcScenarioFilter

Bases: ScenarioFilter

variable: VariableFilter

unit: UnitFilter

region: RegionFilter

run: FacadeRunFilter

id: int

id__in: list[int]

name: str

name__in: list[str]

name__like: str

name__ilike: str

name__notlike: str

name__notilike: str

ixmp4.data.scenario.filter.iamc_facade_to_data_filter(filter_values: Mapping[str, Any]) → IamcScenarioFilter

class ixmp4.data.scenario.filter.FacadeScenarioFilter

Bases: ScenarioFilter

iamc: FacadeIamcScenarioFilter | bool | None

id: int

id__in: list[int]

name: str

name__in: list[str]

name__like: str

name__ilike: str

name__notlike: str

name__notilike: str

ixmp4.data.scenario.filter.facade_to_data_filter(filter_values: Mapping[str, Any]) → ScenarioFilter

Run Meta Indicators (ixmp4.data.meta)

Data Transfer Object

Bases: BaseModel

Run meta entry model.

run__id: int: Foreign unique integer id of a run.

key: str: Key for the entry. Unique for each run__id.

dtype: Type: Datatype of the entry’s value.

value: bool | float | int | str: Value of the entry.

value_int: int | None

model_config = {'from_attributes': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

value_str: str | None

value_float: float | None

value_bool: bool | None

Service

class ixmp4.data.meta.service.RunMetaEntryService(transport: Transport)

Bases: Service

router_prefix: ClassVar[str] = '/meta'

router_tags: ClassVar[Sequence[str]] = ['meta']

http_controller: alias of EnumerationCompatibilityController

executor: SessionExecutor

items: ItemRepository

pandas: PandasRepository

runs: ItemRepository

runs_pandas: PandasRepository

default_filter: RunMetaEntryFilter = {'run': {'default_only': True}}

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

Creates a metadata entry.

Parameters:

run_id (int) – The id of the ixmp4.data.run.dto.Run for which this entry is defined.
key (str) – The key (unique to this run) for which value is associated.
value (MetaValueType) – The value for this entry.

Raises:

RunMetaEntryNotUnique – If the metadata entry with key and run__id is not unique.

Returns:

The created metadata entry.

Return type:

RunMetaEntry

create_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol, run_id: int, key: str, value: bool | float | int | str) → None

get(run_id: int, key: str) → RunMetaEntry

Retrieves a metadata entry by the run id and key.

Parameters:

run_id (int) – The id of the ixmp4.data.run.dto.Run for which this entry is defined.
key (str) – The key (unique to this run) for which value is to be retrieved.

Raises:

RunMetaEntryNotFound – If the metadata entry with id does not exist.

Returns:

The retrieved metadata entry.

Return type:

RunMetaEntry

get_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol, run_id: int, key: str) → None

delete_by_id(id: int) → None

Deletes a metadata entry.

Parameters:: id (int) – Unique integer id of the entry to delete
Raises:: RunMetaEntryNotFound – If the metadata entry with id was not found.

delete_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol, id: int) → None

list(**kwargs: Unpack[RunMetaEntryFilter]) → list[RunMetaEntry]

Lists metadata entries by specified criteria.

Parameters:: **kwargs (any) – Filter parameters as specified in RunMetaEntryFilter.
Returns:: List of metadata entries.
Return type:: Iterable[RunMetaEntry]

list_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

paginated_list(pagination: Pagination, **kwargs: Unpack[RunMetaEntryFilter]) → PaginatedResult[List[RunMetaEntry]]

get_columns(*, join_run_index: bool | None, include_run_index: bool) → List[str]

tabulate(include_run_index: bool = False, join_run_index: bool | None = None, **kwargs: Unpack[RunMetaEntryFilter]) → WithJsonSchema(json_schema={'properties': {'index': {'anyOf': [{'items': {'type': 'integer'}, 'type': 'array'}, {'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Index'}, 'columns': {'anyOf': [{'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Columns'}, 'dtypes': {'anyOf': [{'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Dtypes'}, 'data': {'anyOf': [{'items': {'items': {'anyOf': [{'type': 'boolean'}, {'type': 'integer'}, {'type': 'number'}, {'type': 'string'}, {'additionalProperties': True, 'type': 'object'}, {'items': {'type': 'number'}, 'type': 'array'}, {'items': {'type': 'integer'}, 'type': 'array'}, {'items': {'type': 'string'}, 'type': 'array'}, {'format': 'date-time', 'type': 'string'}, {'type': 'null'}]}, 'type': 'array'}, 'type': 'array'}, {'type': 'null'}], 'title': 'Data'}}, 'required': ['data'], 'title': 'DataFrameTypeAdapter', 'type': 'object'}, mode=serialization)]

Tabulates metadata entries by specified criteria.

Parameters:

include_run_index (bool, optional) – Whether to include run columns in the data frame. Default: False
**kwargs (any) – Filter parameters as specified in RunMetaEntryFilter.

Returns:

A data frame with the columns:

id
dtype
key
value

if include_run_index is False (default):

run__id

if include_run_index is True:

model
scenario
version

Return type:

pandas.DataFrame

tabulate_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

paginated_tabulate(pagination: Pagination, include_run_index: bool = False, join_run_index: bool | None = None, **kwargs: Unpack[RunMetaEntryFilter]) → PaginatedResult[Annotated[DataFrame, PlainValidator, PlainSerializer, WithJsonSchema]]

bulk_upsert(df: WithJsonSchema(json_schema={'properties': {'index': {'anyOf': [{'items': {'type': 'integer'}, 'type': 'array'}, {'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Index'}, 'columns': {'anyOf': [{'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Columns'}, 'dtypes': {'anyOf': [{'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Dtypes'}, 'data': {'anyOf': [{'items': {'items': {'anyOf': [{'type': 'boolean'}, {'type': 'integer'}, {'type': 'number'}, {'type': 'string'}, {'additionalProperties': True, 'type': 'object'}, {'items': {'type': 'number'}, 'type': 'array'}, {'items': {'type': 'integer'}, 'type': 'array'}, {'items': {'type': 'string'}, 'type': 'array'}, {'format': 'date-time', 'type': 'string'}, {'type': 'null'}]}, 'type': 'array'}, 'type': 'array'}, {'type': 'null'}], 'title': 'Data'}}, 'required': ['data'], 'title': 'DataFrameTypeAdapter', 'type': 'object'}, mode=serialization)]) → None

Upserts a dataframe of run meta indicator entries.

Parameters:

df (pandas.DataFrame) –

A data frame with the columns:

run__id
key
value

bulk_upsert_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol, df: WithJsonSchema(json_schema={'properties': {'index': {'anyOf': [{'items': {'type': 'integer'}, 'type': 'array'}, {'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Index'}, 'columns': {'anyOf': [{'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Columns'}, 'dtypes': {'anyOf': [{'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Dtypes'}, 'data': {'anyOf': [{'items': {'items': {'anyOf': [{'type': 'boolean'}, {'type': 'integer'}, {'type': 'number'}, {'type': 'string'}, {'additionalProperties': True, 'type': 'object'}, {'items': {'type': 'number'}, 'type': 'array'}, {'items': {'type': 'integer'}, 'type': 'array'}, {'items': {'type': 'string'}, 'type': 'array'}, {'format': 'date-time', 'type': 'string'}, {'type': 'null'}]}, 'type': 'array'}, 'type': 'array'}, {'type': 'null'}], 'title': 'Data'}}, 'required': ['data'], 'title': 'DataFrameTypeAdapter', 'type': 'object'}, mode=serialization)]) → None

bulk_delete(df: WithJsonSchema(json_schema={'properties': {'index': {'anyOf': [{'items': {'type': 'integer'}, 'type': 'array'}, {'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Index'}, 'columns': {'anyOf': [{'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Columns'}, 'dtypes': {'anyOf': [{'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Dtypes'}, 'data': {'anyOf': [{'items': {'items': {'anyOf': [{'type': 'boolean'}, {'type': 'integer'}, {'type': 'number'}, {'type': 'string'}, {'additionalProperties': True, 'type': 'object'}, {'items': {'type': 'number'}, 'type': 'array'}, {'items': {'type': 'integer'}, 'type': 'array'}, {'items': {'type': 'string'}, 'type': 'array'}, {'format': 'date-time', 'type': 'string'}, {'type': 'null'}]}, 'type': 'array'}, 'type': 'array'}, {'type': 'null'}], 'title': 'Data'}}, 'required': ['data'], 'title': 'DataFrameTypeAdapter', 'type': 'object'}, mode=serialization)]) → 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:

df (pandas.DataFrame) –

A data frame with the columns:

run__id
key

bulk_delete_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol, df: WithJsonSchema(json_schema={'properties': {'index': {'anyOf': [{'items': {'type': 'integer'}, 'type': 'array'}, {'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Index'}, 'columns': {'anyOf': [{'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Columns'}, 'dtypes': {'anyOf': [{'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Dtypes'}, 'data': {'anyOf': [{'items': {'items': {'anyOf': [{'type': 'boolean'}, {'type': 'integer'}, {'type': 'number'}, {'type': 'string'}, {'additionalProperties': True, 'type': 'object'}, {'items': {'type': 'number'}, 'type': 'array'}, {'items': {'type': 'integer'}, 'type': 'array'}, {'items': {'type': 'string'}, 'type': 'array'}, {'format': 'date-time', 'type': 'string'}, {'type': 'null'}]}, 'type': 'array'}, 'type': 'array'}, {'type': 'null'}], 'title': 'Data'}}, 'required': ['data'], 'title': 'DataFrameTypeAdapter', 'type': 'object'}, mode=serialization)]) → None

Filters

class ixmp4.data.meta.filter.RunFilter

Bases: RunFilter

model: InstrumentedAttribute object at 0x79d927323420>]

scenario: InstrumentedAttribute object at 0x79d9273234c0>]

id: int

id__in: list[int]

version: int

version__in: list[int]

is_default: bool

default_only: Annotated[bool, <function filter_by_default_only at 0x79d926f42e80>]

class ixmp4.data.meta.filter.RunMetaEntryFilter

Bases: RunMetaEntryFilter

run: InstrumentedAttribute object at 0x79d927446660>]

id: int

id__in: list[int]

key: str

key__in: list[str]

key__like: str

key__ilike: str

key__notlike: str

key__notilike: str

run__id: int

run__id__in: list[int]

dtype: str

dtype__in: list[str]

class ixmp4.data.meta.filter.FacadeRunMetaEntryFilter

Bases: RunMetaEntryFilter

run: FacadeRunFilter

id: int

id__in: list[int]

key: str

key__in: list[str]

key__like: str

key__ilike: str

key__notlike: str

key__notilike: str

run__id: int

run__id__in: list[int]

dtype: str

dtype__in: list[str]

ixmp4.data.meta.filter.facade_to_data_filter(filter_values: Mapping[str, Any]) → RunMetaEntryFilter

Regions (ixmp4.data.region)

Data Transfer Object

class ixmp4.data.region.dto.Region(*, created_at: datetime | None, created_by: str | None, id: int, name: str, hierarchy: str)

Bases: BaseModel, HasCreationInfo

Region data model.

name: str: Unique name of the region.

model_config = {'from_attributes': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

hierarchy: str: Region hierarchy.

Service

class ixmp4.data.region.service.RegionService(transport: Transport)

Bases: DocsService, GetByIdService

router_prefix: ClassVar[str] = '/regions'

router_tags: ClassVar[Sequence[str]] = ['regions']

http_controller: alias of EnumerationCompatibilityController

executor: SessionExecutor

items: ItemRepository

pandas: PandasRepository

versions: VersionRepository

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

Creates a region.

Parameters:

name (str) – The name of the region.
hierarchy (str) – The hierarchy this region is assigned to.

Raises:

RegionNotUnique – If the region with name is not unique.
Unauthorized – If the current user is not authorized to perform this action.

Returns:

The created region.

Return type:

Region

create_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

delete_by_id(id: int) → None

Deletes a region.

Parameters:

id (int) – The unique integer id of the region.

Raises:

RegionNotFound – If the region with id does not exist.
RegionDeletionPrevented – If the region with id is used in the database, preventing it’s deletion.
Unauthorized – If the current user is not authorized to perform this action.

delete_by_id_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

get_by_name(name: str) → Region

Retrieves a region by its name.

Parameters:

name (str) – The unique name of the region.

Raises:

RegionNotFound – If the region with name does not exist.
Unauthorized – If the current user is not authorized to perform this action.

Returns:

The retrieved region.

Return type:

Region

get_by_name_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

get_by_id(id: int) → Region

Retrieves a region by its id.

Parameters:

id (int) – The integer id of the region.

Raises:

RegionNotFound – If the region with id does not exist.
Unauthorized – If the current user is not authorized to perform this action.

Returns:

The retrieved region.

Return type:

Region

get_by_id_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

get_or_create(name: str, hierarchy: str | None = None) → Region

list(**kwargs: Unpack[RegionFilter]) → List[Region]

Lists regions by specified criteria.

Parameters:: **kwargs (any) – Filter parameters as specified in RegionFilter.
Raises:: Unauthorized – If the current user is not authorized to perform this action.
Returns:: List of regions.
Return type:: list[ixmp4.data.region.dto.Region]

list_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

paginated_list(pagination: Pagination, **kwargs: Unpack[RegionFilter]) → PaginatedResult[List[Region]]

tabulate(**kwargs: Unpack[RegionFilter]) → WithJsonSchema(json_schema={'properties': {'index': {'anyOf': [{'items': {'type': 'integer'}, 'type': 'array'}, {'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Index'}, 'columns': {'anyOf': [{'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Columns'}, 'dtypes': {'anyOf': [{'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Dtypes'}, 'data': {'anyOf': [{'items': {'items': {'anyOf': [{'type': 'boolean'}, {'type': 'integer'}, {'type': 'number'}, {'type': 'string'}, {'additionalProperties': True, 'type': 'object'}, {'items': {'type': 'number'}, 'type': 'array'}, {'items': {'type': 'integer'}, 'type': 'array'}, {'items': {'type': 'string'}, 'type': 'array'}, {'format': 'date-time', 'type': 'string'}, {'type': 'null'}]}, 'type': 'array'}, 'type': 'array'}, {'type': 'null'}], 'title': 'Data'}}, 'required': ['data'], 'title': 'DataFrameTypeAdapter', 'type': 'object'}, mode=serialization)]

Tabulates regions by specified criteria.

Parameters:

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

Returns:

A data frame with the columns:

id
name
hierarchy

Return type:

pandas.DataFrame

tabulate_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

paginated_tabulate(pagination: Pagination, **kwargs: Unpack[RegionFilter]) → PaginatedResult[Annotated[DataFrame, PlainValidator, PlainSerializer, WithJsonSchema]]

Filters

class ixmp4.data.region.filter.IamcRegionFilter

Bases: RegionFilter

variable: InstrumentedAttribute object at 0x79d927827ce0>)]

unit: InstrumentedAttribute object at 0x79d927827d80>)]

run: InstrumentedAttribute object at 0x79d927827b00>)]

id: int

id__in: list[int]

name: str

name__in: list[str]

name__like: str

name__ilike: str

name__notlike: str

name__notilike: str

hierarchy: str

hierarchy__in: list[str]

hierarchy__like: str

hierarchy__ilike: str

hierarchy__notlike: str

hierarchy__notilike: str

ixmp4.data.region.filter.filter_by_iamc(exc: Select | Update | Delete, value: dict[str, Any] | bool | None, *, schema: type[Any], repo: BaseRepository[Any]) → Select | Update | Delete

class ixmp4.data.region.filter.RegionFilter

Bases: RegionFilter

iamc: IamcRegionFilter | bool | None, <function filter_by_iamc at 0x79d92597ed40>]

id: int

id__in: list[int]

name: str

name__in: list[str]

name__like: str

name__ilike: str

name__notlike: str

name__notilike: str

hierarchy: str

hierarchy__in: list[str]

hierarchy__like: str

hierarchy__ilike: str

hierarchy__notlike: str

hierarchy__notilike: str

class ixmp4.data.region.filter.FacadeIamcRegionFilter

Bases: RegionFilter

variable: VariableFilter

unit: UnitFilter

run: FacadeRunFilter

id: int

id__in: list[int]

name: str

name__in: list[str]

name__like: str

name__ilike: str

name__notlike: str

name__notilike: str

hierarchy: str

hierarchy__in: list[str]

hierarchy__like: str

hierarchy__ilike: str

hierarchy__notlike: str

hierarchy__notilike: str

ixmp4.data.region.filter.iamc_facade_to_data_filter(filter_values: Mapping[str, Any]) → IamcRegionFilter

class ixmp4.data.region.filter.FacadeRegionFilter

Bases: RegionFilter

iamc: FacadeIamcRegionFilter | bool | None

id: int

id__in: list[int]

name: str

name__in: list[str]

name__like: str

name__ilike: str

name__notlike: str

name__notilike: str

hierarchy: str

hierarchy__in: list[str]

hierarchy__like: str

hierarchy__ilike: str

hierarchy__notlike: str

hierarchy__notilike: str

ixmp4.data.region.filter.facade_to_data_filter(filter_values: Mapping[str, Any]) → RegionFilter

Units (ixmp4.data.unit)

Data Transfer Object

class ixmp4.data.unit.dto.Unit(*, created_at: datetime | None, created_by: str | None, id: int, name: str)

Bases: BaseModel, HasCreationInfo

Unit data model.

name: str: Unique name of the unit.

model_config = {'from_attributes': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Service

class ixmp4.data.unit.service.UnitService(transport: Transport)

Bases: DocsService, GetByIdService

router_prefix: ClassVar[str] = '/units'

router_tags: ClassVar[Sequence[str]] = ['units']

http_controller: alias of EnumerationCompatibilityController

executor: SessionExecutor

items: ItemRepository

pandas: PandasRepository

versions: VersionRepository

create(name: str) → Unit

Creates a unit.

Parameters:: name (str) – The name of the model.
Raises:: UnitNotUnique – If the unit with name is not unique.
Returns:: The created unit.
Return type:: ixmp4.data.unit.dto.Unit

create_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

delete_by_id(id: int) → None

Deletes a unit.

Parameters:

id (int) – The unique integer id of the unit.

Raises:

UnitNotFound – If the unit with id does not exist.
UnitDeletionPrevented – If the unit with id is used in the database, preventing it’s deletion.

delete_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

get_by_name(name: str) → Unit

Retrieves a unit by its name.

Parameters:: name (str) – The unique name of the unit.
Raises:: UnitNotFound – If the unit with name does not exist.
Returns:: The retrieved unit.
Return type:: ixmp4.data.base.iamc.Unit

get_by_name_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

get_by_id(id: int) → Unit

Retrieves a unit by its id.

Parameters:: id (int) – The integer id of the unit.
Raises:: ixmp4.data.abstract.Unit.NotFound – If the unit with id does not exist.
Returns:: The retrieved unit.
Return type:: ixmp4.data.base.iamc.Unit

get_by_id_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

get_or_create(name: str) → Unit

list(**kwargs: Unpack[UnitFilter]) → List[Unit]

Lists units by specified criteria.

Parameters:: **kwargs (any) – Filter parameters as specified in UnitFilter.
Returns:: List of units.
Return type:: list[ixmp4.data.unit.dto.Unit]

list_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

paginated_list(pagination: Pagination, **kwargs: Unpack[UnitFilter]) → PaginatedResult[List[Unit]]

tabulate(**kwargs: Unpack[UnitFilter]) → WithJsonSchema(json_schema={'properties': {'index': {'anyOf': [{'items': {'type': 'integer'}, 'type': 'array'}, {'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Index'}, 'columns': {'anyOf': [{'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Columns'}, 'dtypes': {'anyOf': [{'items': {'type': 'string'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'title': 'Dtypes'}, 'data': {'anyOf': [{'items': {'items': {'anyOf': [{'type': 'boolean'}, {'type': 'integer'}, {'type': 'number'}, {'type': 'string'}, {'additionalProperties': True, 'type': 'object'}, {'items': {'type': 'number'}, 'type': 'array'}, {'items': {'type': 'integer'}, 'type': 'array'}, {'items': {'type': 'string'}, 'type': 'array'}, {'format': 'date-time', 'type': 'string'}, {'type': 'null'}]}, 'type': 'array'}, 'type': 'array'}, {'type': 'null'}], 'title': 'Data'}}, 'required': ['data'], 'title': 'DataFrameTypeAdapter', 'type': 'object'}, mode=serialization)]

Tabulates units by specified criteria.

Parameters:

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

Returns:

A data frame with the columns:

id
name

Return type:

pandas.DataFrame

tabulate_auth_check(auth_ctx: AuthorizationContext, platform: PlatformProtocol) → None

paginated_tabulate(pagination: Pagination, **kwargs: Unpack[UnitFilter]) → PaginatedResult[Annotated[DataFrame, PlainValidator, PlainSerializer, WithJsonSchema]]

Filters

class ixmp4.data.unit.filter.IamcUnitFilter

Bases: UnitFilter

variable: InstrumentedAttribute object at 0x79d927827ce0>)]

region: InstrumentedAttribute object at 0x79d927827ba0>)]

run: InstrumentedAttribute object at 0x79d927827b00>)]

id: int

id__in: list[int]

name: str

name__in: list[str]

name__like: str

name__ilike: str

name__notlike: str

name__notilike: str

ixmp4.data.unit.filter.filter_by_iamc(exc: Select | Update | Delete, value: dict[str, Any] | bool | None, *, schema: type[Any], repo: BaseRepository[Any]) → Select | Update | Delete