pyicane

pyicane is a Python wrapper for the Statistical Office of Cantabria’s (ICANE) metadata restful API. This module parses ICANE’s json data and metadata into Python objects and common data structures such as Pandas dataframes [1]. All ICANE’s API classes and methods are covered; also, time-series data can be downloaded into a Python Pandas dataframe structure.

pyicane is written and maintained by Miguel Expósito Martín and is distributed under the Apache 2.0 License (see LICENSE file).

[1]http://pandas.pydata.org for Python Data Analysis Library information
class pyicane.BaseEntity(dict_)

Abstract class to convert deserialized JSON into a Python object. Basic skeleton for almost all the module classes.

label_ str

singular label of the converted entity. Ex: “category”

plabel_ str

plural label of the converted entity. Ex: “categories”

__getattr__(key)

Get dictionary key as attribute. Overriden method.

Parameters:key (string) – key of the dictionary.
Returns:self[key](string): key associated value.
class pyicane.BaseMixin

Mixin abstract class with attributes and methods shared by most of the classes.

label_ str

singular label of the converted entity. Ex: “category”. Defaults to None in the parent class.

plabel_ str

plural label of the converted entity. Ex: “categories”. Defaults to None in the parent class.

classmethod find_all()

Retrieve all available entities of the class.

Returns:List of Python objects from the entity class represented by the uri_tag parameter.
classmethod get(uri_tag)

Retrieve an entity by its uri_tag. :param uri_tag: the uri_tag (ie. label) of the entity.

Returns:Python object from the entity class represented by the uri_tag parameter.
class pyicane.Category(dict_)

Class mapping icane.es ‘Category’ entity. A Category classifies data based on their temporal or geographical area.

class pyicane.Class(dict_)

Class mapping icane.es ‘Class’ entity.

classmethod find_all(lang)

Retrieve the description of all classes or entities. :param lang: language; possible values: ‘es’, ‘en’

Returns:Python list of objects from ‘Class’ class.
classmethod get(class_name, lang)

Retrieve the description of a class or entity by its name. :param class_name: name of the class to get the description of. :type class_name: string :param lang: language; possible values: ‘es’, ‘en’.

Returns:Python object from ‘Class’ class.
class pyicane.Data(dict_)

Class mapping icane.es ‘Data’ entity.

class pyicane.DataMixin

Mixin abstract class with attributes and methods shared by data-type classes.

label_ str

singular label of the converted entity. Ex: “data”. Defaults to None in the parent class.

classmethod get_last_updated()

Retrieve last updated date in dd/mm/YY format.

Returns:datetime.datetime object in dd/mm/YY format.
classmethod get_last_updated_millis()

Retrieve last updated date in milliseconds.

Returns:int with milliseconds.
class pyicane.DataProvider(dict_)

Class mapping icane.es ‘DataProvider’ entity. A DataProvider represents an organisation which produces data or metadata.

class pyicane.DataSet(dict_)

Class mapping icane.es ‘DataSet’ entity. A DataSet represents any organised collection of data.

Class mapping icane.es ‘Link’ entity. A Link or hyperlink represents a reference to data that can be followed.

class pyicane.LinkType(dict_)

Class mapping icane.es ‘LinkType’ entity. A LinkType is used to distinguish among vocabulary specifications.

class pyicane.Measure(dict_)

Class mapping icane.es ‘Measure’ entity. A Measure represents a phenomenon or phenomena to be measured in a data set.

class pyicane.Metadata(dict_)

Class mapping icane.es ‘Metadata’ entity.

class pyicane.NodeType(dict_)

Class mapping icane.es ‘node_type’ entity. A node_type is used to distinguish among typologies of levels in a hierarchical representation of metadata.

class pyicane.Periodicity(dict_)

Class mapping icane.es ‘Periodicity’ entity. A Periodicity instance represents the frequency of compilation of the data.

class pyicane.ReferenceArea(dict_)

Class mapping icane.es ‘ReferenceArea’ entity. A ReferenceArea represents the geographic area to which the measured statistical phenomenon relates.

class pyicane.Section(dict_)

Class mapping icane.es ‘Section’ entity. A Section represents the first level of classification within a category.

get_subsection(subsection_uri_tag)

Retrieve a subsection instance for a given section. :param section_uri_tag: Section uri tag (ie, label) of the Subsection parent. :type section_uri_tag: string :param subsection_uri_tag: The subsection uri tag to be retrieved. :type subsection_uri_tag: string

Returns:Python objects of ‘Subsection’ class.
get_subsections()

Retrieve all subsections belonging to a given section. :param uri_tag: Section uri tag (ie, label).

Returns:Python list of objects of’Subsection’ class.
class pyicane.Source(dict_)

Class mapping icane.es ‘Source’ entity. A Source represents a specific data set, metadata set, database or metadata repository from where data or metadata are available

class pyicane.Subsection(dict_)

Class mapping icane.es ‘Subsection’ entity. A Subsection represents the second level of classification within a category, i.e. the next level in a section.

class pyicane.TimePeriod(dict_)

Class mapping icane.es ‘TimePeriod’ entity. A TimePeriod represents the period of time or point in time to which the measured observation refers

class pyicane.TimeSeries(dict_)

Class mapping icane.es ‘TimeSeries’ entity. A TimeSeries represents a set of ordered observations on a quantitative characteristic of an individual or collective phenomenon taken at different points of time. Lists of elements of this class are returned adequately classified and nested in a structure with groups, themes and statistics without semantic value.

data_as_dataframe()

Convert TimeSeries data into pandas.DataFrame object.

Returns: Python Pandas Dataframe.

classmethod find_all(category_uri_tag, section_uri_tag=None, subsection_uri_tag=None, data_set_uri_tag=None, node_type_uri_tag=None, inactive=None)

Retrieve all nodes of type dataset given its category, section and subsection. :param category_uri_tag: uri_tag (ie, label) of the category. :type category_uri_tag: string :param section_uri_tag: uri_tag (ie, label) of the section. If present, it must follow an existing category uri-tag or an exception will be thrown by the restful API. :type section_uri_tag: string, optional :param subsection_uri_tag: uri_tag (ie, label) of the subsection. If present, it must follow an existing section uri-tag or an exception will be thrown by the restful API. :type subsection_uri_tag: string, optional :param data_set_uri_tag: uri_tag (ie, label) of the data-set. If present, it must follow am existing subsection uri-tag or an exception will be thrown by the restful API. :type data_set_uri_tag: string, optional :param node_type: specifies the node type to return. Accepted values: ‘time-series’, ‘data-set’, ‘folder’,’theme’, etc. See node_type class for more info. Defaults to None. :type node_type: string, optional :param inactive: if True, inactive nodes are also returned. Defaults to None.

Returns:Python list of TimeSeries objects representing the nodes or time series associated to a given category, section, subsection or dataset uri_tag, filtered by node_type and inactive status.
classmethod find_all_by_last_updated(data_updated=None, metadata_updated=None)

Retrieve all time series for a given data or metadata update date.

Parameters:
  • data_updated (string, optional) – last data update date. Both arguments are mutually exclusive.
  • metadata_updated (string, optional) – last metadata update date. Both arguments are mutually exclusive.
Returns:

Python list of TimeSeries objects whose data or metadata have been updated in the specified dates.

classmethod find_all_datasets(category_uri_tag, section_uri_tag, subsection_uri_tag)

Retrieve all nodes of type dataset given its category, section and subsection. :param category_uri_tag: uri_tag (ie, label) of the category. :type category_uri_tag: string :param section_uri_tag: uri_tag (ie, label) of the section. :type section_uri_tag: string :param subsection_uri_tag: uri_tag (ie, label) of the subsection.

Returns:Python list of TimeSeries objects with node_type=’data-set’ for a given category, section and subsection.
classmethod get_parent(uri_tag)

Retrieve the parent node of the node or TimeSeries given by its uri_tag. :param uri_tag: uri_tag (ie, label) of the node or TimeSeries.

Returns:Python TimeSeries object representing the parent node of the given one.
classmethod get_parents(uri_tag)

Retrieve all ancestors of the node or TimeSeries given by its uri_tag. :param uri_tag: uri_tag (ie, label) of the node or TimeSeries.

Returns:Python list of TimeSeries objects representing the ancestors of the given node.
classmethod get_possible_subsections(uri_tag)

Retrieve all possible subsections associated to a node or TimeSeries uri_tag. :param uri_tag: uri_tag (ie, label) of the node or TimeSeries.

Returns:Python list of Subsection objects representing the subsections associated to the given node.
classmethod get_possible_time_series(uri_tag)

Retrieve all possible nodes or time series associated to a node or TimeSeries uri_tag. :param uri_tag: uri_tag (ie, label) of the node or TimeSeries.

Returns:Python list of TimeSeries objects representing the nodes or time series associated to a given uri_tag.
metadata_as_dataframe()

Convert TimeSeries metadata digest into pandas.DataFrame object.

Returns: Python Pandas Dataframe.

class pyicane.UnitOfMeasure(dict_)

Class mapping icane.es ‘UnitOfMeasure’ entity. A UnitOfMeasure represents a quantity or increment by which something is counted or described.

pyicane.add_path_params(section_uri_tag=None, subsection_uri_tag=None, data_set_uri_tag=None)

Concatenate path params to a string representing part of a URI.

Parameters:
  • section_uri_tag (string, optional) – uri_tag (ie, label) of the section to be added as path parameter to the URI to be requested. Defaults to None.
  • subsection_uri_tag (string, optional) – uri_tag (ie, label) of the subsection to be added as path parameter to the URI to be requested. Must follow an existing section uri_tag or an exception will be thrown by the restful API. Defaults to None.
  • dataset_uri_tag (string, optional) – uri_tag (ie, label) of the dataset to be added as path parameter to the URI to be requested. Must follow an existing subsection uri_tag or an exception will be thrown by the restful API. Defaults to None.
Returns:

path – conveniently concatenated path params to conform the URI to be requested.

Return type:

string

pyicane.add_query_string_params(node_type=None, inactive=None)

Add query string params to a string representing part of a URI.

Parameters:
  • node_type (string, optional) – specifies the node type to return. Accepted values: ‘time-series’, ‘data-set’, ‘folder’,’theme’, etc. See node_type class for more info. Defaults to None.
  • inactive (boolean, optional) – if True, inactive nodes are also returned. Defaults to None.
Returns:

query_string – conveniently concatenated query string params to conform the URI to be requested.

Return type:

string

pyicane.flatten_data(data, record=None)

Flatten a nested dict generated from a deserialized JSON object provided by ICANE’s Restful data API.

Parameters:
  • data (dict) – a dictionary generated by the ‘’request()’’ function with ICANE’s API time-series data.
  • record (list, optional) – list of values representing a row. It’s used within the recursive calls to the method. Defaults to None.
Yields :

row (list) – A list representing a row in a flattened matrix.

pyicane.flatten_metadata(data)

Flatten a nested dict or list of nested dicts generated from a deserialized JSON object provided by ICANE’s Restful metadata API.

Parameters:data (dict) – a dictionary or list of dictionaries containing nested TimeSeries objects.
Yields :Python List of node_digest_model elements: A list with the most relevant metadata for a given node or list of nodes with node type equal to ‘time-series’, ‘document’ or ‘olap-native’ in flattened format.
pyicane.node_digest_model(node)

Extracts plain relevant metadata fields only. Relevant metadata has been selected by ICANE’s technical staff.

Parameters:node (dict) – a dictionary generated by the ‘’request()’’ function containing nested TimeSeries objects.
Returns:List of relevant time-series metadata fields with the intention of using them to populate a CSV row.
pyicane.request(path)

Send a request to a given URL accepting JSON format and return a deserialized Python object. If no “http://” protocol is specified, BASE_URL is used in the request.

Parameters:

path (str) – The URI to be requested.

Returns:

Deserialized JSON Python object.

Return type:

response

Raises :
  • HTTPError – the HTTP error returned by the requested server.
  • InvalidURL – an invalid URL has been requested.
  • Exception – generic exception.

Previous topic

Welcome to pyicane’s documentation!

This Page