Signals from the Exabel Data API

Data uploaded with the Exabel Data API can be accessed by using the data(...) and graph_signal(...) expressions.

When time series are uploaded through the Exabel Data API, they are always associated with some entity. An entity can for example be a company, a brand belonging to a company, or a sector which consists of multiple companies. The data(...) signal allows you to access the raw data for an entity, while the graph_signal(...) allows you to traverse relationships in the graph to access data for entities connected to your evaluation entity.

Note: we are in the process of simplifying the process of extracting and aggregating data from different entities in the graph.

A signal is always evaluated for some root entity, for example a company. The graph signal accepts a path argument, which is a list of relationships to be traversed, starting at the root entity. For more information on how to traverse relationships in the graph, see the page on graph relations.

If you have uploaded time series for, say, company sentiments and associated them with companies using the signal signals/namespace.company_sentiment, you can retrieve these time series with the expression data('namespace.company_sentiment').

However, if you have uploaded time series for a brand, connected to the company through a namespace.HAS_BRAND entity, you can create a company signal which retrieves the time series for all the brands connected to the company the signal is evaluated for. There are two ways of doing this. One is by specifying the entity type we should traverse to, to find the data:

data('namespace.brand_sales').for_type('ns.brand')

The other way is to specify the relationship to follow, to find the data:

graph_signal('namespace.brand_sales', ['namespace.HAS_BRAND'])

To read more about the first way of traversing the graph, see this page.

data(signal)

Retrieve time series from a Data API signal.

Parameters:

signal – a Data API signal name, on the format namespace.signal_name.

Examples

Retrieve the time series for signals/namespace.company_metric for the evaluation entities:

data('namespace.company_metric')
graph_signal(signal, path=[], leaf_entity_as_label=True, *, semantic_labels=None, target_entity_index=-1, revisions_for_date=None)

Retrieve time series for entities in the graph by following a sequence of relationships from the evaluation entity.

Parameters:

  • signal – a Data API signal name, which is on the format namespace.signal_name, or a regular signal expression

  • path (list) –

    a list of relationships to traverse from the root entity. Each relationship is specified either as a string with the name of the relationship type or as a dict specifying the name of the relationship type and additional restrictions. When using a dict, the following dict keys are available:

    • relationship_type (str): Mandatory relationship type.

    • direction (str): Direction of relationship. Allowed values are 'IN', 'OUT' and None, where None specifies that both directions will be followed. Default value is None.

    • target_types (list[str]): Target entity types. The given target entity types will be prefixed with “entityTypes/” to construct the entity type resource name. Default value is empty list, which means all target types are allowed.

    • tag (str): Semantic tag id identifying a tag which the target entities must be part of. Default value is None, which means no tag filtering is performed.

    • target_ids (list[str]): Semantic target entity ids. Default value is empty list, which means no target id filtering is performed.

  • leaf_entity_as_label (bool) – Deprecated. Was previously used to control whether leaf entities were included in the result, but they are now always included.

  • semantic_labels (bool) – whether this signal may produce multiple time series for each entity it is evaluated for. By default, this is True if a non-empty path is given. However, if there is a single leaf entity for each root entity that this signal is evaluated for, this may be set to True to produce time series with the same name for all entities.

  • target_entity_index (int) – index of the target entity in the path. This can be used to return intermediate entities in the traversal path. The index is 0-indexed, such that index 0 corresponds to the root entities. The default value is -1, which corresponds to the target entity of the last element in the path (or the root entity if no path is given).

  • revisions_for_date (str) – a string on the format YYYY-MM-DD; if provided, the signal produces the historical revisions for the signal at this date.

Examples

Retrieve the time series for signals/namespace.brand_sales for all the brands connected to the evaluation entity:

graph_signal('namespace.brand_sales', ['namespace.HAS_BRAND'])

Fetch the close price of the company which owns a brand, assuming the signal is evaluated for a brand entity:

graph_signal(Close_Price, ['namespace.HAS_BRAND'])

Follow a relationship in a specific direction:

graph_signal(Close_Price, [{'relationship_type': 'namespace.OWNS', 'direction': 'OUT'}])

For more information on how to traverse relationships in the graph, see the page on graph relations.