Codelists, hierarchies and value lists

Model for SDMX Codes and Codelists.

Two different types of collections are provided:

Codelist: A flat structure, i.e. a structure where all codes are at the same level. In SDMX terms, this structure can be fed from information stored as a codelist or a value list.
Hierarchy: A structure where codes can be organized in a hierarchical fashion, like a list of country groups and their respective countries.

This is an example of what is meant with pysdmx being opinionated. While SDMX allows two different types of hierarchies (simple hierarchies expressed as codelists, and more complex hierarchies expressed as SDMX hierarchies), pysdmx expects codelists and value lists to be flat (which seems to be the vast majority of the cases), thereby leaving the representation of hierarchical relationships to hierarchies only.

class pysdmx.model.code.Code(id: str, name: str | None = None, description: str | None = None, valid_from: datetime | None = None, valid_to: datetime | None = None)

A code, such as a country code in the list of ISO 3166 codes.

Codes may have business validity information.

id: The identifier for the code (e.g. UY).

name: The code’s name (e.g. Uruguay).

description: Additional descriptive information about the code.

valid_from: Start of the code’s validity period.

valid_to: End of the code’s validity period.

class pysdmx.model.code.Codelist(id: str, name: str, agency: str, description: str | None = None, version: str = '1.0', codes: Sequence[Code] = (), sdmx_type: Literal['codelist', 'valuelist'] = 'codelist')

An immutable collection of codes, such as the ISO 3166 country codes.

A codelist is maintained by its agency, typically, an organisation like the BIS, the ECB, the IMF, etc.

A codelist has an identifier and a name. It may also have a description and business validity information.

A codelist is iterable, i.e. it can be used as is in a for loop.

A codelist represents a flat list of codes, without any hierarchical relationship between them. Both SDMX codelists and SDMX value lists are represented as a Codelist class.

id: The identifier for the codelist (e.g. CL_FREQ).

name: The codelist name (e.g. “Frequency codelist”).

agency: The maintainer of the codelist (e.g. SDMX).

description: Additional descriptive information about the codelist (e.g. “This codelist provides a set of values indicating the frequency of the data”).

version: The codelist version (e.g. 2.0.42)

codes: The list of codes in the codelist.

class pysdmx.model.code.HierarchicalCode(id: str, name: str | None = None, description: str | None = None, valid_from: datetime | None = None, valid_to: datetime | None = None, rel_valid_from: datetime | None = None, rel_valid_to: datetime | None = None, codes: Sequence[HierarchicalCode] = ())

A code, as used in a hierarchy.

Hierachical codes may contain other codes.

As codes, hierarchial codes may have business validity information. In addition, they may also have business validity associated with their relationship in the hierarchy.

For example, let’s imagine a hierarchy representing country groups. A country might have a valid_from property, with the date that country declared its independence. In addition, it may also have a rel_valid_from property, with the date the country joined that particular group (e.g. European Union).

id: The identifier for the code (e.g. UY).

name: The code’s name (e.g. Uruguay).

description: Additional descriptive information about the code.

valid_from: Start of the code’s validity period.

valid_to: End of the code’s validity period.

rel_valid_from: Start of the hierarchical relationship validity.

rel_valid_to: End of the hierarchical relationship validity.

codes: The child codes.

class pysdmx.model.code.Hierarchy(id: str, name: str, agency: str, description: str | None = None, version: str = '1.0', codes: Sequence[HierarchicalCode] = (), operator: str | None = None)

An immutable collection of codes, organized hierarchically.

A hierarchy is maintained by its agency, typically, an organisation like the BIS, the ECB, the IMF, etc.

A hierarchy has an identifier and a name. It may also have a description and business validity information.

A hierarchy is iterable, i.e. it can be used as is in a for loop.

id: The identifier for the hierarchy (e.g. AREA).

name: The hierarchy name (e.g. “Country groups and their composition”).

agency: The maintainer of the hierarchy (e.g. SDMX).

description: Additional descriptive information about the hierarchy (e.g. “This hierarchy provides a set of country groups and their respective composition”).

version: The hierarchy version (e.g. 2.0.42)

codes: The list of codes in the hierarchy.

operator: The URN of the operator to be applied to the items of an hierarchy. This is mainly used for data validation or data compilation purposes. For example, Let’s assume a hierarchy with a top level code (A), with 2 child codes (B and C). And let’s assume that the operator property references a VTL operator representing a sum. This can then be used for validation purposes, to check that A = B + C.

all_codes()

Get all the codes in the hierarchy as a flat list.

This is useful for validation purposes. The sequence behaves as a set, i.e. even if a code is attached to multiple nodes, it will be available only once in the returned sequence.

Return type:: Sequence[HierarchicalCode]
Returns:: A flat list of the codes present in the hierarchy.

by_id(id)

Get a code without knowing its parent IDs.

Codes in a hierarchy can be retrieved using their full ID, i.e. the code ID, as well as the IDs of their parents in the hierarchy, separated by dots (e.g. 1.11.111).

This function can be used when you just know the code ID, and not the ID of its parents.

Parameters:: id (str) – The ID of the code to be returned.
Return type:: Sequence[HierarchicalCode]
Returns:: A set with the matching codes. If there is no matching code, the set will be empty. If a code is attached to multiple parents, it will be returned only once. As hierarchies can reference codes from multiple codelists, we could have different codes with the same ID in the returned set.