.. role:: python(code)
    :language: python

Documentation for TrendMiner Python SDK Core
============================================

The TrendMiner Python SDK Core allows you to interact with TrendMiner via a high-level API from any Python runtime, e.g. from
a Python notebook embedded within TrendMiner, custom python calculations etc.
Most boilerplate code has been written for you, so you can focus on what is important:
getting valuable insights from your time series data.

To interact with TrendMiner via this SDK, you will first have to create a :python:`TrendMinerClient` object.
The client creation requires the URL of your TrendMiner installation and an `OAuth2 <https://oauth.net/2/>`_ token.
However, if you are working from a TrendMiner embedded notebook, we simplified this for you and creating a
:python:`TrendMinerClient` is as simple as (note :python:`os.environ["KERNEL_USER_TOKEN”]` is detected and replaced with
your current OAuth2 token):

.. code-block:: python

    from trendminer import TrendMinerClient

    client = TrendMinerClient.from_token(token=os.environ['KERNEL_USER_TOKEN'])


If however, you are working from an external environment (or an environment with SSL enabled),
you must provide a valid TrendMiner URL and OAuth2 token:

.. code-block:: python

    from trendminer import TrendMinerClient

    client = TrendMinerClient.from_token(url='https://trendminer.yourcompany.com',token='<oauth2_token>')


Loading a tag
=============

.. code-block:: python

    tag = client.tag.get_by_name("<tag_name>")


Loading data of a tag
=====================

.. code-block:: python
    
    tag = client.tag.get_by_name("<tag_name>")
    period = ("2019-03-25", "2019-03-26")
    data = tag.get_data(period, resolution="1m")


Performing a Value Based Search
===============================

.. code-block:: python

    from trendminer.sdk.search import ValueBasedSearchOperators
    from trendminer.sdk.search import LogicalOperators
    
    level = client.tag.get_by_name("<tag_name>")
    vbs = client.search.value(queries=[
        (level, ValueBasedSearchOperators.GREATER_THAN, 35),
        ("<tag2_name>", ValueBasedSearchOperators.EQUAL_TO, "<value>"),
    ],
    operator=LogicalOperators.AND,
    duration="2m"
    )
    
    results = vbs.get_results(("2019-01-20", "2019-01-29"))


Loading a TrendHub view as a `pandas <https://pandas.pydata.org/>`_ dataframe
=============================================================================

.. code-block:: python
    
    view = client.view.get_by_name("<view_name>")
    df = view.get_data()[0]


Loading Context items as a `pandas <https://pandas.pydata.org/>`_ dataframe
===========================================================================

.. code-block:: python

    client = TrendMinerClient(url='https://trendminer.yourcompany.com',token='<oauth2_token>')
    chv = client.context.view.get_by_identifier("<context_view_identifier>")
    items = chv.search_items()
    df = pd.DataFrame(
        [{
            **item,
            "start_date": item.interval.start,
            "end_date": item.interval.end,
            "total_duration": item.interval.duration,
            "type": item.context_type,
            "last_state": item.events[-1].state,
        } for item in items]
    )



Overview of packages
====================

.. toctree::
    :maxdepth: 3
    :glob:

    api/trendminer

Indices and tables
==================

* :ref:`modindex`