Mapping definitions

Note

Additional information about how mapping definitions can be used to drive mapping processes is available in the following tutorial:

Map Your Data.

Model for Mapping Definitions.

class pysdmx.model.map.ComponentMap(source: str, target: str, values: RepresentationMap)

Maps a source component to a target component.

Examples

For example, let’s assume that we want to map the country code from an ISO 2-letter country code to an ISO 3-letter country code. This can be expressed as follows:

>>> ar = ValueMap("AR", "ARG")
>>> uy = ValueMap("UY", "URY")
>>> cm = ComponentMap("COUNTRY", "COUNTRY", [ar, uy])

source: The source component

target: The target component

values: The representation map, with the list of mapped values (one in the source and one in the target)

class pysdmx.model.map.DatePatternMap(source: str, target: str, pattern: str, frequency: str, id: str | None = None, locale: str = 'en', pattern_type: Literal['fixed', 'variable'] = 'fixed')

A mapping based on a date pattern.

Examples

For example, let’s assume a component in the source, with ID DATE, and containing string values such as Sep 23. In the target, we want this to be mapped to the TIME_PERIOD component, with ISO 8601 periods for monthly data (e.g. 2023-09). This can be expressed with the following mapping:

>>> DatePatternMap("DATE", "TIME_PERIOD", "MMM yy", "M")

source: The ID of the source component.

target: The ID of the target component.

pattern: Describes the source date using conventions for describing years, months, days, etc

frequency: The frequency to convert the input date into or a reference to a dimension or an atttribute with the frequency code. See pattern_type below for additional information.

id: The Map ID, as defined in the Registry.

locale: The locale on which the input will be parsed according to the pattern.

pattern_type: The type of date pattern, i.e. fixed or variable. When the type is fixed, frequency is a fixed value from the frequency codelist (e.g. A for annual frequency). When the type is variable, frequency references a dimension or attribute in the target structure (e.g. FREQ). In this case, the input date can be converted to a different format, depending on the frequency of the converted data.

class pysdmx.model.map.FixedValueMap(target: str, value: Any, located_in: Literal['source', 'target'] = 'target')

Set a component to a fixed value.

Examples

For example, let’s assume that all observations in the target must be treated as free for publication. This can be expressed with the following mapping:

>>> FixedValueMap("CONF_STATUS", "F")

target: The ID of the component to which the fixed value is assigned.

value: The fixed value of the referenced component.

located_in: Whether the component with a fixed value is in the source structure or the target structure. It usually is in the target structure (the default), but it can also be in the source, in case of bi-directional mapping.

class pysdmx.model.map.ImplicitComponentMap(source: str, target: str)

A mapping where the value in the source is copied to the target.

Examples

For example, let’s assume a component in the source (OBS_CONF), indicating the confidentiality of data, that we want to map as-is to a target component (CONF_STATUS). This can be expressed with the following mapping:

>>> ImplicitComponentMap("OBS_CONF", "CONF_STATUS")

source: The ID of the source component to be mapped, from which we want to copy the value.

target: The ID of the target component.

class pysdmx.model.map.MultiComponentMap(source: Sequence[str], target: Sequence[str], values: MultiRepresentationMap)

Maps one or more source components to one or more target components.

Examples

For example, let’s assume that we want to map the the code for local currency (say LC) to an ISO 3-letter currency code, depending on the country. So, if the country is DE (Germany), then the currency in the target should be EUR but, if the country is CH, then it should be CHF. This can be expressed as follows:

>>> de = MultiValueMap(["DE", "LC"], ["EUR"])
>>> ch = MultiValueMap(["CH", "LC"], ["CHF"])
>>> src = ["COUNTRY", "CURRENCY"]
>>> tgt = ["CURRENCY"]
>>> cm = MultiComponentMap(src, tgt, [de, ch])

source: The source component(s)

target: The target component(s)

values: The representation map, with the list of mapped values (one or more in the source and one or more in the target)

class pysdmx.model.map.MultiValueMap(source: Sequence[str | Pattern[str]], target: Sequence[str], valid_from: datetime | None = None, valid_to: datetime | None = None)

Provides the values for a mapping between one or more components.

Examples

For example, let’s assume that we want to map the the code for local currency (say LC) to an ISO 3-letter currency code, depending on the country. So, if the country is DE (Germany), then the currency in the target should be EUR but, if the country is CH, then it should be CHF. This can be expressed with the following value maps:

>>> MultiValueMap(["DE", "LC"], ["EUR"])
>>> MultiValueMap(["CH", "LC"], ["CHF"])

Also, the mapping can depending on the time period.

Examples

For example, for periods before January 1999, we may want to map the local currency for Germany to DEM and afterwards to EUR. This can be expressed with the following value maps:

>>> from datetime import datetime
>>> t1 = datetime(1998, 12, 31, 23, 59, 59)
>>> t2 = datetime(1999, 1, 1)
>>> MultiValueMap(["DE", "LC"], ["EUR"], valid_to: t1)
>>> MultiValueMap(["DE", "LC"], ["EUR"], valid_from: t2)
>>> MultiValueMap(["CH", "LC"], ["CHF"])

Values in the source may represent regular expressions with capture groups.

source: One or more source values

target: One or more target values

valid_from: Start of business validity for the mapping

valid_to: End of business validity for the mapping

class pysdmx.model.map.StructureMap(id: str, name: str, agency: str, source: str, target: str, maps: Sequence[ComponentMap | DatePatternMap | FixedValueMap | ImplicitComponentMap | MultiComponentMap], description: str | None = None, version: str = '1.0')

Maps a source structure to a target structure.

The various mapping rules are classified by types.

A structure map is an iterable, i.e. it is possible to iterate over the various mapping rules using a for loop.

It is also possible to retrieve the mapping rule applying to a component by using the component id (e.g. map[“FREQ”]).

id: The identifier for the structure map.

name: The name of the structure map.

agency: The maintainer of the structure map.

source: The source structure.

target: The target structure.

maps: The various mapping rules in the structure map.

description: Additional descriptive information about the structure map.

version: The version of the structure map (e.g. 2.0.42).

property component_maps: Sequence[ComponentMap]: Maps between one source and one target component.

property date_pattern_maps: Sequence[DatePatternMap]: Maps based on date patterns.

property fixed_value_maps: Sequence[FixedValueMap]: Maps with a fixed value.

property implicit_component_maps: Sequence[ImplicitComponentMap]: Maps where the source value is copied to the target.

property multi_component_maps: Sequence[MultiComponentMap]: Maps between one or more source & one or more target components.

class pysdmx.model.map.ValueMap(source: str | Pattern[str], target: str, valid_from: datetime | None = None, valid_to: datetime | None = None)

Maps the values of two components together.

Examples

For example, let’s assume that we want to map the ISO 2-letter country code with the ISO 3-letter country code. This can be expressed with the following value maps:

>>> ValueMap("BE", "BEL")

Values in the source may represent regular expressions with capture groups.

Also, a map may have business validity associated with it.

source: The source value

target: The target value

valid_from: Start of business validity for the mapping

valid_to: End of business validity for the mapping