Kestrel Analytics Interface

The abstract interface for building an analytics interface for Kestrel.

A Kestrel analytics interface is a Python package with the following rules:

  • The package name should use prefix kestrel_analytics_.

  • The package should have one and only one root level class inherited from AbstractAnalyticsInterface.

    • There is no restriction on package structure for the package.

    • There is no restriction on interface class name.

    • The interface class should inhert AbstractAnalyticsInterface.

    • The interface class should be importable from the package directly, i.e., it needs to be imported into __init__.py of the package.

    • Zero class inherited from AbstractAnalyticsInterface will result in an exception.

    • Multiple classes inherited from AbstractAnalyticsInterface will result in an exception.

class kestrel.analytics.interface.AbstractAnalyticsInterface[source]

Bases: ABC

The abstract class for building an analytics interface.

abstract static schemes()[source]

scheme (the URI prefix before ://) of the analytics interface.

Every analytics interface should have at least one unique scheme to use at the beginning of the analytics URI. To develop a new analytics interface, one needs to check public Kestrel analytics packages to name a new one that is not taken. Note that scheme defined here should be in lowercase, and Kestrel analytics manager will normalize schemes of incoming URIs into lowercase.

Returns

A list of schemes; A URI with one of the scheme will be processed by this interface.

Return type

[str]

abstract static list_analytics(config)[source]

List analytics names accessible from this interface.

Parameters

config (dict) – a layered list/dict that contains config for the interface and can be edited/updated by the interface.

Returns

A list of analytics names accessible from this interface.

Return type

[str]

abstract static execute(uri, argument_variables, config, session_id=None, parameters=None)[source]

Execute an analytics.

An analytics updates argument variables in place with revised attributes or additional attributes computed. Therefore, there is no need to return any variable, but the optional display object can be returned if the analytics generate anything to be shown by the front-end, e.g., a visualization analytics.

When realizing the execute() method of an analytics interface, one needs to realize the following functionalities:

  1. Execute the specified analytics.

  2. Keep track of input/output Kestrel variables

  3. Kestrel variable update (in most cases, this is done by the analytics interface; in some cases, an analytics may directly update the store).

  4. Prepare returned display object.

Parameters

  • uri (str) – the full URI including the scheme and analytics name.

  • argument_variables ([kestrel.symboltable.variable.VarStruct]) – the list of Kestrel variables as arguments.

  • config (dict) – a layered list/dict that contains config for the interface and can be edited/updated by the interface.

  • session_id (str) – id of the session, may be useful for analytics directly writing into the store.

  • parameters (dict) – analytics execution parameters in key-value pairs {"str":"str"}.

Returns

returned display or None.

Return type

kestrel.codegen.display.AbstractDisplay