Contents

Convert sdmx objects to other formats

Convert sdmx objects to other formats

writer.pandas: Convert to pandas objects

Changed in version 1.0: sdmx.to_pandas() handles all types of objects, replacing the earlier, separate data2pandas and structure2pd writers.

to_pandas() implements a dispatch pattern according to the type of obj. Some of the internal methods take specific arguments and return varying values. These arguments can be passed to to_pandas() when obj is of the appropriate type:

sdmx.writer.pandas.write_dataset(obj[, ...])

Convert DataSet.

sdmx.writer.pandas.write_datamessage(obj, *args)

Convert DataMessage.

sdmx.writer.pandas.write_itemscheme(obj[, ...])

Convert ItemScheme.

sdmx.writer.pandas.write_structuremessage(obj)

Convert StructureMessage.

sdmx.writer.pandas.DEFAULT_RTYPE

Default return type for write_dataset() and similar methods.

Other objects are converted as follows:

Component

The id attribute of the concept_identity is returned.

DataMessage

The DataSet or data sets within the Message are converted to pandas objects. Returns:

dict

The values of the mapping are converted individually. If the resulting values are str or Series with indexes that share the same name, then they are converted to a Series, possibly with a pandas.MultiIndex. Otherwise, a DictLike is returned.

DimensionDescriptor

The components of the DimensionDescriptor are written.

list

For the following obj, returns Series instead of a list:

NameableArtefact

The name attribute of obj is returned.

sdmx.writer.pandas.DEFAULT_RTYPE = 'rows'

Default return type for write_dataset() and similar methods. Either ‘compat’ or ‘rows’. See the ref:HOWTO <howto-rtype>.

sdmx.writer.pandas.write_datamessage(obj: sdmx.message.DataMessage, *args, rtype=None, **kwargs)[source]

Convert DataMessage.

Parameters
Returns

sdmx.writer.pandas.write_dataset(obj: sdmx.model.DataSet, attributes='', dtype=<class 'numpy.float64'>, constraint=None, datetime=False, **kwargs)[source]

Convert DataSet.

See the walkthrough for examples of using the datetime argument.

Parameters

  • obj (DataSet or iterable of Observation) –

  • attributes (str) –

    Types of attributes to return with the data. A string containing zero or more of:

    • 'o': attributes attached to each Observation .

    • 's': attributes attached to any (0 or 1) SeriesKey associated with each Observation.

    • 'g': attributes attached to any (0 or more) GroupKey associated with each Observation.

    • 'd': attributes attached to the DataSet containing the Observations.

  • dtype (str or numpy.dtype or None) – Datatype for values. If None, do not return the values of a series. In this case, attributes must not be an empty string so that some attribute is returned.

  • constraint (ContentConstraint, optional) – If given, only Observations included by the constraint are returned.

  • datetime (bool or str or or .Dimension or dict, optional) –

    If given, return a DataFrame with a DatetimeIndex or PeriodIndex as the index and all other dimensions as columns. Valid datetime values include:

    • bool: if True, determine the time dimension automatically by detecting a TimeDimension.

    • str: ID of the time dimension.

    • Dimension: the matching Dimension is the time dimension.

    • dict: advanced behaviour. Keys may include:

      • dim (Dimension or str): the time dimension or its ID.

      • axis ({0 or ‘index’, 1 or ‘columns’}): axis on which to place the time dimension (default: 0).

      • freq (True or str or Dimension): produce pandas.PeriodIndex. If str, the ID of a Dimension containing a frequency specification. If a Dimension, the specified dimension is used for the frequency specification.

        Any Dimension used for the frequency specification is does not appear in the returned DataFrame.

Returns

  • pandas.DataFrame –

    • if attributes is not '', a data frame with one row per Observation, value as the first column, and additional columns for each attribute;

    • if datetime is given, various layouts as described above; or

    • if _rtype (passed from write_datamessage()) is ‘compat’, various layouts as described in the HOWTO.

  • pandas.Series with pandas.MultiIndex – Otherwise.

sdmx.writer.pandas.write_itemscheme(obj: sdmx.model.ItemScheme, locale='en')[source]

Convert ItemScheme.

Parameters

locale (str, optional) – Locale for names to return.

Returns

Return type

pandas.Series

sdmx.writer.pandas.write_structuremessage(obj: sdmx.message.StructureMessage, include=None, **kwargs)[source]

Convert StructureMessage.

Parameters

  • obj (StructureMessage) –

  • include (iterable of str or str, optional) – One or more of the attributes of the StructureMessage ( ‘category_scheme’, ‘codelist’, etc.) to transform.

  • kwargs – Passed to write() for each attribute.

Returns

Keys are StructureMessage attributes; values are pandas objects.

Return type

DictLike

Todo

Support selection of language for conversion of InternationalString.

writer.xml: Write to SDMX-ML

New in version 1.1.

See to_xml().

SDMXML v2.1 writer.

sdmx.writer.xml.i11lstring(obj, name)[source]

InternationalString.

Returns a list of elements with name name.

sdmx.writer.xml.identifiable(obj, **kwargs)[source]

Write IdentifiableArtefact.

Unless the keyword argument _with_urn is False, a URN is generated for objects lacking one, and forwarded to annotable()

sdmx.writer.xml.reference(obj, parent=None, tag=None, style=None)[source]

Write a reference to obj.

Todo

Currently other functions in writer.xml all pass the style argument to this function. As an enhancement, allow user or automatic selection of different reference styles.

Writer API

class sdmx.writer.base.BaseWriter(format_name)[source]

Base class for recursive writers.

Usage:

  • Create an instance of this class.

  • Use register() in the same manner as Python’s built-in functools.singledispatch() to decorate functions that certain types of sdmx.model or sdmx.message objects.

  • Call recurse() to kick off recursive writing of objects, including from inside other functions.

Example

>>> MyWriter = BaseWriter('my')

>>> @MyWriter.register
>>> def _(obj: sdmx.model.ItemScheme):
>>>     ... code to write an ItemScheme ...
>>>     return result

>>> @MyWriter.register
>>> def _(obj: sdmx.model.Codelist):
>>>     ... code to write a Codelist ...
>>>     return result
recurse(obj, *args, **kwargs)[source]

Recursively write obj.

If there is no register() ‘ed function to write the class of obj, then the parent class of obj is used to find a method.

previous

Parse SDMX file formats

next

Implementation notes