Regions

class ixmp4.core.region.RegionServiceFacade(backend: Backend)

Used to manipulate regions on a platform.

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

Creates a region.

platform.regions.create("Region", "Hierarchy")
#> <Region 1 name='Region' hierarchy='Hierarchy'>

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:

ixmp4.core.region.Region

get_by_name(name: str) → Region

Retrieves a region by its name.

platform.regions.get_by_name("Region")
#> <Region 1 name='Region' hierarchy='Hierarchy'>

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:

ixmp4.core.region.Region

delete(ref: Region | int | str) → None

Deletes a region.

platform.regions.delete("Region")

Parameters:

ref (ixmp4.core.region.Region | int | str) – Region object, region id or region name.

Raises:

RegionNotFound – If no region matching ref exists.
RegionDeletionPrevented – If the region matching ref is used in the database, preventing its deletion.
Unauthorized – If the current user is not authorized to perform this action.

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

Lists regions by specified criteria.

platform.regions.list()
#> [<Region 1 name='Region' hierarchy='Hierarchy'>]

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.core.region.Region]

tabulate(**kwargs: Unpack[FacadeRegionFilter]) → DataFrame

Tabulates regions by specified criteria.

platform.regions.tabulate()
#>     name  hierarchy  id                 created_at created_by
# 0  Region  Hierarchy   1 2026-01-14 15:37:49.996256   @unknown

Parameters:

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

Returns:

A data frame with the columns: