# TrendMiner Interface
> TrendMiner API control package
Python control package (SDK) for the TrendMiner API. Everything branches from an authenticated TrendMinerClient obtained via a factory function; facades group functionality (client.tag, client.search, client.context, client.tag_builder, ...) and return live objects, local *Definition builders, and lazy paged containers.
# Guides
# TrendMiner Interface
Python control package for the TrendMiner API.
## Installation
Install the latest release ([`v1.6.0a2`](https://github.com/TrendMinerCS/trendminer-interface/releases/tag/v1.6.0a2)) directly from its wheel:
```
pip install https://github.com/TrendMinerCS/trendminer-interface/releases/download/v1.6.0a2/trendminer_interface-1.6.0.a2-py3-none-any.whl
```
New here? Start with **[Getting started](https://trendminercs.github.io/trendminer-interface/getting-started/index.md)**.
## Reference
- **[Interface tree](https://trendminercs.github.io/trendminer-interface/reference/interface-tree/index.md)** — the full interface tree; every namespace lists its methods and return types, with links through to the detailed pages.
- **Objects & Types** — the `TrendMinerClient`, the interface (facade) classes, and the classes their methods return (objects, definitions, containers, exceptions), each showing its public attributes, properties and methods.
## For LLMs
Using an AI assistant with this SDK? The most robust way to get started with most LLMs is to download **`llms-full.txt`** — the full guides and API reference in a single file — and upload it to your assistant as a file attachment:
[Download llms-full.txt](https://trendminercs.github.io/trendminer-interface/llms-full.txt)
Uploading works with any chat assistant, including those that cannot browse the web or that only read part of a long page. The file is large, so a large-context model gives the best results. Download it again after upgrading to a new release.
If your tool can fetch URLs itself (e.g. coding agents), you can instead point it at **`llms.txt`**: a concise, linked index of the documentation that follows the [llms.txt](https://llmstxt.org/) convention:
```
https://trendminercs.github.io/trendminer-interface/llms.txt
```
# Getting started
## Authentication
All interactions with your TrendMiner server will run through an authenticated [`TrendMinerClient`](https://trendminercs.github.io/trendminer-interface/reference/types/TrendMinerClient/index.md) instance. All methods for retrieval of objects and creation of new objects will branch from this instance.
Typically, you will authenticate a client instance directly from credentials. The following will authenticate you as a client user. For more details on authentication and client creation, refer to [creating a client](https://trendminercs.github.io/trendminer-interface/creating-a-client/index.md).
```
from trendminer_interface import client_from_credentials
client = client_from_credentials(
url="https://training.trendminer.cloud",
client_id="clientuser",
client_secret="GdYDrRef3hwdshIJwj3e3IsiUJqigVxZ",
)
```
Note that the credentials above are only for illustration, and that it is insecure to hard-code secrets and passwords directly in your code. Use a `.env` file or a [keyring service](https://pypi.org/project/keyring/) instead.
## The client as entry point
Once we have our authenticated [`TrendMinerClient`](https://trendminercs.github.io/trendminer-interface/reference/types/TrendMinerClient/index.md) instance, we can start interacting with TrendMiner. For example, we can search for some tags.
```
import pandas as pd
tag = client.tag.from_name("TM_Hour_UTC")
print(tag)
```
Output
```
2026-01-01 00:00:00+00:00 0.0
2026-01-01 01:00:00+00:00 1.0
2026-01-01 02:00:00+00:00 2.0
2026-01-01 03:00:00+00:00 3.0
2026-01-01 04:00:00+00:00 4.0
Freq: h, Name: value, dtype: float64
```
Once authenticated, you can retrieve and create tags, work organizer items, context items, ... all from your `client`. For a full overview of methods available from the client, refer to [Interface tree](https://trendminercs.github.io/trendminer-interface/reference/interface-tree/index.md).
## Getting to work
After exploring how to [create the correct type of client](https://trendminercs.github.io/trendminer-interface/creating-a-client/index.md), the easiest way to get started is to check the [Examples](https://trendminercs.github.io/trendminer-interface/examples/index.md) section for snippets similar to your use cases. The [Interface tree](https://trendminercs.github.io/trendminer-interface/reference/interface-tree/index.md) overview should give you an idea on what functionalities are available in the SDK. You can dive into class details from this page, or navigate through the [Objects & Types](https://trendminercs.github.io/trendminer-interface/objects-and-types/index.md) section directly.
For examples of fully fleshed-out use cases, you can check the [Use cases](https://trendminercs.github.io/trendminer-interface/use-cases/index.md) section.
# Creating a client
Every interaction with TrendMiner starts from an authenticated `TrendMinerClient`. All retrieval and creation of objects branches from this instance — you never construct it directly, but obtain it through one of the factory functions below.
How a client authenticates depends on which factory you use. `client_from_credentials` and `client_from_refresh_token` perform an OAuth token exchange against your appliance and therefore need a **client id** and **client secret** (generated in ConfigHub by an administrator). `client_from_env` and `client_with_bearer_auth` instead receive a ready-made access token from the environment they run in, and perform no exchange of their own. In every case the client refreshes its access token transparently while it is in use.
## Which function should I use?
- **[`client_from_credentials`](https://trendminercs.github.io/trendminer-interface/creating-a-client/client_from_credentials/index.md)** — authenticate directly from credentials, and the most common starting point. With only a client id and secret you authenticate as the *client user*; add a `username` and `password` and you authenticate as that (local) user, taking on their permissions. Credentials are verified immediately, so a mistake surfaces the moment you create the client.
- **[`client_from_refresh_token`](https://trendminercs.github.io/trendminer-interface/creating-a-client/client_from_refresh_token/index.md)** — reuse an existing OAuth refresh token instead of a username and password. This is the way to run automations for SSO users, who cannot use the password grant. A client id and secret are still required; the appliance URL is read from the token itself.
- **[`client_from_env`](https://trendminercs.github.io/trendminer-interface/creating-a-client/client_from_env/index.md)** — read the access token directly from environment variables. The intended use case is embedded Python applications such as MLHub notebooks (`KERNEL_USER_TOKEN`) and Custom Calculations (`ACCESS_TOKEN`), where the host provides the token for you.
- **[`client_with_bearer_auth`](https://trendminercs.github.io/trendminer-interface/creating-a-client/client_with_bearer_auth/index.md)** — supply a callable that returns a bearer token. Use this when embedding the SDK into a custom application that implements its own authentication and already manages token retrieval and refresh.
## User types
Which factory you reach for is largely determined by *what kind of user* you are authenticating as.
### Client User
A client user is the service account behind an OAuth client (its username has the form `service-account-{client id}`). It is reachable only through the API — you cannot log in as a client user in the TrendMiner UI — and it cannot hold admin permissions. Like any user, it must be granted access to the relevant data sources in ConfigHub. A client user does have a work organizer, but because that work organizer is never accessible from the UI, a client user is best suited to retrieving data rather than saving work organizer items.
Authenticate as a client user with `client_from_credentials`, passing only the client id and secret.
### Local User
A local user is a user account created directly in TrendMiner, as opposed to one coming from an external identity provider. You authenticate as a local user with `client_from_credentials` by supplying a `username` and `password` **in addition to** the client id and secret. The resulting client carries that user's permissions — including admin permissions, which only real users can hold — regardless of the permissions attached to the client id.
Note that the password grant works for local users only: LDAP or SAML credentials cannot be used this way.
### OAuth User
An OAuth user signs in through an external identity provider (SSO / LDAP / SAML). Because only local users can log in with a username and password, an OAuth user cannot be authenticated with `client_from_credentials`. The only way to authenticate as an OAuth user is to log in through the browser and inject the resulting refresh token into your script with `client_from_refresh_token`. Treat this token as you would a password — keep it in a `.env` file rather than pasting it directly into the script.
## Robustness
An authenticated client refreshes its access token automatically while you use it. Through inactivity or prolonged use (on the order of a few hours), the underlying session will nonetheless eventually expire, at which point you need to authenticate again. The client never keeps sensitive information such as your password in memory.
For long-running scripts it is worth adding **automated retries**, so that a transient network hiccup or a momentarily overloaded appliance does not abort the whole run. Every factory accepts a `transport` argument, which is the injection point for a retry policy. The example below uses the third-party [`httpx-retries`](https://pypi.org/project/httpx-retries/) package (install it alongside the SDK):
```
from httpx_retries import Retry, RetryTransport
from trendminer_interface import client_from_credentials
retry = Retry(
total=5, # up to 5 retries per request
backoff_factor=1, # exponential backoff between attempts
status_forcelist=[429, 502, 503, 504], # retry on rate-limit / gateway errors
allowed_methods=["GET", "PUT", "DELETE", "POST"],
)
client = client_from_credentials(
url="https://your.trendminer.cloud",
client_id="your-client",
client_secret="...", # load from a .env file or keyring
transport=RetryTransport(retry=retry),
)
```
`status_forcelist` limits retries to transient responses — 429 (too many requests) and the 502/503/504 gateway errors — while `allowed_methods` opts even non-idempotent `POST` requests into the policy. Tune these to taste; the same `transport` argument works with every factory function.
# `client_from_credentials`
## trendminer_interface.client_from_credentials
```
client_from_credentials(
url: str,
client_id: str,
client_secret: str,
username: str | None = None,
password: str | None = None,
tz: ZoneInfo | str = ZoneInfo("UTC"),
verify: bool = True,
timeout: float | tuple[float, float] = (10, 120),
transport: BaseTransport | None = None,
check_version: bool = True,
) -> TrendMinerClient
```
Create a TrendMinerClient from credentials
Providing client id and client secret leads to client authentication. The resulting client will have the permissions of that client user. To authenticate as a specific user, username and password need to be provided. The resulting permissions will be of that user, ignoring any permissions linked to the client id.
Some functions may require admin permissions. Only actual users can have these permissions.
Credentials are validated immediately: the client authenticates with the appliance as it is created, so invalid credentials raise straight away rather than on first use. When `username` is given, `password` must be given as well.
Parameters:
| Name | Type | Description | Default |
| --------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `url` | `str` | TrendMiner appliance url | *required* |
| `client_id` | `str` | Valid client id for the given appliance. | *required* |
| `client_secret` | `str` | Client secret matching the given client id. | *required* |
| `username` | `str` | Setting username provides access to the resources of this user (e.g., saved items). Requires password to be set as well. Only works for local users, not for SSO (LDAP/SAML) users. | `None` |
| `password` | `str` | Password matching the given username. | `None` |
| `tz` | `str or ZoneInfo` | Client timezone. All time outputs given in client timezone. All inputs without explicit timezone are considered to be in the client timezone. | `UTC` |
| `verify` | `bool` | Sets verify parameter for the requests to appliance. Setting to False prevents SSLError in case appliance SSL certificates are not valid. | `True` |
| `timeout` | `float or tuple` | Timeout settings for requests. | `(10, 120)` |
| `transport` | `BaseTransport` | Custom httpx transport for the underlying httpx.Client. | `None` |
| `check_version` | `bool` | Whether to check if the TrendMiner appliance version is supported by this SDK version. If True, a warning is raised if the appliance version does not match the supported versions. | `True` |
Returns:
| Type | Description |
| ------------------ | ----------- |
| `TrendMinerClient` | |
Raises:
| Type | Description |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `HTTPStatusError` | If the appliance rejects the credentials during the initial token request performed while the client is being created. |
See Also
client_from_refresh_token : Authenticate an SSO user from a browser-obtained refresh token. client_from_env : Authenticate from a host-provided token (MLHub notebooks, Custom Calculations). client_with_bearer_auth : Authenticate with a caller-supplied token provider.
Examples:
Authenticating as a client user:
```
>>> from trendminer_interface import client_from_credentials
>>> client = client_from_credentials(
... url="https://your.trendminer.cloud",
... client_id="your-client",
... client_secret="...", # load from a .env file or keyring, never hard-code
... )
```
Authenticating as a local user with custom timezone:
```
>>> client = client_from_credentials(
... url="https://your.trendminer.cloud",
... client_id="your-client",
... client_secret="...", # load from a .env file or keyring, never hard-code
... username="jane.doe",
... password="...", # load from a .env file or keyring, never hard-code
... tz="Europe/Brussels",
... )
```
# `client_from_env`
## trendminer_interface.client_from_env
```
client_from_env(
tz: ZoneInfo | str = ZoneInfo("UTC"),
verify: bool = True,
timeout: float | tuple[float, float] = (10, 120),
transport: BaseTransport | None = None,
) -> TrendMinerClient
```
Create a TrendMinerClient from environmental variables
Reads an access token from `KERNEL_USER_TOKEN` (set inside MLHub notebooks) or, if that is not set, `ACCESS_TOKEN` (set for Custom Calculations). The token is re-read from the environment on every request, so a token rotated by the host is picked up automatically. The appliance URL is derived from the token itself.
Unlike the other factories, no appliance version check is performed — that responsibility is left to the embedding application, whose SDK and appliance versions are expected to match.
Parameters:
| Name | Type | Description | Default |
| ----------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `tz` | `str or ZoneInfo` | Client timezone. All time outputs given in client timezone. All inputs without explicit timezone are considered to be in the client timezone. | `UTC` |
| `verify` | `bool` | Sets verify parameter for the requests to appliance. Setting to False prevents SSLError in case appliance SSL certificates are not valid. | `True` |
| `timeout` | `float or tuple` | Timeout settings for requests. | `(10, 120)` |
| `transport` | `BaseTransport` | Custom httpx transport for the underlying httpx.Client. | `None` |
Returns:
| Type | Description |
| ------------------ | ----------- |
| `TrendMinerClient` | |
Raises:
| Type | Description |
| ------------ | ------------------------------------------------------------------------ |
| `ValueError` | If neither KERNEL_USER_TOKEN nor ACCESS_TOKEN is set in the environment. |
See Also
client_with_bearer_auth : Supply the token through a callable instead of the environment.
Examples:
```
>>> from trendminer_interface import client_from_env
>>> client = client_from_env() # inside an MLHub notebook or Custom Calculation
```
# `client_from_refresh_token`
## trendminer_interface.client_from_refresh_token
```
client_from_refresh_token(
refresh_token: str,
client_id: str,
client_secret: str,
tz: ZoneInfo | str = ZoneInfo("UTC"),
verify: bool = True,
timeout: float | tuple[float, float] = (10, 120),
transport: BaseTransport | None = None,
check_version: bool = True,
) -> TrendMinerClient
```
Create a TrendMinerClient from a refresh token
Intended use case is to run automations for SSO-based users, who cannot use the password grant type. The refresh token can be obtained by logging in to the TrendMiner appliance via the browser, opening the developer tools, and copying the refresh token.
A client ID and client secret are still required, but the resulting client will have the permissions of the user linked to the refresh token. The appliance URL is taken from the token itself, so no `url` argument is needed.
Parameters:
| Name | Type | Description | Default |
| --------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `refresh_token` | `str` | Refresh token obtained from the TrendMiner appliance. | *required* |
| `client_id` | `str` | Valid client id for the given appliance. | *required* |
| `client_secret` | `str` | Client secret matching the given client id. | *required* |
| `tz` | `str or ZoneInfo` | Client timezone. All time outputs given in client timezone. All inputs without explicit timezone are considered to be in the client timezone. | `UTC` |
| `verify` | `bool` | Sets verify parameter for the requests to appliance. Setting to False prevents SSLError in case appliance SSL certificates are not valid. | `True` |
| `timeout` | `float or tuple` | Timeout settings for requests. | `(10, 120)` |
| `transport` | `BaseTransport` | Custom httpx transport for the underlying httpx.Client. | `None` |
| `check_version` | `bool` | Whether to check if the TrendMiner appliance version is supported by this SDK version. If True, a warning is raised if the appliance version does not match the supported versions. | `True` |
Returns:
| Type | Description |
| ------------------ | ----------- |
| `TrendMinerClient` | |
Raises:
| Type | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `HTTPStatusError` | If the appliance rejects the refresh token during the initial token request performed while the client is being created. |
See Also
client_from_credentials : Authenticate a client user or local user from credentials.
Notes
The refresh token is rotated on every refresh: once the client refreshes, the token you originally copied from the browser is no longer valid. For long-running automations keep the client alive rather than recreating it from the same copied token.
# `client_with_bearer_auth`
## trendminer_interface.client_with_bearer_auth
```
client_with_bearer_auth(
access_token_provider: Callable[[], str],
server_url: str,
tz: ZoneInfo | str = ZoneInfo("UTC"),
verify: bool = True,
timeout: float | tuple[float, float] = (10, 120),
transport: BaseTransport | None = None,
) -> TrendMinerClient
```
Create a TrendMinerClient authenticated with a bearer token.
Use this when embedding the SDK into an application that manages its own authentication. The SDK does not cache, refresh, or track the expiry of the token — `access_token_provider` is called on every request and is fully responsible for returning a currently-valid token (for example by caching and refreshing internally). Because no token exchange happens up front, an invalid token surfaces only on the first request, as an `AuthenticationError`.
Parameters:
| Name | Type | Description | Default |
| ----------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `access_token_provider` | `Callable[[], str]` | Zero-argument callable that returns a currently-valid access token string. Called on every request, so it should be cheap and thread-safe. | *required* |
| `server_url` | `str` | Base URL of the TrendMiner appliance. | *required* |
| `tz` | `str or ZoneInfo` | Client timezone. All time outputs given in client timezone. All inputs without explicit timezone are considered to be in the client timezone. | `UTC` |
| `verify` | `bool` | Sets verify parameter for the requests to appliance. Setting to False prevents SSLError in case appliance SSL certificates are not valid. | `True` |
| `timeout` | `float or tuple` | Timeout settings for requests. | `(10, 120)` |
| `transport` | `BaseTransport` | Custom httpx transport for the underlying httpx.Client. | `None` |
Returns:
| Type | Description |
| ------------------ | ----------- |
| `TrendMinerClient` | |
See Also
client_from_env : Read the token from the environment instead of a callable. client_from_refresh_token : Let the SDK manage token refresh from a refresh token.
# Objects & Types
The interface exposes several kinds of classes. You rarely construct them yourself — you reach them by navigating the client and calling its methods.
- **Interfaces** — the facade classes reached as namespaces on the client (for example `client.tag_builder.aggregation`). Each groups related methods and sub-namespaces. See the **[Interface tree](https://trendminercs.github.io/trendminer-interface/reference/interface-tree/index.md)** for the full hierarchy.
- **Objects** — the resources returned by interface methods (for example `Aggregation`, `Asset`, `Dashboard`). These carry the data and behaviour of a single TrendMiner entity.
- **Definitions** — the `*Definition` classes you build to create new resources, typically via a `define` call, before saving them back to TrendMiner.
- **Containers** — the collection types returned by search-style methods, such as `PagedList`, `PagedDataFrame` and `PagedDict`, which stream results a page at a time.
- **Exceptions** — the errors the interface may raise, all derived from `TrendMinerError`.
Browse the sections for the full reference of each type.
## Retrieving items
Search and list methods usually return a **container** — `PagedList`, `PagedDataFrame`, or `PagedDict` — rather than a plain Python collection. A container holds only the first page of results and fetches further pages from the appliance on demand, so large result sets are never loaded all at once.
You don't iterate or index a container directly; you consume it in one of two ways:
- **Stream** — `stream()` yields items one at a time (key–value pairs for `PagedDict`), fetching the next page only once the current one is exhausted. Use it to process results without holding them all in memory.
- **Collect** — `collect()` materialises the results into a concrete `list`, `pandas.DataFrame`, or `dict`. Use it when you want the whole result set in hand.
Both default to `max_pages=10`, a guardrail against accidentally making a large number of API calls; pass `max_pages=None` to retrieve every page. The current page is always available directly as `.data`, alongside `.has_next` and `.next_page()` for manual paging.
```
tags = client.tag.search(name="Reactor*") # -> PagedList[Tag]
# Stream: process one tag at a time, paging lazily
for tag in tags.stream():
print(tag.name)
# Collect: materialise into a list (pass max_pages=None for every page)
all_tags = tags.collect(max_pages=None)
```
`PagedDataFrame` is the exception: it offers only `collect()` (returning a single concatenated `DataFrame`), while `stream()` is available on `PagedList` and `PagedDict`.
## Creating items
Creating something in TrendMiner typically involves three kinds of methods that build on one another:
- **`new(...)`** — constructs an in-memory building block that has no independent existence on the server, such as a context filter or a trend layer. These are the pieces you assemble into a larger object, and are found on the small builder facades (for example `client.context.filter.*`).
- **`define(...)`** — assembles those pieces into a local **definition** (a `*Definition` object): a complete, in-memory specification of a work organizer item that has not yet been saved.
- **`create(...)`** — persists a definition on the server and returns the live, saved work organizer item.
The example below builds and saves a ContextHub view, using all three:
```
# A context type to filter on (retrieved from the server)
anomaly = client.context.type.from_name("Anomaly")
# 1. new(...) — in-memory filter building blocks, not saved anywhere yet
type_filter = client.context.filter.context_types.new(types=[anomaly])
keyword_filter = client.context.filter.keyword.new(keywords=["shutdown"])
# 2. define(...) — assemble the pieces into a local ContextHubViewDefinition
definition = client.context.view.define(
filters=[type_filter, keyword_filter],
view_type="grid", # "grid", "gantt" or "scatter"
)
# 3. create(...) — persist on the server, returning a live ContextHubView
view = client.context.view.create(
definition=definition,
name="Shutdown events",
description="Grid view of shutdown context items",
)
```
Splitting creation this way keeps the intermediate objects reusable: the same definition can be created more than once (for instance into different folders), and the `new(...)` building blocks can be combined into different definitions.
# Interval utilities
Importing `trendminer_interface` automatically imports `interval_utilities`, which registers a pandas DataFrame accessor under the `inu` namespace — you never need to import it yourself. From that point on, any DataFrame whose index is a [`pandas.IntervalIndex`](https://pandas.pydata.org/docs/reference/api/pandas.IntervalIndex.html) of timezone-aware timestamps gains a family of interval operations under `df.inu`: shifting, growing, shrinking and rounding interval edges, deriving new intervals relative to existing ones, inverting an index to its gaps, grouping overlapping intervals, and drawing random samples. The SDK uses these same utilities internally.
Every method returns a **new** DataFrame; nothing is edited in place. That makes the operations composable — you can chain them to shape interval data into exactly the form your analysis needs.
## Intervals, interval indices, and events
Intervals are a key concept throughout this library — they appear all over as both parameters and return types — so it is worth familiarizing yourself with pandas' own interval types before reaching for these utilities. The accessor operates directly on them, and their `closed` semantics, edge attributes and timedelta arguments all follow pandas' conventions:
- an **interval** is a single [`pandas.Interval`](https://pandas.pydata.org/docs/reference/api/pandas.Interval.html) — a span with a `left` edge, a `right` edge, and a `closed` attribute.
- **intervals** are a [`pandas.IntervalIndex`](https://pandas.pydata.org/docs/reference/api/pandas.IntervalIndex.html) — an index made up of many such intervals.
- **events** are a `pandas.DataFrame` indexed by an `IntervalIndex`, pairing each interval with the data recorded over it.
This is the vocabulary used throughout the documentation. The `inu` namespace only exists on events — a DataFrame with an `IntervalIndex`; accessing it on a DataFrame with any other index raises `AttributeError`.
## Examples
Widen every interval by an hour on each side:
```
widened = df.inu.grow(left="1h", right="1h")
```
Shift every interval an hour later in time:
```
shifted = df.inu.shift(pd.Timedelta("1h"))
```
Round interval edges to a whole hour, growing outwards so nothing is lost:
```
rounded = df.inu.round("1h", left="grow", right="grow")
```
Take the overall span of the index as a single `pandas.Interval`:
```
span = df.inu.get_span()
```
Invert the index to get the gaps between the intervals as a new set of events:
```
gaps = df.inu.invert(name="gaps")
```
Group overlapping intervals together and aggregate within each group:
```
merged = df.inu.group_overlapping().first()
```
Draw three random five-minute sub-intervals in total, spread across all the intervals:
```
samples = df.inu.sample(duration=pd.Timedelta("5m"), n=3)
```
## Reference
- **[The `inu` accessor](https://trendminercs.github.io/trendminer-interface/interval-utilities/DataFrameIntervalUtilitiesAccessor/index.md)** — full reference for every method on the accessor, with signatures and parameter descriptions.
# `DataFrameIntervalUtilitiesAccessor`
## interval_utilities.DataFrameIntervalUtilitiesAccessor
Custom accessor for interval-based calculations and utilities
This accessor is applicable to any DataFrame which has an IntervalIndex based on timezone-aware timestamps. It contains a method for performing TrendMiner-based calculations on the intervals represented by the IntervalIndex, as well as some more generic utility methods for manipulating the IntervalIndex itself.
Methods always return a modified DataFrame, they do not edit in place.
The idea of this accessor is to provide users with an interface to chain multiple calculations and interval operations to gather the data needed for their analysis, directly in the format (a pandas DataFrame) in which their custom analysis will likely take place.
Raises:
| Type | Description |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AttributeError` | If the DataFrame's index is not an IntervalIndex. This is checked on first .inu access, so accessing the namespace on a DataFrame with any other index raises immediately. |
### set_closed
```
set_closed(
closed: Literal["left", "right", "both", "neither"],
) -> DataFrame
```
Set the closed attribute of the DataFrame index
Parameters:
| Name | Type | Description | Default |
| -------- | ----- | ---------------------------- | ---------- |
| `closed` | `str` | left, right, both or neither | *required* |
Returns:
| Name | Type | Description |
| ---- | ----------- | --------------------------------------------- |
| `df` | `DataFrame` | DataFrame with altered DataFrame.index.closed |
### shift
```
shift(
by: Timedelta,
name: str | None = None,
drop: bool = True,
) -> DataFrame
```
Shift intervals by a given timedelta
Parameters:
| Name | Type | Description | Default |
| ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `by` | `Timedelta` | How much to shift the IntervalIndex. Positive values shift the intervals forward to a later time, while negative values shift backwards to an earlier time | *required* |
| `name` | `str` | Name of the new IntervalIndex | `None` |
| `drop` | `bool` | Whether to drop the original IntervalIndex, or keep it as a column in the DataFrame (under its original name) | `True` |
Returns:
| Name | Type | Description |
| ---- | ----------- | ------------------------------------ |
| `df` | `DataFrame` | DataFrame with shifted IntervalIndex |
### grow
```
grow(
left: Timedelta | None = None,
right: Timedelta | None = None,
name: str | None = None,
drop: bool = True,
) -> DataFrame
```
Extend the intervals in the index outwards, setting a new IntervalIndex
Parameters:
| Name | Type | Description | Default |
| ------- | ----------- | ------------------------------------------------------------------------------------------------------------- | ------- |
| `left` | `Timedelta` | How much to extend the interval left (start) point | `None` |
| `right` | `Timedelta` | How much to extend the interval right (end) point | `None` |
| `name` | `str` | Name of the new IntervalIndex | `None` |
| `drop` | `bool` | Whether to drop the original IntervalIndex, or keep it as a column in the DataFrame (under its original name) | `True` |
Returns:
| Name | Type | Description |
| ---- | ----------- | ------------------------------------- |
| `df` | `DataFrame` | DataFrame with extended IntervalIndex |
See Also
shrink : Shrink the intervals inwards.
### shrink
```
shrink(
left: Timedelta | None = None,
right: Timedelta | None = None,
name: str | None = None,
drop: bool = True,
) -> DataFrame
```
Shrink the intervals in the index inwards, setting a new IntervalIndex
Parameters:
| Name | Type | Description | Default |
| ------- | ----------- | ------------------------------------------------------------------------------------------------------------- | ------- |
| `left` | `Timedelta` | How much to shrink the interval left (start) point | `None` |
| `right` | `Timedelta` | How much to shrink the interval right (end) point | `None` |
| `name` | `str` | Name of the new IntervalIndex | `None` |
| `drop` | `bool` | Whether to drop the original IntervalIndex, or keep it as a column in the DataFrame (under its original name) | `True` |
Returns:
| Name | Type | Description |
| ---- | ----------- | ------------------------------------- |
| `df` | `DataFrame` | DataFrame with shrunken IntervalIndex |
See Also
grow : Extend the intervals outwards.
### after_start
```
after_start(
length: Timedelta,
name: str | None = None,
drop: bool = True,
) -> DataFrame
```
Set an IntervalIndex of given length with the same starts as the current IntervalIndex
Parameters:
| Name | Type | Description | Default |
| -------- | ----------- | ------------------------------------------------------------------------------------------------------------- | ---------- |
| `length` | `Timedelta` | The length of the intervals in the new IntervalIndex | *required* |
| `name` | `str` | Name of the new IntervalIndex | `None` |
| `drop` | `bool` | Whether to drop the original IntervalIndex, or keep it as a column in the DataFrame (under its original name) | `True` |
Returns:
| Name | Type | Description |
| ---- | ----------- | -------------------------------- |
| `df` | `DataFrame` | DataFrame with new IntervalIndex |
### after_end
```
after_end(
length: Timedelta,
name: str | None = None,
drop: bool = True,
) -> DataFrame
```
Set an IntervalIndex with intervals of given length that follows right after the current IntervalIndex
Parameters:
| Name | Type | Description | Default |
| -------- | ----------- | ------------------------------------------------------------------------------------------------------------- | ---------- |
| `length` | `Timedelta` | The length of the intervals in the new IntervalIndex | *required* |
| `name` | `str` | Name of the new IntervalIndex | `None` |
| `drop` | `bool` | Whether to drop the original IntervalIndex, or keep it as a column in the DataFrame (under its original name) | `True` |
Returns:
| Name | Type | Description |
| ---- | ----------- | -------------------------------- |
| `df` | `DataFrame` | DataFrame with new IntervalIndex |
### before_start
```
before_start(
length: Timedelta,
name: str | None = None,
drop: bool = True,
) -> DataFrame
```
Set an IntervalIndex with intervals of given length that falls right before the current IntervalIndex
Parameters:
| Name | Type | Description | Default |
| -------- | ----------- | ------------------------------------------------------------------------------------------------------------- | ---------- |
| `length` | `Timedelta` | The length of the intervals in the new IntervalIndex | *required* |
| `name` | `str` | Name of the new IntervalIndex | `None` |
| `drop` | `bool` | Whether to drop the original IntervalIndex, or keep it as a column in the DataFrame (under its original name) | `True` |
Returns:
| Name | Type | Description |
| ---- | ----------- | -------------------------------- |
| `df` | `DataFrame` | DataFrame with new IntervalIndex |
### before_end
```
before_end(
length: Timedelta,
name: str | None = None,
drop: bool = True,
) -> DataFrame
```
Set an IntervalIndex with intervals of given length with the same ends as the current IntervalIndex
Parameters:
| Name | Type | Description | Default |
| -------- | ----------- | ------------------------------------------------------------------------------------------------------------- | ---------- |
| `length` | `Timedelta` | The length of the intervals in the new IntervalIndex | *required* |
| `name` | `str` | Name of the new IntervalIndex | `None` |
| `drop` | `bool` | Whether to drop the original IntervalIndex, or keep it as a column in the DataFrame (under its original name) | `True` |
Returns:
| Name | Type | Description |
| ---- | ----------- | -------------------------------- |
| `df` | `DataFrame` | DataFrame with new IntervalIndex |
### round
```
round(
freq: Timedelta,
left: Literal["shrink", "grow", "nearest"] = "shrink",
right: Literal["shrink", "grow", "nearest"] = "shrink",
) -> DataFrame
```
Round the intervals to a given frequency
Parameters:
| Name | Type | Description | Default |
| ------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `freq` | `Timedelta` | Rounding frequency | *required* |
| `left` | `str` | 'shrink' round interval start timestamp inwards, shrinking the interval 'grow' round interval start timestamp outwards, growing the interval 'nearest' round interval start timestamp to the nearest rounded timestamp | `'shrink'` |
| `right` | `str` | 'shrink' round interval end timestamp inwards, shrinking the interval 'grow' round interval end timestamp outwards, growing the interval 'nearest' round interval end timestamp to the nearest rounded timestamp | `'shrink'` |
Returns:
| Name | Type | Description |
| ---- | ----------- | ------------------------------------ |
| `df` | `DataFrame` | DataFrame with rounded IntervalIndex |
### group_overlapping
```
group_overlapping() -> DataFrameGroupBy
```
Group overlapping intervals
Returns:
| Type | Description |
| ------------------ | ----------- |
| `DataFrameGroupBy` | |
Notes
This method will not group intervals that simply touch (i.e. when one interval's `left` is the other interval's `right`, but the `IntervalIndex.closed` is `left`, `right` or `neither`).
### invert
```
invert(
name: str, span: Interval | None = None
) -> DataFrame
```
Get the intervals in between the current intervals
The output will be sorted from oldest to newest intervals.
Parameters:
| Name | Type | Description | Default |
| ------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `name` | `str` | Name of the new, inverted IntervalIndex | *required* |
| `span` | `Interval` | Range over which the intervals need to be inverted. The time from the start of the span to the start of the leftmost interval, and the time from the rightmost interval to the end of the span are also returned as inverted intervals. Input intervals outside the given span are ignored. When no span is given, the intervals inbetween the input intervals are returned as inverted intervals. | `None` |
Returns:
| Type | Description |
| ----------- | ------------------------------------------- |
| `DataFrame` | Empty DataFrame with inverted IntervalIndex |
Notes
- The `closed` attribute of the IntervalIndex will invert 'neither' \<-> 'both', while 'left' and 'right' will stay unchanged.
See Also
get_span : Interval encompassing all intervals in the index, usable as the `span` argument.
### get_span
```
get_span() -> Interval
```
Get the interval encompassing all intervals in the index
Returns:
| Name | Type | Description |
| ------ | ---------- | -------------------------------------------- |
| `span` | `Interval` | The interval spanning the full IntervalIndex |
See Also
invert : Get the gaps between the intervals, optionally bounded by a span.
### sample
```
sample(
duration: Timedelta,
n: int = 1,
overlap: bool = False,
freq: Timedelta = Timedelta(minutes=1),
drop: bool = True,
name: str = "samples",
seed: int | Generator | None = None,
) -> DataFrame
```
Sample random sub-intervals from a given list of intervals
Parameters:
| Name | Type | Description | Default |
| ---------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| `duration` | `Timedelta` | Duration of the sample intervals | *required* |
| `n` | `int` | Total number of sample intervals to return, drawn across all input intervals (not per interval) | `1` |
| `overlap` | `bool` | Whether the returned sample intervals can overlap | `False` |
| `freq` | `Timedelta` | The resolution to which all inputs and outputs will be rounded. | `1m` |
| `drop` | `bool` | Whether to drop the original IntervalIndex in the returned DataFrame | `True` |
| `name` | `str` | Name of the new IntervalIndex column of samples | `'samples'` |
| `seed` | `int or Generator` | Seed or generator for the random sampling, for reproducible output. When omitted, a fresh non-deterministic generator is used. | `None` |
Returns:
| Name | Type | Description |
| --------- | ----------- | ----------------------------------------- |
| `samples` | `DataFrame` | DataFrame with sampled intervals as index |
Notes
Intervals will be rounded down to the given freq before sampling.
The sampling method first determines how many samples should be taken per interval, and then iteratively samples that number of sub-intervals from each interval. The number of samples per interval is distributed randomly in proportion to the number of possible sample positions within an interval. An interval can be sampled in `(interval length - duration)/freq + 1` possible ways. For example, there is only 1 way to take a 1h sample out of a 1h interval, while for a freq of 1m there are 60 ways of taking a 1h sample out of a 2h interval.
When the `IntervalIndex.closed` property is `both` it is possible that two samples theoretically overlap at their endpoints even when `overlap=False`.
# Examples
# Getting tag data[¶](#getting-tag-data)
This example shows how to load tag data.
## Setup[¶](#setup)
We start by [authenticating a client](https://trendminercs.github.io/trendminer-interface/creating-a-client/index.md). For getting data, it is imporant to realize all returned timestamps will be in the chosen client timezone (UTC by default; Brussels time in this example).
In \[1\]:
Copied!
```
import os
from dotenv import find_dotenv, load_dotenv
from trendminer_interface import client_from_credentials
# Credentials and server details are securely stored in .env.docs for our example code.
# find_dotenv walks up from the working directory to locate it, so this works
# regardless of the directory the notebook is run from.
load_dotenv(find_dotenv(".env.docs", usecwd=True))
client = client_from_credentials(
url=os.environ["TM_URL"],
client_id=os.environ["TM_CLIENT_ID"],
client_secret=os.environ["TM_CLIENT_SECRET"],
tz="Europe/Brussels",
)
```
import os from dotenv import find_dotenv, load_dotenv from trendminer_interface import client_from_credentials
# Credentials and server details are securely stored in .env.docs for our example code.
# find_dotenv walks up from the working directory to locate it, so this works
# regardless of the directory the notebook is run from.
load_dotenv(find_dotenv(".env.docs", usecwd=True)) client = client_from_credentials( url=os.environ["TM_URL"], client_id=os.environ["TM_CLIENT_ID"], client_secret=os.environ["TM_CLIENT_SECRET"], tz="Europe/Brussels", )
## Tag time series data[¶](#tag-time-series-data)
First step is loading the tags we want to get the data from.
In \[2\]:
Copied!
```
temp = client.tag.from_name("TM6-BP2-TEMP.1")
product = client.tag.from_name("TM6-BP2-PRODUCT.1")
```
temp = client.tag.from_name("TM6-BP2-TEMP.1") product = client.tag.from_name("TM6-BP2-PRODUCT.1")
We need to decide for what interval to get the data, and at what frequency. Note that the interval must be timezone-aware. Typically we will want the timezone to be identical to that of the client.
In \[3\]:
Copied!
```
import pandas as pd
interval = pd.Interval(
pd.Timestamp("2025-01-01", tz=client.tz),
pd.Timestamp("2025-02-01", tz=client.tz),
)
freq = pd.Timedelta(minutes=30)
```
import pandas as pd interval = pd.Interval( pd.Timestamp("2025-01-01", tz=client.tz), pd.Timestamp("2025-02-01", tz=client.tz), ) freq = pd.Timedelta(minutes=30)
Getting data returns a pandas series
In \[4\]:
Copied!
```
ser_temp = temp.get_data(interval=interval, freq=freq)
ser_temp
```
ser_temp = temp.get_data(interval=interval, freq=freq) ser_temp
Often we will want to get data of multiple tags in a single DataFrame. This is easy to achieve as timestamps are regular.
In \[5\]:
Copied!
```
ser_product = product.get_data(interval=interval, freq=freq)
pd.concat([ser_temp, ser_product], axis=1, keys=["temperature", "product"])
```
ser_product = product.get_data(interval=interval, freq=freq) pd.concat([ser_temp, ser_product], axis=1, keys=["temperature", "product"])
## Getting aggregated data[¶](#getting-aggregated-data)
You can also get aggregated data directly from a tag by first defining the intervals for which you want to get data. These intervals will form the index of the result.
In \[6\]:
Copied!
```
intervals = pd.interval_range(
start=pd.Timestamp("2025-01-01", tz=client.tz),
end=pd.Timestamp("2025-01-10", tz=client.tz),
freq="D", # daily frequency
)
daily_temp = temp.get_aggregation(intervals=intervals, method="mean")
daily_temp
```
intervals = pd.interval_range( start=pd.Timestamp("2025-01-01", tz=client.tz), end=pd.Timestamp("2025-01-10", tz=client.tz), freq="D", # daily frequency ) daily_temp = temp.get_aggregation(intervals=intervals, method="mean") daily_temp
This IntervalIndex can easily be converted to DateTimeIndex. For example, to just get the mean temperature per day:
In \[7\]:
Copied!
```
daily_temp.set_axis(daily_temp.index.left)
```
daily_temp.set_axis(daily_temp.index.left)
## On indexing[¶](#on-indexing)
Getting data from tags which are not indexed will fail. Index requests can be sent in advance to make sure the tags are at least partially indexed.
In \[8\]:
Copied!
```
temp.index() # index the tag and return the current index details
```
temp.index() # index the tag and return the current index details
The only way to guarantee tags have actually completed indexing is to write a loop which halts further execution until tag index status is no longer `in progress`. See the [Indexing tags](https://trendminercs.github.io/trendminer-interface/examples/indexing_tags/index.md) example for a robust implementation.
# Indexing tags[¶](#indexing-tags)
Indexing tags is an essential mechanism, as unlike the UI, attempting to use unindexed tags with the SDK will not automatically start their indexing: you will get an error instead. Additionally, you may want to use the SDK to index tags in bulk to have them ready for use (in the UI or in other SDK scripts).
Do keep in mind that confirming tags are indexed in each and every script is a lot of overhead. For most applications you are better off indexing them once and then assume they remain indexed (they will unless an admin explicitly removes the index).
## Setup[¶](#setup)
We start by [authenticating a client](https://trendminercs.github.io/trendminer-interface/creating-a-client/index.md).
In \[1\]:
Copied!
```
import os
from dotenv import find_dotenv, load_dotenv
from trendminer_interface import client_from_credentials
# Credentials and server details are securely stored in .env.docs for our example code.
# find_dotenv walks up from the working directory to locate it, so this works
# regardless of the directory the notebook is run from.
load_dotenv(find_dotenv(".env.docs", usecwd=True))
client = client_from_credentials(
url=os.environ["TM_URL"],
client_id=os.environ["TM_CLIENT_ID"],
client_secret=os.environ["TM_CLIENT_SECRET"],
)
```
import os from dotenv import find_dotenv, load_dotenv from trendminer_interface import client_from_credentials
# Credentials and server details are securely stored in .env.docs for our example code.
# find_dotenv walks up from the working directory to locate it, so this works
# regardless of the directory the notebook is run from.
load_dotenv(find_dotenv(".env.docs", usecwd=True)) client = client_from_credentials( url=os.environ["TM_URL"], client_id=os.environ["TM_CLIENT_ID"], client_secret=os.environ["TM_CLIENT_SECRET"], )
## Indexing tags[¶](#indexing-tags)
To make sure tags are indexed, we need to keep checking the status until indexing completed sucessfully. This is a way to make sure that tags are indexed for following script steps. This step may take a very long time if there are many other tags already indexing on the server.
It is possible that a tag finishes indexing with an error or warning (any status other than `ok`). You may want to show a warning or raise an error in such a case.
Best practice is to check the amount of tags which are currently indexing and only add more tags to the queue when there is room. This will always leave room for other users' indexing needs.
A robust indexing function ends up looking like this:
In \[2\]:
Copied!
```
import time
import warnings
from trendminer_interface import Tag
def wait_until_indexed(tags: list[Tag]):
"""Function that waits until all tags are indexed"""
# copy the tag list to not edit original
tags_queue = tags.copy()
# Iterate over all tags and rebuild queue
while tags_queue:
new_tags_queue = [] # reset list
for tag in tags_queue:
index_details = tag.get_index_details()
# If the tag has not been indexed at all, start it
if index_details is None:
# If there are already 8 or more tags indexing, wait
while client.tag.index_details.search(statuses=["in progress"]).total_elements >= 8:
time.sleep(1) # pause 1s before checking again
index_details = tag.index() # refresh details (status becomes 'in progress')
status = index_details.status
if status == "ok":
continue # fully indexed
elif status == "in progress":
new_tags_queue.append(tag) # still ongoing
time.sleep(1) # pause 1s before checking next tag
else:
warnings.warn( # unsuccessful indexing
f"Indexing of tag '{tag}' completed with status '{status}'"
)
tags_queue = new_tags_queue
```
import time import warnings from trendminer_interface import Tag def wait_until_indexed(tags: list[Tag]): """Function that waits until all tags are indexed"""
# copy the tag list to not edit original
tags_queue = tags.copy()
# Iterate over all tags and rebuild queue
while tags_queue: new_tags_queue = [] # reset list for tag in tags_queue: index_details = tag.get_index_details()
# If the tag has not been indexed at all, start it
if index_details is None:
# If there are already 8 or more tags indexing, wait
while client.tag.index_details.search(statuses=["in progress"]).total_elements >= 8: time.sleep(1) # pause 1s before checking again index_details = tag.index() # refresh details (status becomes 'in progress') status = index_details.status if status == "ok": continue # fully indexed elif status == "in progress": new_tags_queue.append(tag) # still ongoing time.sleep(1) # pause 1s before checking next tag else: warnings.warn( # unsuccessful indexing f"Indexing of tag '{tag}' completed with status '{status}'" ) tags_queue = new_tags_queue
We can then use that function to make sure any given list of tags is indexed.
In \[3\]:
Copied!
```
tags = [
client.tag.from_name(tag_name)
for tag_name in ["TM_hour_UTC", "TM_day_UTC"]
]
wait_until_indexed(tags)
```
tags = \[ client.tag.from_name(tag_name) for tag_name in ["TM_hour_UTC", "TM_day_UTC"] \] wait_until_indexed(tags)
## Bulk indexing[¶](#bulk-indexing)
For bulk operations we will want to perform a search to get a certain set of tags in one go. Filtering on a specific datasource is good way to avoid unexpected matches from another datasource. Keep in mind the result of a tag search is always the first page of tags, not a list of tags.
In \[4\]:
Copied!
```
datasource = client.datasource.from_name("demo")
name_query = "TM6-*"
tag_page = client.tag.search(name=name_query, datasources=[datasource])
tag_page
```
datasource = client.datasource.from_name("demo") name_query = "TM6-\*" tag_page = client.tag.search(name=name_query, datasources=[datasource]) tag_page
We can collect all tags in a single list
In \[5\]:
Copied!
```
tags = tag_page.collect(max_pages=None)
```
tags = tag_page.collect(max_pages=None)
If we expect a big portion of these tags to already be indexed, it is inefficient to check the status of all of them individually. It is better the search through the indexed tags (which is much faster) as well and cross-reference this with the tag list. This way we don't waste time on tags that have already completed indexing.
In \[6\]:
Copied!
```
# Index details of the fully indexed tags
completed_details = client.tag.index_details.search(
name=name_query,
datasources=[datasource],
statuses=["ok"]
).collect(max_pages=None)
# Build list of completed tags
completed_tags = [index_details.tag for index_details in completed_details]
# Keep only the searched tags which are not in the list of completed tags
tags_to_complete = [tag for tag in tags if tag not in completed_tags]
# And wait only for these tags
wait_until_indexed(tags_to_complete)
```
# Index details of the fully indexed tags
completed_details = client.tag.index_details.search( name=name_query, datasources=[datasource], statuses=["ok"] ).collect(max_pages=None)
# Build list of completed tags
completed_tags = [index_details.tag for index_details in completed_details]
# Keep only the searched tags which are not in the list of completed tags
tags_to_complete = [tag for tag in tags if tag not in completed_tags]
# And wait only for these tags
wait_until_indexed(tags_to_complete)
# Value-based search[¶](#value-based-search)
A *value-based search* finds the intervals in time where one or more tags meet a condition — for example, every period where a flow rate stays above a threshold. This notebook builds one up in three steps:
1. a basic search,
1. the same search enriched with **calculations**, and
1. a second search run **within the results** of the first.
Each step returns a `PagedDataFrame`; we call `.collect()` to materialise it into a pandas `DataFrame` whose `IntervalIndex` holds the found events.
## Setup[¶](#setup)
We start by [authenticating a client](https://trendminercs.github.io/trendminer-interface/creating-a-client/index.md) and retrieving the tags we need for our example.
In \[1\]:
Copied!
```
import os
import pandas as pd
from dotenv import find_dotenv, load_dotenv
from trendminer_interface import client_from_credentials
# Credentials and server details are securely stored in .env.docs for our example code.
# find_dotenv walks up from the working directory to locate it, so this works
# regardless of the directory the notebook is run from.
load_dotenv(find_dotenv(".env.docs", usecwd=True))
client = client_from_credentials(
url=os.environ["TM_URL"],
client_id=os.environ["TM_CLIENT_ID"],
client_secret=os.environ["TM_CLIENT_SECRET"],
)
level = client.tag.from_name("TM6-BP2-LEVEL.1")
temp = client.tag.from_name("TM6-BP2-TEMP.1")
product = client.tag.from_name("TM6-BP2-PRODUCT.1")
```
import os import pandas as pd from dotenv import find_dotenv, load_dotenv from trendminer_interface import client_from_credentials
# Credentials and server details are securely stored in .env.docs for our example code.
# find_dotenv walks up from the working directory to locate it, so this works
# regardless of the directory the notebook is run from.
load_dotenv(find_dotenv(".env.docs", usecwd=True)) client = client_from_credentials( url=os.environ["TM_URL"], client_id=os.environ["TM_CLIENT_ID"], client_secret=os.environ["TM_CLIENT_SECRET"], ) level = client.tag.from_name("TM6-BP2-LEVEL.1") temp = client.tag.from_name("TM6-BP2-TEMP.1") product = client.tag.from_name("TM6-BP2-PRODUCT.1")
## A basic search[¶](#a-basic-search)
A value-based search is built from one or more `(tag, operator, value)` queries and a minimum `duration`, then run over a time window with `get_results`. The result is a `PagedDataFrame` whose `IntervalIndex` holds the events where the condition held — here, every period of at least 15 minutes where the level stays above 10. The `open` column tells us whether a result is still ongoing at the end of the search window.
In \[2\]:
Copied!
```
# Time window to search in
search_window = pd.Interval(
pd.Timestamp("2025-01-01", tz="UTC"),
pd.Timestamp("2026-01-01", tz="UTC"),
)
high_level = client.search.value.define(
queries=[
(level, ">", 10),
],
duration=pd.Timedelta(minutes=15),
)
df_high_level = high_level.get_results(target=search_window).collect()
df_high_level
```
# Time window to search in
search_window = pd.Interval( pd.Timestamp("2025-01-01", tz="UTC"), pd.Timestamp("2026-01-01", tz="UTC"), ) high_level = client.search.value.define( queries=[ (level, ">", 10), ], duration=pd.Timedelta(minutes=15), ) df_high_level = high_level.get_results(target=search_window).collect() df_high_level
## Adding calculations[¶](#adding-calculations)
By default a search returns only the event intervals. Passing `calculations` attaches computed columns to each event — each is a `(tag, method, unit)` tuple, keyed by the resulting column name. Here we record the product grade at the start of each event and the mean level during it.
In \[3\]:
Copied!
```
high_level = client.search.value.define(
queries=[
(level, ">", 10),
],
duration=pd.Timedelta(minutes=15),
calculations={
"product": (product, "start", ""),
"mean_level": (level, "mean", "m"),
},
)
df_high_level = high_level.get_results(target=search_window).collect()
df_high_level
```
high_level = client.search.value.define( queries=[ (level, ">", 10), ], duration=pd.Timedelta(minutes=15), calculations={ "product": (product, "start", ""), "mean_level": (level, "mean", "m"), }, ) df_high_level = high_level.get_results(target=search_window).collect() df_high_level
## Searching within results[¶](#searching-within-results)
We can search directly within other events (a DataFrame with IntervalIndex). The existing columns (calculations) of the target will be kept, showing for each new search result the values of the original interval in which the new result sits.
In \[4\]:
Copied!
```
high_temp = client.search.value.define(
queries=[
(temp, ">", 20),
],
duration=pd.Timedelta(minutes=2),
calculations={
"max_temp": (temp, "max", "degC"),
}
)
df_high_temp = high_temp.get_results(target=df_high_level).collect()
df_high_temp
```
high_temp = client.search.value.define( queries=[ (temp, ">", 20), ], duration=pd.Timedelta(minutes=2), calculations={ "max_temp": (temp, "max", "degC"), } ) df_high_temp = high_temp.get_results(target=df_high_level).collect() df_high_temp
# Asset Framework Navigation[¶](#asset-framework-navigation)
An asset framework provides as structure to your collection of tags that make them easier to understand and navigate. Furthermore an asset framework allows cross-asset functionalities, as illustrated in the [Cross-Asset Rollout](https://trendminercs.github.io/trendminer-interface/examples/cross_asset_rollout/index.md) example.
## Setup[¶](#setup)
We start by [authenticating a client](https://trendminercs.github.io/trendminer-interface/creating-a-client/index.md) and retrieving the tags we need for our example. Keep in mind the authenticated user will need access to the asset framework.
In \[1\]:
Copied!
```
import os
import pandas as pd
from dotenv import find_dotenv, load_dotenv
from trendminer_interface import client_from_credentials
# Credentials and server details are securely stored in .env.docs for our example code.
# find_dotenv walks up from the working directory to locate it, so this works
# regardless of the directory the notebook is run from.
load_dotenv(find_dotenv(".env.docs", usecwd=True))
client = client_from_credentials(
url=os.environ["TM_URL"],
client_id=os.environ["TM_CLIENT_ID"],
client_secret=os.environ["TM_CLIENT_SECRET"],
username=os.environ["TM_USERNAME"],
password=os.environ["TM_PASSWORD"],
tz="Europe/Brussels",
)
```
import os import pandas as pd from dotenv import find_dotenv, load_dotenv from trendminer_interface import client_from_credentials
# Credentials and server details are securely stored in .env.docs for our example code.
# find_dotenv walks up from the working directory to locate it, so this works
# regardless of the directory the notebook is run from.
load_dotenv(find_dotenv(".env.docs", usecwd=True)) client = client_from_credentials( url=os.environ["TM_URL"], client_id=os.environ["TM_CLIENT_ID"], client_secret=os.environ["TM_CLIENT_SECRET"], username=os.environ["TM_USERNAME"], password=os.environ["TM_PASSWORD"], tz="Europe/Brussels", )
## Retrieving specific assets[¶](#retrieving-specific-assets)
The deterministic way of retrieving a specific path is by its path of asset names, starting with the root asset. The root asset has the same name as the asset framework.
In \[2\]:
Copied!
```
framework_name = "DO NOT EDIT"
asset = client.asset_framework.asset.from_path(
names=[framework_name, "Houston", "Time"]
)
asset
```
framework_name = "DO NOT EDIT" asset = client.asset_framework.asset.from_path( names=[framework_name, "Houston", "Time"] ) asset
We can always get the full hierarchy from an `Asset` instance:
In \[3\]:
Copied!
```
asset.get_hierarchy()
```
asset.get_hierarchy()
## Navigating the tree[¶](#navigating-the-tree)
From an asset, we can always retrieve its children (which can be `Asset` or `Attribute` instances), as well as its parent `Asset`.
In \[4\]:
Copied!
```
asset.search_children().collect()
```
asset.search_children().collect()
In \[5\]:
Copied!
```
asset.parent
```
asset.parent
Sometimes we will want to grab a specific child asset or attribute.
In \[6\]:
Copied!
```
asset.get_child_attribute(name="Hour")
```
asset.get_child_attribute(name="Hour")
## Searching for assets[¶](#searching-for-assets)
We often want to search for a specific set of assets, so we can apply the same operation to them. For example, we can look for all of the assets with a certain name in a specific asset framework:
In \[7\]:
Copied!
```
framework = client.asset_framework.from_name(framework_name)
assets = client.asset_framework.asset.search(
name="Time",
frameworks=[framework],
).collect()
assets
```
framework = client.asset_framework.from_name(framework_name) assets = client.asset_framework.asset.search( name="Time", frameworks=[framework], ).collect() assets
A more robust approach is to explicitly define asset templates in our framework, and use these to search.
In \[8\]:
Copied!
```
assets[0].template
```
assets[0].template
In \[9\]:
Copied!
```
client.asset_framework.asset.search(
template="time tags",
frameworks=[framework],
).collect()
```
client.asset_framework.asset.search( template="time tags", frameworks=[framework], ).collect()
Or we might want to navigate to a specific parent asset first, and then search in its direct children. Note that the `*` is a wildcard character in the search.
In \[10\]:
Copied!
```
from trendminer_interface import Asset
parent_asset = client.asset_framework.asset.from_path(
names=["cip"],
)
assets = parent_asset.search_children(
name="CIP Unit *",
child_type=Asset,
).collect()
assets
```
from trendminer_interface import Asset parent_asset = client.asset_framework.asset.from_path( names=["cip"], ) assets = parent_asset.search_children( name="CIP Unit \*", child_type=Asset, ).collect() assets
We can also search in all decendants of an asset (direct or indirect):
In \[13\]:
Copied!
```
client.asset_framework.asset.search(
name="CIP Unit *",
ancestor=parent_asset,
).collect()
```
client.asset_framework.asset.search( name="CIP Unit \*", ancestor=parent_asset, ).collect()
# Managing Work Items[¶](#managing-work-items)
The SDK allows us to create and update items in the work organizer of the authenticated user. This example uses value-based searches throughout, but the same retrieve, search, create, update and delete patterns apply to every saved item type.
For the object model behind these items — the interface facades, the objects they return, and the `*Definition` builders used to create them — see [Objects & Types](https://trendminercs.github.io/trendminer-interface/objects-and-types/index.md) and the [Interface tree](https://trendminercs.github.io/trendminer-interface/reference/interface-tree/index.md).
## Setup[¶](#setup)
We start by [authenticating our user](https://trendminercs.github.io/trendminer-interface/creating-a-client/index.md).
In \[1\]:
Copied!
```
import os
import pandas as pd
from dotenv import find_dotenv, load_dotenv
from trendminer_interface import client_from_credentials
# Credentials and server details are securely stored in .env.docs for our example code.
# find_dotenv walks up from the working directory to locate it, so this works
# regardless of the directory the notebook is run from.
load_dotenv(find_dotenv(".env.docs", usecwd=True))
client = client_from_credentials(
url=os.environ["TM_URL"],
client_id=os.environ["TM_CLIENT_ID"],
client_secret=os.environ["TM_CLIENT_SECRET"],
username=os.environ["TM_USERNAME"],
password=os.environ["TM_PASSWORD"],
tz="Europe/Brussels",
)
```
import os import pandas as pd from dotenv import find_dotenv, load_dotenv from trendminer_interface import client_from_credentials
# Credentials and server details are securely stored in .env.docs for our example code.
# find_dotenv walks up from the working directory to locate it, so this works
# regardless of the directory the notebook is run from.
load_dotenv(find_dotenv(".env.docs", usecwd=True)) client = client_from_credentials( url=os.environ["TM_URL"], client_id=os.environ["TM_CLIENT_ID"], client_secret=os.environ["TM_CLIENT_SECRET"], username=os.environ["TM_USERNAME"], password=os.environ["TM_PASSWORD"], tz="Europe/Brussels", )
## Retrieving specific items[¶](#retrieving-specific-items)
To get an item from a specific location in our work organizer, we first retrieve the folder the item is in:
In \[3\]:
Copied!
```
folder = client.work.folder.from_path(names=["SDK work example"])
folder
```
folder = client.work.folder.from_path(names=["SDK work example"]) folder
We can then get an item with a specific name and of a specific type directly from this folder:
In \[4\]:
Copied!
```
from trendminer_interface import ValueBasedSearch
folder.get_item(
name="SDK example search 1",
content_type=ValueBasedSearch,
)
```
from trendminer_interface import ValueBasedSearch folder.get_item( name="SDK example search 1", content_type=ValueBasedSearch, )
If the item to retrieve sits directly in your home folder, you can do the following instead:
In \[5\]:
Copied!
```
client.work.my_work.get_item(
name="SDK example search 2",
content_type=ValueBasedSearch,
)
```
client.work.my_work.get_item( name="SDK example search 2", content_type=ValueBasedSearch, )
We can also retrieve items directly by their name from anywhere in our saved work by calling `from_name` on the appropriate interface:
In \[6\]:
Copied!
```
client.search.value.from_name("SDK example search 1")
```
client.search.value.from_name("SDK example search 1")
Note that when two or more items exist with the same name within the scope (a specific folder or the whole work organizer), an `AmbiguousResource` error will be raised.
## Searching for items[¶](#searching-for-items)
We can retrieve multiple items at once via a search in the work organizer. We filter on specific content types, or retrieve items of any content type by not passing a parameter.
From within a folder:
In \[7\]:
Copied!
```
folder.search_contents().collect()
```
folder.search_contents().collect()
From the home folder:
In \[8\]:
Copied!
```
client.work.my_work.search_contents(content_type=ValueBasedSearch).collect()
```
client.work.my_work.search_contents(content_type=ValueBasedSearch).collect()
Searching the full work organizer from a content-type-specific interface allows us to filter on a name/description `query` parameter:
In \[9\]:
Copied!
```
client.search.value.search(query="SDK *").collect()
```
client.search.value.search(query="SDK \*").collect()
## Creating, updating and deleting items[¶](#creating-updating-and-deleting-items)
The SDK allows the creation of work items of most types. Creating a new item first requires us to create a definition instance containing the desired configuration. This configuration is of course highly specific to the type of work item we are creating — see [Objects & Types](https://trendminercs.github.io/trendminer-interface/objects-and-types/index.md) for the available `*Definition` builders.
In \[10\]:
Copied!
```
hour_tag = client.tag.from_name("TM_Hour_UTC")
vbs_def = client.search.value.define(
queries=[(hour_tag, ">", 12)],
)
vbs_def
```
hour_tag = client.tag.from_name("TM_Hour_UTC") vbs_def = client.search.value.define( queries=[(hour_tag, ">", 12)], ) vbs_def
Note that these definitions can be actionable in themselves. For example, we do not need to actually save a value-based search item in the work organizer in order to get search results (see the [Value-based search](https://trendminercs.github.io/trendminer-interface/examples/value_based_search/index.md) example for more on running searches).
In \[11\]:
Copied!
```
import pandas as pd
search_interval = pd.Interval(
pd.Timestamp("2026-01-01", tz=client.tz),
pd.Timestamp("2026-02-01", tz=client.tz),
)
vbs_def.get_results(target=search_interval)
```
import pandas as pd search_interval = pd.Interval( pd.Timestamp("2026-01-01", tz=client.tz), pd.Timestamp("2026-02-01", tz=client.tz), ) vbs_def.get_results(target=search_interval)
When actually saving the work item, we need to provide a name, and optionally a description and save location (folder) as well. The action of creating the item returns the newly created item.
In \[12\]:
Copied!
```
vbs = client.search.value.create(
name="My New Search",
description="An example search",
folder=folder,
definition=vbs_def,
)
vbs
```
vbs = client.search.value.create( name="My New Search", description="An example search", folder=folder, definition=vbs_def, ) vbs
Folders do not carry a definition, and can be created directly:
In \[13\]:
Copied!
```
new_folder = client.work.folder.create(
name="New Folder",
folder=None, # place in home folder
)
new_folder
```
new_folder = client.work.folder.create( name="New Folder", folder=None, # place in home folder ) new_folder
We can update definition and the metadata properties of our saved items.
In \[14\]:
Copied!
```
vbs.definition.duration = pd.Timedelta(hours=1)
vbs.name = "My Updated Search"
vbs = vbs.update()
vbs
```
vbs.definition.duration = pd.Timedelta(hours=1) vbs.name = "My Updated Search" vbs = vbs.update() vbs
All work items will also have a (non-reversible) delete method:
In \[15\]:
Copied!
```
vbs.delete()
```
vbs.delete()
Deleting a folder deletes all items in it.
In \[16\]:
Copied!
```
new_folder.delete()
```
new_folder.delete()
## Caveat on deleting Tag Builder items[¶](#caveat-on-deleting-tag-builder-items)
As Tag Builder work items (`Formula`, `Aggregation`, ...) lead to the creation of a new tag, their names need to be unique over the whole TrendMiner instance. However, deleting a Tag Builder item does not free up the name for re-use. The result is that **you can never re-use the name of a deleted Tag Builder tag**.
To avoid names becoming unavailable, best practice is to rename Tag Builder items before deleting them:
In \[17\]:
Copied!
```
def safe_delete(item):
# Add the current time to the name and update
item.name = item.name + pd.Timestamp.now().isoformat()
item.update()
# We can safely delete now
item.delete()
print(f"Deleted as '{item.name}'")
agg_def = client.tag_builder.aggregation.define(
target=hour_tag,
method="mean",
position="center",
window=pd.Timedelta(hours=3),
)
agg = client.tag_builder.aggregation.create(
name="ReusableTag",
definition=agg_def,
)
safe_delete(agg)
```
def safe_delete(item):
# Add the current time to the name and update
item.name = item.name + pd.Timestamp.now().isoformat() item.update()
# We can safely delete now
item.delete() print(f"Deleted as '{item.name}'") agg_def = client.tag_builder.aggregation.define( target=hour_tag, method="mean", position="center", window=pd.Timedelta(hours=3), ) agg = client.tag_builder.aggregation.create( name="ReusableTag", definition=agg_def, ) safe_delete(agg)
Name blocking also occurs for Tag Builder items which have been implicitly deleted because the folder they were in got deleted. For safely deleting a folder that may contain Tag Builder items, we can build a folder crawler-renamer function:
In \[18\]:
Copied!
```
from trendminer_interface import Formula, Aggregation, CustomCalculation, Prediction, MachineLearningModel, Folder
tag_builder_types = [Formula, Aggregation, CustomCalculation, Prediction, MachineLearningModel]
def rename_folder_tags(folder: Folder):
# Rename tag builder items
for content_type in tag_builder_types:
for item in folder.search_contents(content_type=content_type).stream(max_pages=None):
item.name = item.name + pd.Timestamp.now().isoformat()
item.update()
print(f"Renamed to '{item.name}'")
# Recursively rename items in subfolders
for subfolder in folder.search_contents(content_type=Folder).stream(max_pages=None):
rename_folder_tags(subfolder)
# As an example, create an aggregation in the existing folder
client.tag_builder.aggregation.create(
name="ReusableTag",
definition=agg_def,
folder=folder,
)
# Rename all tag builder items in the folder
rename_folder_tags(folder)
# Folder can be safely deleted
folder.delete()
```
from trendminer_interface import Formula, Aggregation, CustomCalculation, Prediction, MachineLearningModel, Folder tag_builder_types = [Formula, Aggregation, CustomCalculation, Prediction, MachineLearningModel] def rename_folder_tags(folder: Folder):
# Rename tag builder items
for content_type in tag_builder_types: for item in folder.search_contents(content_type=content_type).stream(max_pages=None): item.name = item.name + pd.Timestamp.now().isoformat() item.update() print(f"Renamed to '{item.name}'")
# Recursively rename items in subfolders
for subfolder in folder.search_contents(content_type=Folder).stream(max_pages=None): rename_folder_tags(subfolder)
# As an example, create an aggregation in the existing folder
client.tag_builder.aggregation.create( name="ReusableTag", definition=agg_def, folder=folder, )
# Rename all tag builder items in the folder
rename_folder_tags(folder)
# Folder can be safely deleted
folder.delete()
## The upsert pattern[¶](#the-upsert-pattern)
Robust scripts check whether an item already exists before creating a new one. This prevents duplicate items with the same name from being created every time the script is run, and avoids an error for Tag Builder items (which need a unique name).
For example, to create a folder directly in our home folder only if it does not exist already, we can use the snippet below. We can run this snippet as many times as we want without creating any duplicates.
In \[19\]:
Copied!
```
from trendminer_interface.exceptions import ResourceNotFound
folder_name = "Project Folder"
# If the folder does not exist at the root level, create it
try:
folder = client.work.folder.from_path(names=[folder_name])
except ResourceNotFound:
folder = client.work.folder.create(
name=folder_name,
folder=None,
)
folder
```
from trendminer_interface.exceptions import ResourceNotFound folder_name = "Project Folder"
# If the folder does not exist at the root level, create it
try: folder = client.work.folder.from_path(names=[folder_name]) except ResourceNotFound: folder = client.work.folder.create( name=folder_name, folder=None, ) folder
For items whose definition can change, we should make sure existing items get updated to the latest configuration (insert/update → upsert).
However, it is good to have the option to skip the update of existing items for when you know no changes to the definition have occurred. Especially for Tag Builder items, you want to avoid needlessly updating the items on the server, as this will remove existing indexes of the resulting tags.
In the example below, we check whether a value-based search with a given name exists specifically in our project folder, and update it if it does.
In \[20\]:
Copied!
```
update_existing = True
vbs_name = "MySearch"
vbs_def = client.search.value.define(
queries=[(hour_tag, ">", 12)],
)
try:
vbs = folder.get_item(name=vbs_name, content_type=ValueBasedSearch)
if update_existing:
vbs.definition = vbs_def
vbs = vbs.update()
except ResourceNotFound:
vbs = client.search.value.create(
name=vbs_name,
folder=folder,
definition=vbs_def,
)
vbs
```
update_existing = True vbs_name = "MySearch" vbs_def = client.search.value.define( queries=[(hour_tag, ">", 12)], ) try: vbs = folder.get_item(name=vbs_name, content_type=ValueBasedSearch) if update_existing: vbs.definition = vbs_def vbs = vbs.update() except ResourceNotFound: vbs = client.search.value.create( name=vbs_name, folder=folder, definition=vbs_def, ) vbs
# Context items[¶](#context-items)
*Context items* are the annotations that live in TrendMiner's ContextHub: each one marks a period of time on a specific [`Tag`](https://trendminercs.github.io/trendminer-interface/reference/types/objects/Tag/index.md), [`Asset`](https://trendminercs.github.io/trendminer-interface/reference/types/objects/Asset/index.md) or [`Attribute`](https://trendminercs.github.io/trendminer-interface/reference/types/objects/Attribute/index.md), carries a [`ContextType`](https://trendminercs.github.io/trendminer-interface/reference/types/objects/ContextType/index.md), and can hold a description, keywords and typed fields.
The SDK represents a set of context items as **events** — a [`pandas.DataFrame`](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html) whose [`IntervalIndex`](https://pandas.pydata.org/docs/reference/api/pandas.IntervalIndex.html) holds each item's start and end, alongside columns for its type, component and other metadata (see [Interval utilities](https://trendminercs.github.io/trendminer-interface/interval-utilities/index.md) for this shared *events* vocabulary). Every operation in this notebook is really just building or reshaping such a DataFrame and handing it to the [`client.context`](https://trendminercs.github.io/trendminer-interface/reference/interfaces/context/index.md) facade.
This example shows how to create, retrieve, update and delete context items, and then how to populate them at scale — from a [value-based search](https://trendminercs.github.io/trendminer-interface/examples/value_based_search/index.md), from a monitor, and from a scheduled update service.
## Setup[¶](#setup)
We start by [authenticating a client](https://trendminercs.github.io/trendminer-interface/creating-a-client/index.md).
In \[1\]:
Copied!
```
import os
import pandas as pd
from dotenv import find_dotenv, load_dotenv
from trendminer_interface import client_from_credentials
# Credentials and server details are securely stored in .env.docs for our example code.
# find_dotenv walks up from the working directory to locate it, so this works
# regardless of the directory the notebook is run from.
load_dotenv(find_dotenv(".env.docs", usecwd=True))
client = client_from_credentials(
url=os.environ["TM_URL"],
client_id=os.environ["TM_CLIENT_ID"],
client_secret=os.environ["TM_CLIENT_SECRET"],
)
```
import os import pandas as pd from dotenv import find_dotenv, load_dotenv from trendminer_interface import client_from_credentials
# Credentials and server details are securely stored in .env.docs for our example code.
# find_dotenv walks up from the working directory to locate it, so this works
# regardless of the directory the notebook is run from.
load_dotenv(find_dotenv(".env.docs", usecwd=True)) client = client_from_credentials( url=os.environ["TM_URL"], client_id=os.environ["TM_CLIENT_ID"], client_secret=os.environ["TM_CLIENT_SECRET"], )
## Creating context items[¶](#creating-context-items)
Creating context items comes down to assembling a DataFrame with the right structure and passing it to [`client.context.item.create`](https://trendminercs.github.io/trendminer-interface/reference/interfaces/context.item/index.md). We build that DataFrame up one column at a time.
The index must be an [`IntervalIndex`](https://pandas.pydata.org/docs/reference/api/pandas.IntervalIndex.html) of timezone-aware timestamps — each interval becomes one context item's start and end. Here we use [`pandas.interval_range`](https://pandas.pydata.org/docs/reference/api/pandas.interval_range.html) to make one month-long item for each of the last six months, anchored to the client's timezone (`client.tz`).
In \[2\]:
Copied!
```
# 1 item per month for the last 6 months
df = pd.DataFrame(
index=pd.interval_range(
end=pd.Timestamp.now(tz=client.tz).normalize(),
freq="MS",
periods=6,
),
)
```
# 1 item per month for the last 6 months
df = pd.DataFrame( index=pd.interval_range( end=pd.Timestamp.now(tz=client.tz).normalize(), freq="MS", periods=6, ), )
The `type` column holds each item's [`ContextType`](https://trendminercs.github.io/trendminer-interface/reference/types/objects/ContextType/index.md), which we look up by name through the [`client.context.type`](https://trendminercs.github.io/trendminer-interface/reference/interfaces/context.type/index.md) interface. We assign a single type to every row here, but the column may mix types freely.
In \[3\]:
Copied!
```
context_type = client.context.type.from_name("Month Example")
df["type"] = context_type
```
context_type = client.context.type.from_name("Month Example") df["type"] = context_type
Every item is anchored to a *component* — a [`Tag`](https://trendminercs.github.io/trendminer-interface/reference/types/objects/Tag/index.md), [`Asset`](https://trendminercs.github.io/trendminer-interface/reference/types/objects/Asset/index.md) or [`Attribute`](https://trendminercs.github.io/trendminer-interface/reference/types/objects/Attribute/index.md) — supplied in the `component` column. We look our tag up by name with [`client.tag.from_name`](https://trendminercs.github.io/trendminer-interface/reference/interfaces/tag/index.md); see [Asset Framework navigation](https://trendminercs.github.io/trendminer-interface/examples/asset_framework_navigation/index.md) for retrieving assets and attributes instead.
In \[4\]:
Copied!
```
month_tag = client.tag.from_name("TM_Month_UTC")
df["component"] = month_tag
```
month_tag = client.tag.from_name("TM_Month_UTC") df["component"] = month_tag
Two further columns are recognised as first-class item metadata: `description` (a string) and `keywords` (a list of strings per row). Both are optional.
In \[5\]:
Copied!
```
description = "Monthly overview"
df["description"] = description
keywords = ["sdk"]
df["keywords"] = [keywords] * len(df)
```
description = "Monthly overview" df["description"] = description keywords = ["sdk"] df["keywords"] = [keywords] * len(df)
Any remaining columns are stored as **fields** on the item. When a column name matches the [`key`](https://trendminercs.github.io/trendminer-interface/reference/types/objects/ContextField/index.md) of one of the type's [`fields`](https://trendminercs.github.io/trendminer-interface/reference/types/objects/ContextType/index.md) (`ContextType.fields`), its value is shown and formatted in that field in TrendMiner; a column that matches no field key appears instead as an *Other Property*.
In \[6\]:
Copied!
```
df["month"] = df.index.left.month_name()
```
df["month"] = df.index.left.month_name()
The completed DataFrame looks like this:
In \[7\]:
Copied!
```
df
```
df
With the DataFrame complete, a single call creates every item on the server:
In \[8\]:
Copied!
```
client.context.item.create(items=df)
```
client.context.item.create(items=df)
## Retrieving, updating and deleting context items[¶](#retrieving-updating-and-deleting-context-items)
Items are retrieved by describing *which* items you want with a set of **filters**. Each filter is built from the [`client.context.filter`](https://trendminercs.github.io/trendminer-interface/reference/interfaces/context.filter/index.md) interface; combined, they narrow the result down to the items created above. Filtering on [`created_by`](https://trendminercs.github.io/trendminer-interface/reference/types/objects/ContextCreatedByFilter/index.md) is the only way to fully control what comes back — other users may have created items that match the rest of your filters.
The filters are bundled into a [`ContextHubViewDefinition`](https://trendminercs.github.io/trendminer-interface/reference/types/definitions/ContextHubViewDefinition/index.md) via [`client.context.view.define`](https://trendminercs.github.io/trendminer-interface/reference/interfaces/context.view/index.md), whose `get_items` returns a lazy [`PagedDataFrame`](https://trendminercs.github.io/trendminer-interface/reference/types/containers/PagedDataFrame/index.md); calling `collect` materialises it into an events DataFrame. Notice that creating the items added a lot of metadata (keys, identifiers, timestamps), while the data we supplied came back intact.
In \[9\]:
Copied!
```
context_filters = [
client.context.filter.created_by.new(users=[client.user.self]),
client.context.filter.period.new(period=pd.Timedelta(days=200)),
client.context.filter.context_types.new(types=[context_type]),
client.context.filter.keyword.new(keywords=["sdk"]),
client.context.filter.components.new(queries=[(month_tag, "self")])
]
chv_def = client.context.view.define(
filters=context_filters,
)
df = chv_def.get_items().collect()
df
```
context_filters = \[ client.context.filter.created_by.new(users=[client.user.self]), client.context.filter.period.new(period=pd.Timedelta(days=200)), client.context.filter.context_types.new(types=[context_type]), client.context.filter.keyword.new(keywords=["sdk"]), client.context.filter.components.new(queries=[(month_tag, "self")]) \] chv_def = client.context.view.define( filters=context_filters, ) df = chv_def.get_items().collect() df
To update items, modify the DataFrame and pass it to [`client.context.item.update`](https://trendminercs.github.io/trendminer-interface/reference/interfaces/context.item/index.md). Rows are matched to existing items through the `identifier` column that `get_items` returned, so keep that column intact.
In \[10\]:
Copied!
```
df["description"] = "Updated item"
client.context.item.update(df)
```
df["description"] = "Updated item" client.context.item.update(df)
The most efficient way to delete items is [`ContextHubViewDefinition.delete_items`](https://trendminercs.github.io/trendminer-interface/reference/types/definitions/ContextHubViewDefinition/index.md), which removes every item matching the definition's filters. This is powerful and easy to misuse: with loose filters you can delete far more than you intended. As a safeguard, always include at least a [`ContextCreatedByFilter`](https://trendminercs.github.io/trendminer-interface/reference/types/objects/ContextCreatedByFilter/index.md) scoped to specific users (usually yourself), so you never remove other users' items.
In \[11\]:
Copied!
```
chv_def.delete_items()
```
chv_def.delete_items()
## Populating items from a search[¶](#populating-items-from-a-search)
A common pattern is to run a [value-based search](https://trendminercs.github.io/trendminer-interface/examples/value_based_search/index.md) and turn each result into a context item — often writing the search's calculations straight into context fields. The call below reuses the search from that example and adds the `component` and `type` columns that make its result a valid input for [`create`](https://trendminercs.github.io/trendminer-interface/reference/interfaces/context.item/index.md).
Watch out for **open** results (rows where the `open` column is `True`): these create *open* context items that will never be closed, because there is no link back to the originating search. To avoid items that stay open indefinitely, either drop the open rows (creating no item for them) or clear/adjust the `open` column so a closed item is written up to the current time.
In \[12\]:
Copied!
```
now = pd.Timestamp.now(tz=client.tz)
search_interval=pd.Interval(
now - pd.Timedelta(days=180),
now,
)
vbs_def = client.search.value.define(
queries=[(month_tag, "constant")],
calculations={
"month": (month_tag, "start", ""),
}
)
df = vbs_def.get_results(search_interval).collect()
df = df[~df["open"]] # drop open results
df["component"] = month_tag
df["type"] = context_type
df["keywords"] = [keywords] * len(df)
df["description"] = description
df
```
now = pd.Timestamp.now(tz=client.tz) search_interval=pd.Interval( now - pd.Timedelta(days=180), now, ) vbs_def = client.search.value.define( queries=[(month_tag, "constant")], calculations={ "month": (month_tag, "start", ""), } ) df = vbs_def.get_results(search_interval).collect() df = df\[~df["open"]\] # drop open results df["component"] = month_tag df["type"] = context_type df["keywords"] = [keywords] * len(df) df["description"] = description df
## Creating items automatically with a monitor[¶](#creating-items-automatically-with-a-monitor)
Rather than writing historic items by hand, we can attach a **monitor** to a saved search so that every new result automatically becomes a context item. We persist the search with [`client.search.value.create`](https://trendminercs.github.io/trendminer-interface/reference/interfaces/search.value/index.md), take its monitor with `get_monitor`, and configure the monitor's [context settings](https://trendminercs.github.io/trendminer-interface/reference/types/objects/ContextItemMonitorNotification/index.md) — the type, component, description and keywords each new item should get. The same technique is used as part of the [Cross-asset rollout](https://trendminercs.github.io/trendminer-interface/examples/cross_asset_rollout/index.md) example.
In \[13\]:
Copied!
```
vbs = client.search.value.create(
name="SDK Example - Months",
definition=vbs_def,
)
monitor = vbs.get_monitor()
monitor.context.context_type = context_type
monitor.context.component = month_tag
monitor.context.description = description
monitor.context.keywords = keywords
monitor.context.enabled = True
monitor.update()
monitor.enable()
```
vbs = client.search.value.create( name="SDK Example - Months", definition=vbs_def, ) monitor = vbs.get_monitor() monitor.context.context_type = context_type monitor.context.component = month_tag monitor.context.description = description monitor.context.keywords = keywords monitor.context.enabled = True monitor.update() monitor.enable()
## Backfilling without creating duplicates[¶](#backfilling-without-creating-duplicates)
Typically we want a monitor for new events *and* a one-off backfill of the historic events that predate it. The catch: naively re-running the backfill creates duplicate items every time. Rather than relying on running it exactly once, the robust approach is to cross-reference the items that already exist and create only the ones that are missing — the same upsert idea used in [Managing work items](https://trendminercs.github.io/trendminer-interface/examples/managing_work_items/index.md).
In \[14\]:
Copied!
```
# `df` still holds the items initialised from the search above.
# Retrieve every item that already exists (all pages).
df_existing = chv_def.get_items().collect(max_pages=None)
# Keep only the intervals that are not present yet, and create those.
df_new = df[~df.index.isin(df_existing.index)]
client.context.item.create(df_new)
```
# `df` still holds the items initialised from the search above.
# Retrieve every item that already exists (all pages).
df_existing = chv_def.get_items().collect(max_pages=None)
# Keep only the intervals that are not present yet, and create those.
df_new = df[~df.index.isin(df_existing.index)] client.context.item.create(df_new)
## Keeping fields up to date with an update service[¶](#keeping-fields-up-to-date-with-an-update-service)
Items created by a monitor cannot carry dynamic calculations. To enrich them with calculations that are only correct once the event has finished, run a small update script on a schedule.
Two practical points make that script both safe and cheap:
- Filter on the target field being **empty** (a [`ContextStringFieldFilter`](https://trendminercs.github.io/trendminer-interface/reference/types/objects/ContextStringFieldFilter/index.md) in `"empty"` mode) so you only touch items that have not been updated yet.
- Filter on the item being **closed** (a [`ContextStateFilter`](https://trendminercs.github.io/trendminer-interface/reference/types/objects/ContextStateFilter/index.md)), since a still-open result gives premature calculation results — an integral or average would only cover the event up to *now*.
It is also good practice to update the index of the tags your calculations need at the start of the script; see [Indexing tags](https://trendminercs.github.io/trendminer-interface/examples/indexing_tags/index.md).
In \[15\]:
Copied!
```
month_tag.index()
context_field = client.context.field.from_name("month")
field_filter = client.context.filter.string_field.new(
field=context_field,
mode="empty",
)
state_filter = client.context.filter.state.new(
mode="closed",
)
# Keep the previous filters, add empty field filter
context_filters_update = context_filters + [field_filter]
chv_def_update = client.context.view.define(
filters=context_filters_update,
)
# Get items, update the `month` field
df = chv_def_update.get_items().collect()
df = month_tag.add_aggregation(events=df, method="start", name="month")
client.context.item.update(df)
```
month_tag.index() context_field = client.context.field.from_name("month") field_filter = client.context.filter.string_field.new( field=context_field, mode="empty", ) state_filter = client.context.filter.state.new( mode="closed", )
# Keep the previous filters, add empty field filter
context_filters_update = context_filters + [field_filter] chv_def_update = client.context.view.define( filters=context_filters_update, )
# Get items, update the `month` field
df = chv_def_update.get_items().collect() df = month_tag.add_aggregation(events=df, method="start", name="month") client.context.item.update(df)
# Cross-Asset Rollout[¶](#cross-asset-rollout)
The SDK provides a way to do bulk creation of work items by iterating over a set of assets. In this example, we will programatically create aggregation tags, TrendHub views, searches, monitors, ContextHub vies and dashboards for Cleaning in Place (CIP) assets.
If no asset framework is available, you can opt to iterate over tags instead by programatically inferring the tag names if the the names are systematically structured. If tag names are not uniform you can create a file of tag names for the script to read, though generating such a file would roughly be the same amount of effort as the cleaner and more permanent solution of building an asset framework in TrendMiner.
## Setup[¶](#setup)
We start by [authenticating a client](https://trendminercs.github.io/trendminer-interface/creating-a-client/index.md) and retrieving the tags we need for our example. Keep in mind the authenticated user will need access to the asset framework.
In \[1\]:
Copied!
```
import os
import pandas as pd
from dotenv import find_dotenv, load_dotenv
from trendminer_interface import client_from_credentials
# Credentials and server details are securely stored in .env.docs for our example code.
# find_dotenv walks up from the working directory to locate it, so this works
# regardless of the directory the notebook is run from.
load_dotenv(find_dotenv(".env.docs", usecwd=True))
client = client_from_credentials(
url=os.environ["TM_URL"],
client_id=os.environ["TM_CLIENT_ID"],
client_secret=os.environ["TM_CLIENT_SECRET"],
username=os.environ["TM_USERNAME"],
password=os.environ["TM_PASSWORD"],
tz="Europe/Brussels",
)
```
import os import pandas as pd from dotenv import find_dotenv, load_dotenv from trendminer_interface import client_from_credentials
# Credentials and server details are securely stored in .env.docs for our example code.
# find_dotenv walks up from the working directory to locate it, so this works
# regardless of the directory the notebook is run from.
load_dotenv(find_dotenv(".env.docs", usecwd=True)) client = client_from_credentials( url=os.environ["TM_URL"], client_id=os.environ["TM_CLIENT_ID"], client_secret=os.environ["TM_CLIENT_SECRET"], username=os.environ["TM_USERNAME"], password=os.environ["TM_PASSWORD"], tz="Europe/Brussels", )
## Creating/updating items[¶](#creatingupdating-items)
As described in [Managing Work Items](https://trendminercs.github.io/trendminer-interface/examples/managing_work_items/index.md), we take care to not create duplicate items whenever we rerun the script. We define a parameter that defines what should be done if an item already exists throughout our entire script.
As long as we are simply adding additional items, we will want to ignore existing items, while if we make any changes in configuration, we will want to update the existing items as well.
In \[2\]:
Copied!
```
update_existing = True
```
update_existing = True
## Asset retrieval[¶](#asset-retrieval)
All CIP assets are named `CIP Unit *`, and sit under the `cip` parent.
In \[3\]:
Copied!
```
from trendminer_interface import Asset
parent_asset = client.asset_framework.asset.from_path(
names=["cip"],
)
assets = parent_asset.search_children(
name="CIP Unit *",
child_type=Asset,
).collect()
assets
```
from trendminer_interface import Asset parent_asset = client.asset_framework.asset.from_path( names=["cip"], ) assets = parent_asset.search_children( name="CIP Unit \*", child_type=Asset, ).collect() assets
## Folder structure[¶](#folder-structure)
All items will be stored under the same project folder, with a dedicated subfolder per asset.
In \[4\]:
Copied!
```
from trendminer_interface import Folder
from trendminer_interface.exceptions import ResourceNotFound
project_folder_name = "CIP"
# Get folder or create a new one
try:
project_folder = client.work.folder.from_path(
names=[project_folder_name]
)
except ResourceNotFound:
project_folder = client.work.folder.create(
name=project_folder_name,
folder=None, # place in root directory
)
project_folder
```
from trendminer_interface import Folder from trendminer_interface.exceptions import ResourceNotFound project_folder_name = "CIP"
# Get folder or create a new one
try: project_folder = client.work.folder.from_path( names=[project_folder_name] ) except ResourceNotFound: project_folder = client.work.folder.create( name=project_folder_name, folder=None, # place in root directory ) project_folder
We simply name the folder after the asset. We keep the folders accessible for later use.
In \[5\]:
Copied!
```
folder_dict = {}
for asset in assets:
try:
asset_folder = project_folder.get_item(
name=asset.name,
content_type=Folder,
)
except ResourceNotFound:
asset_folder = client.work.folder.create(
name=asset.name,
folder=project_folder,
)
folder_dict[asset] = asset_folder
```
folder_dict = {} for asset in assets: try: asset_folder = project_folder.get_item( name=asset.name, content_type=Folder, ) except ResourceNotFound: asset_folder = client.work.folder.create( name=asset.name, folder=project_folder, ) folder_dict[asset] = asset_folder
## Tag Builder tags[¶](#tag-builder-tags)
The first object to create are additional Tag Builder tags, since additional objects will depend on them. In this example, we want to have a smoothed version of every asset's flow measurement by using a mean-value aggregation.
To avoid name clashes with other users, we will prefix the names of the tags we created with our username. Furthermore, we of course need to make sure any derived tag names are unique.
We will store the resulting tags (not the Aggregation work items) for future use.
In \[6\]:
Copied!
```
import pandas as pd
from trendminer_interface import Aggregation
aggregation_tag_dict = {}
for asset in assets:
asset_folder = folder_dict[asset]
conductivity = asset.get_child_attribute("Flow")
aggregation_name = f"[{client.user.self.name}][{asset.name}][Flow][10m]"
aggregation_def = client.tag_builder.aggregation.define(
target=conductivity.tag,
method="mean",
position="center",
window=pd.Timedelta(minutes=10),
units="m3/h",
)
try:
aggregation = asset_folder.get_item(
name=aggregation_name,
content_type=Aggregation,
)
if update_existing:
aggregation.definition = aggregation_def
aggregation = aggregation.update()
except ResourceNotFound:
aggregation = client.tag_builder.aggregation.create(
name=aggregation_name,
folder=asset_folder,
definition=aggregation_def,
)
aggregation_tag = client.tag.from_name(aggregation_name)
aggregation_tag_dict[asset] = aggregation_tag
# Request to update tag index
aggregation_tag.index()
```
import pandas as pd from trendminer_interface import Aggregation aggregation_tag_dict = {} for asset in assets: asset_folder = folder_dict[asset] conductivity = asset.get_child_attribute("Flow") aggregation_name = f"[{client.user.self.name}][{asset.name}][Flow][10m]" aggregation_def = client.tag_builder.aggregation.define( target=conductivity.tag, method="mean", position="center", window=pd.Timedelta(minutes=10), units="m3/h", ) try: aggregation = asset_folder.get_item( name=aggregation_name, content_type=Aggregation, ) if update_existing: aggregation.definition = aggregation_def aggregation = aggregation.update() except ResourceNotFound: aggregation = client.tag_builder.aggregation.create( name=aggregation_name, folder=asset_folder, definition=aggregation_def, ) aggregation_tag = client.tag.from_name(aggregation_name) aggregation_tag_dict[asset] = aggregation_tag
# Request to update tag index
aggregation_tag.index()
## TrendHub views[¶](#trendhub-views)
We will create the TrendHub views that we will later add to the dashboards. We fix attribute and tag colors and scales for a uniform look.
In \[8\]:
Copied!
```
from trendminer_interface import TrendHubView
thv_dict = {}
for asset in assets:
asset_folder = folder_dict[asset]
# Phase attribute
phase = asset.get_child_attribute("Phase")
# Flow attribute and smoothed flow tag
smoothed_flow_tag = aggregation_tag_dict[asset]
smoothed_flow_tag.color = "#050dfa"
flow = asset.get_child_attribute(name="Flow")
flow.color = "#adbfdb"
flow_group = client.trend.group.new(
entries=[
smoothed_flow_tag,
flow,
],
name="Flow",
scale=(0, 70),
)
# Temperature
temperature = asset.get_child_attribute("Temperature")
# Focus chart interval
# Since we will make a locked and live view, only the duration matters
now = pd.Timestamp.now(tz=client.tz)
chart_interval = pd.Interval(
now-pd.Timedelta(days=7),
now,
)
layer = client.trend.layer.new(
interval=chart_interval,
base=True, # base layer
)
# Context interval (last 30d)
context_interval = pd.Interval(
now-pd.Timedelta(days=30),
now,
)
# View definition
chart_properties = client.trend.chart.stacked.new(locked=True)
thv_def = client.trend.view.define(
entries=[phase, flow_group, temperature],
layers=[layer],
context_interval=context_interval,
live=True,
chart_properties=chart_properties,
)
# Create/update
thv_name = asset.name + " Overview"
try:
thv = asset_folder.get_item(
name=thv_name,
content_type=TrendHubView,
)
if update_existing or True:
thv.definition = thv_def
thv.update()
except ResourceNotFound:
thv = client.trend.view.create(
name=thv_name,
folder=asset_folder,
definition=thv_def,
)
thv_dict[asset] = thv
```
from trendminer_interface import TrendHubView thv_dict = {} for asset in assets: asset_folder = folder_dict[asset]
# Phase attribute
phase = asset.get_child_attribute("Phase")
# Flow attribute and smoothed flow tag
smoothed_flow_tag = aggregation_tag_dict[asset] smoothed_flow_tag.color = "#050dfa" flow = asset.get_child_attribute(name="Flow") flow.color = "#adbfdb" flow_group = client.trend.group.new( entries=[ smoothed_flow_tag, flow, ], name="Flow", scale=(0, 70), )
# Temperature
temperature = asset.get_child_attribute("Temperature")
# Focus chart interval
# Since we will make a locked and live view, only the duration matters
now = pd.Timestamp.now(tz=client.tz) chart_interval = pd.Interval( now-pd.Timedelta(days=7), now, ) layer = client.trend.layer.new( interval=chart_interval, base=True, # base layer )
# Context interval (last 30d)
context_interval = pd.Interval( now-pd.Timedelta(days=30), now, )
# View definition
chart_properties = client.trend.chart.stacked.new(locked=True) thv_def = client.trend.view.define( entries=[phase, flow_group, temperature], layers=[layer], context_interval=context_interval, live=True, chart_properties=chart_properties, )
# Create/update
thv_name = asset.name + " Overview" try: thv = asset_folder.get_item( name=thv_name, content_type=TrendHubView, ) if update_existing or True: thv.definition = thv_def thv.update() except ResourceNotFound: thv = client.trend.view.create( name=thv_name, folder=asset_folder, definition=thv_def, ) thv_dict[asset] = thv
## Searches and monitors[¶](#searches-and-monitors)
We create a value-based search per asset, indicating whether the asset is active, as well as activate the monitor corresponding to the search. Note that creating a search automatically creates a matching monitor.
We will set up the monitor to create context items, of which we need to configure the context type.
In \[9\]:
Copied!
```
context_type = client.context.type.from_name("Operational")
context_type
```
context_type = client.context.type.from_name("Operational") context_type
In \[10\]:
Copied!
```
from trendminer_interface import ValueBasedSearch
vbs_dict = {}
for asset in assets:
active = asset.get_child_attribute("Active")
asset_folder = folder_dict[asset]
vbs_name = asset.name + " Active"
vbs_def = client.search.value.define(
queries=[(active.tag, "=", "ON")],
)
# only update the monitor when we create/update the search
update_monitor = False
try:
vbs = asset_folder.get_item(
name=vbs_name,
content_type=ValueBasedSearch,
)
if update_existing:
vbs.definition = vbs_def
vbs = vbs.update()
update_monitor = True
except ResourceNotFound:
vbs = client.search.value.create(
name=vbs_name,
folder=asset_folder,
definition=vbs_def,
)
update_monitor = True
vbs_dict[asset] = vbs
if update_monitor:
monitor = vbs.get_monitor()
# Create context items on the asset
monitor.context.component = asset
monitor.context.context_type = context_type
monitor.context.keywords = ["cip"]
monitor.context.enabled = True
# Send emails
monitor.email.subject = asset.name + " started"
monitor.email.message = f"CIP has started on asset '{asset.name}'"
monitor.email.to = ["cip@trendminer.com"]
monitor.email.enabled = True
# Update and activate the monitor
monitor.update()
monitor.enable()
```
from trendminer_interface import ValueBasedSearch vbs_dict = {} for asset in assets: active = asset.get_child_attribute("Active") asset_folder = folder_dict[asset] vbs_name = asset.name + " Active" vbs_def = client.search.value.define( queries=[(active.tag, "=", "ON")], )
# only update the monitor when we create/update the search
update_monitor = False try: vbs = asset_folder.get_item( name=vbs_name, content_type=ValueBasedSearch, ) if update_existing: vbs.definition = vbs_def vbs = vbs.update() update_monitor = True except ResourceNotFound: vbs = client.search.value.create( name=vbs_name, folder=asset_folder, definition=vbs_def, ) update_monitor = True vbs_dict[asset] = vbs if update_monitor: monitor = vbs.get_monitor()
# Create context items on the asset
monitor.context.component = asset monitor.context.context_type = context_type monitor.context.keywords = ["cip"] monitor.context.enabled = True
# Send emails
monitor.email.subject = asset.name + " started" monitor.email.message = f"CIP has started on asset '{asset.name}'" monitor.email.to = ["cip@trendminer.com"] monitor.email.enabled = True
# Update and activate the monitor
monitor.update() monitor.enable()
## ContextHub views[¶](#contexthub-views)
We can now create ContextHub views which capture the context items created from the monitors we just set up. The views created below get all context items of the specified type of the last 30d, attached to the specific CIP asset. Furthermore we filter to only retreive items we created ourselves. This is best practice to avoid other user's context items interfering with our views.
In \[11\]:
Copied!
```
from trendminer_interface import ContextHubView
chv_dict = {}
for asset in assets:
asset_folder = folder_dict[asset]
chv_name = asset.name + " runs"
chv_def = client.context.view.define(
filters=[
client.context.filter.period.new(pd.Timedelta(days=30)),
client.context.filter.components.new([(asset, "self")]),
client.context.filter.context_types.new([context_type]),
client.context.filter.created_by.new([client.user.self]),
],
view_type="grid",
)
try:
chv = asset_folder.get_item(
name=chv_name,
content_type=ContextHubView,
)
if update_existing:
chv.definition = chv_def
chv = chv.update()
except ResourceNotFound:
chv = client.context.view.create(
name=chv_name,
folder=asset_folder,
definition=chv_def,
)
chv_dict[asset] = chv
```
from trendminer_interface import ContextHubView chv_dict = {} for asset in assets: asset_folder = folder_dict[asset] chv_name = asset.name + " runs" chv_def = client.context.view.define( filters=\[ client.context.filter.period.new(pd.Timedelta(days=30)), client.context.filter.components.new([(asset, "self")]), client.context.filter.context_types.new([context_type]), client.context.filter.created_by.new([client.user.self]), \], view_type="grid", ) try: chv = asset_folder.get_item( name=chv_name, content_type=ContextHubView, ) if update_existing: chv.definition = chv_def chv = chv.update() except ResourceNotFound: chv = client.context.view.create( name=chv_name, folder=asset_folder, definition=chv_def, ) chv_dict[asset] = chv
## Dashboards[¶](#dashboards)
Everything is now in place to create a dashboard per CIP unit. Furthermore, we will create a single dashboard showing an overview of all units. We will link the overview dashboard to the unit dashboards and vice versa via text tiles.
We start by getting an overview dashboard. In this case the overview dashboard starts out without any tiles. Then we create the unit dashboards and add tiles to the overview dashboard in one go. Every unit will get its own row on the overview dashboard. Note that we can only link the unit dashboard in the overview dashboard once the unit dashboard has been saved.
In \[12\]:
Copied!
```
from trendminer_interface import Dashboard
overview_db_name = "CIP Overview"
overview_db_def = client.dashboard.define(
tiles=[],
live=True,
)
try:
overview_db = project_folder.get_item(
name=overview_db_name,
content_type=Dashboard,
)
if update_existing:
overview_db.definition = overview_db_def
overview_db = overview_db.update()
except ResourceNotFound:
overview_db = client.dashboard.create(
name=overview_db_name,
folder=project_folder,
definition=overview_db_def,
)
for i, asset in enumerate(assets):
asset_folder = folder_dict[asset]
# UNIT DASHBOARD
tiles = []
# Text tile - link back to overview
overview_tile = client.dashboard.text.new(
position=(0, 0, 4, 4),
content=f''
)
tiles.append(overview_tile)
# Flow rate gauge
flow_gauge_config = client.dashboard.gauge.config(
show_timestamp=False,
show_range_labels=False,
)
flow_gauge_tile = client.dashboard.gauge.new(
position=(4, 0, 4, 4),
component=asset.get_child_attribute("Flow"),
default_range=(0, 75, "off", "#ffffff"),
ranges=[
(1, 25, "low", "#2f8400"), # green
(25, 50, "increased", "#ffa03d"), # orange
(50, 75, "high", "#af1a00"), # red
],
title="Flow",
config=flow_gauge_config,
)
tiles.append(flow_gauge_tile)
# Temperature current value tile
temperature = asset.get_child_attribute("Temperature")
temp_value_config = client.dashboard.value.config(
show_component_names=False,
show_timestamp=False,
show_title=False,
)
temp_value_tile = client.dashboard.value.new(
position=(8, 0, 4, 4),
entries=[(temperature, "", "#4070d6", [])],
config=temp_value_config,
)
tiles.append(temp_value_tile)
# 30d run counter
counter_tile = client.dashboard.context.new(
position=(12, 0, 4, 4),
view=chv_dict[asset],
mode="count",
title="Runs last 30d",
)
tiles.append(counter_tile)
# TrendHub view tile
thv_tile_config = client.dashboard.trend.config(
show_title=False,
show_context_items=False,
)
thv_tile = client.dashboard.trend.new(
position=(0, 4, 24, 8),
view=thv_dict[asset],
config=thv_tile_config,
)
tiles.append(thv_tile)
# Create the unit dashboard
db_name = asset.name
db_def = client.dashboard.define(
tiles=tiles,
live=True,
)
try:
db = asset_folder.get_item(
name=db_name,
content_type=Dashboard,
)
if update_existing:
db.definition = db_def
db.update()
except ResourceNotFound:
db = client.dashboard.create(
name=db_name,
folder=asset_folder,
definition=db_def,
)
# OVERVIEW DASHBOARD
# Row per asset in overview, 4 high
overview_y_pos = 4*i
# Overview text tile - link to unit dashboard
unit_tile = client.dashboard.text.new(
position=(0, overview_y_pos, 4, 4),
content=f''
)
overview_db.definition.tiles.append(unit_tile)
# Reuse some of the unit tiles, but at different position
flow_gauge_tile.position = (4, overview_y_pos, 4, 4)
temp_value_tile.position = (8, overview_y_pos, 4, 4)
counter_tile.position = (12, overview_y_pos, 4, 4)
overview_db.definition.tiles.extend([
counter_tile,
temp_value_tile,
flow_gauge_tile,
])
# Update the overview dashboard
overview_db.update()
```
from trendminer_interface import Dashboard overview_db_name = "CIP Overview" overview_db_def = client.dashboard.define( tiles=[], live=True, ) try: overview_db = project_folder.get_item( name=overview_db_name, content_type=Dashboard, ) if update_existing: overview_db.definition = overview_db_def overview_db = overview_db.update() except ResourceNotFound: overview_db = client.dashboard.create( name=overview_db_name, folder=project_folder, definition=overview_db_def, ) for i, asset in enumerate(assets): asset_folder = folder_dict[asset]
# UNIT DASHBOARD
tiles = []
# Text tile - link back to overview
overview_tile = client.dashboard.text.new( position=(0, 0, 4, 4), content=f'
## [To Overview](https://trendminercs.github.io/trendminer-interface/examples/cross_asset_rollout/%7Boverview_db.url%7D)
' ) tiles.append(overview_tile)
# Flow rate gauge
flow_gauge_config = client.dashboard.gauge.config( show_timestamp=False, show_range_labels=False, ) flow_gauge_tile = client.dashboard.gauge.new( position=(4, 0, 4, 4), component=asset.get_child_attribute("Flow"), default_range=(0, 75, "off", "#ffffff"), ranges=[ (1, 25, "low", "#2f8400"), # green (25, 50, "increased", "#ffa03d"), # orange (50, 75, "high", "#af1a00"), # red ], title="Flow", config=flow_gauge_config, ) tiles.append(flow_gauge_tile)
# Temperature current value tile
temperature = asset.get_child_attribute("Temperature") temp_value_config = client.dashboard.value.config( show_component_names=False, show_timestamp=False, show_title=False, ) temp_value_tile = client.dashboard.value.new( position=(8, 0, 4, 4), entries=\[(temperature, "", "#4070d6", [])\], config=temp_value_config, ) tiles.append(temp_value_tile)
# 30d run counter
counter_tile = client.dashboard.context.new( position=(12, 0, 4, 4), view=chv_dict[asset], mode="count", title="Runs last 30d", ) tiles.append(counter_tile)
# TrendHub view tile
thv_tile_config = client.dashboard.trend.config( show_title=False, show_context_items=False, ) thv_tile = client.dashboard.trend.new( position=(0, 4, 24, 8), view=thv_dict[asset], config=thv_tile_config, ) tiles.append(thv_tile)
# Create the unit dashboard
db_name = asset.name db_def = client.dashboard.define( tiles=tiles, live=True, ) try: db = asset_folder.get_item( name=db_name, content_type=Dashboard, ) if update_existing: db.definition = db_def db.update() except ResourceNotFound: db = client.dashboard.create( name=db_name, folder=asset_folder, definition=db_def, )
# OVERVIEW DASHBOARD
# Row per asset in overview, 4 high
overview_y_pos = 4\*i
# Overview text tile - link to unit dashboard
unit_tile = client.dashboard.text.new( position=(0, overview_y_pos, 4, 4), content=f'
## [{asset.name}](https://trendminercs.github.io/trendminer-interface/examples/cross_asset_rollout/%7Bdb.url%7D)
' ) overview_db.definition.tiles.append(unit_tile)
# Reuse some of the unit tiles, but at different position
flow_gauge_tile.position = (4, overview_y_pos, 4, 4) temp_value_tile.position = (8, overview_y_pos, 4, 4) counter_tile.position = (12, overview_y_pos, 4, 4) overview_db.definition.tiles.extend([ counter_tile, temp_value_tile, flow_gauge_tile, ])
# Update the overview dashboard
overview_db.update()
# API — client & interfaces
# `TrendMinerClient`
## trendminer_interface.\_client.TrendMinerClient
Handles authentication to, and interaction with the TrendMiner appliance.
This class is the sole entry point for users of this library. It provides access to the retrieval and instantiation of all other objects, and handles authentication and session management.
Attributes:
| Name | Type | Description |
| --------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tz` | `ZoneInfo` | Client timezone. All time outputs given in client timezone. All inputs without explicit timezone are considered to be in the client timezone. |
| `session` | `Client` | Session object for making requests to the TrendMiner appliance. This session is shared across all objects created by this client, and handles authentication. |
### SUPPORTED_VERSIONS
```
SUPPORTED_VERSIONS: tuple[str, ...] = (
"2026.R1.0",
"2026.R2.0",
)
```
### session
```
session: Client = session
```
### tz
```
tz: ZoneInfo = tz
```
### url
```
url: str
```
Base URL of the TrendMiner appliance
### appliance
```
appliance: ApplianceFacade
```
Facade to TrendMiner appliance information
### asset_framework
```
asset_framework: AssetFrameworkFacade
```
Facade to interact with the asset framework
### context
```
context: ContextFacade
```
Facade to interact with context hub
### dashboard
```
dashboard: DashboardFacade
```
Facade to interact with dashboards
### datasource
```
datasource: DatasourceFacade
```
Facade to interact with tag datasources
### filter
```
filter: FilterFacade
```
Facade to interact with filters
### fingerprint
```
fingerprint: FingerprintFacade
```
Facade to interact with fingerprints
### monitor
```
monitor: MonitorFacade
```
Facade to interact with monitors
### notebook
```
notebook: NotebookFacade
```
Facade to interact with notebooks
### search
```
search: SearchFacade
```
Facade to interact with searches
### tag
```
tag: TagFacade
```
Facade to interact with tags
### tag_builder
```
tag_builder: TagBuilderFacade
```
Facade to build tags without instantiating them first
### trend
```
trend: TrendFacade
```
Facade to interact with trend hub
### user
```
user: UserFacade
```
Facade to interact with users
### work
```
work: WorkFacade
```
Facade to interact with the work organizer
# Interface tree
```
TrendMinerClient
├── appliance
│ ├── get_version → str
│ ├── get_index_resolution → Timedelta
│ └── get_index_horizon → Timestamp
├── asset_framework
│ ├── create → AssetFramework
│ ├── search → PagedList[AssetFramework]
│ ├── from_identifier → AssetFramework
│ ├── from_name → AssetFramework
│ ├── asset
│ │ ├── create → Asset
│ │ ├── from_identifier → Asset
│ │ ├── from_hex_path → Asset
│ │ ├── from_path → Asset
│ │ └── search → PagedList[Asset]
│ └── attribute
│ ├── create → Attribute
│ ├── from_identifier → Attribute
│ └── search → PagedList[Attribute]
├── context
│ ├── view
│ │ ├── define → ContextHubViewDefinition
│ │ ├── create → ContextHubView
│ │ ├── from_identifier → ContextHubView
│ │ ├── from_name → ContextHubView
│ │ └── search → PagedList[ContextHubView]
│ ├── item
│ │ ├── create → None
│ │ ├── update → None
│ │ └── delete → None
│ ├── type
│ │ ├── create → ContextType
│ │ ├── from_key → ContextType
│ │ ├── from_name → ContextType
│ │ └── search → PagedList[ContextType]
│ ├── field
│ │ ├── create → ContextField
│ │ ├── from_identifier → ContextField
│ │ ├── from_key → ContextField
│ │ ├── from_name → ContextField
│ │ └── search → PagedList[ContextField]
│ ├── workflow
│ │ ├── create → ContextWorkflow
│ │ ├── from_identifier → ContextWorkflow
│ │ ├── from_name → ContextWorkflow
│ │ └── search → PagedList[ContextWorkflow]
│ └── filter
│ ├── approval
│ │ └── new → ContextApprovalFilter
│ ├── components
│ │ └── new → ContextComponentFilter
│ ├── context_types
│ │ └── new → ContextTypeFilter
│ ├── created_by
│ │ └── new → ContextCreatedByFilter
│ ├── creation_date
│ │ └── new → ContextCreationDateFilter
│ ├── description
│ │ └── new → ContextDescriptionFilter
│ ├── duration
│ │ └── new → ContextDurationFilter
│ ├── interval
│ │ └── new → ContextIntervalFilter
│ ├── keyword
│ │ └── new → ContextKeywordFilter
│ ├── period
│ │ └── new → ContextPeriodFilter
│ ├── state
│ │ └── new → ContextStateFilter
│ ├── enumeration_field
│ │ └── new → ContextEnumerationFieldFilter
│ ├── numeric_field
│ │ └── new → ContextNumericFieldFilter
│ └── string_field
│ └── new → ContextStringFieldFilter
├── dashboard
│ ├── config → DashboardConfiguration
│ ├── define → DashboardDefinition
│ ├── create → Dashboard
│ ├── from_identifier → Dashboard
│ ├── from_name → Dashboard
│ ├── search → PagedList[Dashboard]
│ ├── context
│ │ ├── config → ContextHubViewTileConfiguration
│ │ └── new → ContextHubViewTile
│ ├── external
│ │ ├── config → ExternalContentTileConfiguration
│ │ └── new → ExternalContentTile
│ ├── gauge
│ │ ├── config → GaugeTileConfiguration
│ │ └── new → GaugeTile
│ ├── monitor
│ │ ├── config → MonitorTileConfiguration
│ │ └── new → MonitorTile
│ ├── notebook
│ │ ├── config → NotebookTileConfiguration
│ │ └── new → NotebookTile
│ ├── text
│ │ ├── config → TextTileConfiguration
│ │ └── new → TextTile
│ ├── trend
│ │ ├── config → TrendHubViewTileConfiguration
│ │ └── new → TrendHubViewTile
│ └── value
│ ├── config → CurrentValueTileConfiguration
│ └── new → CurrentValueTile
├── datasource
│ ├── from_identifier → Datasource
│ ├── from_name → Datasource
│ ├── get_builtin → list[Datasource]
│ └── search → PagedList[Datasource]
├── filter
│ ├── define → FilterDefinition
│ ├── create → Filter
│ ├── from_identifier → Filter
│ ├── from_name → Filter
│ └── search → PagedList[Filter]
├── fingerprint
│ ├── define → FingerprintDefinition
│ ├── create → Fingerprint
│ ├── from_identifier → Fingerprint
│ ├── from_name → Fingerprint
│ ├── search → PagedList[Fingerprint]
│ └── layer
│ └── new → FingerprintLayer
├── monitor
│ ├── from_identifier → Monitor
│ ├── get_overview → DataFrame
│ └── search → list[Monitor]
├── notebook
│ ├── from_identifier → Notebook
│ ├── from_name → Notebook
│ ├── search → PagedList[Notebook]
│ └── pipeline
│ ├── from_identifier → Pipeline
│ ├── from_name → Pipeline
│ └── search → PagedList[Pipeline]
├── search
│ ├── value
│ │ ├── define → ValueBasedSearchDefinition
│ │ ├── create → ValueBasedSearch
│ │ ├── from_identifier → ValueBasedSearch
│ │ ├── from_name → ValueBasedSearch
│ │ └── search → PagedList[ValueBasedSearch]
│ ├── digital_step
│ │ ├── from_identifier → DigitalStepSearch
│ │ ├── from_name → DigitalStepSearch
│ │ └── search → PagedList[DigitalStepSearch]
│ ├── similarity
│ │ ├── from_identifier → SimilaritySearch
│ │ ├── from_name → SimilaritySearch
│ │ └── search → PagedList[SimilaritySearch]
│ └── area
│ ├── from_identifier → AreaSearch
│ ├── from_name → AreaSearch
│ └── search → PagedList[AreaSearch]
├── tag
│ ├── from_identifier → Tag
│ ├── from_name → Tag
│ ├── search → PagedList[Tag]
│ └── index_details
│ ├── from_name → IndexDetails
│ └── search → PagedList[IndexDetails]
├── tag_builder
│ ├── aggregation
│ │ ├── define → AggregationDefinition
│ │ ├── create → Aggregation
│ │ ├── from_identifier → Aggregation
│ │ ├── from_name → Aggregation
│ │ └── search → PagedList[Aggregation]
│ ├── custom_calculation
│ │ ├── define → CustomCalculationDefinition
│ │ ├── create → CustomCalculation
│ │ ├── from_identifier → CustomCalculation
│ │ ├── from_name → CustomCalculation
│ │ └── search → PagedList[CustomCalculation]
│ ├── formula
│ │ ├── define → FormulaDefinition
│ │ ├── create → Formula
│ │ ├── from_identifier → Formula
│ │ ├── from_name → Formula
│ │ └── search → PagedList[Formula]
│ ├── machine_learning_model
│ │ ├── from_identifier → MachineLearningModel
│ │ ├── from_name → MachineLearningModel
│ │ └── search → PagedList[MachineLearningModel]
│ ├── prediction
│ │ ├── create → Prediction
│ │ ├── from_identifier → Prediction
│ │ ├── from_name → Prediction
│ │ └── search → PagedList[Prediction]
│ └── imported
│ ├── create → None
│ ├── search → PagedList[TagImport]
│ └── from_name → TagImport
├── trend
│ ├── view
│ │ ├── define → TrendHubViewDefinition
│ │ ├── create → TrendHubView
│ │ ├── from_identifier → TrendHubView
│ │ ├── from_name → TrendHubView
│ │ └── search → PagedList[TrendHubView]
│ ├── layer
│ │ └── new → TrendHubLayer
│ ├── group
│ │ └── new → TrendHubEntryGroup
│ └── chart
│ ├── stacked
│ │ └── new → StackedChartProperties
│ ├── trend
│ │ └── new → TrendChartProperties
│ └── scatter
│ └── new → ScatterChartProperties
├── user
│ ├── self → User
│ ├── from_identifier → User
│ ├── from_name → User
│ ├── all_client_users → PagedList[User]
│ ├── search → PagedList[User]
│ └── group
│ ├── from_identifier → UserGroup
│ ├── from_name → UserGroup
│ ├── search → PagedList[UserGroup]
│ └── everyone → UserGroup
└── work
├── transfer → None
├── folder
│ ├── create → Folder
│ ├── from_identifier → Folder
│ ├── from_path → Folder
│ ├── from_name → Folder
│ ├── search → PagedList[Folder]
│ ├── get_user_home → Folder
│ └── get_users_root → Folder
├── my_work
│ ├── search_contents → PagedList[SavedItem]
│ └── get_item → SavedItem
├── shared
│ ├── search_contents → PagedList[SavedItem]
│ └── get_item → SavedItem
└── favorites
├── search_contents → PagedList[SavedItem]
└── get_item → SavedItem
```
# `client.appliance`
## trendminer_interface.\_client.appliance.ApplianceFacade
Facade to TrendMiner appliance information
### get_version
```
get_version() -> str
```
Get the version of the TrendMiner appliance
Returns:
| Name | Type | Description |
| --------- | ----- | -------------------------------------------------------- |
| `version` | `str` | Version of the TrendMiner appliance, e.g. "2025.R4.0-12" |
### get_index_resolution
```
get_index_resolution() -> Timedelta
```
Get the index resolution of the TrendMiner appliance
Returns:
| Name | Type | Description |
| ------------ | ----------- | ----------------------------------------------------------------------- |
| `resolution` | `Timedelta` | Index resolution of the TrendMiner appliance, e.g. pd.Timedelta("1min") |
### get_index_horizon
```
get_index_horizon() -> Timestamp
```
Get the index horizon of the TrendMiner appliance
Returns:
| Name | Type | Description |
| --------- | ----------- | -------------------------------------------------------------------------------------------------- |
| `horizon` | `Timestamp` | Index horizon of the TrendMiner appliance, i.e. the starting point of the stored time series data. |
# `client.asset_framework.asset`
## trendminer_interface.\_client.asset_framework.asset.AssetFacade
Facade to retrieve and create TrendMiner asset instances
### create
```
create(
name: str, parent: Asset, description: str | None = None
) -> Asset
```
Create a new asset in the asset framework
Parameters:
| Name | Type | Description | Default |
| ------------- | ------- | ------------------------------------------------------------ | ---------- |
| `name` | `str` | Name of the asset | *required* |
| `parent` | `Asset` | Parent Asset under which the asset will be placed as a child | *required* |
| `description` | `str` | Asset description | `None` |
Returns:
| Type | Description |
| ------- | ------------------- |
| `Asset` | Newly created asset |
Notes
The creation of a root asset (i.e., an asset without a parent) happens indirectly through the creation of an asset framework
### from_identifier
```
from_identifier(identifier: str) -> Asset
```
Get an asset from its UUID
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ----------------------- | ---------- |
| `identifier` | `str` | Identifier of the asset | *required* |
Returns:
| Type | Description |
| ------- | ------------------------------- |
| `Asset` | Asset with the given identifier |
Raises:
| Type | Description |
| ------------------ | --------------------------------------------- |
| `ResourceNotFound` | If no asset with the given identifier exists. |
### from_hex_path
```
from_hex_path(hex_path: str) -> Asset
```
Get an asset from its hex path
Parameters:
| Name | Type | Description | Default |
| ---------- | ----- | ------------------------------------------------------------------------------------------------------------------------------ | ---------- |
| `hex_path` | `str` | Path of hexadecimal level identifiers of the asset, as available on Asset.hex_path. For example, "0000025e.0000025f.00000260". | *required* |
Returns:
| Type | Description |
| ------- | -------------------------------------------- |
| `Asset` | Asset corresponding to the provided hex path |
Raises:
| Type | Description |
| ------------------ | ---------------------------------------------- |
| `ResourceNotFound` | If no asset corresponds to the given hex path. |
### from_path
```
from_path(names: list[str]) -> Asset
```
Retrieve an asset from the asset framework by its path
Parameters:
| Name | Type | Description | Default |
| ------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `names` | `List[str]` | List of asset names, representing the path of the asset in the asset framework. For example, ["MyRootAsset", "MyAsset", "MyChildAsset"]. | *required* |
Returns:
| Type | Description |
| ------- | ---------------------------------------- |
| `Asset` | Asset corresponding to the provided path |
Raises:
| Type | Description |
| ------------------- | ------------------------------------------ |
| `ResourceNotFound` | If no asset matches a segment of the path. |
| `AmbiguousResource` | If a path segment matches multiple assets. |
See Also
Asset.get_child_asset : Retrieve a single child asset by name and/or template. Asset.get_child_attribute : Retrieve a single child attribute by name and/or template.
### search
```
search(
name: str | None = None,
description: str | None = None,
template: str | None = None,
frameworks: list[AssetFramework] | None = None,
ancestor: Asset | None = None,
root_only=False,
page: int = 0,
size: int = 1000,
resolve_tag_data: bool = False,
) -> PagedList[Asset]
```
Search Assets
Parameters:
| Name | Type | Description | Default |
| ------------------ | ---------------------- | --------------------------------------------------------------------------------------------- | ------- |
| `name` | `str` | Name search condition. Wildcard '\*' is supported. | `None` |
| `description` | `str` | Description search condition. Wildcard '\*' is supported. | `None` |
| `template` | `str` | Template search condition. Wildcard '\*' is supported. | `None` |
| `frameworks` | `list[AssetFramework]` | Asset frameworks to search in. Searches in all asset frameworks by default. | `None` |
| `ancestor` | `Asset` | If given, only returns assets that are (direct or indirect) descendants of the given asset | `None` |
| `root_only` | `bool` | Whether to only return root assets (i.e., assets without a parent). False by default. | `False` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `1000` |
| `resolve_tag_data` | `bool` | Whether to load tag data for attributes. Results in a much slower request. | `False` |
Returns:
| Type | Description |
| ------------------ | ------------------------------------------------------- |
| `PagedList[Asset]` | Paginated list of assets matching the search conditions |
# `client.asset_framework.attribute`
## trendminer_interface.\_client.asset_framework.attribute.AttributeFacade
Facade to retrieve and create TrendMiner attribute instances
### create
```
create(
name: str,
parent: Asset,
tag: Tag,
description: str | None = None,
) -> Attribute
```
Create a new attribute in the asset framework
Parameters:
| Name | Type | Description | Default |
| ------------- | ------- | ---------------------------------------------------------------- | ---------- |
| `name` | `str` | Name of the attribute | *required* |
| `parent` | `Asset` | Parent Asset under which the attribute will be placed as a child | *required* |
| `tag` | `Tag` | Tag that the attribute refers to | *required* |
| `description` | `str` | Attribute description | `None` |
Returns:
| Type | Description |
| ----------- | ----------------------- |
| `Attribute` | Newly created attribute |
### from_identifier
```
from_identifier(identifier: str) -> Attribute
```
Get an attribute from its UUID
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | --------------------------- | ---------- |
| `identifier` | `str` | Identifier of the attribute | *required* |
Returns:
| Type | Description |
| ----------- | ----------------------------------- |
| `Attribute` | Attribute with the given identifier |
Raises:
| Type | Description |
| ------------------ | ------------------------------------------------- |
| `ResourceNotFound` | If no attribute with the given identifier exists. |
### search
```
search(
name: str | None = None,
description: str | None = None,
template: str | None = None,
frameworks: list[AssetFramework] | None = None,
ancestor: Asset | None = None,
page: int = 0,
size: int = 1000,
resolve_tag_data: bool = False,
) -> PagedList[Attribute]
```
Search Attributes
Parameters:
| Name | Type | Description | Default |
| ------------------ | ---------------------- | ----------------------------------------------------------------------------------------------- | ------- |
| `name` | `str` | Name search condition. Wildcard '\*' is supported. | `None` |
| `description` | `str` | Description search condition. Wildcard '\*' is supported. | `None` |
| `template` | `str` | Template search condition. Wildcard '\*' is supported. | `None` |
| `frameworks` | `list[AssetFramework]` | Asset frameworks to search in. Searches all frameworks by default. | `None` |
| `ancestor` | `Asset` | If given, only returns attributes that are (direct or indirect) descendants of the given asset. | `None` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `1000` |
| `resolve_tag_data` | `bool` | Whether to load tag data for attributes. Results in a much slower request. | `False` |
Returns:
| Type | Description |
| ---------------------- | ----------------------------------------------------------- |
| `PagedList[Attribute]` | Paginated list of attributes matching the search conditions |
# `client.asset_framework`
## trendminer_interface.\_client.asset_framework.AssetFrameworkFacade
Facade to retrieve and create TrendMiner asset framework instances
### asset
```
asset: AssetFacade
```
Facade for retrieving and creating assets in the asset framework
### attribute
```
attribute: AttributeFacade
```
Facade for retrieving and creating attributes in the asset framework
### create
```
create(
name: str, published: bool = False
) -> AssetFramework
```
Create a new asset framework
Parameters:
| Name | Type | Description | Default |
| ----------- | ------ | ------------------------------------------------------------------------ | ---------- |
| `name` | `str` | Name of the asset framework | *required* |
| `published` | `bool` | Whether the asset framework should be published or not, by default False | `False` |
Returns:
| Type | Description |
| ---------------- | --------------------------- |
| `AssetFramework` | The created asset framework |
### search
```
search(
name: str | None = None,
published: bool | None = None,
framework_type: AssetFrameworkType | None = None,
page: int = 0,
size: int = 500,
) -> PagedList[AssetFramework]
```
Search for asset frameworks matching the given criteria
Calling this method without parameters will return all asset frameworks the authenticated user has access to.
Parameters:
| Name | Type | Description | Default |
| ---------------- | -------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `name` | `str` | Filter on (partial) name of the asset framework. Wildcard character * is supported. | `None` |
| `published` | `bool` | Filter on published status of the asset framework. | `None` |
| `framework_type` | \`AssetFrameworkType | None\` | Filter on the type of the asset framework. Should be "csv" or "datasource". |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `500` |
Returns:
| Type | Description |
| --------------------------- | --------------------------------------------------------------- |
| `PagedList[AssetFramework]` | Paginated list of asset frameworks matching the search criteria |
Notes
Asset frameworks to which the user has no permissions are also returned by the API. These are filtered out before returning to the user, with the downside that the `total_elements` results is unavailable (`None`) and pages may not contain the number of results requested.
### from_identifier
```
from_identifier(identifier: str) -> AssetFramework
```
Get an asset framework by its identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | --------------------------- | ---------- |
| `identifier` | `str` | UUID of the asset framework | *required* |
Returns:
| Type | Description |
| ---------------- | --------------------------------------------- |
| `AssetFramework` | The asset framework with the given identifier |
Raises:
| Type | Description |
| ------------------ | ------------------------------------------------------- |
| `ResourceNotFound` | If no asset framework with the given identifier exists. |
### from_name
```
from_name(
name: str,
published: bool | None = None,
framework_type: AssetFrameworkType | None = None,
) -> AssetFramework
```
Get an asset framework by its name
Parameters:
| Name | Type | Description | Default |
| ---------------- | ------ | --------------------------------------------------------------------------------------------- | ---------- |
| `name` | `str` | Name of the asset framework | *required* |
| `published` | `bool` | Only retrieve asset framework with the given published status. | `None` |
| `framework_type` | `str` | Only retrieve asset framework with the given framework type. Should be "csv" or "datasource". | `None` |
Returns:
| Type | Description |
| ---------------- | --------------------------------------- |
| `AssetFramework` | The asset framework with the given name |
Raises:
| Type | Description |
| ------------------- | -------------------------------------------------- |
| `ResourceNotFound` | If no asset framework with the given name exists. |
| `AmbiguousResource` | If multiple asset frameworks match the given name. |
# `client.context.field`
## trendminer_interface.\_client.context.field.ContextFieldFacade
Facade for retrieving and creating context fields
### create
```
create(
key: str,
name: str,
field_type: ContextFieldType,
placeholder: str = "",
options: list[str] | None = None,
) -> ContextField
```
Create a new context field
Parameters:
| Name | Type | Description | Default |
| ------------- | ------------------ | ----------------------------------------------------------------------------------------- | ---------- |
| `key` | `str` | Key of the context field. Must be unique across all context fields. | *required* |
| `name` | `str` | Name of the context field. Does not have to be unique. | *required* |
| `field_type` | `ContextFieldType` | Type of the context field. Can be 'string', 'numeric', or 'enumeration'. | *required* |
| `placeholder` | `str` | Placeholder text for the context field. Default is an empty string. | `""` |
| `options` | `list of str` | Options for enumeration fields. Must be None for non-enumeration fields. Default is None. | `None` |
Returns:
| Type | Description |
| -------------- | -------------------------- |
| `ContextField` | The created context field. |
### from_identifier
```
from_identifier(identifier: str) -> ContextField
```
Get a context field by its identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ------------------------------------- | ---------- |
| `identifier` | `str` | UUID of the context field to retrieve | *required* |
Returns:
| Type | Description |
| -------------- | --------------------------------------- |
| `ContextField` | Context field with the given identifier |
Raises:
| Type | Description |
| ------------------ | ----------------------------------------------------- |
| `ResourceNotFound` | If no context field with the given identifier exists. |
### from_key
```
from_key(key: str) -> ContextField
```
Get a context field by its key
Parameters:
| Name | Type | Description | Default |
| ----- | ----- | ------------------------------------ | ---------- |
| `key` | `str` | Key of the context field to retrieve | *required* |
Returns:
| Type | Description |
| -------------- | -------------------------------- |
| `ContextField` | Context field with the given key |
Raises:
| Type | Description |
| ------------------- | ----------------------------------------------- |
| `ResourceNotFound` | If no context field with the given key exists. |
| `AmbiguousResource` | If multiple context fields match the given key. |
### from_name
```
from_name(name: str) -> ContextField
```
Get a context field by its name
Parameters:
| Name | Type | Description | Default |
| ------ | ----- | ------------------------------------- | ---------- |
| `name` | `str` | Name of the context field to retrieve | *required* |
Returns:
| Type | Description |
| -------------- | --------------------------------- |
| `ContextField` | Context field with the given name |
Raises:
| Type | Description |
| ------------------- | ------------------------------------------------ |
| `ResourceNotFound` | If no context field with the given name exists. |
| `AmbiguousResource` | If multiple context fields match the given name. |
### search
```
search(
key: str | None = None,
name: str | None = None,
page=0,
size=2000,
) -> PagedList[ContextField]
```
Search for context fields
Parameters:
| Name | Type | Description | Default |
| ------ | ----- | ---------------------------------------------------------------------------------------------- | ------- |
| `key` | `str` | Search for context fields with keys matching this query. Can use the '\*' symbol as wildcard. | `None` |
| `name` | `str` | Search for context fields with names matching this query. Can use the '\*' symbol as wildcard. | `None` |
| `page` | `int` | Page number to start the search from (0-indexed). Default is 0. | `0` |
| `size` | `int` | Number of results to return per page. Default is 2000 (the maximum supported by the backend). | `2000` |
Returns:
| Type | Description |
| ------------------------- | ------------------------------------------------------ |
| `PagedList[ContextField]` | Page with context fields matching the search criteria. |
# `client.context.filter.approval`
## trendminer_interface.\_client.context.filter.approval_filter.ContextApprovalFilterFacade
Facade for creating context approval filters
### new
```
new(approved: bool) -> ContextApprovalFilter
```
Context filter on item approval
Parameters:
| Name | Type | Description | Default |
| ---------- | ------ | --------------------------------- | ---------- |
| `approved` | `bool` | Item approval status to filter on | *required* |
Returns:
| Type | Description |
| ----------------------- | ----------- |
| `ContextApprovalFilter` | |
# `client.context.filter.components`
## trendminer_interface.\_client.context.filter.component_filter.ContextComponentFilterFacade
Facade for creating context component filters
### new
```
new(
queries: list[
tuple[
Tag | Asset | Attribute,
Literal["self", "ancestors", "descendants"],
]
]
| None = None,
mode: EmptyMode | None = None,
) -> ContextComponentFilter
```
Context filter on components the context items are attached to
Parameters:
| Name | Type | Description | Default |
| --------- | ------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------- |
| `queries` | \`list\[tuple\[Tag | Asset | Attribute, Literal['self', 'ancestors', 'descendants']\]\] |
| `mode` | \`EmptyMode | None\` | When not None, filter on whether the context items are attached to any component at all. Ignores the queries when not None. |
# `client.context.filter.context_types`
## trendminer_interface.\_client.context.filter.context_type_filter.ContextTypeFilterFacade
Facade for creating context type filters
### new
```
new(types: list[ContextType]) -> ContextTypeFilter
```
Context filter on item type
Parameters:
| Name | Type | Description | Default |
| ------- | ------------------- | ---------------------------------------- | ---------- |
| `types` | `list[ContextType]` | List of context types on which to filter | *required* |
Returns:
| Type | Description |
| ------------------- | ----------- |
| `ContextTypeFilter` | |
# `client.context.filter.created_by`
## trendminer_interface.\_client.context.filter.created_by_filter.ContextCreatedByFilterFacade
Facade for creating context created-by filters
### new
```
new(users: list[User]) -> ContextCreatedByFilter
```
Filter on context item creator
Parameters:
| Name | Type | Description | Default |
| ------- | ------------ | ------------------------ | ---------- |
| `users` | `list[User]` | Users on which to filter | *required* |
Returns:
| Type | Description |
| ------------------------ | ----------- |
| `ContextCreatedByFilter` | |
# `client.context.filter.creation_date`
## trendminer_interface.\_client.context.filter.creation_date_filter.ContextCreationDateFilterFacade
Facade for creating context creation date filters
### new
```
new(
operator: Literal[">", ">=", "<", "<="],
timestamp: Timestamp,
) -> ContextCreationDateFilter
```
Conditional filter on context item creation date
Parameters:
| Name | Type | Description | Default |
| ----------- | ------------------------ | ------------------------------------------------------------------ | ---------- |
| `operator` | `('>', '>=', '<', '<=')` | The operator to apply to the timestamp criterion | `">"` |
| `timestamp` | `Timestamp` | The timestamp criterion to apply to the context item creation date | *required* |
Returns:
| Type | Description |
| --------------------------- | ----------- |
| `ContextCreationDateFilter` | |
# `client.context.filter.description`
## trendminer_interface.\_client.context.filter.description_filter.ContextDescriptionFilterFacade
Facade for creating context description filters
### new
```
new(
values: list[str] | None = None,
mode: EmptyMode | None = None,
) -> ContextDescriptionFilter
```
Context filter on item description
Parameters:
| Name | Type | Description | Default |
| -------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `values` | `list of str` | Non-empty list of string queries to filter on the description. Can use '\*' as wildcard character. | `None` |
| `mode` | `('empty', 'not empty')` | Filter mode. If None, the filter will be applied on the values. If "empty", the filter will return items with empty description. If "not empty", the filter will return items with non-empty description. | `"empty"` |
Notes
Either values or mode should be provided. They cannot be combined.
Returns:
| Type | Description |
| -------------------------- | ----------- |
| `ContextDescriptionFilter` | |
# `client.context.filter.duration`
## trendminer_interface.\_client.context.filter.duration_filter.ContextDurationFilterFacade
Facade for creating context duration filters
### new
```
new(
queries: list[tuple[DurationOperator, Timedelta]],
) -> ContextDurationFilter
```
Filter on context item duration
Parameters:
| Name | Type | Description | Default |
| --------- | ------------------------------------------ | ----------------------------- | ---------- |
| `queries` | `list[tuple[DurationOperator, Timedelta]]` | Duration queries to filter on | *required* |
Returns:
| Type | Description |
| ----------------------- | ----------- |
| `ContextDurationFilter` | |
# `client.context.filter.enumeration_field`
## trendminer_interface.\_client.context.filter.enumeration_field_filter.ContextEnumerationFieldFilterFacade
Facade for creating context enumeration field filters
### new
```
new(
field: ContextField,
values: list[str] | None = None,
mode: EmptyMode | None = None,
) -> ContextEnumerationFieldFilter
```
Filter on context enumeration field values
Parameters:
| Name | Type | Description | Default |
| -------- | ------------------------ | -------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `field` | `ContextField` | The context field on which to filter. Must be of 'enumeration' type. | *required* |
| `values` | \`list of str | None\` | List of values to filter on. Must be values allowed by the field. |
| `mode` | `('empty', 'not empty')` | When not None, filter on empty/non-empty field instead of specific values. | `"empty"` |
Returns:
| Type | Description |
| ------------------------------- | ----------- |
| `ContextEnumerationFieldFilter` | |
# `client.context.filter.interval`
## trendminer_interface.\_client.context.filter.interval_filter.ContextIntervalFilterFacade
Facade for creating context interval filters
### new
```
new(
interval: Interval,
scope: Literal["event", "creation date"] = "event",
) -> ContextIntervalFilter
```
Filter on context item event or creation time through fixed interval
Parameters:
| Name | Type | Description | Default |
| ---------- | ----------------------------------- | ----------------------------------------------------------------------------------- | ---------- |
| `interval` | `Interval` | The time interval on which to filter | *required* |
| `scope` | `Literal['event', 'creation date']` | Whether to filter on the context item timestamps or the context item creation date. | `'event'` |
Returns:
| Type | Description |
| ----------------------- | ----------- |
| `ContextIntervalFilter` | |
# `client.context.filter.keyword`
## trendminer_interface.\_client.context.filter.keyword_filter.ContextKeywordFilterFacade
Facade for creating context keyword filters
### new
```
new(
keywords: list[str] | None = None,
mode: EmptyMode | None = None,
) -> ContextKeywordFilter
```
Filter on context item keywords
Parameters:
| Name | Type | Description | Default |
| ---------- | ------------------------ | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `keywords` | \`list of str | None\` | Keywords which must be present on the context items. Ignored when using mode. |
| `mode` | `('empty', 'not empty')` | When not None, filter for context items without or with keywords. Ignores the keywords parameter when used. | `"empty"` |
Returns:
| Type | Description |
| ---------------------- | ----------- |
| `ContextKeywordFilter` | |
# `client.context.filter`
## trendminer_interface.\_client.context.filter.ContextFilterFacade
Facade for creating context filters
### approval
```
approval: ContextApprovalFilterFacade
```
Facade for creating context approval filters
### components
```
components: ContextComponentFilterFacade
```
Facade for creating context component filters
### context_types
```
context_types: ContextTypeFilterFacade
```
Facade for creating context type filters
### created_by
```
created_by: ContextCreatedByFilterFacade
```
Facade for creating context created-by filters
### creation_date
```
creation_date: ContextCreationDateFilterFacade
```
Facade for creating context creation date filters
### description
```
description: ContextDescriptionFilterFacade
```
Facade for creating context description filters
### duration
```
duration: ContextDurationFilterFacade
```
Facade for creating context duration filters
### interval
```
interval: ContextIntervalFilterFacade
```
Facade for creating context interval filters
### keyword
```
keyword: ContextKeywordFilterFacade
```
Facade for creating context keyword filters
### period
```
period: ContextPeriodFilterFacade
```
Facade for creating context period filters
### state
```
state: ContextStateFilterFacade
```
Facade for creating context state filters
### enumeration_field
```
enumeration_field: ContextEnumerationFieldFilterFacade
```
Facade for creating context enumeration field filters
### numeric_field
```
numeric_field: ContextNumericFieldFilterFacade
```
Facade for creating context numeric field filters
### string_field
```
string_field: ContextStringFieldFilterFacade
```
Facade for creating context string field filters
# `client.context.filter.numeric_field`
## trendminer_interface.\_client.context.filter.numeric_field_filter.ContextNumericFieldFilterFacade
Facade for creating context numeric field filters
### new
```
new(
field: ContextField,
queries: list[
tuple[
Literal["=", "!=", ">", "<", ">=", "<="], float
]
]
| None = None,
mode: EmptyMode | None = None,
) -> ContextNumericFieldFilter
```
Filter on context numeric field values
Parameters:
| Name | Type | Description | Default |
| --------- | ----------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------- |
| `field` | `ContextField` | The context field on which to filter. Must be of 'numeric' type. | *required* |
| `queries` | \`list of tuple[{"=", "!=", ">", "\<", ">=", "\<="}, float] | None\` | List of operator-value tuples to filter on. |
| `mode` | `('empty', 'not empty')` | When not None, filter on empty/non-empty field instead of specific values. | `"empty"` |
Returns:
| Type | Description |
| --------------------------- | ----------- |
| `ContextNumericFieldFilter` | |
# `client.context.filter.period`
## trendminer_interface.\_client.context.filter.period_filter.ContextPeriodFilterFacade
Facade for creating context period filters
### new
```
new(
period: Timedelta, live: bool = False
) -> ContextPeriodFilter
```
Filter on context item event time with dynamic period
Parameters:
| Name | Type | Description | Default |
| -------- | ----------- | ----------------------------------------------------------------------------------------------------------------- | ---------- |
| `period` | `Timedelta` | Duration marking a time interval running up to the current time, on which to filter the context items. | *required* |
| `live` | `bool` | Whether a ContextHubView having this filter needs to update live. Does not impact the retrieval of context items. | `False` |
Returns:
| Type | Description |
| --------------------- | ----------- |
| `ContextPeriodFilter` | |
# `client.context.filter.state`
## trendminer_interface.\_client.context.filter.state_filter.ContextStateFilterFacade
Facade for creating context state filters
### new
```
new(
states: list[str] | None = None,
mode: Literal["open", "closed"] | None = None,
) -> ContextStateFilter
```
Filter on context item current state
Parameters:
| Name | Type | Description | Default |
| -------- | -------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `states` | \`list of str | None\` | Allowed context item states. Ignored when using mode. |
| `mode` | `('open', 'closed')` | When not None, filter for only open (ongoing) or closed context items, ignoring any given states. | `"open"` |
Returns:
| Type | Description |
| -------------------- | ----------- |
| `ContextStateFilter` | |
# `client.context.filter.string_field`
## trendminer_interface.\_client.context.filter.string_field_filter.ContextStringFieldFilterFacade
Facade for creating context string field filters
### new
```
new(
field: ContextField,
values: list[str] | None = None,
mode: EmptyMode | None = None,
) -> ContextStringFieldFilter
```
Filter on context string field values
Parameters:
| Name | Type | Description | Default |
| -------- | ------------------------ | -------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `field` | `ContextField` | The context field on which to filter. Must be of 'string' type. | *required* |
| `values` | \`list of str | None\` | List of values to filter on. Allows wildcard character '\*'. |
| `mode` | `('empty', 'not empty')` | When not None, filter on empty/non-empty field instead of specific values. | `"empty"` |
Returns:
| Type | Description |
| -------------------------- | ----------- |
| `ContextStringFieldFilter` | |
# `client.context.item`
## trendminer_interface.\_client.context.item.ContextItemFacade
Facade for managing context items in TrendMiner
Context items are always represented as a pandas DataFrame, where each row corresponds to a context item.
### create
```
create(items: DataFrame) -> None
```
Create new context items from a valid DataFrame.
Parameters:
| Name | Type | Description | Default |
| ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `items` | `DataFrame` | Input DataFrame with a pandas.IntervalIndex and the following structure: Index: The index will be a pandas.IntervalIndex, with index.left and index.right the timestamps of the context item start and end events, respectively. Required columns: - type (ContextType): context type of each item - component (Tag or Asset or Attribute): component to which the item will be attached Optional columns: - open (bool): whether the context item is open-ended (no end state). Default behavior is closed. - keywords (list[str]): the keywords to attach to the context item - description (str): the context item description Event columns: Additional pandas.Timestamp values will be considered additional states (events) with the column name as the state name. Field columns: Any remaining numeric or string values will be considered context fields with the column name as the key. The following metadata columns will be ignored: key, identifier, identifier_external, created_by, created_at, last_modified. | *required* |
Returns:
| Type | Description |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `None` | No output is returned. To load the created context items (with their metadata such as identifiers), use get_items on a ContextHubViewDefinition with appropriate filters. |
Notes
If a DataFrame of existing context items is passed, copies of these context items will be created.
### update
```
update(items: DataFrame) -> None
```
Update existing context items to a new state
Parameters:
| Name | Type | Description | Default |
| ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `items` | `DataFrame` | Input DataFrame with a pandas.IntervalIndex and the following structure: Index: The index will be a pandas.IntervalIndex, with index.left and index.right the timestamps of the context item start and end events, respectively. Required columns: - identifier (str): identifier of the existing context item - type (ContextType): context type of each item - component (Tag or Asset or Attribute): component to which the item will be attached Optional columns: - open (bool): whether the context item is open-ended (no end state). Default behavior is closed. - keywords (list[str]): the keywords to attach to the context item - description (str): the context item description Event columns: Additional pandas.Timestamp values will be considered additional states (events) with the column name as the state name. Field columns: Any remaining numeric or string values will be considered context fields with the column name as the key. The following metadata columns will be ignored: key, identifier_external, created_by, created_at, last_modified. | *required* |
Returns:
| Type | Description |
| ------ | ----------- |
| `None` | |
### delete
```
delete(items: DataFrame) -> None
```
Permanently delete all context items in the DataFrame
# `client.context`
## trendminer_interface.\_client.context.ContextFacade
Facade for interacting with ContextHub and context items
### view
```
view: ContextHubViewFacade
```
Facade for getting saved ContextHub views
### item
```
item: ContextItemFacade
```
Facade for creating, updating and deleting context items
### type
```
type: ContextTypeFacade
```
Facade for retrieving and creating context types
### field
```
field: ContextFieldFacade
```
Facade for retrieving and creating context fields
### workflow
```
workflow: ContextWorkflowFacade
```
Facade for retrieving and creating context workflows
### filter
```
filter: ContextFilterFacade
```
Facade for creating filters to filter context items when retrieving them
# `client.context.type`
## trendminer_interface.\_client.context.type.ContextTypeFacade
Facade for retrieving and creating context types
### create
```
create(
key: str,
name: str,
workflow: ContextWorkflow | None,
fields: list[ContextField],
color: str = "#4A75E2",
icon: ContextTypeIcon = "information",
description: str | None = None,
approvals_enabled: bool = False,
audit_trail_enabled: bool = False,
) -> ContextType
```
Create a new context type
Parameters:
| Name | Type | Description | Default |
| --------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| `key` | `str` | Unique key that is used as the identifier of the context type. Must be unique across all context types and cannot be changed after creation. | *required* |
| `name` | `str` | Name that is visible to the users in the appliance | *required* |
| `workflow` | `ContextWorkflow` | Workflow associated with the context type. When None, the context type can only have a single associated timestamp. | *required* |
| `fields` | `list[ContextField]` | List of fields that are associated with the context type. | *required* |
| `color` | `str` | Color of the context type in hex format (e.g. "#FF0000") | `"#4A75E2"` |
| `icon` | `ContextTypeIcon` | Icon of the context type. See ContextTypeIcon for the allowed values. | `"information"` |
| `description` | `str` | Description of the context type | `None` |
| `approvals_enabled` | `bool` | Whether context items of this type can be approved. | `False` |
| `audit_trail_enabled` | `bool` | Whether context item edit history will be saved as metadata to the item. | `False` |
Returns:
| Type | Description |
| ------------- | ------------------------- |
| `ContextType` | The created context type. |
### from_key
```
from_key(key: str) -> ContextType
```
Get a context type by its key
Parameters:
| Name | Type | Description | Default |
| ----- | ----- | ----------------------------------- | ---------- |
| `key` | `str` | Key of the context type to retrieve | *required* |
Returns:
| Type | Description |
| ------------- | ------------------------------- |
| `ContextType` | Context type with the given key |
Raises:
| Type | Description |
| ------------------ | --------------------------------------------- |
| `ResourceNotFound` | If no context type with the given key exists. |
### from_name
```
from_name(name: str) -> ContextType
```
Get a context type by its name
Parameters:
| Name | Type | Description | Default |
| ------ | ----- | ------------------------------------ | ---------- |
| `name` | `str` | Name of the context type to retrieve | *required* |
Returns:
| Type | Description |
| ------------- | -------------------------------- |
| `ContextType` | Context type with the given name |
Raises:
| Type | Description |
| ------------------- | ----------------------------------------------- |
| `ResourceNotFound` | If no context type with the given name exists. |
| `AmbiguousResource` | If multiple context types match the given name. |
### search
```
search(
key: str | None = None,
name: str | None = None,
page=0,
size=2000,
) -> PagedList[ContextType]
```
Search for context types
Parameters:
| Name | Type | Description | Default |
| ------ | ----- | --------------------------------------------------------------------------------------------- | ------- |
| `key` | `str` | Search for context types with keys matching this query. Can use the '\*' symbol as wildcard. | `None` |
| `name` | `str` | Search for context types with names matching this query. Can use the '\*' symbol as wildcard. | `None` |
| `page` | `int` | Page number to start the search from (0-indexed). Default is 0. | `0` |
| `size` | `int` | Number of results to return per page. Default is 2000 (the maximum supported by the backend). | `2000` |
Returns:
| Type | Description |
| ------------------------ | ----------------------------------------------------- |
| `PagedList[ContextType]` | Page with context types matching the search criteria. |
# `client.context.view`
## trendminer_interface.\_client.context.view.ContextHubViewFacade
Bases: `WorkFacadeBase[ContextHubView]`
Facade for getting saved context hub view objects
### define
```
define(
filters: list[ContextFilter],
calculations: dict[str, SearchCalculation]
| None = None,
view_type: ContextHubViewType = "grid",
) -> ContextHubViewDefinition
```
Define a new ContextHub view
Parameters:
| Name | Type | Description | Default |
| -------------- | ------------------------------ | ------------------------------------------------- | ---------------------------------------------------------------------- |
| `filters` | `list[ContextFilter]` | Filters to apply to the context items | *required* |
| `calculations` | \`dict[str, SearchCalculation] | None\` | Calculations to apply to the context items when getting search results |
| `view_type` | `ContextHubViewType` | The type of view to create (grid, gantt, scatter) | `'grid'` |
Returns:
| Type | Description |
| -------------------------- | ------------------------------------- |
| `ContextHubViewDefinition` | The definition of the ContextHub view |
### create
```
create(
definition: ContextHubViewDefinition,
name: str,
description: str | None = None,
folder: Folder | None = None,
) -> ContextHubView
```
Create a new ContextHub view in TrendMiner
Parameters:
| Name | Type | Description | Default |
| ------------- | -------------------------- | ------------------------------------- | ---------------------------------------- |
| `definition` | `ContextHubViewDefinition` | Definition of the new ContextHub view | *required* |
| `name` | `str` | Name of the saved view | *required* |
| `description` | \`str | None\` | Description of the saved view |
| `folder` | \`Folder | None\` | The folder in which to save the new view |
Returns:
| Type | Description |
| ---------------- | -------------------------------------- |
| `ContextHubView` | The created and saved ContextHub view. |
### from_identifier
```
from_identifier(identifier: str) -> T
```
Get an item by its unique identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ---------------------------------------- | ---------- |
| `identifier` | `str` | The unique identifier of the item to get | *required* |
Returns:
| Name | Type | Description |
| ------ | ---- | ------------------------------ |
| `item` | `T` | Item with the given identifier |
Raises:
| Type | Description |
| ------------------ | -------------------------------------------- |
| `ResourceNotFound` | If no item with the given identifier exists. |
### from_name
```
from_name(name: str, scope: WorkScope = 'my work') -> T
```
Get an item from its name
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `name` | `str` | The name of the item to get | *required* |
| `scope` | `str` | Searching scope for getting the item. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
Returns:
| Name | Type | Description |
| ------ | ---- | ---------------------------- |
| `item` | `T` | The item with the given name |
Raises:
| Type | Description |
| ------------------- | --------------------------------------------------- |
| `ResourceNotFound` | If no item with the given name exists in the scope. |
| `AmbiguousResource` | If multiple items match the given name. |
### search
```
search(
query: str | None = None,
scope: WorkScope = "my work",
page: int = 0,
size: int = 2000,
) -> PagedList[T]
```
Search items by name or description
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `query` | `str` | The search query. The '\*' can be used as a wildcard. Returns all items if query is None (default). | `None` |
| `scope` | `str` | Searching scope. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `2000` |
Returns:
| Name | Type | Description |
| ------- | -------------- | ------------------------------------------------- |
| `items` | `PagedList[T]` | Paginated list of items matching the search query |
# `client.context.workflow`
## trendminer_interface.\_client.context.workflow.ContextWorkflowFacade
Facade for retrieving and creating context workflows
### create
```
create(name: str, states: list[str]) -> ContextWorkflow
```
Create a new context workflow
Parameters:
| Name | Type | Description | Default |
| -------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `name` | `str` | Name of the context workflow. Does not have to be unique. | *required* |
| `states` | `list[str]` | Possible states of the workflow; the first and last items are considered the start and end states, respectively, and can occur only once in a context item. | *required* |
Returns:
| Type | Description |
| ----------------- | ----------------------------- |
| `ContextWorkflow` | The created context workflow. |
### from_identifier
```
from_identifier(identifier: str) -> ContextWorkflow
```
Get a context workflow by its identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ---------------------------------------- | ---------- |
| `identifier` | `str` | UUID of the context workflow to retrieve | *required* |
Returns:
| Type | Description |
| ----------------- | ------------------------------------------ |
| `ContextWorkflow` | Context workflow with the given identifier |
Raises:
| Type | Description |
| ------------------ | -------------------------------------------------------- |
| `ResourceNotFound` | If no context workflow with the given identifier exists. |
### from_name
```
from_name(name: str) -> ContextWorkflow
```
Get a context workflow by its name
Parameters:
| Name | Type | Description | Default |
| ------ | ----- | ---------------------------------------- | ---------- |
| `name` | `str` | Name of the context workflow to retrieve | *required* |
Returns:
| Type | Description |
| ----------------- | ------------------------------------ |
| `ContextWorkflow` | Context workflow with the given name |
Raises:
| Type | Description |
| ------------------- | --------------------------------------------------- |
| `ResourceNotFound` | If no context workflow with the given name exists. |
| `AmbiguousResource` | If multiple context workflows match the given name. |
### search
```
search(
name: str | None = None, page=0, size=2000
) -> PagedList[ContextWorkflow]
```
Search for context workflows
Parameters:
| Name | Type | Description | Default |
| ------ | ----- | ------------------------------------------------------------------------------------------------- | ------- |
| `name` | `str` | Search for context workflows with names matching this query. Can use the '\*' symbol as wildcard. | `None` |
| `page` | `int` | Page number to start the search from (0-indexed). Default is 0. | `0` |
| `size` | `int` | Number of results to return per page. Default is 2000 (the maximum supported by the backend). | `2000` |
Returns:
| Type | Description |
| ---------------------------- | --------------------------------------------------------- |
| `PagedList[ContextWorkflow]` | Page with context workflows matching the search criteria. |
# `client.dashboard.context`
## trendminer_interface.\_client.dashboard.context.ContextHubViewTileFacade
Facade for creating ContextHub view tiles
### config
```
config(
show_title: bool = True,
show_legend: bool = True,
show_timeframe: bool = True,
) -> ContextHubViewTileConfiguration
```
Default configuration for ContextHub view tiles
Parameters:
| Name | Type | Description | Default |
| ---------------- | ------ | -------------------------------------------------------------------------- | ------- |
| `show_title` | `bool` | Whether to show the tile title, by default True | `True` |
| `show_legend` | `bool` | Whether to show the colored points legend in scatter mode, by default True | `True` |
| `show_timeframe` | `bool` | Whether to show the timeframe, by default True | `True` |
Returns:
| Type | Description |
| --------------------------------- | ----------- |
| `ContextHubViewTileConfiguration` | |
### new
```
new(
position: tuple[int, int, int, int],
view: ContextHubView,
mode: ContextHubViewTileMode = "count",
title: str = "",
refresh_rate: Timedelta = Timedelta(minutes=5),
config: ContextHubViewTileConfiguration | None = None,
) -> ContextHubViewTile
```
Instantiate a new ContextHub view tile
Parameters:
| Name | Type | Description | Default |
| -------------- | --------------------------------- | ----------------------------------------------------------------------------------- | ---------------------- |
| `position` | `tuple[int, int, int, int]` | Position of the tile on the dashboard (x, y, width, height) | *required* |
| `view` | `ContextHubView` | ContextHub view to display in the tile | *required* |
| `mode` | `ContextHubViewTileMode` | Display mode of the tile ("table", "gantt", "scatter" or "count"). Default "count". | `'count'` |
| `title` | `str` | Title of the tile, by default "" | `''` |
| `refresh_rate` | `Timedelta` | Refresh rate of the tile. Default is 5m. | `Timedelta(minutes=5)` |
| `config` | `ContextHubViewTileConfiguration` | Configuration of the tile. If None, default configuration is used. | `None` |
Returns:
| Type | Description |
| -------------------- | ----------- |
| `ContextHubViewTile` | |
# `client.dashboard.external`
## trendminer_interface.\_client.dashboard.external.ExternalContentTileFacade
Facade for creating external content tiles
### config
```
config(
show_title: bool = True,
) -> ExternalContentTileConfiguration
```
Create a new external content tile configuration
Parameters:
| Name | Type | Description | Default |
| ------------ | ------ | ------------------------------ | ------- |
| `show_title` | `bool` | Whether to show the tile title | `True` |
Returns:
| Type | Description |
| ---------------------------------- | ----------- |
| `ExternalContentTileConfiguration` | |
### new
```
new(
position: tuple[int, int, int, int],
url: str | None = None,
title: str = "",
refresh_rate: Timedelta = Timedelta(minutes=5),
config: ExternalContentTileConfiguration | None = None,
) -> ExternalContentTile
```
Create a new external content tile
Parameters:
| Name | Type | Description | Default |
| -------------- | ---------------------------------- | ------------------------------------------------------------------------ | ---------------------- |
| `position` | `tuple[int, int, int, int]` | x, y, width and height of the tile on the dashboard | *required* |
| `url` | `str` | The URL of the external content to display | `None` |
| `title` | `str` | Title of the tile, by default "" | `''` |
| `refresh_rate` | `Timedelta` | How often the tile is refreshed if the dashboard is live. Default is 5m. | `Timedelta(minutes=5)` |
| `config` | `ExternalContentTileConfiguration` | The configuration of the tile. Default configuration when not provided. | `None` |
Returns:
| Type | Description |
| --------------------- | ----------- |
| `ExternalContentTile` | |
# `client.dashboard.gauge`
## trendminer_interface.\_client.dashboard.gauge.GaugeTileFacade
Facade for creating gauge tiles
### config
```
config(
show_title: bool = True,
accuracy: float | None = None,
colored_value: bool = False,
percentage_ranges: bool = False,
percentage_delta: bool = False,
percentage_value: bool = False,
show_range_labels: bool = True,
show_delta: bool = False,
show_ticks: bool = True,
show_timestamp: bool = True,
use_chart_alias: bool = False,
) -> GaugeTileConfiguration
```
Default configuration for gauge tiles
Parameters:
| Name | Type | Description | Default |
| ------------------- | ------- | -------------------------------------------------------------------------- | ------- |
| `show_title` | `bool` | Whether to show the tile title, by default True | `True` |
| `accuracy` | `float` | Number of decimal places to show for the value, by default None | `None` |
| `colored_value` | `bool` | Whether to color the value based on the range colors, by default False | `False` |
| `percentage_ranges` | `bool` | Whether to display the ranges as percentages, by default False | `False` |
| `percentage_delta` | `bool` | Whether to display the target difference as a percentage, by default False | `False` |
| `percentage_value` | `bool` | Whether to display the value as a percentage, by default False | `False` |
| `show_range_labels` | `bool` | Whether to show the range labels, by default True | `True` |
| `show_delta` | `bool` | Whether to show the target difference, by default False | `False` |
| `show_ticks` | `bool` | Whether to show the ticks on the gauge, by default True | `True` |
| `show_timestamp` | `bool` | Whether to show the timestamp of the value, by default True | `True` |
| `use_chart_alias` | `bool` | Whether to use the chart alias for the component, by default False | `False` |
Returns:
| Type | Description |
| ------------------------ | ----------- |
| `GaugeTileConfiguration` | |
### new
```
new(
position: tuple[int, int, int, int],
component: Tag | Attribute,
default_range: GaugeTileRange,
ranges: list[GaugeTileRange] | None = None,
mode: GaugeTileMode = "angular",
target: float | None = None,
title: str = "",
refresh_rate: Timedelta = Timedelta(minutes=1),
config: GaugeTileConfiguration | None = None,
) -> GaugeTile
```
Instantiate a new gauge tile
Parameters:
| Name | Type | Description | Default |
| --------------- | --------------------------- | --------------------------------------------------------------------------------------------- | ---------------------- |
| `position` | `tuple[int, int, int, int]` | Position of the tile on the dashboard (x, y, width, height) | *required* |
| `component` | `Tag or Attribute` | Time-series component to display in the gauge tile | *required* |
| `default_range` | `GaugeTileRange` | Default range for the gauge tile (min, max, label, color) | *required* |
| `ranges` | `list[GaugeTileRange]` | Additional ranges for the gauge tile. List of (min, max, label, color), by default None | `None` |
| `mode` | `GaugeTileMode` | Type of gauge tile ("vertical", "horizontal", "angular" or "speedometer"). Default "angular". | `'angular'` |
| `target` | `float` | Target value to display in the gauge tile, by default None | `None` |
| `title` | `str` | Title of the tile, by default "" | `''` |
| `refresh_rate` | `Timedelta` | Refresh rate of the tile, by default 1m. | `Timedelta(minutes=1)` |
| `config` | `GaugeTileConfiguration` | Configuration of the tile. If None, default configuration is used. | `None` |
Returns:
| Type | Description |
| ----------- | ----------- |
| `GaugeTile` | |
# `client.dashboard`
## trendminer_interface.\_client.dashboard.DashboardFacade
Bases: `WorkFacadeBase[Dashboard]`
Facade for getting saved dashboard objects
### context
```
context: ContextHubViewTileFacade
```
Facade for creating ContextHub view tiles
### external
```
external: ExternalContentTileFacade
```
Facade for creating external content tiles
### gauge
```
gauge: GaugeTileFacade
```
Facade for creating gauge tiles
### monitor
```
monitor: MonitorTileFacade
```
Facade for creating monitor tiles
### notebook
```
notebook: NotebookTileFacade
```
Facade for creating notebook tiles
### text
```
text: TextTileFacade
```
Facade for creating text tiles
### trend
```
trend: TrendHubViewTileFacade
```
Facade for creating TrendHub view tiles
### value
```
value: CurrentValueTileFacade
```
Facade for creating current value tiles
### config
```
config(
context: ContextHubViewTileConfiguration | None = None,
external: ExternalContentTileConfiguration
| None = None,
gauge: GaugeTileConfiguration | None = None,
monitor: MonitorTileConfiguration | None = None,
notebook: NotebookTileConfiguration | None = None,
text: TextTileConfiguration | None = None,
trend: TrendHubViewTileConfiguration | None = None,
value: CurrentValueTileConfiguration | None = None,
) -> DashboardConfiguration
```
Create a global dashboard configuration object
Can override settings for the different tile types. Takes the configurations of the different tile types as input. If a configuration is not provided, the default configuration of the respective tile factory is used.
Parameters:
| Name | Type | Description | Default |
| ---------- | ---------------------------------- | ----------------------------------------------- | ------- |
| `context` | `ContextHubViewTileConfiguration` | Global configuration for ContextHub view tiles | `None` |
| `external` | `ExternalContentTileConfiguration` | Global configuration for External content tiles | `None` |
| `gauge` | `GaugeTileConfiguration` | Global configuration for Gauge tiles | `None` |
| `monitor` | `MonitorTileConfiguration` | Global configuration for Monitor tiles | `None` |
| `notebook` | `NotebookTileConfiguration` | Global configuration for Notebook tiles | `None` |
| `text` | `TextTileConfiguration` | Global configuration for Text tiles | `None` |
| `trend` | `TrendHubViewTileConfiguration` | Global configuration for TrendHub view tiles | `None` |
| `value` | `CurrentValueTileConfiguration` | Global configuration for Current value tiles | `None` |
Returns:
| Type | Description |
| ------------------------ | ----------- |
| `DashboardConfiguration` | |
### define
```
define(
tiles: list[DashboardTile],
live: bool = False,
dynamic_font_sizing: bool = True,
override_tile_config: bool = False,
config: DashboardConfiguration | None = None,
chart_aliases: dict[Tag | Attribute, str] | None = None,
) -> DashboardDefinition
```
Initialize a new dashboard
Parameters:
| Name | Type | Description | Default |
| ---------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `tiles` | `list[TileBase]` | Tiles to add to the dashboard | *required* |
| `live` | `bool` | Whether the dashboard will be updated live | `False` |
| `dynamic_font_sizing` | `bool` | Whether dynamic font sizing is enabled | `True` |
| `override_tile_config` | `bool` | Whether the dashboard configuration overrides individual tile settings | `False` |
| `config` | `DashboardConfiguration` | Dashboard global configuration settings. Overrides tile settings when override_tile_config is True, otherwise does not have an effect. | `None` |
| `chart_aliases` | \`dict\[Tag | Attribute, str\] | None\` |
Returns:
| Type | Description |
| --------------------- | ----------- |
| `DashboardDefinition` | |
Notes
The dashboard grid has a width of 24, but no length limit as dashboards are scrollable.
### create
```
create(
definition: DashboardDefinition,
name: str,
description: str | None = None,
folder: Folder | None = None,
) -> Dashboard
```
Create a new dashboard in TrendMiner
Parameters:
| Name | Type | Description | Default |
| ------------- | --------------------- | ------------------------------- | --------------------------------------------- |
| `definition` | `DashboardDefinition` | Definition of the new dashboard | *required* |
| `name` | `str` | Name of the saved dashboard | *required* |
| `description` | \`str | None\` | Description of the saved dashboard |
| `folder` | \`Folder | None\` | The folder in which to save the new dashboard |
### from_identifier
```
from_identifier(identifier: str) -> T
```
Get an item by its unique identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ---------------------------------------- | ---------- |
| `identifier` | `str` | The unique identifier of the item to get | *required* |
Returns:
| Name | Type | Description |
| ------ | ---- | ------------------------------ |
| `item` | `T` | Item with the given identifier |
Raises:
| Type | Description |
| ------------------ | -------------------------------------------- |
| `ResourceNotFound` | If no item with the given identifier exists. |
### from_name
```
from_name(name: str, scope: WorkScope = 'my work') -> T
```
Get an item from its name
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `name` | `str` | The name of the item to get | *required* |
| `scope` | `str` | Searching scope for getting the item. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
Returns:
| Name | Type | Description |
| ------ | ---- | ---------------------------- |
| `item` | `T` | The item with the given name |
Raises:
| Type | Description |
| ------------------- | --------------------------------------------------- |
| `ResourceNotFound` | If no item with the given name exists in the scope. |
| `AmbiguousResource` | If multiple items match the given name. |
### search
```
search(
query: str | None = None,
scope: WorkScope = "my work",
page: int = 0,
size: int = 2000,
) -> PagedList[T]
```
Search items by name or description
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `query` | `str` | The search query. The '\*' can be used as a wildcard. Returns all items if query is None (default). | `None` |
| `scope` | `str` | Searching scope. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `2000` |
Returns:
| Name | Type | Description |
| ------- | -------------- | ------------------------------------------------- |
| `items` | `PagedList[T]` | Paginated list of items matching the search query |
# `client.dashboard.monitor`
## trendminer_interface.\_client.dashboard.monitor.MonitorTileFacade
Facade for creating monitor tiles
### config
```
config(
show_title: bool = True, fill_background: bool = False
) -> MonitorTileConfiguration
```
Default configuration for monitor tiles
Parameters:
| Name | Type | Description | Default |
| ----------------- | ------ | ------------------------------------------------------------------------------------------- | ------- |
| `show_title` | `bool` | Whether to show the tile title, by default True | `True` |
| `fill_background` | `bool` | Whether to fill the tile background with color based on the monitor state, by default False | `False` |
Returns:
| Type | Description |
| -------------------------- | ----------- |
| `MonitorTileConfiguration` | |
### new
```
new(
position: tuple[int, int, int, int],
monitor: Monitor,
active: MonitorTileCondition = (
"alert-circle",
"",
"#FF0010",
),
inactive: MonitorTileCondition = (
"circle-success",
"",
"#2BCE48",
),
title: str = "",
refresh_rate: Timedelta = Timedelta(minutes=1),
config: MonitorTileConfiguration | None = None,
) -> MonitorTile
```
Instantiate a new monitor tile
Parameters:
| Name | Type | Description | Default |
| -------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `position` | `tuple[int, int, int, int]` | Position of the tile on the dashboard (x, y, width, height) | *required* |
| `monitor` | `Monitor` | Monitor to display in the tile | *required* |
| `active` | `MonitorTileCondition` | Condition to display when the monitor is active (icon, text, color), by default ("alert-circle", "", "#FF0010") | `('alert-circle', '', '#FF0010')` |
| `inactive` | `MonitorTileCondition` | Condition to display when the monitor is inactive (icon, text, color), by default ("circle-success", "", "#2BCE48") | `('circle-success', '', '#2BCE48')` |
| `title` | `str` | Title of the tile, by default "" | `''` |
| `refresh_rate` | `Timedelta` | Refresh rate of the tile, by default 1m. | `Timedelta(minutes=1)` |
| `config` | `MonitorTileConfiguration` | Configuration of the tile. If None, default configuration is used. | `None` |
Returns:
| Type | Description |
| ------------- | ----------- |
| `MonitorTile` | |
# `client.dashboard.notebook`
## trendminer_interface.\_client.dashboard.notebook.NotebookTileFacade
Facade for creating notebook tiles
### config
```
config(
show_title: bool = True,
) -> NotebookTileConfiguration
```
Default configuration for notebook pipeline tiles
Parameters:
| Name | Type | Description | Default |
| ------------ | ------ | ----------------------------------------------- | ------- |
| `show_title` | `bool` | Whether to show the tile title, by default True | `True` |
Returns:
| Type | Description |
| --------------------------- | ----------- |
| `NotebookTileConfiguration` | |
### new
```
new(
position: tuple[int, int, int, int],
pipeline: Pipeline | None = None,
title: str = "",
refresh_rate: Timedelta = Timedelta(minutes=5),
config: NotebookTileConfiguration | None = None,
) -> NotebookTile
```
Instantiate a new notebook pipeline tile
Parameters:
| Name | Type | Description | Default |
| -------------- | --------------------------- | ------------------------------------------------------------------ | ---------------------- |
| `position` | `tuple[int, int, int, int]` | Position of the tile on the dashboard (x, y, width, height) | *required* |
| `pipeline` | `Pipeline` | Notebook pipeline to display in the tile | `None` |
| `title` | `str` | Title of the tile, by default "" | `''` |
| `refresh_rate` | `Timedelta` | Refresh rate of the tile, by default 5m. | `Timedelta(minutes=5)` |
| `config` | `NotebookTileConfiguration` | Configuration of the tile. If None, default configuration is used. | `None` |
Returns:
| Type | Description |
| -------------- | ----------- |
| `NotebookTile` | |
# `client.dashboard.text`
## trendminer_interface.\_client.dashboard.text.TextTileFacade
Facade for creating text tiles
### config
```
config(show_title: bool = True) -> TextTileConfiguration
```
Create a new text tile configuration
Parameters:
| Name | Type | Description | Default |
| ------------ | ------ | ------------------------------ | ------- |
| `show_title` | `bool` | Whether to show the tile title | `True` |
Returns:
| Type | Description |
| ----------------------- | ----------- |
| `TextTileConfiguration` | |
### new
```
new(
position: tuple[int, int, int, int],
content: str,
title: str = "",
config: TextTileConfiguration | None = None,
) -> TextTile
```
Create a new text tile
The text tile content will be rendered as HTML.
Parameters:
| Name | Type | Description | Default |
| ---------- | --------------------------- | ----------------------------------------------------------------------- | ---------- |
| `position` | `tuple[int, int, int, int]` | x, y, width and height of the tile on the dashboard | *required* |
| `content` | `str` | The HTML content to display in the text tile | *required* |
| `title` | `str` | The tile title | `''` |
| `config` | `TextTileConfiguration` | The configuration of the tile. Default configuration when not provided. | `None` |
Returns:
| Type | Description |
| ---------- | ----------- |
| `TextTile` | |
Examples:
```
>>> content = (
... '"
... )
>>> tile = client.dashboard.text.new(position=(0, 0, 4, 4), content=content)
```
# `client.dashboard.trend`
## trendminer_interface.\_client.dashboard.trend.TrendHubViewTileFacade
Facade for creating TrendHub view tiles
### config
```
config(
show_title: bool = True,
show_context_items: bool = True,
show_timeframe: bool = True,
show_component_names: bool = True,
show_legend: bool = True,
) -> TrendHubViewTileConfiguration
```
New configuration for TrendHub view tiles
Parameters:
| Name | Type | Description | Default |
| ---------------------- | ------ | ---------------------------------------------------------- | ------- |
| `show_title` | `bool` | Whether to show the tile title, by default True | `True` |
| `show_context_items` | `bool` | Whether to show context items, by default True | `True` |
| `show_timeframe` | `bool` | Whether to show the timeframe, by default True | `True` |
| `show_component_names` | `bool` | Whether to show data reference labels, by default True | `True` |
| `show_legend` | `bool` | Whether to show the colored points legend, by default True | `True` |
Returns:
| Type | Description |
| ------------------------------- | ----------- |
| `TrendHubViewTileConfiguration` | |
### new
```
new(
position: tuple[int, int, int, int],
view: TrendHubView,
mode: TrendHubViewTileMode = "plot",
title: str = "",
refresh_rate: Timedelta = Timedelta(minutes=5),
config: TrendHubViewTileConfiguration | None = None,
) -> TrendHubViewTile
```
Instantiate a new TrendHub view tile
Parameters:
| Name | Type | Description | Default |
| -------------- | ------------------------------- | ----------------------------------------------------------------------- | ---------------------- |
| `position` | `tuple[int, int, int, int]` | Position of the tile on the dashboard (x, y, width, height) | *required* |
| `view` | `TrendHubView` | TrendHub view to display in the tile | *required* |
| `mode` | `str` | Display mode of the tile: "plot" or "statistics table". Default "plot". | `'plot'` |
| `title` | `str` | Title of the tile, by default "" | `''` |
| `refresh_rate` | `Timedelta` | Refresh rate of the tile, by default 5m. | `Timedelta(minutes=5)` |
| `config` | `TrendHubViewTileConfiguration` | Configuration of the tile. If None, default configuration is used. | `None` |
Returns:
| Type | Description |
| ------------------ | ----------- |
| `TrendHubViewTile` | |
# `client.dashboard.value`
## trendminer_interface.\_client.dashboard.value.CurrentValueTileFacade
Facade for creating current value tiles
### config
```
config(
show_title: bool = True,
accuracy: float | None = None,
show_graph: bool = True,
graph_duration: Timedelta = Timedelta(hours=1),
fill_background: bool = False,
show_component_names: bool = True,
show_timestamp: bool = True,
use_chart_alias: bool = False,
) -> CurrentValueTileConfiguration
```
Create a new current value tile configuration
Parameters:
| Name | Type | Description | Default |
| ---------------------- | --------------- | ------------------------------------------------------------------------------------ | ------- |
| `show_title` | `bool` | Whether to show the tile title, by default True | `True` |
| `accuracy` | `float or None` | Accuracy to which values are displayed (..., 10, 1, 0.1, 0.01, ...), by default None | `None` |
| `show_graph` | `bool` | Whether to show the trend graph, by default True | `True` |
| `graph_duration` | `Timedelta` | Duration of the trend graph | `1h` |
| `fill_background` | `bool` | Whether to fill the background, by default False | `False` |
| `show_component_names` | `bool` | Whether to show component names, by default True | `True` |
| `show_timestamp` | `bool` | Whether to show timestamp of latest datapoint, by default True | `True` |
| `use_chart_alias` | `bool` | Whether to use chart aliases, by default False | `False` |
Returns:
| Type | Description |
| ------------------------------- | ----------- |
| `CurrentValueTileConfiguration` | |
### new
```
new(
position: tuple[int, int, int, int],
entries: list[CurrentValueTileEntry],
title: str = "",
refresh_rate: Timedelta = Timedelta(minutes=1),
config: CurrentValueTileConfiguration | None = None,
) -> CurrentValueTile
```
Create a new current value tile
Parameters:
| Name | Type | Description | Default |
| -------------- | ------------------------------- | ----------------------------------------------------------------------- | ---------------------- |
| `position` | `tuple[int, int, int, int]` | Position of the tile on the dashboard (x, y, width, height) | *required* |
| `entries` | `list[CurrentValueTileEntry]` | Entries to show in the tile | *required* |
| `title` | `str` | Title of the tile, by default "" | `''` |
| `refresh_rate` | `Timedelta` | Refresh rate of the tile when the dashboard is live. Default is 1m. | `Timedelta(minutes=1)` |
| `config` | `CurrentValueTileConfiguration` | Configuration of the tile, defaults to a standard configuration if None | `None` |
Returns:
| Type | Description |
| ------------------ | ----------- |
| `CurrentValueTile` | |
# `client.datasource`
## trendminer_interface.\_client.datasource.DatasourceFacade
Facade to retrieve tag datasource instances
### from_identifier
```
from_identifier(identifier: str) -> Datasource
```
Retrieve a datasource by its identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | --------------------- | ---------- |
| `identifier` | `str` | Datasource identifier | *required* |
Returns:
| Type | Description |
| ------------ | --------------------------------------- |
| `Datasource` | Datasource with the provided identifier |
Raises:
| Type | Description |
| ------------------ | -------------------------------------------------- |
| `ResourceNotFound` | If no datasource with the given identifier exists. |
### from_name
```
from_name(name: str) -> Datasource
```
Retrieve a datasource by its name
Parameters:
| Name | Type | Description | Default |
| ------ | ----- | --------------- | ---------- |
| `name` | `str` | Datasource name | *required* |
Returns:
| Type | Description |
| ------------ | --------------------------------- |
| `Datasource` | Datasource with the provided name |
Raises:
| Type | Description |
| ------------------- | --------------------------------------------- |
| `ResourceNotFound` | If no datasource with the given name exists. |
| `AmbiguousResource` | If multiple datasources match the given name. |
Notes
This method will return the datasource with the provided name, regardless of whether it is a built-in datasource or not.
### get_builtin
```
get_builtin() -> list[Datasource]
```
Get all built-in datasources
Returns:
| Type | Description |
| ------------------ | ---------------------------- |
| `list[Datasource]` | List of built-in datasources |
### search
```
search(
name: str | None = None, page: int = 0, size: int = 1000
) -> PagedList[Datasource]
```
Search for non-builtin datasources matching the provided search conditions.
Parameters:
| Name | Type | Description | Default |
| ------ | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `name` | `str` | Name search condition. Only datasources with a partial name match will be returned. Wildcard characters (\*) are NOT supported. If None (default), all datasources are returned. | `None` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `1000` |
Returns:
| Type | Description |
| ----------------------- | ---------------------------------------------------- |
| `PagedList[Datasource]` | Page with datasources matching the search conditions |
Notes
To get built-in datasources, use the `get_builtin` method.
# `client.filter`
## trendminer_interface.\_client.filter.FilterFacade
Bases: `WorkFacadeBase[Filter]`
Facade for getting saved filter objects
### define
```
define(
condition: IntervalIndex | tuple[Search, bool],
) -> FilterDefinition
```
Define a new TrendHub Filter
Parameters:
| Name | Type | Description | Default |
| ----------- | --------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `condition` | \`IntervalIndex | tuple[Search, bool]\` | The filter condition. Either the intervals to be filtered out, or a tuple with the saved search on which to filter and whether to invert the search results (False: filter out search results; True: filter out everything that is not a search result). |
Returns:
| Type | Description |
| ------------------ | ---------------------------------------- |
| `FilterDefinition` | Definition that can be passed to create. |
### create
```
create(
definition: FilterDefinition,
name: str,
description: str | None = None,
folder: Folder | None = None,
) -> Filter
```
Create a new filter in TrendMiner
Parameters:
| Name | Type | Description | Default |
| ------------- | ------------------ | ------------------------------------------------------- | ------------------------------------------ |
| `definition` | `FilterDefinition` | Definition of the new filter | *required* |
| `name` | `str` | Name of the saved filter. This will equal the tag name. | *required* |
| `description` | \`str | None\` | Description of the saved filter |
| `folder` | \`Folder | None\` | The folder in which to save the new filter |
### from_identifier
```
from_identifier(identifier: str) -> T
```
Get an item by its unique identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ---------------------------------------- | ---------- |
| `identifier` | `str` | The unique identifier of the item to get | *required* |
Returns:
| Name | Type | Description |
| ------ | ---- | ------------------------------ |
| `item` | `T` | Item with the given identifier |
Raises:
| Type | Description |
| ------------------ | -------------------------------------------- |
| `ResourceNotFound` | If no item with the given identifier exists. |
### from_name
```
from_name(name: str, scope: WorkScope = 'my work') -> T
```
Get an item from its name
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `name` | `str` | The name of the item to get | *required* |
| `scope` | `str` | Searching scope for getting the item. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
Returns:
| Name | Type | Description |
| ------ | ---- | ---------------------------- |
| `item` | `T` | The item with the given name |
Raises:
| Type | Description |
| ------------------- | --------------------------------------------------- |
| `ResourceNotFound` | If no item with the given name exists in the scope. |
| `AmbiguousResource` | If multiple items match the given name. |
### search
```
search(
query: str | None = None,
scope: WorkScope = "my work",
page: int = 0,
size: int = 2000,
) -> PagedList[T]
```
Search items by name or description
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `query` | `str` | The search query. The '\*' can be used as a wildcard. Returns all items if query is None (default). | `None` |
| `scope` | `str` | Searching scope. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `2000` |
Returns:
| Name | Type | Description |
| ------- | -------------- | ------------------------------------------------- |
| `items` | `PagedList[T]` | Paginated list of items matching the search query |
# `client.fingerprint.layer`
## trendminer_interface.\_client.fingerprint.layer.FingerprintLayerFacade
Facade for instantiating new fingerprint layers
### new
```
new(
interval: Interval,
base: bool,
name: str = "",
line_style: LineStyle | None = None,
hidden_references: list[Tag | Attribute] | None = None,
) -> FingerprintLayer
```
Define a new fingerprint layer
Parameters:
| Name | Type | Description | Default |
| ------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `interval` | `Interval` | Time interval set in the layer. | *required* |
| `base` | `bool` | Whether the layer is a base layer. Base layers always have a solid line style, and cannot be shifted. Every fingerprint must contain a single base layer. | *required* |
| `name` | `str` | Name of the layer, displayed in TrendHub. Default is an empty string, which will be displayed as 'Layer' in TrendHub. | `''` |
| `line_style` | `LineStyle` | Line style of the layer. If not specified, defaults to 'solid' for base layers and 'dash' for non-base layers. | `None` |
| `hidden_references` | \`list\[Tag | Attribute\]\` | List of tags and attributes that are hidden in the layer. Default is an empty list. |
Returns:
| Type | Description |
| ------------------ | ----------- |
| `FingerprintLayer` | |
# `client.fingerprint`
## trendminer_interface.\_client.fingerprint.FingerprintFacade
Bases: `WorkFacadeBase[Fingerprint]`
Facade for getting saved fingerprint objects
### layer
```
layer: FingerprintLayerFacade
```
Facade for instantiating new fingerprint layers
### define
```
define(
entries: list[Attribute | Tag],
layers: list[FingerprintLayer],
) -> FingerprintDefinition
```
Create a fingerprint definition
Parameters:
| Name | Type | Description | Default |
| --------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `entries` | \`list\[Tag | Attribute\]\` | List of time series entries for the fingerprint. |
| `layers` | `list[FingerprintLayer]` | List of layers included in the fingerprint. Layers are expected to contain intervals of the same length. A single layer must have been configured as the base layer. | *required* |
Returns:
| Type | Description |
| ----------------------- | ------------------------------ |
| `FingerprintDefinition` | The new fingerprint definition |
Raises:
| Type | Description |
| ------------ | -------------------------------------------------------------------------------------------------------- |
| `ValueError` | If the layers do not contain exactly one base layer, or if the layers do not all have the same duration. |
### create
```
create(
definition: FingerprintDefinition,
name: str,
description: str = "",
folder: Folder | None = None,
) -> Fingerprint
```
Create a new fingerprint in TrendMiner
Parameters:
| Name | Type | Description | Default |
| ------------- | ----------------------- | ----------------------------------------------- | ---------- |
| `definition` | `FingerprintDefinition` | Definition of the new fingerprint | *required* |
| `name` | `str` | Name of the saved fingerprint | *required* |
| `description` | `str` | Description of the saved fingerprint | `''` |
| `folder` | `Folder` | The folder in which to save the new fingerprint | `None` |
Returns:
| Type | Description |
| ------------- | ------------------------------------------- |
| `Fingerprint` | The saved fingerprint created in TrendMiner |
### from_identifier
```
from_identifier(identifier: str) -> T
```
Get an item by its unique identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ---------------------------------------- | ---------- |
| `identifier` | `str` | The unique identifier of the item to get | *required* |
Returns:
| Name | Type | Description |
| ------ | ---- | ------------------------------ |
| `item` | `T` | Item with the given identifier |
Raises:
| Type | Description |
| ------------------ | -------------------------------------------- |
| `ResourceNotFound` | If no item with the given identifier exists. |
### from_name
```
from_name(name: str, scope: WorkScope = 'my work') -> T
```
Get an item from its name
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `name` | `str` | The name of the item to get | *required* |
| `scope` | `str` | Searching scope for getting the item. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
Returns:
| Name | Type | Description |
| ------ | ---- | ---------------------------- |
| `item` | `T` | The item with the given name |
Raises:
| Type | Description |
| ------------------- | --------------------------------------------------- |
| `ResourceNotFound` | If no item with the given name exists in the scope. |
| `AmbiguousResource` | If multiple items match the given name. |
### search
```
search(
query: str | None = None,
scope: WorkScope = "my work",
page: int = 0,
size: int = 2000,
) -> PagedList[T]
```
Search items by name or description
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `query` | `str` | The search query. The '\*' can be used as a wildcard. Returns all items if query is None (default). | `None` |
| `scope` | `str` | Searching scope. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `2000` |
Returns:
| Name | Type | Description |
| ------- | -------------- | ------------------------------------------------- |
| `items` | `PagedList[T]` | Paginated list of items matching the search query |
# `client.monitor`
## trendminer_interface.\_client.monitor.MonitorFacade
Facade for retrieving monitors
Notes
Retrieving a monitor by name is not supported. You must first retrieve the search or fingerprint by its name, and then call `get_monitor` on that object.
### from_identifier
```
from_identifier(identifier: int) -> Monitor
```
Retrieve monitor from identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ------------------ | ---------- |
| `identifier` | `int` | Monitor identifier | *required* |
Returns:
| Type | Description |
| --------- | ------------------------------------- |
| `Monitor` | The monitor with the given identifier |
Raises:
| Type | Description |
| ------------------ | ----------------------------------------------- |
| `ResourceNotFound` | If no monitor with the given identifier exists. |
### get_overview
```
get_overview(
since: Timestamp | str | None = None,
) -> DataFrame
```
Get an overview of the number of hits for all active monitors
Parameters:
| Name | Type | Description | Default |
| ------- | ------------------ | ----------------------------------------------------------------------------------------- | ------- |
| `since` | `Timestamp or str` | The start date from when to count the number of monitor results (up to the current date). | `None` |
Returns:
| Type | Description |
| ----------- | -------------------------------------------------------- |
| `DataFrame` | DataFrame with columns 'monitor' and 'number_of_results' |
### search
```
search(
user: User | None = None, active_only: bool = True
) -> list[Monitor]
```
Search for monitors
Parameters:
| Name | Type | Description | Default |
| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `user` | `User` | User for which to retrieve the monitors. If not provided, monitors for the currently authenticated user are retrieved. | `None` |
| `active_only` | `bool` | Whether only the currently active monitors need to be retrieved, otherwise a monitor is retrieved for every search that is implemented in the SDK. | `True` |
Returns:
| Type | Description |
| ----------------- | ------------------------- |
| `list of Monitor` | List of Monitor instances |
Notes
Contrary to other search methods, this method does NOT result in a paginated list as the underlying endpoint is not paginated.
# `client.notebook`
## trendminer_interface.\_client.notebook.NotebookFacade
Bases: `WorkFacadeBase[Notebook]`
Facade for getting saved notebook objects
### pipeline
```
pipeline: PipelineFacade
```
Facade for getting saved pipelines
### from_identifier
```
from_identifier(identifier: str) -> T
```
Get an item by its unique identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ---------------------------------------- | ---------- |
| `identifier` | `str` | The unique identifier of the item to get | *required* |
Returns:
| Name | Type | Description |
| ------ | ---- | ------------------------------ |
| `item` | `T` | Item with the given identifier |
Raises:
| Type | Description |
| ------------------ | -------------------------------------------- |
| `ResourceNotFound` | If no item with the given identifier exists. |
### from_name
```
from_name(name: str, scope: WorkScope = 'my work') -> T
```
Get an item from its name
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `name` | `str` | The name of the item to get | *required* |
| `scope` | `str` | Searching scope for getting the item. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
Returns:
| Name | Type | Description |
| ------ | ---- | ---------------------------- |
| `item` | `T` | The item with the given name |
Raises:
| Type | Description |
| ------------------- | --------------------------------------------------- |
| `ResourceNotFound` | If no item with the given name exists in the scope. |
| `AmbiguousResource` | If multiple items match the given name. |
### search
```
search(
query: str | None = None,
scope: WorkScope = "my work",
page: int = 0,
size: int = 2000,
) -> PagedList[T]
```
Search items by name or description
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `query` | `str` | The search query. The '\*' can be used as a wildcard. Returns all items if query is None (default). | `None` |
| `scope` | `str` | Searching scope. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `2000` |
Returns:
| Name | Type | Description |
| ------- | -------------- | ------------------------------------------------- |
| `items` | `PagedList[T]` | Paginated list of items matching the search query |
# `client.notebook.pipeline`
## trendminer_interface.\_client.notebook.pipeline.PipelineFacade
Bases: `WorkFacadeBase[Pipeline]`
Facade for getting saved pipeline objects
### from_identifier
```
from_identifier(identifier: str) -> T
```
Get an item by its unique identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ---------------------------------------- | ---------- |
| `identifier` | `str` | The unique identifier of the item to get | *required* |
Returns:
| Name | Type | Description |
| ------ | ---- | ------------------------------ |
| `item` | `T` | Item with the given identifier |
Raises:
| Type | Description |
| ------------------ | -------------------------------------------- |
| `ResourceNotFound` | If no item with the given identifier exists. |
### from_name
```
from_name(name: str, scope: WorkScope = 'my work') -> T
```
Get an item from its name
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `name` | `str` | The name of the item to get | *required* |
| `scope` | `str` | Searching scope for getting the item. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
Returns:
| Name | Type | Description |
| ------ | ---- | ---------------------------- |
| `item` | `T` | The item with the given name |
Raises:
| Type | Description |
| ------------------- | --------------------------------------------------- |
| `ResourceNotFound` | If no item with the given name exists in the scope. |
| `AmbiguousResource` | If multiple items match the given name. |
### search
```
search(
query: str | None = None,
scope: WorkScope = "my work",
page: int = 0,
size: int = 2000,
) -> PagedList[T]
```
Search items by name or description
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `query` | `str` | The search query. The '\*' can be used as a wildcard. Returns all items if query is None (default). | `None` |
| `scope` | `str` | Searching scope. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `2000` |
Returns:
| Name | Type | Description |
| ------- | -------------- | ------------------------------------------------- |
| `items` | `PagedList[T]` | Paginated list of items matching the search query |
# `client.search.area`
## trendminer_interface.\_client.search.area.AreaSearchFacade
Bases: `WorkFacadeBase[AreaSearch]`
Facade for getting saved area search objects
### from_identifier
```
from_identifier(identifier: str) -> T
```
Get an item by its unique identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ---------------------------------------- | ---------- |
| `identifier` | `str` | The unique identifier of the item to get | *required* |
Returns:
| Name | Type | Description |
| ------ | ---- | ------------------------------ |
| `item` | `T` | Item with the given identifier |
Raises:
| Type | Description |
| ------------------ | -------------------------------------------- |
| `ResourceNotFound` | If no item with the given identifier exists. |
### from_name
```
from_name(name: str, scope: WorkScope = 'my work') -> T
```
Get an item from its name
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `name` | `str` | The name of the item to get | *required* |
| `scope` | `str` | Searching scope for getting the item. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
Returns:
| Name | Type | Description |
| ------ | ---- | ---------------------------- |
| `item` | `T` | The item with the given name |
Raises:
| Type | Description |
| ------------------- | --------------------------------------------------- |
| `ResourceNotFound` | If no item with the given name exists in the scope. |
| `AmbiguousResource` | If multiple items match the given name. |
### search
```
search(
query: str | None = None,
scope: WorkScope = "my work",
page: int = 0,
size: int = 2000,
) -> PagedList[T]
```
Search items by name or description
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `query` | `str` | The search query. The '\*' can be used as a wildcard. Returns all items if query is None (default). | `None` |
| `scope` | `str` | Searching scope. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `2000` |
Returns:
| Name | Type | Description |
| ------- | -------------- | ------------------------------------------------- |
| `items` | `PagedList[T]` | Paginated list of items matching the search query |
# `client.search.digital_step`
## trendminer_interface.\_client.search.digital_step.DigitalStepSearchFacade
Bases: `WorkFacadeBase[DigitalStepSearch]`
Facade for getting saved digital step search objects
### from_identifier
```
from_identifier(identifier: str) -> T
```
Get an item by its unique identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ---------------------------------------- | ---------- |
| `identifier` | `str` | The unique identifier of the item to get | *required* |
Returns:
| Name | Type | Description |
| ------ | ---- | ------------------------------ |
| `item` | `T` | Item with the given identifier |
Raises:
| Type | Description |
| ------------------ | -------------------------------------------- |
| `ResourceNotFound` | If no item with the given identifier exists. |
### from_name
```
from_name(name: str, scope: WorkScope = 'my work') -> T
```
Get an item from its name
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `name` | `str` | The name of the item to get | *required* |
| `scope` | `str` | Searching scope for getting the item. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
Returns:
| Name | Type | Description |
| ------ | ---- | ---------------------------- |
| `item` | `T` | The item with the given name |
Raises:
| Type | Description |
| ------------------- | --------------------------------------------------- |
| `ResourceNotFound` | If no item with the given name exists in the scope. |
| `AmbiguousResource` | If multiple items match the given name. |
### search
```
search(
query: str | None = None,
scope: WorkScope = "my work",
page: int = 0,
size: int = 2000,
) -> PagedList[T]
```
Search items by name or description
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `query` | `str` | The search query. The '\*' can be used as a wildcard. Returns all items if query is None (default). | `None` |
| `scope` | `str` | Searching scope. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `2000` |
Returns:
| Name | Type | Description |
| ------- | -------------- | ------------------------------------------------- |
| `items` | `PagedList[T]` | Paginated list of items matching the search query |
# `client.search`
## trendminer_interface.\_client.search.SearchFacade
Facade for interacting with searches
### value
```
value: ValueBasedSearchFacade
```
Facade for getting saved value based searches
### digital_step
```
digital_step: DigitalStepSearchFacade
```
Facade for getting saved digital step searches
### similarity
```
similarity: SimilaritySearchFacade
```
Facade for getting saved similarity searches
### area
```
area: AreaSearchFacade
```
Facade for getting saved area searches
# `client.search.similarity`
## trendminer_interface.\_client.search.similarity.SimilaritySearchFacade
Bases: `WorkFacadeBase[SimilaritySearch]`
Facade for getting saved similarity search objects
### from_identifier
```
from_identifier(identifier: str) -> T
```
Get an item by its unique identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ---------------------------------------- | ---------- |
| `identifier` | `str` | The unique identifier of the item to get | *required* |
Returns:
| Name | Type | Description |
| ------ | ---- | ------------------------------ |
| `item` | `T` | Item with the given identifier |
Raises:
| Type | Description |
| ------------------ | -------------------------------------------- |
| `ResourceNotFound` | If no item with the given identifier exists. |
### from_name
```
from_name(name: str, scope: WorkScope = 'my work') -> T
```
Get an item from its name
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `name` | `str` | The name of the item to get | *required* |
| `scope` | `str` | Searching scope for getting the item. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
Returns:
| Name | Type | Description |
| ------ | ---- | ---------------------------- |
| `item` | `T` | The item with the given name |
Raises:
| Type | Description |
| ------------------- | --------------------------------------------------- |
| `ResourceNotFound` | If no item with the given name exists in the scope. |
| `AmbiguousResource` | If multiple items match the given name. |
### search
```
search(
query: str | None = None,
scope: WorkScope = "my work",
page: int = 0,
size: int = 2000,
) -> PagedList[T]
```
Search items by name or description
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `query` | `str` | The search query. The '\*' can be used as a wildcard. Returns all items if query is None (default). | `None` |
| `scope` | `str` | Searching scope. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `2000` |
Returns:
| Name | Type | Description |
| ------- | -------------- | ------------------------------------------------- |
| `items` | `PagedList[T]` | Paginated list of items matching the search query |
# `client.search.value`
## trendminer_interface.\_client.search.value.ValueBasedSearchFacade
Bases: `WorkFacadeBase[ValueBasedSearch]`
Facade for getting saved value based search objects
### define
```
define(
queries: list[ValueBasedSearchQuery],
calculations: dict[str, SearchCalculation]
| None = None,
duration=Timedelta(minutes=2),
mode: ValueBasedSearchMode = "and",
) -> ValueBasedSearchDefinition
```
Define a new value based search
Parameters:
| Name | Type | Description | Default |
| -------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------- | ---------------------- |
| `queries` | `list[ValueBasedSearchQuery]` | List of queries to include in the search. Each query is a (Tag, operator, value) tuple. | *required* |
| `calculations` | `dict[str, SearchCalculation]` | Dictionary of calculations to include in the search, by default None | `None` |
| `duration` | `Timedelta` | Duration of the search, by default 2 minutes | `Timedelta(minutes=2)` |
| `mode` | `('and', 'or')` | How to combine multiple queries: "and" requires all queries to match simultaneously, "or" requires at least one. | `"and"` |
Returns:
| Type | Description |
| ---------------------------- | -------------------------------------- |
| `ValueBasedSearchDefinition` | The new value based search definition. |
Examples:
```
>>> definition = client.search.value.define(
... queries=[(tag, ">", 100.0), (other_tag, "=", "running")],
... mode="and",
... )
```
### create
```
create(
definition: ValueBasedSearchDefinition,
name: str,
description: str | None = None,
folder: Folder | None = None,
) -> ValueBasedSearch
```
Create a new value-based search in TrendMiner
Parameters:
| Name | Type | Description | Default |
| ------------- | ---------------------------- | ---------------------------------------- | ------------------------------------------ |
| `definition` | `ValueBasedSearchDefinition` | Definition of the new value-based search | *required* |
| `name` | `str` | Name of the saved search | *required* |
| `description` | \`str | None\` | Description of the saved search |
| `folder` | \`Folder | None\` | The folder in which to save the new search |
### from_identifier
```
from_identifier(identifier: str) -> T
```
Get an item by its unique identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ---------------------------------------- | ---------- |
| `identifier` | `str` | The unique identifier of the item to get | *required* |
Returns:
| Name | Type | Description |
| ------ | ---- | ------------------------------ |
| `item` | `T` | Item with the given identifier |
Raises:
| Type | Description |
| ------------------ | -------------------------------------------- |
| `ResourceNotFound` | If no item with the given identifier exists. |
### from_name
```
from_name(name: str, scope: WorkScope = 'my work') -> T
```
Get an item from its name
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `name` | `str` | The name of the item to get | *required* |
| `scope` | `str` | Searching scope for getting the item. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
Returns:
| Name | Type | Description |
| ------ | ---- | ---------------------------- |
| `item` | `T` | The item with the given name |
Raises:
| Type | Description |
| ------------------- | --------------------------------------------------- |
| `ResourceNotFound` | If no item with the given name exists in the scope. |
| `AmbiguousResource` | If multiple items match the given name. |
### search
```
search(
query: str | None = None,
scope: WorkScope = "my work",
page: int = 0,
size: int = 2000,
) -> PagedList[T]
```
Search items by name or description
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `query` | `str` | The search query. The '\*' can be used as a wildcard. Returns all items if query is None (default). | `None` |
| `scope` | `str` | Searching scope. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `2000` |
Returns:
| Name | Type | Description |
| ------- | -------------- | ------------------------------------------------- |
| `items` | `PagedList[T]` | Paginated list of items matching the search query |
# `client.tag.index_details`
## trendminer_interface.\_client.tag.index_details.IndexDetailsFacade
Facade to retrieve indexing details of tags
### from_name
```
from_name(
name: str, datasource: Datasource | None = None
) -> IndexDetails
```
Get index details for a tag from its name.
Parameters:
| Name | Type | Description | Default |
| ------------ | ------------ | ------------------------------------------------------------------------------------------------------- | ---------- |
| `name` | `str` | The name of the tag in TrendMiner. | *required* |
| `datasource` | `Datasource` | The datasource of the tag. By default, the index details of any tag matching the name will be returned. | `None` |
Returns:
| Type | Description |
| -------------- | ----------------------------------------------------- |
| `IndexDetails` | The index details for the tag with the provided name. |
Raises:
| Type | Description |
| ------------------- | -------------------------------------- |
| `ResourceNotFound` | If no tag with the given name exists. |
| `AmbiguousResource` | If multiple tags match the given name. |
### search
```
search(
name: str | None = None,
statuses: list[TagIndexStatus] | None = None,
datasources: list[Datasource] | None = None,
delayed: bool | None = None,
freq: Timedelta
| tuple[Timedelta, Timedelta]
| None = None,
page: int = 0,
size: int = 10000,
) -> PagedList[IndexDetails]
```
Search index details
Parameters:
| Name | Type | Description | Default |
| ------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `name` | `str` | Tag name search query | `None` |
| `statuses` | `list of TagIndexStatus` | Filter on specific index statuses. See TagIndexStatus for the allowed values. | `None` |
| `datasources` | `List[Datasource]` | Filter on specific datasources | `None` |
| `delayed` | `bool` | Filter on only delayed or non-delayed indexes. A tag is considered delayed if its last index update is longer ago than 4 times the configured index update frequency. | `None` |
| `freq` | `Timedelta or tuple[Timedelta, Timedelta]` | The configured index update frequency: - 2m as the monitor policy - 1h as a default policy - 24h for reduced policy When a tuple is given, the first value is considered the minimum, the second value the maximum. | `None` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `10000` |
Returns:
| Type | Description |
| ------------------------- | ------------------------------------------------------------ |
| `PagedList[IndexDetails]` | Paginated list of index details matching the search criteria |
Notes
If no parameters are given, all index details are returned.
# `client.tag`
## trendminer_interface.\_client.tag.TagFacade
Facade to retrieve and create TrendMiner tag instances
### index_details
```
index_details: IndexDetailsFacade
```
Get facade for retrieving indexing details of tags.
### from_identifier
```
from_identifier(identifier: str) -> Tag
```
Get a tag instance from its identifier.
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ---------------------------------- | ---------- |
| `identifier` | `str` | The UUID of the tag in TrendMiner. | *required* |
Returns:
| Type | Description |
| ----- | ---------------------------------------------- |
| `Tag` | The tag instance with the provided identifier. |
Raises:
| Type | Description |
| ------------------ | ------------------------------------------- |
| `ResourceNotFound` | If no tag with the given identifier exists. |
### from_name
```
from_name(
name: str, datasource: Datasource | None = None
) -> Tag
```
Get a tag instance from its name.
Parameters:
| Name | Type | Description | Default |
| ------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------- | ---------- |
| `name` | `str` | The name of the tag in TrendMiner. | *required* |
| `datasource` | `Datasource` | The datasource to which the tag belongs. By default, the tag with the given name from any datasource will be returned. | `None` |
Returns:
| Type | Description |
| ----- | ---------------------------------------- |
| `Tag` | The tag instance with the provided name. |
Raises:
| Type | Description |
| ------------------- | -------------------------------------- |
| `ResourceNotFound` | If no tag with the given name exists. |
| `AmbiguousResource` | If multiple tags match the given name. |
### search
```
search(
name: str | None = None,
description: str | None = None,
datasources: list[Datasource] | None = None,
page: int = 0,
size: int = 2000,
) -> PagedList[Tag]
```
Search tags
Parameters:
| Name | Type | Description | Default |
| ------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `name` | `str` | Tag name filter, can use '\*' as wildcard | `None` |
| `description` | `str` | Tag description filter, can use '\*' as wildcard | `None` |
| `datasources` | `List[Datasource]` | Datasources to which to limit the search. By default, all accessible datasources are searched. | `None` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. Default is set to 2000, which is the maximum size supported by the API. Set a smaller size for exploratory purposes. | `2000` |
Returns:
| Type | Description |
| ---------------- | --------------------------------------------------- |
| `PagedList[Tag]` | Paginated list of tags matching the search criteria |
# `client.tag_builder.aggregation`
## trendminer_interface.\_client.tag_builder.aggregation.AggregationFacade
Bases: `WorkFacadeBase[Aggregation]`
Facade for getting saved aggregation objects
### define
```
define(
target: Tag,
method: TagAggregationMethod,
position: TagAggregationPosition,
window: Timedelta,
units: str | None = None,
) -> AggregationDefinition
```
Define a new aggregation definition
Parameters:
| Name | Type | Description | Default |
| ---------- | ------------------------ | ------------------------------------------- | -------------------------------------- |
| `target` | `Tag` | The tag that is aggregated | *required* |
| `method` | `TagAggregationMethod` | Method by which to aggregate the target tag | *required* |
| `position` | `TagAggregationPosition` | Tag aggregation position | *required* |
| `window` | `Timedelta` | Aggregation window | *required* |
| `units` | \`str | None\` | Units of the resulting aggregation tag |
Returns:
| Type | Description |
| ----------------------- | -------------------------------- |
| `AggregationDefinition` | Resulting aggregation definition |
### create
```
create(
definition: AggregationDefinition,
name: str,
description: str | None = None,
folder: Folder | None = None,
) -> Aggregation
```
Create a new aggregation in TrendMiner
Parameters:
| Name | Type | Description | Default |
| ------------- | ----------------------- | ------------------------------------------------------------ | ----------------------------------------------- |
| `definition` | `AggregationDefinition` | Definition of the new aggregation | *required* |
| `name` | `str` | Name of the saved aggregation. This will equal the tag name. | *required* |
| `description` | \`str | None\` | Description of the saved aggregation |
| `folder` | \`Folder | None\` | The folder in which to save the new aggregation |
### from_identifier
```
from_identifier(identifier: str) -> T
```
Get an item by its unique identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ---------------------------------------- | ---------- |
| `identifier` | `str` | The unique identifier of the item to get | *required* |
Returns:
| Name | Type | Description |
| ------ | ---- | ------------------------------ |
| `item` | `T` | Item with the given identifier |
Raises:
| Type | Description |
| ------------------ | -------------------------------------------- |
| `ResourceNotFound` | If no item with the given identifier exists. |
### from_name
```
from_name(name: str, scope: WorkScope = 'my work') -> T
```
Get an item from its name
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `name` | `str` | The name of the item to get | *required* |
| `scope` | `str` | Searching scope for getting the item. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
Returns:
| Name | Type | Description |
| ------ | ---- | ---------------------------- |
| `item` | `T` | The item with the given name |
Raises:
| Type | Description |
| ------------------- | --------------------------------------------------- |
| `ResourceNotFound` | If no item with the given name exists in the scope. |
| `AmbiguousResource` | If multiple items match the given name. |
### search
```
search(
query: str | None = None,
scope: WorkScope = "my work",
page: int = 0,
size: int = 2000,
) -> PagedList[T]
```
Search items by name or description
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `query` | `str` | The search query. The '\*' can be used as a wildcard. Returns all items if query is None (default). | `None` |
| `scope` | `str` | Searching scope. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `2000` |
Returns:
| Name | Type | Description |
| ------- | -------------- | ------------------------------------------------- |
| `items` | `PagedList[T]` | Paginated list of items matching the search query |
# `client.tag_builder.custom_calculation`
## trendminer_interface.\_client.tag_builder.custom_calculation.CustomCalculationFacade
Bases: `WorkFacadeBase[CustomCalculation]`
Facade for getting saved custom calculation objects
### define
```
define(
script: str,
dependencies: list[Tag] | None = None,
tag_type: NumericTagType = "analog",
units: str | None = None,
) -> CustomCalculationDefinition
```
Define a new custom calculation definition
Parameters:
| Name | Type | Description | Default |
| -------------- | ---------------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| `script` | `str` | The Python script for the custom calculation | *required* |
| `dependencies` | `list[Tag]` | The tags the custom calculation is dependent on. The indexes of these tags will be kept up to date. | `None` |
| `tag_type` | `NumericTagType` | Custom calculation tag type | `'analog'` |
| `units` | \`str | None\` | Units of the resulting custom calculation tag |
Returns:
| Type | Description |
| ----------------------------- | --------------------------------------- |
| `CustomCalculationDefinition` | Resulting custom calculation definition |
### create
```
create(
definition: CustomCalculationDefinition,
name: str,
description: str | None = None,
folder: Folder | None = None,
) -> CustomCalculation
```
Create a new custom calculation in TrendMiner
Parameters:
| Name | Type | Description | Default |
| ------------- | ----------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------ |
| `definition` | `CustomCalculationDefinition` | Definition of the new custom calculation | *required* |
| `name` | `str` | Name of the saved custom calculation. This will equal the tag name. | *required* |
| `description` | \`str | None\` | Description of the saved custom calculation |
| `folder` | \`Folder | None\` | The folder in which to save the new custom calculation |
### from_identifier
```
from_identifier(identifier: str) -> T
```
Get an item by its unique identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ---------------------------------------- | ---------- |
| `identifier` | `str` | The unique identifier of the item to get | *required* |
Returns:
| Name | Type | Description |
| ------ | ---- | ------------------------------ |
| `item` | `T` | Item with the given identifier |
Raises:
| Type | Description |
| ------------------ | -------------------------------------------- |
| `ResourceNotFound` | If no item with the given identifier exists. |
### from_name
```
from_name(name: str, scope: WorkScope = 'my work') -> T
```
Get an item from its name
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `name` | `str` | The name of the item to get | *required* |
| `scope` | `str` | Searching scope for getting the item. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
Returns:
| Name | Type | Description |
| ------ | ---- | ---------------------------- |
| `item` | `T` | The item with the given name |
Raises:
| Type | Description |
| ------------------- | --------------------------------------------------- |
| `ResourceNotFound` | If no item with the given name exists in the scope. |
| `AmbiguousResource` | If multiple items match the given name. |
### search
```
search(
query: str | None = None,
scope: WorkScope = "my work",
page: int = 0,
size: int = 2000,
) -> PagedList[T]
```
Search items by name or description
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `query` | `str` | The search query. The '\*' can be used as a wildcard. Returns all items if query is None (default). | `None` |
| `scope` | `str` | Searching scope. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `2000` |
Returns:
| Name | Type | Description |
| ------- | -------------- | ------------------------------------------------- |
| `items` | `PagedList[T]` | Paginated list of items matching the search query |
# `client.tag_builder.formula`
## trendminer_interface.\_client.tag_builder.formula.FormulaFacade
Bases: `WorkFacadeBase[Formula]`
Facade for getting saved formula objects
### define
```
define(
formula: str,
mapping: dict[str, Tag],
units: str | None = None,
) -> FormulaDefinition
```
Define a new formula definition
Parameters:
| Name | Type | Description | Default |
| --------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
| `formula` | `str` | The formula text | *required* |
| `mapping` | `dict[str, Tag]` | The mapping of formula text variables to tags. All variables must be mapped. An empty dict should be provided in case the formula has no variables. The Tag.shift attributes will be taken into account for the mapping. | *required* |
| `units` | `str` | Units of resulting formula tags created from the definition | `None` |
Returns:
| Type | Description |
| ------------------- | ---------------------------- |
| `FormulaDefinition` | Resulting formula definition |
### create
```
create(
definition: FormulaDefinition,
name: str,
description: str | None = None,
folder: Folder | None = None,
) -> Formula
```
Create a new formula in TrendMiner
Parameters:
| Name | Type | Description | Default |
| ------------- | ------------------- | -------------------------------------------------------- | ------------------------------------------- |
| `definition` | `FormulaDefinition` | Definition of the new formula | *required* |
| `name` | `str` | Name of the saved formula. This will equal the tag name. | *required* |
| `description` | \`str | None\` | Description of the saved formula |
| `folder` | \`Folder | None\` | The folder in which to save the new formula |
### from_identifier
```
from_identifier(identifier: str) -> T
```
Get an item by its unique identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ---------------------------------------- | ---------- |
| `identifier` | `str` | The unique identifier of the item to get | *required* |
Returns:
| Name | Type | Description |
| ------ | ---- | ------------------------------ |
| `item` | `T` | Item with the given identifier |
Raises:
| Type | Description |
| ------------------ | -------------------------------------------- |
| `ResourceNotFound` | If no item with the given identifier exists. |
### from_name
```
from_name(name: str, scope: WorkScope = 'my work') -> T
```
Get an item from its name
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `name` | `str` | The name of the item to get | *required* |
| `scope` | `str` | Searching scope for getting the item. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
Returns:
| Name | Type | Description |
| ------ | ---- | ---------------------------- |
| `item` | `T` | The item with the given name |
Raises:
| Type | Description |
| ------------------- | --------------------------------------------------- |
| `ResourceNotFound` | If no item with the given name exists in the scope. |
| `AmbiguousResource` | If multiple items match the given name. |
### search
```
search(
query: str | None = None,
scope: WorkScope = "my work",
page: int = 0,
size: int = 2000,
) -> PagedList[T]
```
Search items by name or description
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `query` | `str` | The search query. The '\*' can be used as a wildcard. Returns all items if query is None (default). | `None` |
| `scope` | `str` | Searching scope. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `2000` |
Returns:
| Name | Type | Description |
| ------- | -------------- | ------------------------------------------------- |
| `items` | `PagedList[T]` | Paginated list of items matching the search query |
# `client.tag_builder.imported`
## trendminer_interface.\_client.tag_builder.imported.TagImportFacade
Facade for creating new imported tags and retrieving existing imports
### create
```
create(
name: str,
data: Series,
tag_type: ImportTagType,
description: str | None = None,
units: str | None = None,
) -> None
```
Import a new tag or overwrite an existing imported tag with the same name
Parameters:
| Name | Type | Description | Default |
| ------------- | --------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `name` | `str` | The name of the imported tag | *required* |
| `data` | `Series` | The time series data of the imported tag. Must have DatetimeIndex and a data dtype compatible with the tag type. | *required* |
| `tag_type` | `ImportTagType` | The type of the imported tag | *required* |
| `description` | \`str | None\` | The description of the imported tag |
| `units` | \`str | None\` | The units of the imported tag |
Returns:
| Type | Description |
| ------ | ----------- |
| `None` | |
Notes
- The resulting tag will not be automatically indexed.
- If the DatetimeIndex is not timezone-aware, it will be assumed to be in the client timezone
### search
```
search(
query: str | None = None,
page: int = 0,
size: int = 1000,
) -> PagedList[TagImport]
```
Search for tag imports
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | --------------------------------------------------------------------------------------------- | ------- |
| `query` | `str` | Query for tag name or description. Wildcard character '\*' is supported. | `None` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `1000` |
### from_name
```
from_name(name: str) -> TagImport
```
Get a tag import instance from its tag name
Parameters:
| Name | Type | Description | Default |
| ------ | ----- | ---------------------------- | ---------- |
| `name` | `str` | The name of the imported tag | *required* |
Returns:
| Type | Description |
| ----------- | ----------- |
| `TagImport` | |
Raises:
| Type | Description |
| ------------------- | ----------------------------------------------- |
| `ResourceNotFound` | If no imported tag with the given name exists. |
| `AmbiguousResource` | If multiple imported tags match the given name. |
# `client.tag_builder.machine_learning_model`
## trendminer_interface.\_client.tag_builder.machine_learning_model.MachineLearningModelFacade
Bases: `WorkFacadeBase[MachineLearningModel]`
Facade for getting saved machine learning model objects
### from_identifier
```
from_identifier(identifier: str) -> T
```
Get an item by its unique identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ---------------------------------------- | ---------- |
| `identifier` | `str` | The unique identifier of the item to get | *required* |
Returns:
| Name | Type | Description |
| ------ | ---- | ------------------------------ |
| `item` | `T` | Item with the given identifier |
Raises:
| Type | Description |
| ------------------ | -------------------------------------------- |
| `ResourceNotFound` | If no item with the given identifier exists. |
### from_name
```
from_name(name: str, scope: WorkScope = 'my work') -> T
```
Get an item from its name
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `name` | `str` | The name of the item to get | *required* |
| `scope` | `str` | Searching scope for getting the item. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
Returns:
| Name | Type | Description |
| ------ | ---- | ---------------------------- |
| `item` | `T` | The item with the given name |
Raises:
| Type | Description |
| ------------------- | --------------------------------------------------- |
| `ResourceNotFound` | If no item with the given name exists in the scope. |
| `AmbiguousResource` | If multiple items match the given name. |
### search
```
search(
query: str | None = None,
scope: WorkScope = "my work",
page: int = 0,
size: int = 2000,
) -> PagedList[T]
```
Search items by name or description
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `query` | `str` | The search query. The '\*' can be used as a wildcard. Returns all items if query is None (default). | `None` |
| `scope` | `str` | Searching scope. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `2000` |
Returns:
| Name | Type | Description |
| ------- | -------------- | ------------------------------------------------- |
| `items` | `PagedList[T]` | Paginated list of items matching the search query |
# `client.tag_builder`
## trendminer_interface.\_client.tag_builder.TagBuilderFacade
Facade for interacting with tag builder objects
### aggregation
```
aggregation: AggregationFacade
```
Facade for getting tag builder aggregations
### custom_calculation
```
custom_calculation: CustomCalculationFacade
```
Facade for getting tag builder custom calculations
### formula
```
formula: FormulaFacade
```
Facade for getting tag builder formulas
### machine_learning_model
```
machine_learning_model: MachineLearningModelFacade
```
Facade for getting tag builder machine learning models
### prediction
```
prediction: PredictionFacade
```
Facade for getting tag builder predictions
### imported
```
imported: TagImportFacade
```
Facade for managing tag imports
# `client.tag_builder.prediction`
## trendminer_interface.\_client.tag_builder.prediction.PredictionFacade
Bases: `WorkFacadeBase[Prediction]`
Facade for getting and creating prediction items
A prediction can be created from an existing prediction definition, but defining and modifying predictions can only be done from the TrendMiner user interface.
### create
```
create(
definition: PredictionDefinition,
name: str,
description: str | None = None,
folder: Folder | None = None,
) -> Prediction
```
Create a new prediction in TrendMiner
Parameters:
| Name | Type | Description | Default |
| ------------- | ---------------------- | ----------------------------------------------------------- | ---------- |
| `definition` | `PredictionDefinition` | Definition of the new prediction | *required* |
| `name` | `str` | Name of the saved prediction. This will equal the tag name. | *required* |
| `description` | `str` | Description of the saved prediction | `None` |
| `folder` | `Folder` | The folder in which to save the new prediction | `None` |
### from_identifier
```
from_identifier(identifier: str) -> T
```
Get an item by its unique identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ---------------------------------------- | ---------- |
| `identifier` | `str` | The unique identifier of the item to get | *required* |
Returns:
| Name | Type | Description |
| ------ | ---- | ------------------------------ |
| `item` | `T` | Item with the given identifier |
Raises:
| Type | Description |
| ------------------ | -------------------------------------------- |
| `ResourceNotFound` | If no item with the given identifier exists. |
### from_name
```
from_name(name: str, scope: WorkScope = 'my work') -> T
```
Get an item from its name
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `name` | `str` | The name of the item to get | *required* |
| `scope` | `str` | Searching scope for getting the item. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
Returns:
| Name | Type | Description |
| ------ | ---- | ---------------------------- |
| `item` | `T` | The item with the given name |
Raises:
| Type | Description |
| ------------------- | --------------------------------------------------- |
| `ResourceNotFound` | If no item with the given name exists in the scope. |
| `AmbiguousResource` | If multiple items match the given name. |
### search
```
search(
query: str | None = None,
scope: WorkScope = "my work",
page: int = 0,
size: int = 2000,
) -> PagedList[T]
```
Search items by name or description
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `query` | `str` | The search query. The '\*' can be used as a wildcard. Returns all items if query is None (default). | `None` |
| `scope` | `str` | Searching scope. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `2000` |
Returns:
| Name | Type | Description |
| ------- | -------------- | ------------------------------------------------- |
| `items` | `PagedList[T]` | Paginated list of items matching the search query |
# `client.trend.chart`
## trendminer_interface.\_client.trend.chart.ChartPropertiesFacade
Facade for creating new chart property instances
### stacked
```
stacked: StackedChartPropertiesFacade
```
Facade for creating new stacked chart properties
### trend
```
trend: TrendChartPropertiesFacade
```
Facade for creating new trend chart properties
### scatter
```
scatter: ScatterChartPropertiesFacade
```
Facade for creating scatter chart properties
# `client.trend.chart.scatter`
## trendminer_interface.\_client.trend.chart.scatter.ScatterChartPropertiesFacade
Facade for creating new scatter chart properties
### new
```
new(
locked: bool = False,
label_type: ChartLabelType = "alias",
grid_lines: bool = False,
) -> ScatterChartProperties
```
Create a new scatter chart properties instance
Parameters:
| Name | Type | Description | Default |
| ------------ | ---------------- | ------------------------------------------------------- | --------- |
| `locked` | `bool` | Whether to lock the focus chart duration | `False` |
| `label_type` | `ChartLabelType` | Property by which to label the view tags and attributes | `"alias"` |
| `grid_lines` | `bool` | Whether to show grid lines | `False` |
Notes
Other scatter plot chart properties such as colors, layer selection and reference lines are currently not configurable, and will be set to default.
# `client.trend.chart.stacked`
## trendminer_interface.\_client.trend.chart.stacked.StackedChartPropertiesFacade
Facade for creating new stacked chart properties
### new
```
new(
locked: bool = False,
label_type: ChartLabelType = "alias",
grid_lines: bool = False,
filling: bool = False,
context: bool = True,
collapsed_filters: bool = False,
single_line_labels: bool = True,
) -> StackedChartProperties
```
Create a new stacked chart properties instance
Parameters:
| Name | Type | Description | Default |
| -------------------- | ---------------- | ---------------------------------------------------------------- | --------- |
| `locked` | `bool` | Whether to lock the focus chart duration | `False` |
| `label_type` | `ChartLabelType` | Property by which to label the view tags and attributes | `"alias"` |
| `grid_lines` | `bool` | Whether to show grid lines | `False` |
| `context` | `bool` | Whether to display context items | `True` |
| `filling` | `bool` | Whether to fill the area below the trend | `False` |
| `collapsed_filters` | `bool` | Whether to collapse rather than mark filtered-out intervals | `False` |
| `single_line_labels` | `bool` | Whether to display all tag and attribute labels on a single line | `True` |
# `client.trend.chart.trend`
## trendminer_interface.\_client.trend.chart.trend.TrendChartPropertiesFacade
Facade for creating new trend chart properties
### new
```
new(
locked: bool = False,
label_type: ChartLabelType = "alias",
grid_lines: bool = False,
filling: bool = False,
context: bool = True,
collapsed_filters: bool = False,
) -> TrendChartProperties
```
Create a new trend chart properties instance
Parameters:
| Name | Type | Description | Default |
| ------------------- | ---------------- | ----------------------------------------------------------- | --------- |
| `locked` | `bool` | Whether to lock the focus chart duration | `False` |
| `label_type` | `ChartLabelType` | Property by which to label the view tags and attributes | `"alias"` |
| `grid_lines` | `bool` | Whether to show grid lines | `False` |
| `context` | `bool` | Whether to display context items | `True` |
| `filling` | `bool` | Whether to fill the area below the trend | `False` |
| `collapsed_filters` | `bool` | Whether to collapse rather than mark filtered-out intervals | `False` |
# `client.trend.group`
## trendminer_interface.\_client.trend.group.TrendHubEntryGroupFacade
Facade for instantiating new TrendHub entry groups
### new
```
new(
entries: list[Tag | Attribute],
name: str,
scale: tuple[float, float] | None = None,
accuracy: float | None = None,
) -> TrendHubEntryGroup
```
Create a new TrendHub group of tags and attributes
Parameters:
| Name | Type | Description | Default |
| ---------- | --------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entries` | \`list\[Tag | Attribute\]\` | List of at least two tags and/or attributes to group. |
| `name` | `str` | Name of the group, as displayed in TrendHub. | *required* |
| `scale` | \`tuple[float, float] | None\` | Scale to use for the group. Autoscale if None. |
| `accuracy` | \`float | None\` | The accuracy to which tag value representations are rounded. A natural exponent of 10 (..., 10, 0.1, 0.01, ...). If None, no rounding is applied. |
Returns:
| Type | Description |
| -------------------- | ----------- |
| `TrendHubEntryGroup` | |
# `client.trend.layer`
## trendminer_interface.\_client.trend.layer.TrendHubLayerFacade
Facade for instantiating new TrendHub layers
### new
```
new(
interval: Interval,
base: bool,
name: str = "",
line_style: LineStyle | None = None,
visible: bool = True,
hidden_references: list[Tag | Attribute] | None = None,
) -> TrendHubLayer
```
Define a new TrendHub view layer
Parameters:
| Name | Type | Description | Default |
| ------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `interval` | `Interval` | Time interval set in the layer. Matches the interval displayed in the TrendHub view only if the view is not live and there is no shift applied to the layer. The layers in a TrendHub view are expected to have intervals with the same duration. | *required* |
| `base` | `bool` | Whether the layer is a base layer. Base layers are always visible, have a solid line style, and cannot be shifted. Every TrendHub view must have a single base layer. | *required* |
| `name` | `str` | Name of the layer, displayed in TrendHub. Default is an empty string, which will be shown as 'Layer' in TrendHub. | `''` |
| `line_style` | `LineStyle` | Line style of the layer. If not specified, defaults to 'solid' for base layers and 'dash' for non-base layers. | `None` |
| `visible` | `bool` | Whether the layer is visible in the TrendHub view. Default is True. Base layers must be visible. | `True` |
| `hidden_references` | \`list\[Tag | Attribute\]\` | List of tags and attributes that are hidden in the layer. Default is an empty list. |
Returns:
| Type | Description |
| --------------- | ----------- |
| `TrendHubLayer` | |
# `client.trend`
## trendminer_interface.\_client.trend.TrendFacade
Facade for interacting with TrendHub views, layers, and entry groups
### view
```
view: TrendHubViewFacade
```
Facade for getting saved trend hub views
### layer
```
layer: TrendHubLayerFacade
```
Facade for instantiating new TrendHub layers
### group
```
group: TrendHubEntryGroupFacade
```
Facade for instantiating new TrendHub entry groups
### chart
```
chart: ChartPropertiesFacade
```
Facade for creating new charting property instances
# `client.trend.view`
## trendminer_interface.\_client.trend.view.TrendHubViewFacade
Bases: `WorkFacadeBase[TrendHubView]`
Facade for getting saved trend hub view objects
### define
```
define(
entries: Sequence[Tag | Attribute | TrendHubEntryGroup],
layers: Sequence[TrendHubLayer],
context_interval: Interval,
chart_properties: ChartProperties | None = None,
live: bool = False,
filter_entries: Sequence[tuple[Filter, bool]]
| None = None,
fingerprint_entries: Sequence[
tuple[Fingerprint, bool, Interval]
]
| None = None,
) -> TrendHubViewDefinition
```
Define a new TrendHub view
Parameters:
| Name | Type | Description | Default |
| --------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| `entries` | \`list\[Tag | Attribute | TrendHubEntryGroup\]\` |
| `layers` | `list[TrendHubLayer]` | List of layers to show in the view. Layers are expected to have intervals of the same length. A single layer must have been configured as the base layer. | *required* |
| `context_interval` | `Interval` | Context interval for the view. | *required* |
| `chart_properties` | `ChartProperties` | View chart configuration. Defaults to standard stacked plot representation. | `None` |
| `live` | `bool` | Whether the view base layer should always update to end at the current time. | `False` |
| `filter_entries` | `list[tuple[Filter, bool]]` | List of filters included in the view, with their active state | `None` |
| `fingerprint_entries` | `list[tuple[Fingerprint, bool, Interval]]` | List of fingerprints included in the view, with their active state and interval to which they apply | `None` |
Returns:
| Type | Description |
| ------------------------ | ----------- |
| `TrendHubViewDefinition` | |
Raises:
| Type | Description |
| ------------ | ------------------------------------------------------ |
| `ValueError` | If the input layers do not all have the same duration. |
Notes
Statistics and layer comparison table formats are currently not configurable
### create
```
create(
definition: TrendHubViewDefinition,
name: str,
description: str | None = None,
folder: Folder | None = None,
) -> TrendHubView
```
Create a new TrendHub view in TrendMiner
Parameters:
| Name | Type | Description | Default |
| ------------- | ------------------------ | ----------------------------------- | ---------------------------------------- |
| `definition` | `TrendHubViewDefinition` | Definition of the new TrendHub view | *required* |
| `name` | `str` | Name of the saved view | *required* |
| `description` | \`str | None\` | Description of the saved view |
| `folder` | \`Folder | None\` | The folder in which to save the new view |
Returns:
| Type | Description |
| -------------- | ------------------------------------- |
| `TrendHubView` | The saved view created in TrendMiner. |
### from_identifier
```
from_identifier(identifier: str) -> T
```
Get an item by its unique identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ---------------------------------------- | ---------- |
| `identifier` | `str` | The unique identifier of the item to get | *required* |
Returns:
| Name | Type | Description |
| ------ | ---- | ------------------------------ |
| `item` | `T` | Item with the given identifier |
Raises:
| Type | Description |
| ------------------ | -------------------------------------------- |
| `ResourceNotFound` | If no item with the given identifier exists. |
### from_name
```
from_name(name: str, scope: WorkScope = 'my work') -> T
```
Get an item from its name
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `name` | `str` | The name of the item to get | *required* |
| `scope` | `str` | Searching scope for getting the item. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
Returns:
| Name | Type | Description |
| ------ | ---- | ---------------------------- |
| `item` | `T` | The item with the given name |
Raises:
| Type | Description |
| ------------------- | --------------------------------------------------- |
| `ResourceNotFound` | If no item with the given name exists in the scope. |
| `AmbiguousResource` | If multiple items match the given name. |
### search
```
search(
query: str | None = None,
scope: WorkScope = "my work",
page: int = 0,
size: int = 2000,
) -> PagedList[T]
```
Search items by name or description
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `query` | `str` | The search query. The '\*' can be used as a wildcard. Returns all items if query is None (default). | `None` |
| `scope` | `str` | Searching scope. - 'my work': The authenticated user's work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `2000` |
Returns:
| Name | Type | Description |
| ------- | -------------- | ------------------------------------------------- |
| `items` | `PagedList[T]` | Paginated list of items matching the search query |
# `client.user.group`
## trendminer_interface.\_client.user.group.UserGroupFacade
Facade for user group related operations in TrendMiner.
### everyone
```
everyone: UserGroup
```
Group representing all TrendMiner users
This group is always present. It has a fixed identifier and name.
Returns:
| Name | Type | Description |
| ---------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
| `everyone` | `UserGroup` | Group representing all TrendMiner users, with: - identifier: "99999999-9999-9999-9999-999999999999" - name: "\*" |
Notes
This group is not retrievable from its identifier or name.
### from_identifier
```
from_identifier(identifier: str) -> UserGroup
```
Get a user group by its identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ---------------------- | ---------- |
| `identifier` | `str` | UUID of the user group | *required* |
Returns:
| Type | Description |
| ----------- | --------------------------------------------------- |
| `UserGroup` | User group corresponding to the provided identifier |
Raises:
| Type | Description |
| ------------------ | -------------------------------------------------- |
| `ResourceNotFound` | If no user group with the given identifier exists. |
### from_name
```
from_name(name: str) -> UserGroup
```
Get a user group by its name
Parameters:
| Name | Type | Description | Default |
| ------ | ----- | ---------------------- | ---------- |
| `name` | `str` | Name of the user group | *required* |
Returns:
| Type | Description |
| ----------- | --------------------------------------------- |
| `UserGroup` | User group corresponding to the provided name |
Raises:
| Type | Description |
| ------------------- | --------------------------------------------- |
| `ResourceNotFound` | If no user group with the given name exists. |
| `AmbiguousResource` | If multiple user groups match the given name. |
### search
```
search(
name: str, page: int = 0, size: int = 10000
) -> PagedList[UserGroup]
```
Search for user groups by name
Parameters:
| Name | Type | Description | Default |
| ------ | ----- | --------------------------------------------------------------------------------------------- | ---------- |
| `name` | `str` | Partial name to search for. Wildcard character (\*) is not supported. | *required* |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `10000` |
Returns:
| Type | Description |
| ---------------------- | ---------------------------------------------------------- |
| `PagedList[UserGroup]` | Paginated list of user groups matching the search criteria |
# `client.user`
## trendminer_interface.\_client.user.UserFacade
Facade for user related operations in TrendMiner.
### group
```
group: UserGroupFacade
```
Facade for user group related operations in TrendMiner.
### self
```
self: User
```
Get the currently authenticated user
Returns:
| Name | Type | Description |
| ------ | ------ | -------------------------------- |
| `self` | `User` | The currently authenticated user |
### from_identifier
```
from_identifier(identifier: str) -> User
```
Get a user by their identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ---------------- | ---------- |
| `identifier` | `str` | UUID of the user | *required* |
Returns:
| Type | Description |
| ------ | --------------------------------------------- |
| `User` | User corresponding to the provided identifier |
Raises:
| Type | Description |
| ------------------ | -------------------------------------------- |
| `ResourceNotFound` | If no user with the given identifier exists. |
### from_name
```
from_name(name: str) -> User
```
Get a user by their name
Parameters:
| Name | Type | Description | Default |
| ------ | ----- | ---------------- | ---------- |
| `name` | `str` | Name of the user | *required* |
Returns:
| Type | Description |
| ------ | --------------------------------------- |
| `User` | User corresponding to the provided name |
Raises:
| Type | Description |
| ------------------- | --------------------------------------- |
| `ResourceNotFound` | If no user with the given name exists. |
| `AmbiguousResource` | If multiple users match the given name. |
### all_client_users
```
all_client_users(page=0, size=10000) -> PagedList[User]
```
Get all client users
Client users are service accounts for OAuth clients. They have a username of the form `service-account-{client id}`
Parameters:
| Name | Type | Description | Default |
| ------ | ----- | --------------------------------------------------------------------------------------------- | ------- |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `10000` |
Returns:
| Type | Description |
| ----------------- | ---------------------------------- |
| `PagedList[User]` | Paginated list of all client users |
### search
```
search(
query: str, page: int = 0, size: int = 10000
) -> PagedList[User]
```
Search users by a query string
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | --------------------------------------------------------------------------------------------------------- | ---------- |
| `query` | `str` | Query string to search for in username, first name, last name, and email. Supports wildcard character \*. | *required* |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `10000` |
Returns:
| Type | Description |
| ----------------- | ------------------------------------------ |
| `PagedList[User]` | Paginated list of users matching the query |
Notes
There is no endpoint for searching users by a specific property (e.g. username)
Client users cannot be retrieved by this method. They can be retrieved by their exact name (`service-account-{client id}`) using the `.from_name` method.
Searching for a first or last name with a string that includes spaces does not work.
# `client.work.favorites`
## trendminer_interface.\_client.work.favorites.FavoriteWorkFacade
Facade for getting items from 'favorites' directory
### search_contents
```
search_contents(
query: str | None = None,
content_type: type[SavedItem] | None = None,
my_work_only: bool = False,
page: int = 0,
size: int = 2000,
) -> PagedList[SavedItem]
```
Search items saved directly in the 'favorites' root directory.
Parameters:
| Name | Type | Description | Default |
| -------------- | --------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `query` | \`str | None\` | Search query to filter items by name or description. If None, no filtering is applied. |
| `content_type` | `type[T]` | List of types of items to get. If None, items of all types are returned. | `None` |
| `my_work_only` | `bool` | If True, only own favorites are returned. If False, also favorite shared items are returned. | `False` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `2000` |
Returns:
| Name | Type | Description |
| ------- | -------------- | ------------------------------------------------------------- |
| `items` | `PagedList[T]` | Paginated list of favorite items matching the search criteria |
### get_item
```
get_item(
name: str, content_type: type[SavedItem]
) -> SavedItem
```
Get item with the given name and type saved in the 'favorites' root directory
Parameters:
| Name | Type | Description | Default |
| -------------- | ----------------- | ------------------------ | ---------- |
| `name` | `str` | Name of the item to get | *required* |
| `content_type` | `type[SavedItem]` | Type of the item to get. | *required* |
Raises:
| Type | Description |
| ------------------- | ---------------------------------------------------------------- |
| `ResourceNotFound` | If no item with the given name and type exists in the favorites. |
| `AmbiguousResource` | If multiple items match the given name and type. |
# `client.work.folder`
## trendminer_interface.\_client.work.folder.FolderFacade
Facade for getting saved folders in the work organizer
### create
```
create(name: str, folder: Folder | None = None) -> Folder
```
Create a folder in the work organizer
Parameters:
| Name | Type | Description | Default |
| -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
| `name` | `str` | The name of the folder to create | *required* |
| `folder` | `Folder` | The parent folder in which to create the new folder. If None (default), the new folder is created in the root of the work organizer. | `None` |
Returns:
| Type | Description |
| -------- | ------------------ |
| `Folder` | The created folder |
### from_identifier
```
from_identifier(identifier: str) -> Folder
```
Get a folder by its unique identifier
Parameters:
| Name | Type | Description | Default |
| ------------ | ----- | ------------------------------------------ | ---------- |
| `identifier` | `str` | The unique identifier of the folder to get | *required* |
Returns:
| Type | Description |
| -------- | ------------------------------------ |
| `Folder` | The folder with the given identifier |
Raises:
| Type | Description |
| ------------------ | ---------------------------------------------- |
| `ResourceNotFound` | If no folder with the given identifier exists. |
### from_path
```
from_path(
names: list[str], user: User | None = None
) -> Folder
```
Get a folder by its path in the work organizer, starting from a user home folder
Parameters:
| Name | Type | Description | Default |
| ------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `names` | `List[str]` | The path of folder names to the target folder, e.g.['MyFolder', 'MySubfolder', 'MyTargetFolder'] | *required* |
| `user` | `User` | The owner of the folder to retrieve. Path browsing will start from this user's work organizer. By default, the authenticated user's work organizer is parsed. Parsing another user's work organizer requires system administrator privileges. | `None` |
Returns:
| Type | Description |
| -------- | ------------------------------ |
| `Folder` | The folder with the given path |
Raises:
| Type | Description |
| ------------------- | ------------------------------------------- |
| `ResourceNotFound` | If a folder in the path does not exist. |
| `AmbiguousResource` | If a path segment matches multiple folders. |
Examples:
```
>>> client.work.folder.from_path(["MyFolder", "MySubfolder"])
```
### from_name
```
from_name(
name: str, scope: WorkScope = "my work"
) -> Folder
```
Get a folder from its name
Parameters:
| Name | Type | Description | Default |
| ------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `name` | `str` | The name of the folder to get | *required* |
| `scope` | `WorkScope` | Searching scope for getting the folder. - 'my work': The authenticated work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
Returns:
| Type | Description |
| -------- | ------------------------------ |
| `Folder` | The folder with the given name |
Raises:
| Type | Description |
| ------------------- | ----------------------------------------------------- |
| `ResourceNotFound` | If no folder with the given name exists in the scope. |
| `AmbiguousResource` | If multiple folders match the given name. |
### search
```
search(
query: str | None = None,
scope: WorkScope = "my work",
page: int = 0,
size: int = 2000,
) -> PagedList[Folder]
```
Search folders by name or description
Parameters:
| Name | Type | Description | Default |
| ------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `query` | `str` | The search query. The '\*' can be used as a wildcard. Returns all folders if query is None (default). | `None` |
| `scope` | `WorkScope` | Searching scope. - 'my work': The authenticated work organizer (default) - 'shared': Another user's work shared to the authenticated user - 'favorites': The authenticated user's favorites, which can include items from own work and shared items. - 'system': Any user's work. Only accessible for system administrators. | `'my work'` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `2000` |
Returns:
| Name | Type | Description |
| --------- | ------------------- | --------------------------------------------------- |
| `folders` | `PagedList[Folder]` | Paginated list of folders matching the search query |
### get_user_home
```
get_user_home(user: User) -> Folder
```
System administrator method to get the home folder of a given user
Parameters:
| Name | Type | Description | Default |
| ------ | ------ | ------------------------------------------------------------------------------------------------------------------------ | ---------- |
| `user` | `User` | The user for whom to get the home folder. Accessing another user's home folder requires system administrator privileges. | *required* |
Returns:
| Type | Description |
| -------- | --------------------------------- |
| `Folder` | The home folder of the given user |
### get_users_root
```
get_users_root() -> Folder
```
System administrator method to get the `Users` root folder which contains all user home folders
Returns:
| Type | Description |
| -------- | --------------------- |
| `Folder` | The Users root folder |
# `client.work`
## trendminer_interface.\_client.work.WorkFacade
Facade for work organizer management
### folder
```
folder: FolderFacade
```
Facade for getting and creating folders in the work organizer
### my_work
```
my_work: MyWorkFacade
```
Facade for getting items saved directly in the 'my work' root directory
### shared
```
shared: SharedWorkFacade
```
Facade for getting items saved directly in the 'shared with me' root directory
### favorites
```
favorites: FavoriteWorkFacade
```
Facade for getting items saved directly in the 'favorites' root directory
### transfer
```
transfer(
items: list[SavedItem],
user: User,
folder_name: str,
retain_write_access: bool = True,
) -> None
```
Transfer items to another user
Parameters:
| Name | Type | Description | Default |
| --------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------- | ---------- |
| `items` | `list[SavedItem]` | Saved items to transfer | *required* |
| `user` | `User` | New owner of the saved items | *required* |
| `folder_name` | `str` | Name of the folder that will be created in the new user's home folder, which will contain the transferred items. | *required* |
| `retain_write_access` | `bool` | Whether the current user should retain write access to the transferred items | `True` |
# `client.work.my_work`
## trendminer_interface.\_client.work.my_work.MyWorkFacade
Facade for getting items saved directly in the 'my work' root directory
### search_contents
```
search_contents(
content_type: type[SavedItem] | None = None,
page: int = 0,
size: int = 2000,
) -> PagedList[SavedItem]
```
Search items saved directly in the 'my work' root directory.
Parameters:
| Name | Type | Description | Default |
| -------------- | --------- | --------------------------------------------------------------------------------------------- | ------- |
| `content_type` | `type[T]` | List of types of items to get. If None, items of all types are returned. | `None` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `2000` |
Returns:
| Name | Type | Description |
| ------- | -------------- | --------------------------------------------------------------------------------------- |
| `items` | `PagedList[T]` | Paginated list of items of the given type saved in the authenticated user's home folder |
### get_item
```
get_item(
name: str, content_type: type[SavedItem]
) -> SavedItem
```
Get item with the given name and type saved in the 'my work' root directory
Parameters:
| Name | Type | Description | Default |
| -------------- | ----------------- | ------------------------ | ---------- |
| `name` | `str` | Name of the item to get | *required* |
| `content_type` | `type[SavedItem]` | Type of the item to get. | *required* |
Raises:
| Type | Description |
| ------------------- | ------------------------------------------------------------ |
| `ResourceNotFound` | If no item with the given name and type exists in 'my work'. |
| `AmbiguousResource` | If multiple items match the given name and type. |
# `client.work.shared`
## trendminer_interface.\_client.work.shared.SharedWorkFacade
Facade for getting items from the top level of the 'shared with me' directory
### search_contents
```
search_contents(
query: str | None = None,
content_type: type[SavedItem] | None = None,
direct_only: bool = True,
page: int = 0,
size: int = 2000,
) -> PagedList[SavedItem]
```
Search items saved directly in the 'shared with me' root directory.
Parameters:
| Name | Type | Description | Default |
| -------------- | --------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `query` | \`str | None\` | Search query to filter items by name or description. If None, no filtering is applied. |
| `content_type` | `type[T]` | List of types of items to get. If None, items of all types are returned. | `None` |
| `direct_only` | `bool` | If True, only items directly shared with the user are returned. If False, also items in shared folders are returned. | `True` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `2000` |
Returns:
| Name | Type | Description |
| ------ | -------------- | ----------------------------------------------------------- |
| `item` | `PagedList[T]` | Paginated list of shared items matching the search criteria |
### get_item
```
get_item(
name: str, content_type: type[SavedItem]
) -> SavedItem
```
Get item with the given name and type saved in the 'shared with me' root directory
Parameters:
| Name | Type | Description | Default |
| -------------- | ----------------- | ------------------------ | ---------- |
| `name` | `str` | Name of the item to get | *required* |
| `content_type` | `type[SavedItem]` | Type of the item to get. | *required* |
Raises:
| Type | Description |
| ------------------- | ------------------------------------------------------------------ |
| `ResourceNotFound` | If no item with the given name and type exists in the shared work. |
| `AmbiguousResource` | If multiple items match the given name and type. |
# API — objects
## trendminer_interface.objects.Aggregation
Bases: `SavedItemBase`
Aggregation work organizer object
### name
```
name: str = name
```
### description
```
description: str = description
```
### folder
```
folder: Folder | None = folder
```
### identifier
```
identifier: str
```
UUID of the saved object
### created_at
```
created_at: Timestamp | None
```
Timestamp the object was created at
Can be None for items created before item creation date tracking was implemented in TrendMiner.
### last_modified
```
last_modified: Timestamp
```
Timestamp the object was last modified
### last_used
```
last_used: Timestamp
```
Timestamp the object was last used
### last_modified_by
```
last_modified_by: User
```
User that last modified the object
### owner
```
owner: User
```
User that owns the object
### shared
```
shared: bool
```
Whether the object is shared with other users
### favorite
```
favorite: bool
```
Whether the object is marked as a favorite by the owner
### version
```
version: int
```
Version number of the object, incremented on each modification
### definition
```
definition: AggregationDefinition
```
### update
```
update() -> Self
```
Update the saved item in TrendMiner to match the current instance state
### delete
```
delete() -> None
```
Permanently delete the saved item in TrendMiner
### move
```
move(folder: Folder) -> None
```
Move the item to a folder
Parameters:
| Name | Type | Description | Default |
| -------- | -------- | ------------------------------ | ---------- |
| `folder` | `Folder` | The folder to move the item to | *required* |
Notes
Moving an item to another user's folder will not transfer the ownership and may lead to unexpected behavior. Use the client.work.transfer method instead.
### get_folder_path
```
get_folder_path(include_home=False) -> list[Folder]
```
Get the location in the work organizer
Starts from, but does not include, the user's home folder. Does not include the object itself.
Parameters:
| Name | Type | Description | Default |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `include_home` | `bool` | Whether to include the user's home folder as the first element of the returned list. If False (default), the list starts from the first folder after the home folder. | `False` |
Returns:
| Type | Description |
| -------------- | --------------------------------------- |
| `list[Folder]` | List of folders leading up to this item |
### get_permissions
```
get_permissions() -> list[
tuple[User | UserGroup, WorkSharePermission]
]
```
Get the sharing settings of the object
Returns:
| Name | Type | Description |
| --------- | ------------------- | ------------------------------------ |
| `sharing` | \`list\[tuple\[User | UserGroup, WorkSharePermission\]\]\` |
### add_permission
```
add_permission(
subject: User | UserGroup,
permission: WorkSharePermission,
) -> Self
```
Share the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| ------------ | ------------------- | ----------------------------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to share the object with | *required* |
| `permission` | `str` | The permission to share with. Can be "read", "write", or "manage" | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `self` | `SavedItemBase` | The object itself, after being shared with the user or user group. Practically, only the shared property may have changed. |
### remove_permission
```
remove_permission(subject: User | UserGroup) -> Self
```
Remove sharing of the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| --------- | ------------------- | --------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to remove sharing with | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `self` | `SavedItemBase` | The object itself, after removing sharing with the user or user group. Practically, only the shared property may have changed. |
## trendminer_interface.objects.AreaSearch
Bases: `SavedItemBase`
Area search work organizer object
### name
```
name: str = name
```
### description
```
description: str = description
```
### folder
```
folder: Folder | None = folder
```
### identifier
```
identifier: str
```
UUID of the saved object
### created_at
```
created_at: Timestamp | None
```
Timestamp the object was created at
Can be None for items created before item creation date tracking was implemented in TrendMiner.
### last_modified
```
last_modified: Timestamp
```
Timestamp the object was last modified
### last_used
```
last_used: Timestamp
```
Timestamp the object was last used
### last_modified_by
```
last_modified_by: User
```
User that last modified the object
### owner
```
owner: User
```
User that owns the object
### shared
```
shared: bool
```
Whether the object is shared with other users
### favorite
```
favorite: bool
```
Whether the object is marked as a favorite by the owner
### version
```
version: int
```
Version number of the object, incremented on each modification
### definition
```
definition: AreaSearchDefinition
```
### update
```
update() -> Self
```
Update the saved item in TrendMiner to match the current instance state
### delete
```
delete() -> None
```
Permanently delete the saved item in TrendMiner
### move
```
move(folder: Folder) -> None
```
Move the item to a folder
Parameters:
| Name | Type | Description | Default |
| -------- | -------- | ------------------------------ | ---------- |
| `folder` | `Folder` | The folder to move the item to | *required* |
Notes
Moving an item to another user's folder will not transfer the ownership and may lead to unexpected behavior. Use the client.work.transfer method instead.
### get_folder_path
```
get_folder_path(include_home=False) -> list[Folder]
```
Get the location in the work organizer
Starts from, but does not include, the user's home folder. Does not include the object itself.
Parameters:
| Name | Type | Description | Default |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `include_home` | `bool` | Whether to include the user's home folder as the first element of the returned list. If False (default), the list starts from the first folder after the home folder. | `False` |
Returns:
| Type | Description |
| -------------- | --------------------------------------- |
| `list[Folder]` | List of folders leading up to this item |
### get_permissions
```
get_permissions() -> list[
tuple[User | UserGroup, WorkSharePermission]
]
```
Get the sharing settings of the object
Returns:
| Name | Type | Description |
| --------- | ------------------- | ------------------------------------ |
| `sharing` | \`list\[tuple\[User | UserGroup, WorkSharePermission\]\]\` |
### add_permission
```
add_permission(
subject: User | UserGroup,
permission: WorkSharePermission,
) -> Self
```
Share the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| ------------ | ------------------- | ----------------------------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to share the object with | *required* |
| `permission` | `str` | The permission to share with. Can be "read", "write", or "manage" | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `self` | `SavedItemBase` | The object itself, after being shared with the user or user group. Practically, only the shared property may have changed. |
### remove_permission
```
remove_permission(subject: User | UserGroup) -> Self
```
Remove sharing of the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| --------- | ------------------- | --------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to remove sharing with | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `self` | `SavedItemBase` | The object itself, after removing sharing with the user or user group. Practically, only the shared property may have changed. |
## trendminer_interface.objects.Asset
Bases: `NodeBase`
Asset node in the asset framework
Attributes:
| Name | Type | Description |
| ------------- | ------- | ------------------------ |
| `name` | `str` | Name of the asset |
| `description` | `str` | Description of the asset |
| `parent` | \`Asset | None\` |
### name
```
name: str = name
```
### description
```
description: str = description
```
### parent
```
parent: Asset | None = parent
```
### identifier
```
identifier: str
```
Unique UUID.
### source
```
source: AssetFramework
```
Source asset framework.
### template
```
template: str | None
```
Asset framework template, if any.
### hex_path
```
hex_path: str
```
Path of hexadecimal level identifiers of the node
The path contains the hexadecimal identifier of every level in the asset framework, from the root asset down to the node itself, joined by dots (e.g., "0000025e.0000025f.00000260"). The hex path of a node is therefore always prefixed by the hex path of its parent. TrendMiner references asset framework nodes by this path rather than by UUID in several parts of its API, such as access rules and node creation.
Notes
The format of the individual segments is determined by TrendMiner and should be treated as opaque. Use the hex path as a whole, or compare it to the hex path of another node in the same asset framework.
For assets and attributes referenced by a context item of which the underlying node no longer exists in the asset framework, the path is the placeholder "deleted-asset" or "deleted-attribute", consistent with the behavior of `identifier`.
Raises:
| Type | Description |
| ----------------- | --------------------------------------------------------------------------------- |
| `PermissionError` | If the user has no permission for the node, and can therefore not access its path |
| `ValueError` | If the node is an attribute of which the parent asset no longer exists |
### get_access_rules
```
get_access_rules() -> list[AssetAccessRule]
```
Get access rules for the node
Returns:
| Type | Description |
| ------------------------- | ------------------------------------------------- |
| `list of AssetAccessRule` | List of all access rules set directly on the node |
### get_inherited_access_rules
```
get_inherited_access_rules() -> list[AssetAccessRule]
```
Get inherited access rules for the node
Returns:
| Type | Description |
| ------------------------- | --------------------------------------------------------------------------- |
| `list of AssetAccessRule` | List of all access rules inherited from parent nodes in the asset framework |
### add_access_rule
```
add_access_rule(
subject: User | UserGroup,
permission: AssetAccessPermission,
) -> AssetAccessRule
```
Add an access rule to the node
Parameters:
| Name | Type | Description | Default |
| ------------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group who is granted the permissions | *required* |
| `permission` | `('read', 'browse', 'none')` | Access permission to be added for the subject. - "read": allows reading context items of the asset/attribute, and thus also browsing. - "browse": allows browsing the asset/attribute, but not reading context items. - "none": explicit denial of permissions for the asset/attribute. | `"read"` |
Returns:
| Type | Description |
| ----------------- | ----------------------- |
| `AssetAccessRule` | The created access rule |
### search_children
```
search_children(
name: str | None = None,
description: str | None = None,
template: str | None = None,
child_type: None = None,
page: int = 0,
size: int = 1000,
) -> PagedList[Asset | Attribute]
```
```
search_children(
name: str | None = None,
description: str | None = None,
template: str | None = None,
child_type: type[Attribute] = ...,
page: int = 0,
size: int = 1000,
) -> PagedList[Attribute]
```
```
search_children(
name: str | None = None,
description: str | None = None,
template: str | None = None,
child_type: type[Asset] = ...,
page: int = 0,
size: int = 1000,
) -> PagedList[Asset]
```
```
search_children(
name: str | None = None,
description: str | None = None,
template: str | None = None,
child_type: type[Asset] | type[Attribute] | None = None,
page: int = 0,
size: int = 1000,
) -> (
PagedList[Asset]
| PagedList[Attribute]
| PagedList[Asset | Attribute]
)
```
Get direct children of the asset in the asset framework
Parameters:
| Name | Type | Description | Default |
| ------------- | ------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `name` | \`str | None\` | Name of the child asset or attribute to filter for. |
| `description` | \`str | None\` | Description of the child asset or attribute to filter for. |
| `template` | \`str | None\` | Template name to filter for. Only children based on the given template will be returned. |
| `child_type` | \`type[Asset] | type[Attribute] | None\` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `1000` |
Returns:
| Type | Description |
| ------------------ | ------------- |
| \`PagedList\[Asset | Attribute\]\` |
Notes
Calling this method without any parameters will return all direct children of the asset.
### get_child_attribute
```
get_child_attribute(
name: str | None = None, template: str | None = None
) -> Attribute
```
Get a child attribute of the asset by name
At least one of name or template must be provided to identify the attribute.
Parameters:
| Name | Type | Description | Default |
| ---------- | ----- | -------------------------------------- | ------- |
| `name` | `str` | Name of the child attribute to get | `None` |
| `template` | `str` | Template of the child attribute to get | `None` |
Returns:
| Type | Description |
| ----------- | --------------------------------------------------- |
| `Attribute` | Child attribute with the given name and/or template |
Raises:
| Type | Description |
| ------------------- | ------------------------------------------------------------------ |
| `ResourceNotFound` | If no child attribute matches the given name and/or template. |
| `AmbiguousResource` | If multiple child attributes match the given name and/or template. |
### get_child_asset
```
get_child_asset(
name: str | None = None, template: str | None = None
) -> Asset
```
Get a child asset of the asset by name
At least one of name or template must be provided to identify the asset.
Parameters:
| Name | Type | Description | Default |
| ---------- | ----- | ---------------------------------- | ------- |
| `name` | `str` | Name of the child asset to get | `None` |
| `template` | `str` | Template of the child asset to get | `None` |
Returns:
| Type | Description |
| ------- | ----------------------------------------------- |
| `Asset` | Child asset with the given name and/or template |
Raises:
| Type | Description |
| ------------------- | -------------------------------------------------------------- |
| `ResourceNotFound` | If no child asset matches the given name and/or template. |
| `AmbiguousResource` | If multiple child assets match the given name and/or template. |
### update
```
update() -> Asset
```
Update the asset in TrendMiner to the instance state.
Returns:
| Type | Description |
| ------- | ------------------------------------------------------------------------ |
| `Asset` | Updated asset instance reflecting the state in TrendMiner after updating |
### delete
```
delete() -> None
```
Delete the current asset from the asset framework
Notes
Child assets and attributes will not be deleted, but moved up one level in the asset tree.
### get_hierarchy
```
get_hierarchy() -> list[Asset]
```
Get hierarchy from the root asset down to the current asset
Returns:
| Type | Description |
| ------------- | --------------- |
| `list[Asset]` | Asset hierarchy |
## trendminer_interface.objects.AssetAccessRule
Access rule giving a user certain permissions to a certain Asset or Attribute
Attributes:
| Name | Type | Description |
| ------------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subject` | `User or UserGroup` | The subject to which the access rule relates |
| `permission` | `str` | The permission granted to the user - "read": allows reading context items of the asset/attribute, and thus also browsing. - "browse": allows browsing the asset/attribute, but not reading context items. - "none": explicit denial of permissions for the asset/attribute. |
### subject
```
subject: User | UserGroup = subject
```
### permission
```
permission: AssetAccessPermission = permission
```
### identifier
```
identifier: str
```
Unique UUID of the access rule
### node
```
node: Asset | Attribute
```
The asset framework node to which the access rule relates
### delete
```
delete() -> None
```
Delete the access rule
Notes
When a rule is retrieved as an inherited access rule, it will be removed from the asset on which it is defined.
## trendminer_interface.objects.AssetFramework
Asset framework definition
Attributes:
| Name | Type | Description |
| ----------- | ------ | --------------------------------------------------------------------------------------------------------- |
| `name` | `str` | Name of the asset framework |
| `published` | `bool` | Whether the asset framework is published or not. Unpublished asset frameworks are only visible to admins. |
### name
```
name: str = name
```
### published
```
published: bool = published
```
### identifier
```
identifier: str
```
UUID of the asset framework
### framework_type
```
framework_type: AssetFrameworkType
```
Type of the asset framework: "csv" or "datasource".
### synced_at
```
synced_at: Timestamp | None
```
Timestamp of the last synchronization of the asset framework
### get_root_asset
```
get_root_asset() -> Asset
```
Get the root asset of the asset framework
Returns:
| Name | Type | Description |
| ------------ | ------- | --------------------------------- |
| `root_asset` | `Asset` | Root asset of the asset framework |
### delete
```
delete() -> None
```
Delete the asset framework
## trendminer_interface.objects.Attribute
Bases: `NodeBase`
Attribute node in the asset framework
Attributes:
| Name | Type | Description |
| ------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | `str` | Name of the attribute |
| `tag` | \`Tag | None\` |
| `description` | `str` | Description of the attribute |
| `parent` | `Asset` | Parent asset of the attribute. |
| `shift` | `Timedelta` | Time shift of the attribute. Only relevant for visualization in TrendHub views. By default, attributes will have a shift of 0. |
| `visible` | `bool` | Whether the tag is visible in TrendHub. This is used for visualization purposes in TrendHub, and has an impact on fingerprints. Attributes retrieved from anywhere but a TrendHub view or Fingerprint will be visible by default. |
| `color` | `str` | The color of the attribute, as a hex color code (e.g., "#FF0000" for red). This is used for visualization purposes in TrendHub. |
| `scale` | `tuple[float, float] or None` | The manually set scale of the attribute, as a tuple of (min, max) values, as used in TrendHub visualization. If no manual scale is set (None), the attribute will be autoscaled. |
| `alias` | `str or None` | The alias of the attribute, as set in TrendHub. |
| `accuracy` | \`float | None\` |
### name
```
name: str = name
```
### description
```
description: str = description
```
### parent
```
parent: Asset | None = parent
```
### identifier
```
identifier: str
```
Unique UUID.
### source
```
source: AssetFramework
```
Source asset framework.
### template
```
template: str | None
```
Asset framework template, if any.
### hex_path
```
hex_path: str
```
Path of hexadecimal level identifiers of the node
The path contains the hexadecimal identifier of every level in the asset framework, from the root asset down to the node itself, joined by dots (e.g., "0000025e.0000025f.00000260"). The hex path of a node is therefore always prefixed by the hex path of its parent. TrendMiner references asset framework nodes by this path rather than by UUID in several parts of its API, such as access rules and node creation.
Notes
The format of the individual segments is determined by TrendMiner and should be treated as opaque. Use the hex path as a whole, or compare it to the hex path of another node in the same asset framework.
For assets and attributes referenced by a context item of which the underlying node no longer exists in the asset framework, the path is the placeholder "deleted-asset" or "deleted-attribute", consistent with the behavior of `identifier`.
Raises:
| Type | Description |
| ----------------- | --------------------------------------------------------------------------------- |
| `PermissionError` | If the user has no permission for the node, and can therefore not access its path |
| `ValueError` | If the node is an attribute of which the parent asset no longer exists |
### tag
```
tag: Tag | None = tag
```
### shift
```
shift: Timedelta = shift
```
### visible
```
visible: bool = visible
```
### color
```
color: str = color
```
### scale
```
scale: tuple[float, float] | None = scale
```
### alias
```
alias: str | None = alias
```
### accuracy
```
accuracy: float | None = accuracy
```
### get_access_rules
```
get_access_rules() -> list[AssetAccessRule]
```
Get access rules for the node
Returns:
| Type | Description |
| ------------------------- | ------------------------------------------------- |
| `list of AssetAccessRule` | List of all access rules set directly on the node |
### get_inherited_access_rules
```
get_inherited_access_rules() -> list[AssetAccessRule]
```
Get inherited access rules for the node
Returns:
| Type | Description |
| ------------------------- | --------------------------------------------------------------------------- |
| `list of AssetAccessRule` | List of all access rules inherited from parent nodes in the asset framework |
### add_access_rule
```
add_access_rule(
subject: User | UserGroup,
permission: AssetAccessPermission,
) -> AssetAccessRule
```
Add an access rule to the node
Parameters:
| Name | Type | Description | Default |
| ------------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group who is granted the permissions | *required* |
| `permission` | `('read', 'browse', 'none')` | Access permission to be added for the subject. - "read": allows reading context items of the asset/attribute, and thus also browsing. - "browse": allows browsing the asset/attribute, but not reading context items. - "none": explicit denial of permissions for the asset/attribute. | `"read"` |
Returns:
| Type | Description |
| ----------------- | ----------------------- |
| `AssetAccessRule` | The created access rule |
### update
```
update() -> Attribute
```
Update the attribute in TrendMiner to the instance state.
Returns:
| Type | Description |
| ----------- | -------------------------------------------------------------------------- |
| `Attribute` | Updated attribute instance reflecting the state in TrendMiner after saving |
### delete
```
delete() -> None
```
Delete the current attribute from the asset framework
## trendminer_interface.objects.ContextApprovalFilter
Context filter on item approval
Attributes:
| Name | Type | Description |
| ---------- | ------ | --------------------------------- |
| `approved` | `bool` | Item approval status to filter on |
### approved
```
approved: bool
```
## trendminer_interface.objects.ContextComponentFilter
Filter on components the context items are attached to
Attributes:
| Name | Type | Description |
| --------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `queries` | `list of tuple[Tag or Asset or Attribute, {"self", "ancestors", "descendants"}]` | List of components on which to filter, and whether to include ancestors or descendants. For tags, only self is possible. For attributes, only self and ancestors are possible. For assets, all options are possible. |
| `mode` | \`{'empty', 'not empty'} | None\` |
### queries
```
queries: (
list[tuple[Tag | Asset | Attribute, ComponentInclusion]]
| None
)
```
### mode
```
mode: EmptyMode | None
```
## trendminer_interface.objects.ContextCreatedByFilter
Filter on context item creator
Attributes:
| Name | Type | Description |
| ------- | -------------- | ------------------------ |
| `users` | `list of User` | Users on which to filter |
### users
```
users: list[User]
```
## trendminer_interface.objects.ContextCreationDateFilter
Conditional filter on context item creation date
Attributes:
| Name | Type | Description |
| ----------- | ------------------------ | ------------------------------------------------------------------ |
| `operator` | `{'>', '>=', '<', '<='}` | The operator to apply to the timestamp criterion |
| `timestamp` | `Timestamp` | The timestamp criterion to apply to the context item creation date |
### operator
```
operator: CreatedDateOperator
```
### timestamp
```
timestamp: Timestamp
```
## trendminer_interface.objects.ContextDescriptionFilter
Context filter on item description
Attributes:
| Name | Type | Description |
| -------- | ------------------------ | ----------- |
| `values` | \`list of str | None\` |
| `mode` | \`{'empty', 'not empty'} | None\` |
### values
```
values: list[str] | None
```
### mode
```
mode: EmptyMode | None
```
## trendminer_interface.objects.ContextDurationFilter
Filter on context item duration
Attributes:
| Name | Type | Description |
| --------- | -------------------------------------------------------------------- | ----------------------------- |
| `queries` | `list of tuple[{"<", ">", "<=", ">=", "=", "!="}, pandas.Timedelta]` | Duration queries to filter on |
### queries
```
queries: list[tuple[DurationOperator, Timedelta]]
```
## trendminer_interface.objects.ContextEnumerationFieldFilter
Filter on context enumeration field values
Attributes:
| Name | Type | Description |
| -------- | ------------------------ | -------------------------------------------------------------------- |
| `field` | `ContextField` | The context field on which to filter. Must be of 'enumeration' type. |
| `values` | \`list[str] | None\` |
| `mode` | \`{'empty', 'not empty'} | None\` |
### field
```
field: ContextField
```
### values
```
values: list[str] | None
```
### mode
```
mode: EmptyMode | None
```
## trendminer_interface.objects.ContextField
Configuration of a context field
Attributes:
| Name | Type | Description |
| ------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | `str` | Name that is visible to the users in the appliance |
| `placeholder` | `str` | Field placeholder that is displayed to the user if the field is blank. This is NOT a default value, it is a visual aid to the user; "" if not set. |
| `options` | `list of str` | Options for enumeration fields; [] for non-enumeration fields. |
### name
```
name: str = name
```
### placeholder
```
placeholder: str = placeholder
```
### options
```
options: list[str] = options
```
### identifier
```
identifier: str
```
UUID of the context field
### key
```
key: str
```
Unique key that is used as the main identifier of the field
### field_type
```
field_type: ContextFieldType
```
Context field type. Determines what type of values the field can take.
### update
```
update() -> ContextField
```
Update the appliance context field to the current instance configuration
Returns:
| Type | Description |
| -------------- | --------------------- |
| `ContextField` | Updated context field |
### delete
```
delete() -> None
```
Permanently delete the context field
## trendminer_interface.objects.ContextHubView
Bases: `SavedItemBase`
ContextHub view work organizer object
### name
```
name: str = name
```
### description
```
description: str = description
```
### folder
```
folder: Folder | None = folder
```
### identifier
```
identifier: str
```
UUID of the saved object
### created_at
```
created_at: Timestamp | None
```
Timestamp the object was created at
Can be None for items created before item creation date tracking was implemented in TrendMiner.
### last_modified
```
last_modified: Timestamp
```
Timestamp the object was last modified
### last_used
```
last_used: Timestamp
```
Timestamp the object was last used
### last_modified_by
```
last_modified_by: User
```
User that last modified the object
### owner
```
owner: User
```
User that owns the object
### shared
```
shared: bool
```
Whether the object is shared with other users
### favorite
```
favorite: bool
```
Whether the object is marked as a favorite by the owner
### version
```
version: int
```
Version number of the object, incremented on each modification
### definition
```
definition: ContextHubViewDefinition
```
### url
```
url: str
```
Direct link to the saved view
### update
```
update() -> Self
```
Update the saved item in TrendMiner to match the current instance state
### delete
```
delete() -> None
```
Permanently delete the saved item in TrendMiner
### move
```
move(folder: Folder) -> None
```
Move the item to a folder
Parameters:
| Name | Type | Description | Default |
| -------- | -------- | ------------------------------ | ---------- |
| `folder` | `Folder` | The folder to move the item to | *required* |
Notes
Moving an item to another user's folder will not transfer the ownership and may lead to unexpected behavior. Use the client.work.transfer method instead.
### get_folder_path
```
get_folder_path(include_home=False) -> list[Folder]
```
Get the location in the work organizer
Starts from, but does not include, the user's home folder. Does not include the object itself.
Parameters:
| Name | Type | Description | Default |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `include_home` | `bool` | Whether to include the user's home folder as the first element of the returned list. If False (default), the list starts from the first folder after the home folder. | `False` |
Returns:
| Type | Description |
| -------------- | --------------------------------------- |
| `list[Folder]` | List of folders leading up to this item |
### get_permissions
```
get_permissions() -> list[
tuple[User | UserGroup, WorkSharePermission]
]
```
Get the sharing settings of the object
Returns:
| Name | Type | Description |
| --------- | ------------------- | ------------------------------------ |
| `sharing` | \`list\[tuple\[User | UserGroup, WorkSharePermission\]\]\` |
### add_permission
```
add_permission(
subject: User | UserGroup,
permission: WorkSharePermission,
) -> Self
```
Share the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| ------------ | ------------------- | ----------------------------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to share the object with | *required* |
| `permission` | `str` | The permission to share with. Can be "read", "write", or "manage" | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `self` | `SavedItemBase` | The object itself, after being shared with the user or user group. Practically, only the shared property may have changed. |
### remove_permission
```
remove_permission(subject: User | UserGroup) -> Self
```
Remove sharing of the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| --------- | ------------------- | --------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to remove sharing with | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `self` | `SavedItemBase` | The object itself, after removing sharing with the user or user group. Practically, only the shared property may have changed. |
### get_results
```
get_results(
target: Interval[Timestamp] | DataFrame,
drop: bool = True,
page: int = 0,
size: int = 10000,
) -> PagedDataFrame
```
Perform a search based on the definition
Parameters:
| Name | Type | Description | Default |
| -------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `target` | \`Interval[Timestamp] | DataFrame\` | The input intervals to search for. Can be either a single pandas Interval or a DataFrame with IntervalIndex containing non-overlapping intervals. The closed property of the target will be retained in the search results. |
| `drop` | `bool` | Whether to drop the original interval columns from the resulting DataFrame, by default True. If False, the original interval in which each search result was found will be kept as a column in the resulting DataFrame. For a pd.Interval input, the name of this column will be search_interval. For a DataFrame input, the name of the original IntervalIndex will be kept. | `True` |
| `page` | `int` | The page number of results to retrieve. Default is 0 (the first page). | `0` |
| `size` | `int` | The number of results to include in each page. Default is 10000. | `10000` |
Returns:
| Type | Description |
| ---------------- | ----------------------------------------------------------------------------------------------------- |
| `PagedDataFrame` | Page containing DataFrame with IntervalIndex and columns corresponding to the calculations specified. |
Notes
Any columns already present in an input DataFrame will be kept. Their values will be mapped to the search results based on the intervals in which the search results were found.
### get_items
```
get_items(size: int = 10000) -> PagedDataFrame
```
Retrieve all context items matching the ContextHub view definition filters
Parameters:
| Name | Type | Description | Default |
| ------ | ----- | -------------------------------------------------------- | ------- |
| `size` | `int` | The number of items to return per page, by default 10000 | `10000` |
Returns:
| Type | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PagedDataFrame` | PageDataFrame with a DataFrame data attribute with the following structure: Index: The index will be pandas.IntervalIndex, with index.left and index.right timestamps of the context item start and end events, respectively. If a context item only has a single timestamp (i.e., when its type does not have an associated context workflow), index.left and index.right will be identical. For open context item, index.right will be the current time. Metadata columns: - open (bool): whether the context item is still open (i.e., has no end event yet) - key (str): short key - identifier (str): uuid - identifier_external (str): optional identifier by which the item is linked to an external system - description (str): optional description - type (object, ContextType): context item type - component (object, Tag or Asset or Attribute): component the item is linked to - keywords (list[str]): list of keywords linked to the item - created_by (object, User): user that created the item - created_at (datetime64[us, client timezone]): creation date - last_modified: (datetime64[us, client timezone]): last modified date Field columns: There will be a column for every unique field. Values will be float or str. The column name will be the unique field key (not the field name!) If the field is not present on some of the items, the corresponding values will be nan. Note that for context items that were created by monitors, the following metadata fields will be present (but hidden in the TrendMiner UI): - tm_monitor_id (str): Monitor.identifier short ID - tm_search_id (str): SearchBase.identifier UUID - tm_search_type (str): 'valuebased', 'similarity', ... Event columns: All context item events besides of the start and end events will be added as datetime64[ns, client timezone] columns, with the event name as the column name. |
Notes
Context items linked to multiple components are not supported. Only the first component will be returned.
Duplicate column names can occur when a certain event state occurs more than once, or when there is an overlap between field keys, state names and/or metadata column names. It is advised to avoid this situation as this will complicate processing of the resulting DataFrame.
### delete_items
```
delete_items() -> None
```
Delete context items based on the view definition filters
## trendminer_interface.objects.ContextHubViewTile
Bases: `TileBase[ContextHubViewTileConfiguration]`
ContextHub view tile
Tile content is a ContextHub view
Attributes:
| Name | Type | Description |
| -------------- | ------------------------ | --------------------------------------------------------- |
| `view` | `ContextHubView` | The ContextHub view displayed in the tile |
| `mode` | `ContextHubViewTileMode` | The display mode of the tile |
| `refresh_rate` | `Timedelta` | How often the tile is refreshed if the dashboard is live. |
### position
```
position: tuple[int, int, int, int]
```
### title
```
title: str
```
### config
```
config: TConfig
```
### view
```
view: ContextHubView
```
### mode
```
mode: ContextHubViewTileMode
```
### refresh_rate
```
refresh_rate: Timedelta
```
## trendminer_interface.objects.ContextHubViewTileConfiguration
Configuration for ContextHub view tile
Attributes:
| Name | Type | Description |
| ---------------- | ------ | ----------------------------------------- |
| `show_title` | `bool` | Whether to show the tile title |
| `show_legend` | `bool` | Whether to show the colored points legend |
| `show_timeframe` | `bool` | Whether to show the timeframe |
### show_title
```
show_title: bool
```
### show_legend
```
show_legend: bool
```
### show_timeframe
```
show_timeframe: bool
```
## trendminer_interface.objects.ContextIntervalFilter
Filter on context item event or creation time through fixed interval
Attributes:
| Name | Type | Description |
| ---------- | ---------------------------- | ----------------------------------------------------------------------------------- |
| `interval` | `Interval` | The time interval on which to filter |
| `scope` | `{'event', 'creation date'}` | Whether to filter on the context item timestamps or the context item creation date. |
Notes
For a conditional filter on creation date, use ContextCreationDateFilter instead.
### interval
```
interval: Interval
```
### scope
```
scope: ContextIntervalScope
```
## trendminer_interface.objects.ContextItemMonitorNotification
Context item monitor notification
Attributes:
| Name | Type | Description |
| -------------- | --------------------------------------- | ------------------------------------------ |
| `enabled` | `bool` | Whether the notification is enabled |
| `context_type` | `(ContextType, optional)` | The context item type |
| `component` | `(Tag or Attribute or Asset, optional)` | The component the item will be attached to |
| `description` | `str` | The context item description |
| `fields` | `dict` | The context item fields |
| `keywords` | `list of str` | The keywords attached to the context item |
### enabled
```
enabled: bool = enabled
```
### context_type
```
context_type: object | None = context_type
```
### component
```
component: Tag | Asset | Attribute | None = component
```
### description
```
description: str = description
```
### fields
```
fields: dict[str, str | float] = fields
```
### keywords
```
keywords: list[str] = keywords
```
### enabled_at
```
enabled_at: Timestamp | None
```
The timestamp the notification was enabled
## trendminer_interface.objects.ContextKeywordFilter
Filter on context item keywords
Attributes:
| Name | Type | Description |
| ---------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `keywords` | `list of str, optional` | Keywords which must be present on the context items. Ignored when using mode. |
| `mode` | `({'empty', 'not empty'}, optional)` | When not None, filter for context items without or with keywords. Ignores the keywords attribute when used. |
### keywords
```
keywords: list[str] | None
```
### mode
```
mode: EmptyMode | None
```
## trendminer_interface.objects.ContextNumericFieldFilter
Filter on context numeric field values
Attributes:
| Name | Type | Description |
| --------- | --------------------------------------------------------- | ---------------------------------------------------------------- |
| `field` | `ContextField` | The context field on which to filter. Must be of 'numeric' type. |
| `queries` | `list of tuple[{"=", "!=", ">", "<", ">=", "<="}, float]` | List of operator-value tuples to filter on. |
| `mode` | \`{'empty', 'not empty'} | None\` |
### field
```
field: ContextField
```
### queries
```
queries: list[tuple[NumericFieldOperator, float]] | None
```
### mode
```
mode: EmptyMode | None
```
## trendminer_interface.objects.ContextPeriodFilter
Filter on context item event time with dynamic period
Attributes:
| Name | Type | Description |
| -------- | ----------- | ----------------------------------------------------------------------------------------------------------------- |
| `period` | `Timedelta` | Duration marking a time interval running up to the current time, on which to filter the context items. |
| `live` | `bool` | Whether a ContextHubView having this filter needs to update live. Does not impact the retrieval of context items. |
### period
```
period: Timedelta
```
### live
```
live: bool
```
## trendminer_interface.objects.ContextPropertyFilter
Filter on other properties of context items
The values assigned context items for which the key does not match that of a context field defined on the context type are considered 'other properties'. Only string-based searches are possible for other properties.
Attributes:
| Name | Type | Description |
| -------- | ------------- | --------------------------------- |
| `key` | `str` | Other property key to filter on |
| `values` | `list of str` | List of values on which to filter |
### key
```
key: str
```
### values
```
values: list[str]
```
## trendminer_interface.objects.ContextStateFilter
Filter on context item current state
Attributes:
| Name | Type | Description |
| -------- | ---------------------------- | ------------------------------------------------------------------------------------------------- |
| `states` | `list of str` | Allowed context item states. Ignored when using mode. |
| `mode` | `{'open', 'closed'} or None` | When not None, filter for only open (ongoing) or closed context items, ignoring any given states. |
### states
```
states: list[str]
```
### mode
```
mode: ClosedMode | None
```
## trendminer_interface.objects.ContextStringFieldFilter
Filter on context string field values
Attributes:
| Name | Type | Description |
| -------- | ------------------------ | --------------------------------------------------------------- |
| `field` | `ContextField` | The context field on which to filter. Must be of 'string' type. |
| `values` | \`list[str] | None\` |
| `mode` | \`{'empty', 'not empty'} | None\` |
### field
```
field: ContextField
```
### values
```
values: list[str] | None
```
### mode
```
mode: EmptyMode | None
```
## trendminer_interface.objects.ContextType
Configuration of a context type
Attributes:
| Name | Type | Description |
| --------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `name` | `str` | Name that is visible to the users in the appliance |
| `description` | `(str, optional)` | Description of the context type |
| `workflow` | `(ContextWorkflow, optional)` | Workflow associated with the context type. When None, the context type can only have a single associated timestamp. |
| `fields` | `list of ContextField` | List of fields that are associated with the context type. |
| `color` | `str` | Color of the context type in hex format (e.g. "#FF0000") |
| `icon` | `ContextTypeIcon` | Icon of the context type. See ContextTypeIcon for the allowed values. |
| `approvals_enabled` | `bool` | Whether context items of this type can be approved. |
| `audit_trail_enabled` | `bool` | Whether context item edit history will be saved as metadata to the item. |
### name
```
name: str = name
```
### workflow
```
workflow: ContextWorkflow | None = workflow
```
### fields
```
fields: list[ContextField] = fields
```
### color
```
color: str = color
```
### icon
```
icon: ContextTypeIcon = icon
```
### description
```
description: str | None = description
```
### approvals_enabled
```
approvals_enabled: bool = approvals_enabled
```
### audit_trail_enabled
```
audit_trail_enabled: bool = audit_trail_enabled
```
### key
```
key: str
```
Unique key that is used as the identifier of the context type
### update
```
update() -> ContextType
```
Update the appliance context type to the current instance configuration
Returns:
| Type | Description |
| ------------- | -------------------- |
| `ContextType` | Updated context type |
### delete
```
delete() -> None
```
Permanently delete the context type
## trendminer_interface.objects.ContextTypeFilter
Context filter on item type
Attributes:
| Name | Type | Description |
| ------- | ------------------- | ---------------------------------------- |
| `types` | `list[ContextType]` | List of context types on which to filter |
### types
```
types: list[ContextType]
```
## trendminer_interface.objects.ContextWorkflow
Configuration of a context workflow
Attributes:
| Name | Type | Description |
| -------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | `str` | Name that is visible to the users in the appliance |
| `states` | `list of str` | Possible states of the workflow; the first and last items are considered the start and end states, respectively, and can occur only once in a context item. |
### name
```
name: str = name
```
### states
```
states: list[str] = states
```
### identifier
```
identifier: str
```
UUID of the context workflow
### update
```
update() -> ContextWorkflow
```
Update the appliance context workflow to the current instance configuration
Returns:
| Type | Description |
| ----------------- | ------------------------ |
| `ContextWorkflow` | Updated context workflow |
### delete
```
delete() -> None
```
Permanently delete the context workflow
## trendminer_interface.objects.CurrentValueTile
Bases: `TileBase[CurrentValueTileConfiguration]`
Dashboard current value tile
Attributes:
| Name | Type | Description |
| -------------- | ------------------------------ | --------------------------------------------------------- |
| `entries` | `list[CurrentValueTileEntry]` | List of current value entries to display in the tile |
| `refresh_rate` | `pandas.Timedelta, default 1m` | How often the tile is refreshed if the dashboard is live. |
### position
```
position: tuple[int, int, int, int]
```
### title
```
title: str
```
### config
```
config: TConfig
```
### entries
```
entries: list[CurrentValueTileEntry]
```
### refresh_rate
```
refresh_rate: Timedelta
```
## trendminer_interface.objects.CurrentValueTileConfiguration
Configuration for current value tile
Attributes:
| Name | Type | Description |
| ---------------------- | --------------- | ------------------------------------------------------------------- |
| `show_title` | `bool` | Whether to show the tile title |
| `accuracy` | `float or None` | Accuracy to which values are displayed (..., 10, 1, 0.1, 0.01, ...) |
| `show_graph` | `bool` | Whether to show the trend graph |
| `graph_duration` | `Timedelta` | Duration of the trend graph |
| `fill_background` | `bool` | Whether to fill the background |
| `show_component_names` | `bool` | Whether to show component names |
| `show_timestamp` | `bool` | Whether to show timestamp of latest datapoint |
| `use_chart_alias` | `bool` | Whether to use chart alias |
### show_title
```
show_title: bool
```
### accuracy
```
accuracy: float | None
```
### show_graph
```
show_graph: bool
```
### graph_duration
```
graph_duration: Timedelta
```
### fill_background
```
fill_background: bool
```
### show_component_names
```
show_component_names: bool
```
### show_timestamp
```
show_timestamp: bool
```
### use_chart_alias
```
use_chart_alias: bool
```
## trendminer_interface.objects.CustomCalculation
Bases: `SavedItemBase`
Custom calculation work organizer object
### name
```
name: str = name
```
### description
```
description: str = description
```
### folder
```
folder: Folder | None = folder
```
### identifier
```
identifier: str
```
UUID of the saved object
### created_at
```
created_at: Timestamp | None
```
Timestamp the object was created at
Can be None for items created before item creation date tracking was implemented in TrendMiner.
### last_modified
```
last_modified: Timestamp
```
Timestamp the object was last modified
### last_used
```
last_used: Timestamp
```
Timestamp the object was last used
### last_modified_by
```
last_modified_by: User
```
User that last modified the object
### owner
```
owner: User
```
User that owns the object
### shared
```
shared: bool
```
Whether the object is shared with other users
### favorite
```
favorite: bool
```
Whether the object is marked as a favorite by the owner
### version
```
version: int
```
Version number of the object, incremented on each modification
### definition
```
definition: CustomCalculationDefinition
```
### update
```
update() -> Self
```
Update the saved item in TrendMiner to match the current instance state
### delete
```
delete() -> None
```
Permanently delete the saved item in TrendMiner
### move
```
move(folder: Folder) -> None
```
Move the item to a folder
Parameters:
| Name | Type | Description | Default |
| -------- | -------- | ------------------------------ | ---------- |
| `folder` | `Folder` | The folder to move the item to | *required* |
Notes
Moving an item to another user's folder will not transfer the ownership and may lead to unexpected behavior. Use the client.work.transfer method instead.
### get_folder_path
```
get_folder_path(include_home=False) -> list[Folder]
```
Get the location in the work organizer
Starts from, but does not include, the user's home folder. Does not include the object itself.
Parameters:
| Name | Type | Description | Default |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `include_home` | `bool` | Whether to include the user's home folder as the first element of the returned list. If False (default), the list starts from the first folder after the home folder. | `False` |
Returns:
| Type | Description |
| -------------- | --------------------------------------- |
| `list[Folder]` | List of folders leading up to this item |
### get_permissions
```
get_permissions() -> list[
tuple[User | UserGroup, WorkSharePermission]
]
```
Get the sharing settings of the object
Returns:
| Name | Type | Description |
| --------- | ------------------- | ------------------------------------ |
| `sharing` | \`list\[tuple\[User | UserGroup, WorkSharePermission\]\]\` |
### add_permission
```
add_permission(
subject: User | UserGroup,
permission: WorkSharePermission,
) -> Self
```
Share the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| ------------ | ------------------- | ----------------------------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to share the object with | *required* |
| `permission` | `str` | The permission to share with. Can be "read", "write", or "manage" | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `self` | `SavedItemBase` | The object itself, after being shared with the user or user group. Practically, only the shared property may have changed. |
### remove_permission
```
remove_permission(subject: User | UserGroup) -> Self
```
Remove sharing of the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| --------- | ------------------- | --------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to remove sharing with | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `self` | `SavedItemBase` | The object itself, after removing sharing with the user or user group. Practically, only the shared property may have changed. |
## trendminer_interface.objects.Dashboard
Bases: `SavedItemBase`
Dashboard work organizer object
### name
```
name: str = name
```
### description
```
description: str = description
```
### folder
```
folder: Folder | None = folder
```
### identifier
```
identifier: str
```
UUID of the saved object
### created_at
```
created_at: Timestamp | None
```
Timestamp the object was created at
Can be None for items created before item creation date tracking was implemented in TrendMiner.
### last_modified
```
last_modified: Timestamp
```
Timestamp the object was last modified
### last_used
```
last_used: Timestamp
```
Timestamp the object was last used
### last_modified_by
```
last_modified_by: User
```
User that last modified the object
### owner
```
owner: User
```
User that owns the object
### shared
```
shared: bool
```
Whether the object is shared with other users
### favorite
```
favorite: bool
```
Whether the object is marked as a favorite by the owner
### version
```
version: int
```
Version number of the object, incremented on each modification
### definition
```
definition: DashboardDefinition
```
### url
```
url: str
```
Direct link to the saved dashboard
### update
```
update() -> Self
```
Update the saved item in TrendMiner to match the current instance state
### delete
```
delete() -> None
```
Permanently delete the saved item in TrendMiner
### move
```
move(folder: Folder) -> None
```
Move the item to a folder
Parameters:
| Name | Type | Description | Default |
| -------- | -------- | ------------------------------ | ---------- |
| `folder` | `Folder` | The folder to move the item to | *required* |
Notes
Moving an item to another user's folder will not transfer the ownership and may lead to unexpected behavior. Use the client.work.transfer method instead.
### get_folder_path
```
get_folder_path(include_home=False) -> list[Folder]
```
Get the location in the work organizer
Starts from, but does not include, the user's home folder. Does not include the object itself.
Parameters:
| Name | Type | Description | Default |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `include_home` | `bool` | Whether to include the user's home folder as the first element of the returned list. If False (default), the list starts from the first folder after the home folder. | `False` |
Returns:
| Type | Description |
| -------------- | --------------------------------------- |
| `list[Folder]` | List of folders leading up to this item |
### get_permissions
```
get_permissions() -> list[
tuple[User | UserGroup, WorkSharePermission]
]
```
Get the sharing settings of the object
Returns:
| Name | Type | Description |
| --------- | ------------------- | ------------------------------------ |
| `sharing` | \`list\[tuple\[User | UserGroup, WorkSharePermission\]\]\` |
### add_permission
```
add_permission(
subject: User | UserGroup,
permission: WorkSharePermission,
) -> Self
```
Share the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| ------------ | ------------------- | ----------------------------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to share the object with | *required* |
| `permission` | `str` | The permission to share with. Can be "read", "write", or "manage" | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `self` | `SavedItemBase` | The object itself, after being shared with the user or user group. Practically, only the shared property may have changed. |
### remove_permission
```
remove_permission(subject: User | UserGroup) -> Self
```
Remove sharing of the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| --------- | ------------------- | --------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to remove sharing with | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `self` | `SavedItemBase` | The object itself, after removing sharing with the user or user group. Practically, only the shared property may have changed. |
## trendminer_interface.objects.DashboardConfiguration
Global dashboard configuration
Can override settings for the different tile types.
Attributes:
| Name | Type | Description |
| ---------- | ---------------------------------- | ----------------------------------------------- |
| `context` | `ContextHubViewTileConfiguration` | Global configuration for ContextHub view tiles |
| `external` | `ExternalContentTileConfiguration` | Global configuration for External content tiles |
| `gauge` | `GaugeTileConfiguration` | Global configuration for Gauge tiles |
| `monitor` | `MonitorTileConfiguration` | Global configuration for Monitor tiles |
| `notebook` | `NotebookTileConfiguration` | Global configuration for Notebook tiles |
| `text` | `TextTileConfiguration` | Global configuration for Text tiles |
| `trend` | `TrendHubViewTileConfiguration` | Global configuration for TrendHub view tiles |
| `value` | `CurrentValueTileConfiguration` | Global configuration for Current value tiles |
### context
```
context: ContextHubViewTileConfiguration
```
### external
```
external: ExternalContentTileConfiguration
```
### gauge
```
gauge: GaugeTileConfiguration
```
### monitor
```
monitor: MonitorTileConfiguration
```
### notebook
```
notebook: NotebookTileConfiguration
```
### text
```
text: TextTileConfiguration
```
### trend
```
trend: TrendHubViewTileConfiguration
```
### value
```
value: CurrentValueTileConfiguration
```
## trendminer_interface.objects.Datasource
Tag datasource
### identifier
```
identifier: str
```
Datasource identifier
### name
```
name: str
```
Datasource name
### description
```
description: str
```
Datasource description
### capabilities
```
capabilities: list[str]
```
Capability types, e.g. TIME_SERIES
### raw
```
raw: bool
```
Whether the datasource only supports raw values (plots index points only, even when zooming in).
### granularity
```
granularity: Timedelta
```
Chunk size for historic indexing
### source_type
```
source_type: str
```
Datasource type
### created_at
```
created_at: Timestamp
```
Date the datasource was created
### synced_at
```
synced_at: Timestamp
```
Last synced date for the datasource
### builtin
```
builtin: bool
```
Whether the datasource is one of the fixed appliance datasources (e.g., Formula tags)
## trendminer_interface.objects.DigitalStepSearch
Bases: `SavedItemBase`
Digital step search work organizer object
### name
```
name: str = name
```
### description
```
description: str = description
```
### folder
```
folder: Folder | None = folder
```
### identifier
```
identifier: str
```
UUID of the saved object
### created_at
```
created_at: Timestamp | None
```
Timestamp the object was created at
Can be None for items created before item creation date tracking was implemented in TrendMiner.
### last_modified
```
last_modified: Timestamp
```
Timestamp the object was last modified
### last_used
```
last_used: Timestamp
```
Timestamp the object was last used
### last_modified_by
```
last_modified_by: User
```
User that last modified the object
### owner
```
owner: User
```
User that owns the object
### shared
```
shared: bool
```
Whether the object is shared with other users
### favorite
```
favorite: bool
```
Whether the object is marked as a favorite by the owner
### version
```
version: int
```
Version number of the object, incremented on each modification
### definition
```
definition: DigitalStepSearchDefinition
```
### update
```
update() -> Self
```
Update the saved item in TrendMiner to match the current instance state
### delete
```
delete() -> None
```
Permanently delete the saved item in TrendMiner
### move
```
move(folder: Folder) -> None
```
Move the item to a folder
Parameters:
| Name | Type | Description | Default |
| -------- | -------- | ------------------------------ | ---------- |
| `folder` | `Folder` | The folder to move the item to | *required* |
Notes
Moving an item to another user's folder will not transfer the ownership and may lead to unexpected behavior. Use the client.work.transfer method instead.
### get_folder_path
```
get_folder_path(include_home=False) -> list[Folder]
```
Get the location in the work organizer
Starts from, but does not include, the user's home folder. Does not include the object itself.
Parameters:
| Name | Type | Description | Default |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `include_home` | `bool` | Whether to include the user's home folder as the first element of the returned list. If False (default), the list starts from the first folder after the home folder. | `False` |
Returns:
| Type | Description |
| -------------- | --------------------------------------- |
| `list[Folder]` | List of folders leading up to this item |
### get_permissions
```
get_permissions() -> list[
tuple[User | UserGroup, WorkSharePermission]
]
```
Get the sharing settings of the object
Returns:
| Name | Type | Description |
| --------- | ------------------- | ------------------------------------ |
| `sharing` | \`list\[tuple\[User | UserGroup, WorkSharePermission\]\]\` |
### add_permission
```
add_permission(
subject: User | UserGroup,
permission: WorkSharePermission,
) -> Self
```
Share the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| ------------ | ------------------- | ----------------------------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to share the object with | *required* |
| `permission` | `str` | The permission to share with. Can be "read", "write", or "manage" | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `self` | `SavedItemBase` | The object itself, after being shared with the user or user group. Practically, only the shared property may have changed. |
### remove_permission
```
remove_permission(subject: User | UserGroup) -> Self
```
Remove sharing of the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| --------- | ------------------- | --------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to remove sharing with | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `self` | `SavedItemBase` | The object itself, after removing sharing with the user or user group. Practically, only the shared property may have changed. |
## trendminer_interface.objects.DraftContextHubViewTile
Bases: `TileBase[ContextHubViewTileConfiguration]`
Draft ContextHub view tile
Attributes:
| Name | Type | Description |
| -------------- | ----------- | ----------- |
| `refresh_rate` | \`Timedelta | None\` |
### position
```
position: tuple[int, int, int, int]
```
### title
```
title: str
```
### config
```
config: TConfig
```
### refresh_rate
```
refresh_rate: Timedelta | None
```
## trendminer_interface.objects.DraftCurrentValueTile
Bases: `TileBase[CurrentValueTileConfiguration]`
Draft current value tile
Attributes:
| Name | Type | Description |
| -------------- | ------------------------------ | --------------------------------------------------------- |
| `refresh_rate` | `pandas.Timedelta, default 1m` | How often the tile is refreshed if the dashboard is live. |
### position
```
position: tuple[int, int, int, int]
```
### title
```
title: str
```
### config
```
config: TConfig
```
### refresh_rate
```
refresh_rate: Timedelta
```
## trendminer_interface.objects.DraftGaugeTile
Bases: `TileBase[GaugeTileConfiguration]`
Draft Gauge tile
Attributes:
| Name | Type | Description |
| --------------- | ---------------------- | --------------------------------------------------------- |
| `component` | \`Tag | Attribute |
| `mode` | \`GaugeTileMode | None\` |
| `default_range` | \`GaugeTileRange | None\` |
| `ranges` | `list[GaugeTileRange]` | Additional ranges for the gauge tile |
| `target` | \`float | None\` |
| `refresh_rate` | `Timedelta` | How often the tile is refreshed if the dashboard is live. |
### position
```
position: tuple[int, int, int, int]
```
### title
```
title: str
```
### config
```
config: TConfig
```
### component
```
component: Tag | Attribute | None
```
### mode
```
mode: GaugeTileMode | None
```
### default_range
```
default_range: GaugeTileRange | None
```
### ranges
```
ranges: list[GaugeTileRange]
```
### target
```
target: float | None
```
### refresh_rate
```
refresh_rate: Timedelta
```
## trendminer_interface.objects.DraftMonitorTile
Bases: `TileBase[MonitorTileConfiguration]`
Draft monitor tile
Attributes:
| Name | Type | Description |
| -------------- | ----------- | --------------------------------------------------------- |
| `refresh_rate` | `Timedelta` | How often the tile is refreshed if the dashboard is live. |
### position
```
position: tuple[int, int, int, int]
```
### title
```
title: str
```
### config
```
config: TConfig
```
### refresh_rate
```
refresh_rate: Timedelta
```
## trendminer_interface.objects.DraftTrendHubViewTile
Bases: `TileBase[TrendHubViewTileConfiguration]`
Draft TrendHub view tile
Attributes:
| Name | Type | Description |
| -------------- | ----------- | --------------------------------------------------------- |
| `refresh_rate` | `Timedelta` | How often the tile is refreshed if the dashboard is live. |
### position
```
position: tuple[int, int, int, int]
```
### title
```
title: str
```
### config
```
config: TConfig
```
### refresh_rate
```
refresh_rate: Timedelta
```
## trendminer_interface.objects.EmailMonitorNotification
Monitor email notification
Attributes:
| Name | Type | Description |
| --------- | ------------- | ----------------------------------- |
| `enabled` | `bool` | Whether the notification is enabled |
| `subject` | `str` | The email subject |
| `message` | `str` | The email message body |
| `to` | `list of str` | The email recipients |
### enabled
```
enabled: bool = enabled
```
### subject
```
subject: str = subject
```
### message
```
message: str = message
```
### to
```
to: list[str] = to
```
### enabled_at
```
enabled_at: Timestamp | None
```
The timestamp the notification was enabled
## trendminer_interface.objects.ExternalContentTile
Bases: `TileBase[ExternalContentTileConfiguration]`
External content dashboard tile
Attributes:
| Name | Type | Description |
| -------------- | ----------- | --------------------------------------------------------- |
| `url` | \`str | None\` |
| `refresh_rate` | `Timedelta` | How often the tile is refreshed if the dashboard is live. |
### position
```
position: tuple[int, int, int, int]
```
### title
```
title: str
```
### config
```
config: TConfig
```
### url
```
url: str | None
```
### refresh_rate
```
refresh_rate: Timedelta
```
## trendminer_interface.objects.ExternalContentTileConfiguration
Configuration for external content dashboard tile
Attributes:
| Name | Type | Description |
| ------------ | ------ | ------------------------------ |
| `show_title` | `bool` | Whether to show the tile title |
### show_title
```
show_title: bool
```
## trendminer_interface.objects.Filter
Bases: `SavedItemBase`
Filter work organizer object
### name
```
name: str = name
```
### description
```
description: str = description
```
### folder
```
folder: Folder | None = folder
```
### identifier
```
identifier: str
```
UUID of the saved object
### created_at
```
created_at: Timestamp | None
```
Timestamp the object was created at
Can be None for items created before item creation date tracking was implemented in TrendMiner.
### last_modified
```
last_modified: Timestamp
```
Timestamp the object was last modified
### last_used
```
last_used: Timestamp
```
Timestamp the object was last used
### last_modified_by
```
last_modified_by: User
```
User that last modified the object
### owner
```
owner: User
```
User that owns the object
### shared
```
shared: bool
```
Whether the object is shared with other users
### favorite
```
favorite: bool
```
Whether the object is marked as a favorite by the owner
### version
```
version: int
```
Version number of the object, incremented on each modification
### definition
```
definition: FilterDefinition
```
### update
```
update() -> Self
```
Update the saved item in TrendMiner to match the current instance state
### delete
```
delete() -> None
```
Permanently delete the saved item in TrendMiner
### move
```
move(folder: Folder) -> None
```
Move the item to a folder
Parameters:
| Name | Type | Description | Default |
| -------- | -------- | ------------------------------ | ---------- |
| `folder` | `Folder` | The folder to move the item to | *required* |
Notes
Moving an item to another user's folder will not transfer the ownership and may lead to unexpected behavior. Use the client.work.transfer method instead.
### get_folder_path
```
get_folder_path(include_home=False) -> list[Folder]
```
Get the location in the work organizer
Starts from, but does not include, the user's home folder. Does not include the object itself.
Parameters:
| Name | Type | Description | Default |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `include_home` | `bool` | Whether to include the user's home folder as the first element of the returned list. If False (default), the list starts from the first folder after the home folder. | `False` |
Returns:
| Type | Description |
| -------------- | --------------------------------------- |
| `list[Folder]` | List of folders leading up to this item |
### get_permissions
```
get_permissions() -> list[
tuple[User | UserGroup, WorkSharePermission]
]
```
Get the sharing settings of the object
Returns:
| Name | Type | Description |
| --------- | ------------------- | ------------------------------------ |
| `sharing` | \`list\[tuple\[User | UserGroup, WorkSharePermission\]\]\` |
### add_permission
```
add_permission(
subject: User | UserGroup,
permission: WorkSharePermission,
) -> Self
```
Share the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| ------------ | ------------------- | ----------------------------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to share the object with | *required* |
| `permission` | `str` | The permission to share with. Can be "read", "write", or "manage" | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `self` | `SavedItemBase` | The object itself, after being shared with the user or user group. Practically, only the shared property may have changed. |
### remove_permission
```
remove_permission(subject: User | UserGroup) -> Self
```
Remove sharing of the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| --------- | ------------------- | --------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to remove sharing with | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `self` | `SavedItemBase` | The object itself, after removing sharing with the user or user group. Practically, only the shared property may have changed. |
## trendminer_interface.objects.Fingerprint
Bases: `SavedItemBase`
Fingerprint work organizer object
Attributes:
| Name | Type | Description |
| ------------ | ----------------------- | -------------------------------------------------------------------- |
| `definition` | `FingerprintDefinition` | Definition of the fingerprint, containing all configuration details. |
### name
```
name: str = name
```
### description
```
description: str = description
```
### folder
```
folder: Folder | None = folder
```
### identifier
```
identifier: str
```
UUID of the saved object
### created_at
```
created_at: Timestamp | None
```
Timestamp the object was created at
Can be None for items created before item creation date tracking was implemented in TrendMiner.
### last_modified
```
last_modified: Timestamp
```
Timestamp the object was last modified
### last_used
```
last_used: Timestamp
```
Timestamp the object was last used
### last_modified_by
```
last_modified_by: User
```
User that last modified the object
### owner
```
owner: User
```
User that owns the object
### shared
```
shared: bool
```
Whether the object is shared with other users
### favorite
```
favorite: bool
```
Whether the object is marked as a favorite by the owner
### version
```
version: int
```
Version number of the object, incremented on each modification
### definition
```
definition: FingerprintDefinition
```
### update
```
update() -> Self
```
Update the saved item in TrendMiner to match the current instance state
### delete
```
delete() -> None
```
Permanently delete the saved item in TrendMiner
### move
```
move(folder: Folder) -> None
```
Move the item to a folder
Parameters:
| Name | Type | Description | Default |
| -------- | -------- | ------------------------------ | ---------- |
| `folder` | `Folder` | The folder to move the item to | *required* |
Notes
Moving an item to another user's folder will not transfer the ownership and may lead to unexpected behavior. Use the client.work.transfer method instead.
### get_folder_path
```
get_folder_path(include_home=False) -> list[Folder]
```
Get the location in the work organizer
Starts from, but does not include, the user's home folder. Does not include the object itself.
Parameters:
| Name | Type | Description | Default |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `include_home` | `bool` | Whether to include the user's home folder as the first element of the returned list. If False (default), the list starts from the first folder after the home folder. | `False` |
Returns:
| Type | Description |
| -------------- | --------------------------------------- |
| `list[Folder]` | List of folders leading up to this item |
### get_permissions
```
get_permissions() -> list[
tuple[User | UserGroup, WorkSharePermission]
]
```
Get the sharing settings of the object
Returns:
| Name | Type | Description |
| --------- | ------------------- | ------------------------------------ |
| `sharing` | \`list\[tuple\[User | UserGroup, WorkSharePermission\]\]\` |
### add_permission
```
add_permission(
subject: User | UserGroup,
permission: WorkSharePermission,
) -> Self
```
Share the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| ------------ | ------------------- | ----------------------------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to share the object with | *required* |
| `permission` | `str` | The permission to share with. Can be "read", "write", or "manage" | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `self` | `SavedItemBase` | The object itself, after being shared with the user or user group. Practically, only the shared property may have changed. |
### remove_permission
```
remove_permission(subject: User | UserGroup) -> Self
```
Remove sharing of the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| --------- | ------------------- | --------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to remove sharing with | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `self` | `SavedItemBase` | The object itself, after removing sharing with the user or user group. Practically, only the shared property may have changed. |
### get_monitor
```
get_monitor() -> Monitor
```
Get the monitor corresponding to the item
Returns:
| Type | Description |
| --------- | --------------------------------------------- |
| `Monitor` | The monitor associated with this fingerprint. |
## trendminer_interface.objects.Folder
Bases: `SavedItemBase`
Work organizer folder
### name
```
name: str = name
```
### description
```
description: str = description
```
### folder
```
folder: Folder | None = folder
```
### definition
```
definition: Any = definition
```
### identifier
```
identifier: str
```
UUID of the saved object
### created_at
```
created_at: Timestamp | None
```
Timestamp the object was created at
Can be None for items created before item creation date tracking was implemented in TrendMiner.
### last_modified
```
last_modified: Timestamp
```
Timestamp the object was last modified
### last_used
```
last_used: Timestamp
```
Timestamp the object was last used
### last_modified_by
```
last_modified_by: User
```
User that last modified the object
### owner
```
owner: User
```
User that owns the object
### shared
```
shared: bool
```
Whether the object is shared with other users
### favorite
```
favorite: bool
```
Whether the object is marked as a favorite by the owner
### version
```
version: int
```
Version number of the object, incremented on each modification
### delete
```
delete() -> None
```
Permanently delete the saved item in TrendMiner
### move
```
move(folder: Folder) -> None
```
Move the item to a folder
Parameters:
| Name | Type | Description | Default |
| -------- | -------- | ------------------------------ | ---------- |
| `folder` | `Folder` | The folder to move the item to | *required* |
Notes
Moving an item to another user's folder will not transfer the ownership and may lead to unexpected behavior. Use the client.work.transfer method instead.
### get_folder_path
```
get_folder_path(include_home=False) -> list[Folder]
```
Get the location in the work organizer
Starts from, but does not include, the user's home folder. Does not include the object itself.
Parameters:
| Name | Type | Description | Default |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `include_home` | `bool` | Whether to include the user's home folder as the first element of the returned list. If False (default), the list starts from the first folder after the home folder. | `False` |
Returns:
| Type | Description |
| -------------- | --------------------------------------- |
| `list[Folder]` | List of folders leading up to this item |
### get_permissions
```
get_permissions() -> list[
tuple[User | UserGroup, WorkSharePermission]
]
```
Get the sharing settings of the object
Returns:
| Name | Type | Description |
| --------- | ------------------- | ------------------------------------ |
| `sharing` | \`list\[tuple\[User | UserGroup, WorkSharePermission\]\]\` |
### add_permission
```
add_permission(
subject: User | UserGroup,
permission: WorkSharePermission,
) -> Self
```
Share the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| ------------ | ------------------- | ----------------------------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to share the object with | *required* |
| `permission` | `str` | The permission to share with. Can be "read", "write", or "manage" | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `self` | `SavedItemBase` | The object itself, after being shared with the user or user group. Practically, only the shared property may have changed. |
### remove_permission
```
remove_permission(subject: User | UserGroup) -> Self
```
Remove sharing of the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| --------- | ------------------- | --------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to remove sharing with | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `self` | `SavedItemBase` | The object itself, after removing sharing with the user or user group. Practically, only the shared property may have changed. |
### update
```
update() -> Folder
```
Update the folder in the TrendMiner work organizer to match the current instance state
### search_contents
```
search_contents(
content_type: type[SavedItem] | None = None,
page: int = 0,
size: int = 2000,
) -> PagedList[SavedItem]
```
Search items saved in this folder
Parameters:
| Name | Type | Description | Default |
| -------------- | ----------------- | --------------------------------------------------------------------------------------------- | ------- |
| `content_type` | `type[SavedItem]` | Type of items to get. If None, items of all types are returned. | `None` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. | `2000` |
Returns:
| Type | Description |
| ---------------------- | -------------------------------------------------------------- |
| `PagedList[SavedItem]` | Paginated list of items of the given type saved in this folder |
### get_item
```
get_item(
name: str, content_type: type[SavedItem]
) -> SavedItem
```
Get item with the given name and type saved in this folder
Parameters:
| Name | Type | Description | Default |
| -------------- | ----------------- | ------------------------ | ---------- |
| `name` | `str` | Name of the item to get | *required* |
| `content_type` | `type[SavedItem]` | Type of the item to get. | *required* |
Returns:
| Name | Type | Description |
| ------ | ----------- | ---------------------------------------------------------- |
| `item` | `SavedItem` | The item with the given name and type saved in this folder |
Raises:
| Type | Description |
| ------------------- | -------------------------------------------------------------- |
| `ResourceNotFound` | If no item with the given name and type exists in this folder. |
| `AmbiguousResource` | If multiple items match. |
## trendminer_interface.objects.Formula
Bases: `SavedItemBase`
Formula work organizer object
### name
```
name: str = name
```
### description
```
description: str = description
```
### folder
```
folder: Folder | None = folder
```
### identifier
```
identifier: str
```
UUID of the saved object
### created_at
```
created_at: Timestamp | None
```
Timestamp the object was created at
Can be None for items created before item creation date tracking was implemented in TrendMiner.
### last_modified
```
last_modified: Timestamp
```
Timestamp the object was last modified
### last_used
```
last_used: Timestamp
```
Timestamp the object was last used
### last_modified_by
```
last_modified_by: User
```
User that last modified the object
### owner
```
owner: User
```
User that owns the object
### shared
```
shared: bool
```
Whether the object is shared with other users
### favorite
```
favorite: bool
```
Whether the object is marked as a favorite by the owner
### version
```
version: int
```
Version number of the object, incremented on each modification
### definition
```
definition: FormulaDefinition
```
### update
```
update() -> Self
```
Update the saved item in TrendMiner to match the current instance state
### delete
```
delete() -> None
```
Permanently delete the saved item in TrendMiner
### move
```
move(folder: Folder) -> None
```
Move the item to a folder
Parameters:
| Name | Type | Description | Default |
| -------- | -------- | ------------------------------ | ---------- |
| `folder` | `Folder` | The folder to move the item to | *required* |
Notes
Moving an item to another user's folder will not transfer the ownership and may lead to unexpected behavior. Use the client.work.transfer method instead.
### get_folder_path
```
get_folder_path(include_home=False) -> list[Folder]
```
Get the location in the work organizer
Starts from, but does not include, the user's home folder. Does not include the object itself.
Parameters:
| Name | Type | Description | Default |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `include_home` | `bool` | Whether to include the user's home folder as the first element of the returned list. If False (default), the list starts from the first folder after the home folder. | `False` |
Returns:
| Type | Description |
| -------------- | --------------------------------------- |
| `list[Folder]` | List of folders leading up to this item |
### get_permissions
```
get_permissions() -> list[
tuple[User | UserGroup, WorkSharePermission]
]
```
Get the sharing settings of the object
Returns:
| Name | Type | Description |
| --------- | ------------------- | ------------------------------------ |
| `sharing` | \`list\[tuple\[User | UserGroup, WorkSharePermission\]\]\` |
### add_permission
```
add_permission(
subject: User | UserGroup,
permission: WorkSharePermission,
) -> Self
```
Share the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| ------------ | ------------------- | ----------------------------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to share the object with | *required* |
| `permission` | `str` | The permission to share with. Can be "read", "write", or "manage" | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `self` | `SavedItemBase` | The object itself, after being shared with the user or user group. Practically, only the shared property may have changed. |
### remove_permission
```
remove_permission(subject: User | UserGroup) -> Self
```
Remove sharing of the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| --------- | ------------------- | --------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to remove sharing with | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `self` | `SavedItemBase` | The object itself, after removing sharing with the user or user group. Practically, only the shared property may have changed. |
## trendminer_interface.objects.GaugeTile
Bases: `TileBase[GaugeTileConfiguration]`
Gauge tile
Attributes:
| Name | Type | Description |
| --------------- | ---------------------- | --------------------------------------------------------- |
| `component` | \`Tag | Attribute\` |
| `mode` | `GaugeTileMode` | Display mode of the gauge. |
| `default_range` | `GaugeTileRange` | Default range for the gauge: (min, max, label, color) |
| `ranges` | `list[GaugeTileRange]` | Additional ranges for the gauge tile |
| `target` | \`float | None\` |
| `refresh_rate` | `Timedelta` | How often the tile is refreshed if the dashboard is live. |
### position
```
position: tuple[int, int, int, int]
```
### title
```
title: str
```
### config
```
config: TConfig
```
### component
```
component: Tag | Attribute
```
### mode
```
mode: GaugeTileMode
```
### default_range
```
default_range: GaugeTileRange
```
### ranges
```
ranges: list[GaugeTileRange]
```
### target
```
target: float | None
```
### refresh_rate
```
refresh_rate: Timedelta
```
## trendminer_interface.objects.GaugeTileConfiguration
Gauge tile configuration
Attributes:
| Name | Type | Description |
| ------------------- | ------- | -------------------------------------------------------- |
| `show_title` | `bool` | Whether to show the tile title |
| `accuracy` | \`float | None\` |
| `colored_value` | `bool` | Whether to color the value based on the range colors |
| `percentage_ranges` | `bool` | Whether to display the ranges as percentages |
| `percentage_delta` | `bool` | Whether to display the target difference as a percentage |
| `percentage_value` | `bool` | Whether to display the value as a percentage |
| `show_range_labels` | `bool` | Whether to show the range labels |
| `show_delta` | `bool` | Whether to show the target difference |
| `show_ticks` | `bool` | Whether to show the ticks on the gauge |
| `show_timestamp` | `bool` | Whether to show the timestamp of the value |
| `use_chart_alias` | `bool` | Whether to use the chart alias for the component |
### show_title
```
show_title: bool
```
### accuracy
```
accuracy: float | None
```
### colored_value
```
colored_value: bool
```
### percentage_ranges
```
percentage_ranges: bool
```
### percentage_delta
```
percentage_delta: bool
```
### percentage_value
```
percentage_value: bool
```
### show_range_labels
```
show_range_labels: bool
```
### show_delta
```
show_delta: bool
```
### show_ticks
```
show_ticks: bool
```
### show_timestamp
```
show_timestamp: bool
```
### use_chart_alias
```
use_chart_alias: bool
```
## trendminer_interface.objects.IndexDetails
Tag indexing details
### tag
```
tag: Tag
```
The tag for which these index details apply.
### status
```
status: TagIndexStatus
```
The current status of the index.
Returns:
| Name | Type | Description |
| -------- | ----- | ----------------------------------------------------------------------- |
| `status` | `str` | "ok", "in progress", "out of date", "stale", "incomplete", or "dormant" |
### progress
```
progress: float
```
Tag historic indexing progress percentage (0-100).
### created_at
```
created_at: Timestamp
```
Timestamp the index was created at.
### last_modified
```
last_modified: Timestamp
```
Timestamp the index details were modified.
### last_updated
```
last_updated: Timestamp | None
```
Timestamp the index data was last updated.
### coverage_interval
```
coverage_interval: Interval
```
The time interval for which index requests have been sent to the datasource.
This does not mean that data is available for the entire interval. If the index status is 'ok', the interval left value should equal the index horizon, and the right value should be close to the current time.
### data_interval
```
data_interval: Interval
```
The time interval for which actual data is available in the index.
The left and right values of the returned interval are the timestamps of the earliest and latest data points in the index.
### index_frequency
```
index_frequency: Timedelta
```
The frequency at which the index is generally updated with new data.
### update
```
update() -> IndexDetails
```
Send a request to update the index with the latest data
Returns:
| Type | Description |
| -------------- | ---------------------------------------------------------------------- |
| `IndexDetails` | The updated index details after the update request has been processed. |
### refresh
```
refresh() -> None
```
Refresh the tag index
### delete
```
delete() -> None
```
Delete the tag index.
## trendminer_interface.objects.MachineLearningModel
Bases: `SavedItemBase`
Machine learning model work organizer object
### name
```
name: str = name
```
### description
```
description: str = description
```
### folder
```
folder: Folder | None = folder
```
### identifier
```
identifier: str
```
UUID of the saved object
### created_at
```
created_at: Timestamp | None
```
Timestamp the object was created at
Can be None for items created before item creation date tracking was implemented in TrendMiner.
### last_modified
```
last_modified: Timestamp
```
Timestamp the object was last modified
### last_used
```
last_used: Timestamp
```
Timestamp the object was last used
### last_modified_by
```
last_modified_by: User
```
User that last modified the object
### owner
```
owner: User
```
User that owns the object
### shared
```
shared: bool
```
Whether the object is shared with other users
### favorite
```
favorite: bool
```
Whether the object is marked as a favorite by the owner
### version
```
version: int
```
Version number of the object, incremented on each modification
### definition
```
definition: MachineLearningModelDefinition
```
### update
```
update() -> Self
```
Update the saved item in TrendMiner to match the current instance state
### delete
```
delete() -> None
```
Permanently delete the saved item in TrendMiner
### move
```
move(folder: Folder) -> None
```
Move the item to a folder
Parameters:
| Name | Type | Description | Default |
| -------- | -------- | ------------------------------ | ---------- |
| `folder` | `Folder` | The folder to move the item to | *required* |
Notes
Moving an item to another user's folder will not transfer the ownership and may lead to unexpected behavior. Use the client.work.transfer method instead.
### get_folder_path
```
get_folder_path(include_home=False) -> list[Folder]
```
Get the location in the work organizer
Starts from, but does not include, the user's home folder. Does not include the object itself.
Parameters:
| Name | Type | Description | Default |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `include_home` | `bool` | Whether to include the user's home folder as the first element of the returned list. If False (default), the list starts from the first folder after the home folder. | `False` |
Returns:
| Type | Description |
| -------------- | --------------------------------------- |
| `list[Folder]` | List of folders leading up to this item |
### get_permissions
```
get_permissions() -> list[
tuple[User | UserGroup, WorkSharePermission]
]
```
Get the sharing settings of the object
Returns:
| Name | Type | Description |
| --------- | ------------------- | ------------------------------------ |
| `sharing` | \`list\[tuple\[User | UserGroup, WorkSharePermission\]\]\` |
### add_permission
```
add_permission(
subject: User | UserGroup,
permission: WorkSharePermission,
) -> Self
```
Share the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| ------------ | ------------------- | ----------------------------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to share the object with | *required* |
| `permission` | `str` | The permission to share with. Can be "read", "write", or "manage" | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `self` | `SavedItemBase` | The object itself, after being shared with the user or user group. Practically, only the shared property may have changed. |
### remove_permission
```
remove_permission(subject: User | UserGroup) -> Self
```
Remove sharing of the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| --------- | ------------------- | --------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to remove sharing with | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `self` | `SavedItemBase` | The object itself, after removing sharing with the user or user group. Practically, only the shared property may have changed. |
## trendminer_interface.objects.Monitor
TrendMiner monitor
Attributes:
| Name | Type | Description |
| ----------------------- | -------------------------------- | ----------------------------------------------------------- |
| `fingerprint_trigger` | `(ValueBasedSearch, optional)` | Optional search that triggers fingerprint-based monitoring. |
| `fingerprint_threshold` | `(float, optional)` | Threshold value for fingerprint deviation monitoring. |
| `webhook` | `WebhookMonitorNotification` | Webhook notification configuration for this monitor. |
| `email` | `EmailMonitorNotification` | Email notification configuration for this monitor. |
| `context` | `ContextItemMonitorNotification` | Context item notification configuration for this monitor. |
### fingerprint_trigger
```
fingerprint_trigger: (
ValueBasedSearch
| SimilaritySearch
| AreaSearch
| DigitalStepSearch
| Fingerprint
| None
) = fingerprint_trigger
```
### fingerprint_threshold
```
fingerprint_threshold: float | None = fingerprint_threshold
```
### webhook
```
webhook: WebhookMonitorNotification = webhook
```
### email
```
email: EmailMonitorNotification = email
```
### context
```
context: ContextItemMonitorNotification = context
```
### identifier
```
identifier: int
```
Monitor identifier. Not a UUID, just simple sequential numbering.
### name
```
name: str
```
Name of the monitor.
### parent
```
parent: (
ValueBasedSearch
| SimilaritySearch
| AreaSearch
| DigitalStepSearch
| Fingerprint
)
```
The search or fingerprint object that this monitor is based on.
### state
```
state: Literal['enabled', 'disabled', 'system disabled']
```
Current state of the monitor.
### created_at
```
created_at: Timestamp | None
```
Timestamp when the monitor was created.
### last_modified
```
last_modified: Timestamp | None
```
Timestamp when the monitor was last modified.
### update
```
update() -> None
```
Update the monitor configuration on the server
Notes
Does not return the updated monitor object. To get the updated monitor, retrieve it again from its parent or its identifier.
### enable
```
enable() -> None
```
Enable the monitor
Notes
Does not return an updated monitor object nor are any attributes updated in place. To get the updated monitor, retrieve it again from its parent or its identifier.
### disable
```
disable() -> None
```
Disable the monitor
Notes
Does not return an updated monitor object nor are any attributes updated in place. To get the updated monitor, retrieve it again from its parent or its identifier.
### get_results
```
get_results(limit: int = 2000) -> DataFrame
```
Get most recent monitor results
Parameters:
| Name | Type | Description | Default |
| ------- | ----- | ------------------------------------------------------------------------------ | ------- |
| `limit` | `int` | The maximum number of results to retrieve. Defaults to the max allowed number. | `2000` |
Returns:
| Name | Type | Description |
| --------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `results` | `DataFrame` | Result DataFrame with IntervalIndex, and open and score columns. Note that the match score (0 - 100) column will be NaN for all monitors that do not have a SimilaritySearch or Fingerprint parent. |
## trendminer_interface.objects.MonitorTile
Bases: `TileBase[MonitorTileConfiguration]`
Monitor tile
Attributes:
| Name | Type | Description |
| -------------- | ---------------------- | -------------------------------------------------------------------------------------------- |
| `monitor` | `Monitor` | The monitor to display in the tile |
| `active` | `MonitorTileCondition` | Condition to display when the monitor is active (triggered): (icon, text label, color) |
| `inactive` | `MonitorTileCondition` | Condition to display when the monitor is inactive (not triggered): (icon, text label, color) |
| `refresh_rate` | `Timedelta` | How often the tile is refreshed if the dashboard is live. |
### position
```
position: tuple[int, int, int, int]
```
### title
```
title: str
```
### config
```
config: TConfig
```
### monitor
```
monitor: Monitor
```
### active
```
active: MonitorTileCondition
```
### inactive
```
inactive: MonitorTileCondition
```
### refresh_rate
```
refresh_rate: Timedelta
```
## trendminer_interface.objects.MonitorTileConfiguration
Configuration for Monitor tile
Attributes:
| Name | Type | Description |
| ----------------- | ------ | ------------------------------------------ |
| `show_title` | `bool` | Whether to show the tile title |
| `fill_background` | `bool` | Whether to fill the background of the tile |
### show_title
```
show_title: bool
```
### fill_background
```
fill_background: bool
```
## trendminer_interface.objects.Notebook
Bases: `SavedItemBase`
Notebook work organizer object
### name
```
name: str = name
```
### description
```
description: str = description
```
### folder
```
folder: Folder | None = folder
```
### identifier
```
identifier: str
```
UUID of the saved object
### created_at
```
created_at: Timestamp | None
```
Timestamp the object was created at
Can be None for items created before item creation date tracking was implemented in TrendMiner.
### last_modified
```
last_modified: Timestamp
```
Timestamp the object was last modified
### last_used
```
last_used: Timestamp
```
Timestamp the object was last used
### last_modified_by
```
last_modified_by: User
```
User that last modified the object
### owner
```
owner: User
```
User that owns the object
### shared
```
shared: bool
```
Whether the object is shared with other users
### favorite
```
favorite: bool
```
Whether the object is marked as a favorite by the owner
### version
```
version: int
```
Version number of the object, incremented on each modification
### definition
```
definition: NotebookDefinition
```
### update
```
update() -> Self
```
Update the saved item in TrendMiner to match the current instance state
### delete
```
delete() -> None
```
Permanently delete the saved item in TrendMiner
### move
```
move(folder: Folder) -> None
```
Move the item to a folder
Parameters:
| Name | Type | Description | Default |
| -------- | -------- | ------------------------------ | ---------- |
| `folder` | `Folder` | The folder to move the item to | *required* |
Notes
Moving an item to another user's folder will not transfer the ownership and may lead to unexpected behavior. Use the client.work.transfer method instead.
### get_folder_path
```
get_folder_path(include_home=False) -> list[Folder]
```
Get the location in the work organizer
Starts from, but does not include, the user's home folder. Does not include the object itself.
Parameters:
| Name | Type | Description | Default |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `include_home` | `bool` | Whether to include the user's home folder as the first element of the returned list. If False (default), the list starts from the first folder after the home folder. | `False` |
Returns:
| Type | Description |
| -------------- | --------------------------------------- |
| `list[Folder]` | List of folders leading up to this item |
### get_permissions
```
get_permissions() -> list[
tuple[User | UserGroup, WorkSharePermission]
]
```
Get the sharing settings of the object
Returns:
| Name | Type | Description |
| --------- | ------------------- | ------------------------------------ |
| `sharing` | \`list\[tuple\[User | UserGroup, WorkSharePermission\]\]\` |
### add_permission
```
add_permission(
subject: User | UserGroup,
permission: WorkSharePermission,
) -> Self
```
Share the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| ------------ | ------------------- | ----------------------------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to share the object with | *required* |
| `permission` | `str` | The permission to share with. Can be "read", "write", or "manage" | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `self` | `SavedItemBase` | The object itself, after being shared with the user or user group. Practically, only the shared property may have changed. |
### remove_permission
```
remove_permission(subject: User | UserGroup) -> Self
```
Remove sharing of the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| --------- | ------------------- | --------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to remove sharing with | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `self` | `SavedItemBase` | The object itself, after removing sharing with the user or user group. Practically, only the shared property may have changed. |
## trendminer_interface.objects.NotebookTile
Bases: `TileBase[NotebookTileConfiguration]`
Notebook pipeline dashboard tile
Attributes:
| Name | Type | Description |
| -------------- | ------------------------------ | --------------------------------------------------------- |
| `pipeline` | \`Pipeline | None\` |
| `refresh_rate` | `pandas.Timedelta, default 5m` | How often the tile is refreshed if the dashboard is live. |
### position
```
position: tuple[int, int, int, int]
```
### title
```
title: str
```
### config
```
config: TConfig
```
### pipeline
```
pipeline: Pipeline | None
```
### refresh_rate
```
refresh_rate: Timedelta
```
## trendminer_interface.objects.NotebookTileConfiguration
Notebook tile configuration
Attributes:
| Name | Type | Description |
| ------------ | ------ | ------------------------------ |
| `show_title` | `bool` | Whether to show the tile title |
### show_title
```
show_title: bool
```
## trendminer_interface.objects.Pipeline
Bases: `SavedItemBase`
Pipeline work organizer object
### name
```
name: str = name
```
### description
```
description: str = description
```
### folder
```
folder: Folder | None = folder
```
### identifier
```
identifier: str
```
UUID of the saved object
### created_at
```
created_at: Timestamp | None
```
Timestamp the object was created at
Can be None for items created before item creation date tracking was implemented in TrendMiner.
### last_modified
```
last_modified: Timestamp
```
Timestamp the object was last modified
### last_used
```
last_used: Timestamp
```
Timestamp the object was last used
### last_modified_by
```
last_modified_by: User
```
User that last modified the object
### owner
```
owner: User
```
User that owns the object
### shared
```
shared: bool
```
Whether the object is shared with other users
### favorite
```
favorite: bool
```
Whether the object is marked as a favorite by the owner
### version
```
version: int
```
Version number of the object, incremented on each modification
### definition
```
definition: PipelineDefinition
```
### update
```
update() -> Self
```
Update the saved item in TrendMiner to match the current instance state
### delete
```
delete() -> None
```
Permanently delete the saved item in TrendMiner
### move
```
move(folder: Folder) -> None
```
Move the item to a folder
Parameters:
| Name | Type | Description | Default |
| -------- | -------- | ------------------------------ | ---------- |
| `folder` | `Folder` | The folder to move the item to | *required* |
Notes
Moving an item to another user's folder will not transfer the ownership and may lead to unexpected behavior. Use the client.work.transfer method instead.
### get_folder_path
```
get_folder_path(include_home=False) -> list[Folder]
```
Get the location in the work organizer
Starts from, but does not include, the user's home folder. Does not include the object itself.
Parameters:
| Name | Type | Description | Default |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `include_home` | `bool` | Whether to include the user's home folder as the first element of the returned list. If False (default), the list starts from the first folder after the home folder. | `False` |
Returns:
| Type | Description |
| -------------- | --------------------------------------- |
| `list[Folder]` | List of folders leading up to this item |
### get_permissions
```
get_permissions() -> list[
tuple[User | UserGroup, WorkSharePermission]
]
```
Get the sharing settings of the object
Returns:
| Name | Type | Description |
| --------- | ------------------- | ------------------------------------ |
| `sharing` | \`list\[tuple\[User | UserGroup, WorkSharePermission\]\]\` |
### add_permission
```
add_permission(
subject: User | UserGroup,
permission: WorkSharePermission,
) -> Self
```
Share the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| ------------ | ------------------- | ----------------------------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to share the object with | *required* |
| `permission` | `str` | The permission to share with. Can be "read", "write", or "manage" | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `self` | `SavedItemBase` | The object itself, after being shared with the user or user group. Practically, only the shared property may have changed. |
### remove_permission
```
remove_permission(subject: User | UserGroup) -> Self
```
Remove sharing of the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| --------- | ------------------- | --------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to remove sharing with | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `self` | `SavedItemBase` | The object itself, after removing sharing with the user or user group. Practically, only the shared property may have changed. |
## trendminer_interface.objects.Prediction
Bases: `SavedItemBase`
Prediction work organizer object
### name
```
name: str = name
```
### description
```
description: str = description
```
### folder
```
folder: Folder | None = folder
```
### identifier
```
identifier: str
```
UUID of the saved object
### created_at
```
created_at: Timestamp | None
```
Timestamp the object was created at
Can be None for items created before item creation date tracking was implemented in TrendMiner.
### last_modified
```
last_modified: Timestamp
```
Timestamp the object was last modified
### last_used
```
last_used: Timestamp
```
Timestamp the object was last used
### last_modified_by
```
last_modified_by: User
```
User that last modified the object
### owner
```
owner: User
```
User that owns the object
### shared
```
shared: bool
```
Whether the object is shared with other users
### favorite
```
favorite: bool
```
Whether the object is marked as a favorite by the owner
### version
```
version: int
```
Version number of the object, incremented on each modification
### definition
```
definition: PredictionDefinition
```
### update
```
update() -> Self
```
Update the saved item in TrendMiner to match the current instance state
### delete
```
delete() -> None
```
Permanently delete the saved item in TrendMiner
### move
```
move(folder: Folder) -> None
```
Move the item to a folder
Parameters:
| Name | Type | Description | Default |
| -------- | -------- | ------------------------------ | ---------- |
| `folder` | `Folder` | The folder to move the item to | *required* |
Notes
Moving an item to another user's folder will not transfer the ownership and may lead to unexpected behavior. Use the client.work.transfer method instead.
### get_folder_path
```
get_folder_path(include_home=False) -> list[Folder]
```
Get the location in the work organizer
Starts from, but does not include, the user's home folder. Does not include the object itself.
Parameters:
| Name | Type | Description | Default |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `include_home` | `bool` | Whether to include the user's home folder as the first element of the returned list. If False (default), the list starts from the first folder after the home folder. | `False` |
Returns:
| Type | Description |
| -------------- | --------------------------------------- |
| `list[Folder]` | List of folders leading up to this item |
### get_permissions
```
get_permissions() -> list[
tuple[User | UserGroup, WorkSharePermission]
]
```
Get the sharing settings of the object
Returns:
| Name | Type | Description |
| --------- | ------------------- | ------------------------------------ |
| `sharing` | \`list\[tuple\[User | UserGroup, WorkSharePermission\]\]\` |
### add_permission
```
add_permission(
subject: User | UserGroup,
permission: WorkSharePermission,
) -> Self
```
Share the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| ------------ | ------------------- | ----------------------------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to share the object with | *required* |
| `permission` | `str` | The permission to share with. Can be "read", "write", or "manage" | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `self` | `SavedItemBase` | The object itself, after being shared with the user or user group. Practically, only the shared property may have changed. |
### remove_permission
```
remove_permission(subject: User | UserGroup) -> Self
```
Remove sharing of the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| --------- | ------------------- | --------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to remove sharing with | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `self` | `SavedItemBase` | The object itself, after removing sharing with the user or user group. Practically, only the shared property may have changed. |
## trendminer_interface.objects.SimilaritySearch
Bases: `SavedItemBase`
Similarity search work organizer object
### name
```
name: str = name
```
### description
```
description: str = description
```
### folder
```
folder: Folder | None = folder
```
### identifier
```
identifier: str
```
UUID of the saved object
### created_at
```
created_at: Timestamp | None
```
Timestamp the object was created at
Can be None for items created before item creation date tracking was implemented in TrendMiner.
### last_modified
```
last_modified: Timestamp
```
Timestamp the object was last modified
### last_used
```
last_used: Timestamp
```
Timestamp the object was last used
### last_modified_by
```
last_modified_by: User
```
User that last modified the object
### owner
```
owner: User
```
User that owns the object
### shared
```
shared: bool
```
Whether the object is shared with other users
### favorite
```
favorite: bool
```
Whether the object is marked as a favorite by the owner
### version
```
version: int
```
Version number of the object, incremented on each modification
### definition
```
definition: SimilaritySearchDefinition
```
### update
```
update() -> Self
```
Update the saved item in TrendMiner to match the current instance state
### delete
```
delete() -> None
```
Permanently delete the saved item in TrendMiner
### move
```
move(folder: Folder) -> None
```
Move the item to a folder
Parameters:
| Name | Type | Description | Default |
| -------- | -------- | ------------------------------ | ---------- |
| `folder` | `Folder` | The folder to move the item to | *required* |
Notes
Moving an item to another user's folder will not transfer the ownership and may lead to unexpected behavior. Use the client.work.transfer method instead.
### get_folder_path
```
get_folder_path(include_home=False) -> list[Folder]
```
Get the location in the work organizer
Starts from, but does not include, the user's home folder. Does not include the object itself.
Parameters:
| Name | Type | Description | Default |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `include_home` | `bool` | Whether to include the user's home folder as the first element of the returned list. If False (default), the list starts from the first folder after the home folder. | `False` |
Returns:
| Type | Description |
| -------------- | --------------------------------------- |
| `list[Folder]` | List of folders leading up to this item |
### get_permissions
```
get_permissions() -> list[
tuple[User | UserGroup, WorkSharePermission]
]
```
Get the sharing settings of the object
Returns:
| Name | Type | Description |
| --------- | ------------------- | ------------------------------------ |
| `sharing` | \`list\[tuple\[User | UserGroup, WorkSharePermission\]\]\` |
### add_permission
```
add_permission(
subject: User | UserGroup,
permission: WorkSharePermission,
) -> Self
```
Share the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| ------------ | ------------------- | ----------------------------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to share the object with | *required* |
| `permission` | `str` | The permission to share with. Can be "read", "write", or "manage" | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `self` | `SavedItemBase` | The object itself, after being shared with the user or user group. Practically, only the shared property may have changed. |
### remove_permission
```
remove_permission(subject: User | UserGroup) -> Self
```
Remove sharing of the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| --------- | ------------------- | --------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to remove sharing with | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `self` | `SavedItemBase` | The object itself, after removing sharing with the user or user group. Practically, only the shared property may have changed. |
## trendminer_interface.objects.Tag
TrendMiner tag instance
Attributes:
| Name | Type | Description |
| ---------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shift` | `Timedelta` | Time shift of the tag. Any methods returning timestamped data for the tag will consider this shift. A positive shift values means the tag is moved forward in time (i.e., shifted to the right on the time axis). This results in older data being returned on the same timestamps, or the same data being returned on a later timestamp than if no shift were present. The inverse applies for negative shift values. |
| `visible` | `bool` | Whether the tag is visible in TrendHub. This is used for visualization purposes in TrendHub, and has an impact on fingerprints. Tags retrieved from anywhere but a TrendHub view or Fingerprint will be visible by default. |
| `color` | `str` | The color of the tag, as a hex color code (e.g., "#FF0000" for red). This is used for visualization purposes in TrendHub. |
| `scale` | `tuple[float, float] or None` | The manually set scale of the tag, as a tuple of (min, max) values, as used in TrendHub visualization. If no manual scale is set (None), the tag will be autoscaled. |
| `alias` | `str or None` | The alias of the tag, as set in TrendHub. |
| `accuracy` | `float or None` | The accuracy to which tag value representations are rounded in TrendHub. A power of 10 (..., 10, 1, 0.1, 0.01, ...). If None, no rounding is applied. |
### shift
```
shift: Timedelta = shift
```
### visible
```
visible: bool = visible
```
### color
```
color: str = color
```
### scale
```
scale: tuple[float, float] | None = scale
```
### alias
```
alias: str | None = alias
```
### accuracy
```
accuracy: float | None = accuracy
```
### identifier
```
identifier: str
```
UUID of the tag
### name
```
name: str
```
Name of the tag
### description
```
description: str
```
Description of the tag
### tag_type
```
tag_type: TagType
```
Type of the tag
### units
```
units: str
```
Units of the tag
### datasource
```
datasource: Datasource
```
Datasource of the tag
### add_aggregation
```
add_aggregation(
events: DataFrame,
method: IntervalAggregationMethod,
name: str,
) -> DataFrame
```
Add a tag aggregation as a column to an event DataFrame
Parameters:
| Name | Type | Description | Default |
| -------- | --------------------------- | --------------------------------------------------------- | ---------- |
| `events` | `DataFrame` | Events DataFrame with a pd.IntervalIndex. | *required* |
| `method` | `IntervalAggregationMethod` | Aggregation method to apply over each interval. | *required* |
| `name` | `str` | Column name under which the aggregation result is stored. | *required* |
Returns:
| Type | Description |
| ----------- | ----------------------------------------------------------------------- |
| `DataFrame` | Copy of the input DataFrame with the aggregation added as a new column. |
### get_aggregation
```
get_aggregation(
intervals: IntervalIndex,
method: IntervalAggregationMethod,
) -> Series
```
Fetch tag aggregation values for the given intervals
Parameters:
| Name | Type | Description | Default |
| ----------- | --------------------------- | ----------------------------------------------- | ---------- |
| `intervals` | `IntervalIndex` | Intervals over which to aggregate the tag. | *required* |
| `method` | `IntervalAggregationMethod` | Aggregation method to apply over each interval. | *required* |
Returns:
| Type | Description |
| -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `Series` | Aggregation results aligned to the input index. float64 for numeric tags, category for digital tags, string for string tags. |
### get_data
```
get_data(interval: Interval, freq: Timedelta) -> Series
```
Retrieve interpolated time series data for the tag
Parameters:
| Name | Type | Description | Default |
| ---------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `interval` | `Interval` | Time interval for which the data needs to be retrieved. The interval.closed attribute is taken into account when returning datapoints. | *required* |
| `freq` | `Timedelta` | Data resolution. Time between subsequent datapoints. | *required* |
Returns:
| Name | Type | Description |
| ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data` | `Series` | Tag data with the following properties: - name is equal to the tag name - index is a DatetimeIndex in the client timezone. - dtype is float64 for numeric tags, category for digital tags, string for string tags. |
Notes
Data is obtained from linear interpolation of the indexed data in TrendMiner. Asking for a high resolution data will not perform a datasource call to obtain datapoints that are not in the index.
Any tag time shift will be taken into account: the returned data will be for the shifted tag.
The returned timestamps result from the interval start time (interval.left) and the provided frequency. If the interval start time is irregular, the resulting timestamps will also be irregular (e.g., 9:15:17.032, 19:15:47.032, ...). If regular intervals are required, it is the user's responsibility to provide a regular (rounded) input interval.
A call to get TrendMiner data does not automatically trigger indexing of the tag. It is up to the user to ensure the tag is indexed for the required period prior to requesting the data (cfr. Tag.index).
If an analog tag is not fully indexed for the requested interval, NaN values will be present for the interval. For stepped tags (discrete, digital and string), the values up to the current timestamp will be forward filled, and only timestamps after the current time will be NaN (discrete) or NA (digital, string).
### search_state_labels
```
search_state_labels(
name: str | None = None, page: int = 0, size: int = 2000
) -> PagedDict[int, str]
```
Get state index to state name mapping for selected states
Parameters:
| Name | Type | Description | Default |
| ------ | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `name` | `str` | The name of the state label to search for. Can use '\*' as wildcard. By default, all state labels are returned. | `None` |
| `page` | `int` | Page number of results to return. By default, start at the first page of results (0-indexed). | `0` |
| `size` | `int` | Number of results to return per page. Default is set to 2000, which is the maximum size supported by the API. Set a smaller size for exploratory purposes. | `2000` |
Returns:
| Type | Description |
| --------------------- | ---------------------------------------------------------------------------------------------- |
| `PagedDict[int, str]` | Paginated mapping of state indices to state names for the states matching the search criteria. |
### index
```
index() -> IndexDetails
```
Trigger indexing of the tag in TrendMiner
This method triggers indexing of the tag in TrendMiner. Indexing is required to obtain data for a tag, but it is not automatically triggered when requesting data. It is up to the user to ensure the tag is indexed for the required period prior to requesting the data.
Returns:
| Name | Type | Description |
| --------------- | -------------- | ---------------------------------------------------------------------------- |
| `index_details` | `IndexDetails` | The indexing details of the tag in TrendMiner after triggering the indexing. |
### delete_index
```
delete_index() -> None
```
Delete the tag index in TrendMiner
This method fully deletes the tag index in TrendMiner.
### refresh_index
```
refresh_index() -> None
```
Refresh the tag index in TrendMiner
This method sends a request to refresh the tag index in TrendMiner, which fully removes the existing index and triggers a new indexing process, fully refreshing the index data.
### get_index_details
```
get_index_details() -> IndexDetails | None
```
Get the indexing status of the tag in TrendMiner
Returns:
| Name | Type | Description |
| -------- | ---------------------- | ------------------------------------------------------------------------------------------ |
| `status` | `IndexDetails or None` | The indexing status of the tag in TrendMiner. If the tag is not indexed, None is returned. |
## trendminer_interface.objects.TagImport
Wrapper around an imported tag
### identifier
```
identifier: str
```
The identifier of the import itself (not the imported tag)
### tag
```
tag: Tag
```
The imported tag
### created_at
```
created_at: Timestamp
```
Timestamp on which the tag was imported
### delete
```
delete() -> None
```
Permanently remove the imported tag (blocking the tag name for future imports)
Notes
Deleting an imported tag is typically not desirable as you will not be able to use this tag name for future imports. A non-deleted imported tag can simply be overwritten by performing a new import with the same tag name.
## trendminer_interface.objects.TextTile
Bases: `TileBase[TextTileConfiguration]`
Dashboard text tile
Attributes:
| Name | Type | Description |
| --------- | ----------------- | --------------------------------------- |
| `content` | `(str, optional)` | The text content to display in the tile |
### position
```
position: tuple[int, int, int, int]
```
### title
```
title: str
```
### config
```
config: TConfig
```
### content
```
content: str | None
```
## trendminer_interface.objects.TextTileConfiguration
Configuration for text tile
Attributes:
| Name | Type | Description |
| ------------ | ------ | ------------------------------ |
| `show_title` | `bool` | Whether to show the tile title |
### show_title
```
show_title: bool
```
## trendminer_interface.objects.TrendHubEntryGroup
A grouping of two or more tags and/or attributes in TrendHub
Attributes:
| Name | Type | Description |
| ---------- | --------------------- | ----------------------------------------- |
| `entries` | \`list\[Tag | Attribute\]\` |
| `name` | `str` | Name of the group. Displayed in TrendHub. |
| `scale` | \`tuple[float, float] | None\` |
| `accuracy` | \`float | None\` |
### entries
```
entries: list[Tag | Attribute] = entries
```
### name
```
name: str = name
```
### scale
```
scale: tuple[float, float] | None = scale
```
### accuracy
```
accuracy: float | None = accuracy
```
## trendminer_interface.objects.TrendHubLayer
Configuration for a TrendHub layer
A layer itself does not directly specify a time interval. What time interval a layer refers to is determined by the properties (live, locked) of the TrendHub view it is attached to.
Attributes:
| Name | Type | Description |
| ------------------- | ----------- | ---------------------------------------- |
| `name` | `str` | Name of the layer, displayed in TrendHub |
| `hidden_references` | \`list\[Tag | Attribute\]\` |
### name
```
name: str = name
```
### hidden_references
```
hidden_references: list[Tag | Attribute] = hidden_references
```
### stored_interval
```
stored_interval: Interval
```
The interval as configured when the view was saved.
This is NOT the interval currently represented by the layer for live views. The stored interval does not update.
### base
```
base: bool
```
Whether the layer is a base layer or an additional layer
### line_style
```
line_style: LineStyle
```
The line style of the layer
### visible
```
visible: bool
```
Whether the layer is visible in the view
## trendminer_interface.objects.TrendHubView
Bases: `SavedItemBase`
Trend hub view work organizer object
Attributes:
| Name | Type | Description |
| ------------ | ------------------------ | ----------------------------------------------------------------------- |
| `definition` | `TrendHubViewDefinition` | Definition of the trend hub view, containing all configuration details. |
### name
```
name: str = name
```
### description
```
description: str = description
```
### folder
```
folder: Folder | None = folder
```
### identifier
```
identifier: str
```
UUID of the saved object
### created_at
```
created_at: Timestamp | None
```
Timestamp the object was created at
Can be None for items created before item creation date tracking was implemented in TrendMiner.
### last_modified
```
last_modified: Timestamp
```
Timestamp the object was last modified
### last_used
```
last_used: Timestamp
```
Timestamp the object was last used
### last_modified_by
```
last_modified_by: User
```
User that last modified the object
### owner
```
owner: User
```
User that owns the object
### shared
```
shared: bool
```
Whether the object is shared with other users
### favorite
```
favorite: bool
```
Whether the object is marked as a favorite by the owner
### version
```
version: int
```
Version number of the object, incremented on each modification
### definition
```
definition: TrendHubViewDefinition
```
### url
```
url: str
```
Direct link to the saved view
### update
```
update() -> Self
```
Update the saved item in TrendMiner to match the current instance state
### delete
```
delete() -> None
```
Permanently delete the saved item in TrendMiner
### move
```
move(folder: Folder) -> None
```
Move the item to a folder
Parameters:
| Name | Type | Description | Default |
| -------- | -------- | ------------------------------ | ---------- |
| `folder` | `Folder` | The folder to move the item to | *required* |
Notes
Moving an item to another user's folder will not transfer the ownership and may lead to unexpected behavior. Use the client.work.transfer method instead.
### get_folder_path
```
get_folder_path(include_home=False) -> list[Folder]
```
Get the location in the work organizer
Starts from, but does not include, the user's home folder. Does not include the object itself.
Parameters:
| Name | Type | Description | Default |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `include_home` | `bool` | Whether to include the user's home folder as the first element of the returned list. If False (default), the list starts from the first folder after the home folder. | `False` |
Returns:
| Type | Description |
| -------------- | --------------------------------------- |
| `list[Folder]` | List of folders leading up to this item |
### get_permissions
```
get_permissions() -> list[
tuple[User | UserGroup, WorkSharePermission]
]
```
Get the sharing settings of the object
Returns:
| Name | Type | Description |
| --------- | ------------------- | ------------------------------------ |
| `sharing` | \`list\[tuple\[User | UserGroup, WorkSharePermission\]\]\` |
### add_permission
```
add_permission(
subject: User | UserGroup,
permission: WorkSharePermission,
) -> Self
```
Share the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| ------------ | ------------------- | ----------------------------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to share the object with | *required* |
| `permission` | `str` | The permission to share with. Can be "read", "write", or "manage" | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `self` | `SavedItemBase` | The object itself, after being shared with the user or user group. Practically, only the shared property may have changed. |
### remove_permission
```
remove_permission(subject: User | UserGroup) -> Self
```
Remove sharing of the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| --------- | ------------------- | --------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to remove sharing with | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `self` | `SavedItemBase` | The object itself, after removing sharing with the user or user group. Practically, only the shared property may have changed. |
### get_data
```
get_data(freq: Timedelta) -> list[DataFrame]
```
Retrieve interpolated timeseries data for underlying tags
Parameters:
| Name | Type | Description | Default |
| ------ | ----------- | ---------------- | ---------- |
| `freq` | `Timedelta` | Data resolution. | *required* |
Returns:
| Type | Description |
| ----------------- | ----------------------------------------------------------------------- |
| `list[DataFrame]` | A dataframe with DatetimeIndex and tag names as columns for every layer |
Notes
- Any tag time shift will be taken into account: the returned data will be for the shifted tag.
- A call to get TrendMiner data does not automatically trigger indexing of the tag. It is up to the user to ensure the tag is indexed for the required period prior to requesting the data (cfr. Tag.index).
## trendminer_interface.objects.TrendHubViewTile
Bases: `TileBase[TrendHubViewTileConfiguration]`
TrendHub view tile
Attributes:
| Name | Type | Description |
| -------------- | ---------------------- | --------------------------------------------------------- |
| `view` | `TrendHubView` | The TrendHub view to display |
| `mode` | `TrendHubViewTileMode` | The display mode of the TrendHub view |
| `refresh_rate` | `Timedelta` | How often the tile is refreshed if the dashboard is live. |
### position
```
position: tuple[int, int, int, int]
```
### title
```
title: str
```
### config
```
config: TConfig
```
### view
```
view: TrendHubView
```
### mode
```
mode: TrendHubViewTileMode
```
### refresh_rate
```
refresh_rate: Timedelta
```
## trendminer_interface.objects.TrendHubViewTileConfiguration
Configuration for TrendHub view tile
Attributes:
| Name | Type | Description |
| ---------------------- | ------ | -------------------------------------------------------------- |
| `show_title` | `bool` | Whether to show tile title |
| `show_context_items` | `bool` | Whether to show context items on the view |
| `show_timeframe` | `bool` | Whether to show the timeframe of the view |
| `show_component_names` | `bool` | Whether to show the component names as labels |
| `show_legend` | `bool` | Whether to show the point color legend for a scatter plot view |
### show_title
```
show_title: bool
```
### show_context_items
```
show_context_items: bool
```
### show_timeframe
```
show_timeframe: bool
```
### show_component_names
```
show_component_names: bool
```
### show_legend
```
show_legend: bool
```
## trendminer_interface.objects.User
A natural user or a service account
### identifier
```
identifier: str
```
Identifier of the user
### name
```
name: str
```
Username
### first_name
```
first_name: str | None
```
First name of the user
None for service accounts
### last_name
```
last_name: str | None
```
Last name of the user
None for service accounts
### mail
```
mail: str | None
```
Email address of the user
None for service accounts
### groups
```
groups: list[UserGroup]
```
User groups the user belongs to
### created_at
```
created_at: Timestamp
```
User creation timestamp
### roles
```
roles: list[str]
```
List of user roles
## trendminer_interface.objects.UserGroup
A user group in TrendMiner
### identifier
```
identifier: str
```
Identifier of the user group
### name
```
name: str
```
Name of the user group
## trendminer_interface.objects.ValueBasedSearch
Bases: `BaseSearch`
Value based search work organizer object
### name
```
name: str = name
```
### description
```
description: str = description
```
### folder
```
folder: Folder | None = folder
```
### identifier
```
identifier: str
```
UUID of the saved object
### created_at
```
created_at: Timestamp | None
```
Timestamp the object was created at
Can be None for items created before item creation date tracking was implemented in TrendMiner.
### last_modified
```
last_modified: Timestamp
```
Timestamp the object was last modified
### last_used
```
last_used: Timestamp
```
Timestamp the object was last used
### last_modified_by
```
last_modified_by: User
```
User that last modified the object
### owner
```
owner: User
```
User that owns the object
### shared
```
shared: bool
```
Whether the object is shared with other users
### favorite
```
favorite: bool
```
Whether the object is marked as a favorite by the owner
### version
```
version: int
```
Version number of the object, incremented on each modification
### definition
```
definition: ValueBasedSearchDefinition
```
### update
```
update() -> Self
```
Update the saved item in TrendMiner to match the current instance state
### delete
```
delete() -> None
```
Permanently delete the saved item in TrendMiner
### move
```
move(folder: Folder) -> None
```
Move the item to a folder
Parameters:
| Name | Type | Description | Default |
| -------- | -------- | ------------------------------ | ---------- |
| `folder` | `Folder` | The folder to move the item to | *required* |
Notes
Moving an item to another user's folder will not transfer the ownership and may lead to unexpected behavior. Use the client.work.transfer method instead.
### get_folder_path
```
get_folder_path(include_home=False) -> list[Folder]
```
Get the location in the work organizer
Starts from, but does not include, the user's home folder. Does not include the object itself.
Parameters:
| Name | Type | Description | Default |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `include_home` | `bool` | Whether to include the user's home folder as the first element of the returned list. If False (default), the list starts from the first folder after the home folder. | `False` |
Returns:
| Type | Description |
| -------------- | --------------------------------------- |
| `list[Folder]` | List of folders leading up to this item |
### get_permissions
```
get_permissions() -> list[
tuple[User | UserGroup, WorkSharePermission]
]
```
Get the sharing settings of the object
Returns:
| Name | Type | Description |
| --------- | ------------------- | ------------------------------------ |
| `sharing` | \`list\[tuple\[User | UserGroup, WorkSharePermission\]\]\` |
### add_permission
```
add_permission(
subject: User | UserGroup,
permission: WorkSharePermission,
) -> Self
```
Share the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| ------------ | ------------------- | ----------------------------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to share the object with | *required* |
| `permission` | `str` | The permission to share with. Can be "read", "write", or "manage" | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `self` | `SavedItemBase` | The object itself, after being shared with the user or user group. Practically, only the shared property may have changed. |
### remove_permission
```
remove_permission(subject: User | UserGroup) -> Self
```
Remove sharing of the object with a user or user group
Parameters:
| Name | Type | Description | Default |
| --------- | ------------------- | --------------------------------------------- | ---------- |
| `subject` | `User or UserGroup` | The user or user group to remove sharing with | *required* |
Returns:
| Name | Type | Description |
| ------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `self` | `SavedItemBase` | The object itself, after removing sharing with the user or user group. Practically, only the shared property may have changed. |
### get_monitor
```
get_monitor() -> Monitor
```
Get the monitor corresponding to the item
### get_results
```
get_results(
target: Interval[Timestamp] | DataFrame,
drop: bool = True,
page: int = 0,
size: int = 10000,
) -> PagedDataFrame
```
Perform a search based on the definition
Parameters:
| Name | Type | Description | Default |
| -------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `target` | `Interval or DataFrame` | The input intervals to search for. Can be either a single pandas Interval or a DataFrame with IntervalIndex containing non-overlapping intervals. The closed property of the target will be retained in the search results. | *required* |
| `drop` | `bool` | Whether to drop the original interval columns from the resulting DataFrame, by default True. If False, the original interval in which each search result was found will be kept as a column in the resulting DataFrame. For a pd.Interval input, the name of this column will be search_interval. For a DataFrame input, the name of the original IntervalIndex will be kept. | `True` |
| `page` | `int` | The page number of results to retrieve. Default is 0 (the first page). | `0` |
| `size` | `int` | The number of results to include in each page. Default is 10000. | `10000` |
Returns:
| Type | Description |
| ---------------- | ----------------------------------------------------------------------------------------------------- |
| `PagedDataFrame` | Page containing DataFrame with IntervalIndex and columns corresponding to the calculations specified. |
Raises:
| Type | Description |
| ------------ | ------------------------------------------------------------------------------------------------- |
| `ValueError` | If target is neither a pandas Interval nor a pandas DataFrame, or if the input intervals overlap. |
Notes
Any columns already present in an input DataFrame will be kept. Their values will be mapped to the search results based on the intervals in which the search results were found.
## trendminer_interface.objects.WebhookMonitorNotification
Monitor webhook notification
Attributes:
| Name | Type | Description |
| ------------ | ----------------------- | -------------------------------------- |
| `enabled` | `bool` | Whether the notification is enabled |
| `enabled_at` | `(Timestamp, optional)` | What time the notification was enabled |
| `url` | `str` | The webhook URL |
### enabled
```
enabled: bool = enabled
```
### url
```
url: str = url
```
### enabled_at
```
enabled_at: Timestamp | None
```
The timestamp the notification was enabled
# API — definitions
## trendminer_interface.objects.tag_builder.aggregation.AggregationDefinition
Definition for tag builder aggregation
Attributes:
| Name | Type | Description |
| ---------- | ------------------------ | ------------------------------------------- |
| `target` | `Tag` | The tag that is aggregated |
| `method` | `TagAggregationMethod` | Method by which to aggregate the target tag |
| `position` | `TagAggregationPosition` | Position on which to aggregate the tag |
| `window` | `Timedelta` | Aggregation window |
| `units` | `str or None` | Units of the resulting aggregation tag. |
### target
```
target: Tag = target
```
### method
```
method: TagAggregationMethod = method
```
### position
```
position: TagAggregationPosition = position
```
### window
```
window: Timedelta = window
```
### units
```
units: str | None = units
```
## trendminer_interface.objects.search.area_search.AreaSearchDefinition
Definition for an area search
## trendminer_interface.objects.context.contexthub_view.ContextHubViewDefinition
Bases: `BaseSearchDefinition`
Definition for a context item search
Attributes:
| Name | Type | Description |
| ----------- | --------------------- | ------------------------------------------- |
| `filters` | `list[ContextFilter]` | Context item filters to apply to the search |
| `view_type` | `ContextHubViewType` | The type of view (grid, gantt, scatter) |
### calculations
```
calculations: dict[str, SearchCalculation]
```
### filters
```
filters: list[ContextFilter] = filters
```
### view_type
```
view_type: ContextHubViewType = view_type
```
### get_items
```
get_items(size: int = 10000) -> PagedDataFrame
```
Retrieve all context items matching the ContextHub view definition filters
Parameters:
| Name | Type | Description | Default |
| ------ | ----- | -------------------------------------------------------- | ------- |
| `size` | `int` | The number of items to return per page, by default 10000 | `10000` |
Returns:
| Type | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PagedDataFrame` | PageDataFrame with a DataFrame data attribute with the following structure: Index: The index will be pandas.IntervalIndex, with index.left and index.right timestamps of the context item start and end events, respectively. If a context item only has a single timestamp (i.e., when its type does not have an associated context workflow), index.left and index.right will be identical. For open context item, index.right will be the current time. Metadata columns: - open (bool): whether the context item is still open (i.e., has no end event yet) - key (str): short key - identifier (str): uuid - identifier_external (str): optional identifier by which the item is linked to an external system - description (str): optional description - type (object, ContextType): context item type - component (object, Tag or Asset or Attribute): component the item is linked to - keywords (list[str]): list of keywords linked to the item - created_by (object, User): user that created the item - created_at (datetime64[us, client timezone]): creation date - last_modified: (datetime64[us, client timezone]): last modified date Field columns: There will be a column for every unique field. Values will be float or str. The column name will be the unique field key (not the field name!) If the field is not present on some of the items, the corresponding values will be nan. Note that for context items that were created by monitors, the following metadata fields will be present (but hidden in the TrendMiner UI): - tm_monitor_id (str): Monitor.identifier short ID - tm_search_id (str): SearchBase.identifier UUID - tm_search_type (str): 'valuebased', 'similarity', ... Event columns: All context item events besides of the start and end events will be added as datetime64[ns, client timezone] columns, with the event name as the column name. |
Notes
Context items linked to multiple components are not supported. Only the first component will be returned.
Duplicate column names can occur when a certain event state occurs more than once, or when there is an overlap between field keys, state names and/or metadata column names. It is advised to avoid this situation as this will complicate processing of the resulting DataFrame.
### delete_items
```
delete_items() -> None
```
Delete context items based on the definition filters
### get_results
```
get_results(
target: Interval[Timestamp] | DataFrame,
drop: bool = True,
page: int = 0,
size: int = 10000,
) -> PagedDataFrame
```
Perform a search based on the definition
Parameters:
| Name | Type | Description | Default |
| -------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `target` | `Interval or DataFrame` | The input intervals to search for. Can be either a single pandas Interval or a DataFrame with IntervalIndex containing non-overlapping intervals. The closed property of the target will be retained in the search results. | *required* |
| `drop` | `bool` | Whether to drop the original interval columns from the resulting DataFrame, by default True. If False, the original interval in which each search result was found will be kept as a column in the resulting DataFrame. For a pd.Interval input, the name of this column will be search_interval. For a DataFrame input, the name of the original IntervalIndex will be kept. | `True` |
| `page` | `int` | The page number of results to retrieve. Default is 0 (the first page). | `0` |
| `size` | `int` | The number of results to include in each page. Default is 10000. | `10000` |
Returns:
| Type | Description |
| ---------------- | ----------------------------------------------------------------------------------------------------- |
| `PagedDataFrame` | Page containing DataFrame with IntervalIndex and columns corresponding to the calculations specified. |
Raises:
| Type | Description |
| ------------ | ------------------------------------------------------------------------------------------------- |
| `ValueError` | If target is neither a pandas Interval nor a pandas DataFrame, or if the input intervals overlap. |
Notes
Any columns already present in an input DataFrame will be kept. Their values will be mapped to the search results based on the intervals in which the search results were found.
## trendminer_interface.objects.tag_builder.custom_calculation.CustomCalculationDefinition
Definition for a tag builder custom calculation
Attributes:
| Name | Type | Description |
| -------------- | ---------------- | ------------------------------------------------------------------------- |
| `script` | `str` | The custom calculation Python script as a string. |
| `dependencies` | `list[Tag]` | The dependency tags that are referenced in the custom calculation script. |
| `tag_type` | `NumericTagType` | The type of the resulting custom calculation tag. |
| `units` | `str or None` | Units of the resulting custom calculation tag. |
### script
```
script: str = script
```
### dependencies
```
dependencies: list[Tag] = dependencies
```
### tag_type
```
tag_type: NumericTagType = tag_type
```
### units
```
units: str | None = units
```
## trendminer_interface.objects.DashboardDefinition
Dashboard definition
Attributes:
| Name | Type | Description |
| ---------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `tiles` | `list` | Tiles that are on the dashboard |
| `live` | `bool` | Whether the dashboard is updating live |
| `global_timeframe` | `dict` | Global timeframe configuration for the dashboard. Currently configured as a raw dictionary. Setting/editing the global timeframe is not yet supported. |
| `chart_aliases` | \`dict\[Tag | Attribute, str\]\` |
| `dynamic_font_sizing` | `bool` | Whether dynamic font sizing is enabled |
| `override_tile_config` | `bool` | Whether the dashboard configuration overrides individual tile settings |
| `config` | `DashboardConfiguration` | Dashboard configuration settings |
| `scrollable` | `bool` | Whether the dashboard is scrollable. Should be True for new dashboards. Exists for backwards compatibility. |
### tiles
```
tiles = tiles
```
### live
```
live = live
```
### global_timeframe
```
global_timeframe = global_timeframe
```
### dynamic_font_sizing
```
dynamic_font_sizing = dynamic_font_sizing
```
### override_tile_config
```
override_tile_config = override_tile_config
```
### config
```
config = config
```
### scrollable
```
scrollable = scrollable
```
### chart_aliases
```
chart_aliases = chart_aliases
```
## trendminer_interface.objects.search.digital_step_search.DigitalStepSearchDefinition
Definition for a digital step search
## trendminer_interface.objects.filter.\_filter.FilterDefinition
Definition for a filter
Attributes:
| Name | Type | Description |
| ----------- | --------------- | --------------------- |
| `condition` | \`IntervalIndex | tuple[Search, bool]\` |
### condition
```
condition = condition
```
## trendminer_interface.objects.fingerprint.\_fingerprint.FingerprintDefinition
Definition for a fingerprint
Attributes:
| Name | Type | Description |
| --------- | ------------------------ | ------------------------------------------- |
| `entries` | \`list\[Tag | Attribute\]\` |
| `layers` | `list[FingerprintLayer]` | List of layers included in the fingerprint. |
### entries
```
entries: list[Attribute | Tag] = entries
```
### layers
```
layers: list[FingerprintLayer] = layers
```
## trendminer_interface.objects.tag_builder.formula.FormulaDefinition
Definition for a tag builder formula
Attributes:
| Name | Type | Description |
| --------- | ---------------- | ------------------------------------------------------------------------ |
| `formula` | `str` | The formula as a string, using the variable names defined in the mapping |
| `mapping` | `dict[str, Tag]` | Mapping of variable names used in the formula to Tag objects |
| `units` | `str or None` | Units of the resulting formula tag. |
### formula
```
formula: str = formula
```
### mapping
```
mapping: dict[str, Tag] = mapping
```
### units
```
units: str | None = units
```
## trendminer_interface.objects.tag_builder.machine_learning_model.MachineLearningModelDefinition
Definition for a tag builder machine learning model
## trendminer_interface.objects.notebook.\_notebook.NotebookDefinition
Definition for a notebook
## trendminer_interface.objects.notebook.pipeline.PipelineDefinition
Definition for a pipeline
## trendminer_interface.objects.tag_builder.prediction.PredictionDefinition
Definition for a tag builder prediction
The prediction definition is the outcome of a workflow in TrendMiner. Most attributes cannot be directly edited by the user.
Attributes:
| Name | Type | Description |
| ------- | ------------- | -------------------------------------- |
| `units` | `str or None` | Units of the resulting prediction tag. |
### units
```
units = units
```
### formula
```
formula: str
```
The prediction formula
### target
```
target: Tag
```
The target tag predicted by linear regression
### mapping
```
mapping: dict[str, tuple[Tag, float]]
```
The linear regression formula variables mapping to a tag and its coefficient
### intercept
```
intercept: float
```
The linear regression intercept
### interval
```
interval: Interval
```
The interval on which the prediction was calculated
### accuracy
```
accuracy: float
```
The accuracy of the prediction (0-100) for the calculation interval
### calculated_at
```
calculated_at: Timestamp
```
The timestamp on which the prediction was calculated
## trendminer_interface.objects.search.similarity_search.SimilaritySearchDefinition
Definition for a similarity search
## trendminer_interface.objects.trend.trendhub_view.TrendHubViewDefinition
Definition for a trend hub view
Attributes:
| Name | Type | Description |
| --------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| `entries` | `list[TrendHubEntry]` | List of entries (tags, attributes, groups) included in the view |
| `layers` | `list[TrendHubLayer]` | List of layers included in the view |
| `context_interval` | `Interval` | Context interval of the view |
| `chart_properties` | `ChartProperties` | Chart configuration |
| `filter_entries` | `list[tuple[Filter, bool]]` | List of filters included in the view, with their active state |
| `fingerprint_entries` | `list[tuple[Fingerprint, bool, Interval]]` | List of fingerprints included in the view, with their active state and interval to which they apply |
Notes
- fingerprint_entries and filter_entries may reference saved items which no longer exist. Attempting to access the attributes of these items will result in a ResourceNotFound error.
- Statistics and layer comparison table formats are currently not configurable
### entries
```
entries: list[TrendHubEntry] = entries
```
### layers
```
layers: list[TrendHubLayer] = layers
```
### context_interval
```
context_interval: Interval = context_interval
```
### chart_properties
```
chart_properties: ChartProperties = chart_properties
```
### filter_entries
```
filter_entries: list[tuple[Filter, bool]] = filter_entries
```
### fingerprint_entries
```
fingerprint_entries: list[
tuple[Fingerprint, bool, Interval]
] = fingerprint_entries
```
### live
```
live = live
```
### base_layer
```
base_layer: TrendHubLayer
```
The view's base layer
### intervals
```
intervals: IntervalIndex
```
Get the Intervals currently represented by the view layers
This accounts for view live mode and chart lock settings
### generate_url
```
generate_url() -> str
```
Generate a unique link to the defined view in TrendHub
Returns:
| Type | Description |
| ----- | ---------------------------- |
| `str` | Link to the view in TrendHub |
### get_data
```
get_data(freq: Timedelta) -> list[DataFrame]
```
Retrieve interpolated timeseries data for underlying tags
Parameters:
| Name | Type | Description | Default |
| ------ | ----------- | ---------------- | ---------- |
| `freq` | `Timedelta` | Data resolution. | *required* |
Returns:
| Type | Description |
| ----------------- | ----------------------------------------------------------------------- |
| `list[DataFrame]` | A dataframe with DatetimeIndex and tag names as columns for every layer |
Notes
- Any tag time shift will be taken into account: the returned data will be for the shifted tag.
- A call to get TrendMiner data does not automatically trigger indexing of the tag. It is up to the user to ensure the tag is indexed for the required period prior to requesting the data (cfr. Tag.index).
## trendminer_interface.objects.search.value_based_search.ValueBasedSearchDefinition
Bases: `BaseSearchDefinition`
Definition for a value based search
Attributes:
| Name | Type | Description |
| ---------- | ----------------------------- | -------------------------------------------------------------------------- |
| `queries` | `list[ValueBasedSearchQuery]` | Search query tuples. |
| `duration` | `Timedelta` | Duration of the search. |
| `operator` | `{'and', 'or'}` | How the queries are combined ("and": all must match; "or": any may match). |
### queries
```
queries: list[ValueBasedSearchQuery] = queries
```
### duration
```
duration: Timedelta = duration
```
### operator
```
operator: ValueBasedSearchMode = mode
```
### calculations
```
calculations: dict[str, SearchCalculation] = calculations
```
### get_results
```
get_results(
target: Interval[Timestamp] | DataFrame,
drop: bool = True,
page: int = 0,
size: int = 10000,
) -> PagedDataFrame
```
Perform a search based on the definition
Parameters:
| Name | Type | Description | Default |
| -------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `target` | `Interval or DataFrame` | The input intervals to search for. Can be either a single pandas Interval or a DataFrame with IntervalIndex containing non-overlapping intervals. The closed property of the target will be retained in the search results. | *required* |
| `drop` | `bool` | Whether to drop the original interval columns from the resulting DataFrame, by default True. If False, the original interval in which each search result was found will be kept as a column in the resulting DataFrame. For a pd.Interval input, the name of this column will be search_interval. For a DataFrame input, the name of the original IntervalIndex will be kept. | `True` |
| `page` | `int` | The page number of results to retrieve. Default is 0 (the first page). | `0` |
| `size` | `int` | The number of results to include in each page. Default is 10000. | `10000` |
Returns:
| Type | Description |
| ---------------- | ----------------------------------------------------------------------------------------------------- |
| `PagedDataFrame` | Page containing DataFrame with IntervalIndex and columns corresponding to the calculations specified. |
Raises:
| Type | Description |
| ------------ | ------------------------------------------------------------------------------------------------- |
| `ValueError` | If target is neither a pandas Interval nor a pandas DataFrame, or if the input intervals overlap. |
Notes
Any columns already present in an input DataFrame will be kept. Their values will be mapped to the search results based on the intervals in which the search results were found.
# API — containers & aliases
## trendminer_interface.\_services.PagedDataFrame
Paginated DataFrame of search results
### has_next
```
has_next: bool
```
Whether there is a next page of results available
### page_number
```
page_number: int
```
The current page number (0-indexed)
### size
```
size: int
```
The requested number of items per page. Not necessarily the same as the actual number of items on the page
### data
```
data: DataFrame
```
The content of the current result page.
### total_elements
```
total_elements: int | None
```
The total number of elements across all pages
Not available for context items.
### total_pages
```
total_pages: int | None
```
The total number of pages
Not available for context items.
### next_page
```
next_page() -> PagedDataFrame
```
Perform a request to get the next page of results
### collect
```
collect(max_pages: int | None = 10) -> DataFrame
```
Collects all pages of results into a single DataFrame
Parameters:
| Name | Type | Description | Default |
| ----------- | ----- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `max_pages` | \`int | None\` | Maximum number of pages to collect. Default is set to 10 to prevent accidental excessive API calls. Can be set to None to collect all pages regardless of number. Must be 1 (only the current page) or higher if set. |
Returns:
| Type | Description |
| ----------- | ------------------------------------------------------------------------------ |
| `DataFrame` | A single DataFrame containing the concatenated results of all collected pages. |
## trendminer_interface.\_services.PagedDict
Bases: `Generic[K, V]`
Paginated dict of search results
### has_next
```
has_next: bool
```
Whether there is a next page of results available
### page_number
```
page_number: int
```
The current page number (0-indexed)
### size
```
size: int
```
The requested number of items per page. Not necessarily the same as the actual number of items on the page
### data
```
data: dict[K, V]
```
The content of the current result page.
### total_elements
```
total_elements: int
```
The total number of elements across all pages
### next_page
```
next_page() -> PagedDict[K, V]
```
Perform a request to get the next page of results
### collect
```
collect(max_pages: int | None = 10) -> dict[K, V]
```
Collects all pages of results into a single dict
Parameters:
| Name | Type | Description | Default |
| ----------- | ----- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `max_pages` | \`int | None\` | Maximum number of pages to collect. Default is set to 10 to prevent accidental excessive API calls. Can be set to None to collect all pages regardless of number. Must be 1 (only the current page) or higher if set. |
Returns:
| Type | Description |
| --------- | -------------------------------------------------------------------- |
| `content` | A dictionary containing the combined content of all collected pages. |
### stream
```
stream(
max_pages: int | None = 10,
) -> Iterator[tuple[K, V]]
```
Stream dict items one by one, loading new pages as needed
Parameters:
| Name | Type | Description | Default |
| ----------- | ----- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `max_pages` | \`int | None\` | Maximum number of pages to stream. Default is set to 10 to prevent accidental excessive API calls. Can be set to None to stream all pages regardless of number. Must be 1 (only the current page) or higher if set. |
Yields:
| Name | Type | Description |
| ------ | ------------- | ------------------------------------------------------- |
| `item` | `tuple[K, V]` | Each individual key-value pair from all streamed pages. |
## trendminer_interface.\_services.PagedList
Bases: `Generic[T]`
Paginated list of search results
### has_next
```
has_next: bool
```
Whether there is a next page of results available
### page_number
```
page_number: int
```
The current page number (0-indexed)
### size
```
size: int
```
The requested number of items per page. Not necessarily the same as the actual number of items on the page
### data
```
data: list[T]
```
The content of the current result page.
### total_pages
```
total_pages: int | None
```
The total number of pages
Not available for user groups
### total_elements
```
total_elements: int | None
```
The total number of elements across all pages
Not available for user groups
### next_page
```
next_page() -> PagedList[T]
```
Perform a request to get the next page of results
### collect
```
collect(max_pages: int | None = 10) -> list[T]
```
Collects all pages of results into a single list
Parameters:
| Name | Type | Description | Default |
| ----------- | ----- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `max_pages` | \`int | None\` | Maximum number of pages to collect. Default is set to 10 to prevent accidental excessive API calls. Can be set to None to collect all pages regardless of number. Must be 1 (only the current page) or higher if set. |
Returns:
| Type | Description |
| --------- | --------------------------------------------- |
| `content` | A list with the items of all collected pages. |
### stream
```
stream(max_pages: int | None = 10) -> Iterator[T]
```
Streams items one by one, loading new pages as needed
Parameters:
| Name | Type | Description | Default |
| ----------- | ----- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `max_pages` | \`int | None\` | Maximum number of pages to stream. Default is set to 10 to prevent accidental excessive API calls. Can be set to None to stream all pages regardless of number. Must be 1 (only the current page) or higher if set. |
Yields:
| Name | Type | Description |
| --------- | ---- | --------------------------------------------------------------------------- |
| `content` | `T` | Each individual item from the content of all streamed pages, one at a time. |
## trendminer_interface.types.AssetAccessPermission
```
AssetAccessPermission = Literal['read', 'browse', 'none']
```
## trendminer_interface.types.AssetFrameworkType
```
AssetFrameworkType = Literal['csv', 'datasource']
```
## trendminer_interface.types.ChartLabelType
```
ChartLabelType = Literal['alias', 'name', 'description']
```
## trendminer_interface.types.ClosedMode
```
ClosedMode = Literal['open', 'closed']
```
## trendminer_interface.types.ComponentInclusion
```
ComponentInclusion = Literal[
"self", "ancestors", "descendants"
]
```
## trendminer_interface.types.ContextFieldType
```
ContextFieldType = Literal[
"enumeration", "string", "numeric"
]
```
## trendminer_interface.objects.context.filter.ContextFilter
```
ContextFilter = Union[
ContextApprovalFilter,
ContextComponentFilter,
ContextTypeFilter,
ContextCreatedByFilter,
ContextCreationDateFilter,
ContextDescriptionFilter,
ContextDurationFilter,
ContextEnumerationFieldFilter,
ContextIntervalFilter,
ContextKeywordFilter,
ContextNumericFieldFilter,
ContextPeriodFilter,
ContextStateFilter,
ContextStringFieldFilter,
ContextPropertyFilter,
]
```
## trendminer_interface.types.ContextHubViewTileMode
```
ContextHubViewTileMode = Literal[
"table", "gantt", "scatter", "count"
]
```
## trendminer_interface.types.ContextHubViewType
```
ContextHubViewType = Literal['grid', 'gantt', 'scatter']
```
## trendminer_interface.types.ContextIntervalScope
```
ContextIntervalScope = Literal['event', 'creation date']
```
## trendminer_interface.types.ContextTypeIcon
```
ContextTypeIcon = Literal[
"alert-circle",
"arrows-round",
"bucket",
"circle-success",
"clipboard",
"cracked",
"file-check",
"flame",
"flask",
"flow-line",
"information",
"person",
"ruler",
"snowflake",
"spoon",
"trending-down",
"warning",
"waterdrops",
"waves",
"wheelbarrow",
"wrench",
]
```
## trendminer_interface.types.CreatedDateOperator
```
CreatedDateOperator = Literal['>', '>=', '<', '<=']
```
## trendminer_interface.types.CurrentValueTileCondition
```
CurrentValueTileCondition = (
CurrentValueTileNumericCondition
| CurrentValueTileRangeCondition
| CurrentValueTileTextCondition
)
```
## trendminer_interface.types.CurrentValueTileEntry
```
CurrentValueTileEntry = tuple[
Tag | Attribute,
str,
str,
list[CurrentValueTileCondition],
]
```
## trendminer_interface.types.CurrentValueTileNumericOperator
```
CurrentValueTileNumericOperator = Literal[
">", ">=", "<", "<=", "=", "!="
]
```
## trendminer_interface.types.CurrentValueTileNumericRangeOperator
```
CurrentValueTileNumericRangeOperator = Literal[
"between", "not between"
]
```
## trendminer_interface.types.CurrentValueTileTextOperator
```
CurrentValueTileTextOperator = Literal[
"=", "!=", "contains", "does not contain"
]
```
## trendminer_interface.objects.dashboard.tile.DashboardTile
```
DashboardTile = (
ContextHubViewTile
| CurrentValueTile
| DraftContextHubViewTile
| DraftCurrentValueTile
| DraftGaugeTile
| DraftMonitorTile
| DraftTrendHubViewTile
| ExternalContentTile
| GaugeTile
| MonitorTile
| NotebookTile
| TextTile
| TrendHubViewTile
)
```
## trendminer_interface.types.DurationOperator
```
DurationOperator = Literal['>', '>=', '<', '<=', '=', '!=']
```
## trendminer_interface.types.EmptyMode
```
EmptyMode = Literal['empty', 'not empty']
```
## trendminer_interface.types.GaugeTileMode
```
GaugeTileMode = Literal[
"angular", "vertical", "horizontal", "speedometer"
]
```
## trendminer_interface.types.GaugeTileRange
```
GaugeTileRange = tuple[float, float, str, str]
```
## trendminer_interface.types.ImportTagType
```
ImportTagType = Literal['analog', 'discrete', 'string']
```
## trendminer_interface.types.IntervalAggregationMethod
```
IntervalAggregationMethod = (
TagAggregationMethod | Literal["std", "start", "end"]
)
```
## trendminer_interface.types.IntervalClosedType
```
IntervalClosedType = Literal[
"left", "right", "both", "neither"
]
```
## trendminer_interface.types.IntervalRoundType
```
IntervalRoundType = Literal['shrink', 'grow', 'nearest']
```
## trendminer_interface.types.LineStyle
```
LineStyle = NonBaseLineStyle | Literal['solid']
```
## trendminer_interface.types.MonitorState
```
MonitorState = Literal[
"enabled", "disabled", "system disabled"
]
```
## trendminer_interface.types.MonitorTileCondition
```
MonitorTileCondition = tuple[ContextTypeIcon, str, str]
```
## trendminer_interface.types.NonBaseLineStyle
```
NonBaseLineStyle = Literal[
"dash",
"dot",
"dash-dot",
"dash-dot-dot",
"loose-dash-dot",
]
```
## trendminer_interface.types.NumericFieldOperator
```
NumericFieldOperator = Literal[
">", ">=", "<", "<=", "=", "!="
]
```
## trendminer_interface.types.NumericTagType
```
NumericTagType = Literal['analog', 'discrete']
```
## trendminer_interface.objects.SavedItem
```
SavedItem = (
Folder
| Aggregation
| Formula
| CustomCalculation
| Prediction
| ValueBasedSearch
| SimilaritySearch
| AreaSearch
| DigitalStepSearch
| Fingerprint
| TrendHubView
| ContextHubView
| Dashboard
| Notebook
| Pipeline
| Filter
)
```
## trendminer_interface.objects.search.Search
```
Search = (
AreaSearch
| DigitalStepSearch
| SimilaritySearch
| ValueBasedSearch
)
```
## trendminer_interface.types.SearchCalculation
```
SearchCalculation = tuple[
Tag, IntervalAggregationMethod, str
]
```
## trendminer_interface.types.TagAggregationMethod
```
TagAggregationMethod = Literal[
"mean",
"min",
"max",
"range",
"delta",
"integral per day",
"integral per hour",
"integral per minute",
"integral per second",
]
```
## trendminer_interface.types.TagAggregationPosition
```
TagAggregationPosition = Literal['start', 'center', 'end']
```
## trendminer_interface.types.TagIndexStatus
```
TagIndexStatus = Literal[
"ok",
"in progress",
"out of date",
"stale",
"incomplete",
"dormant",
]
```
## trendminer_interface.types.TagType
```
TagType = NumericTagType | Literal['digital', 'string']
```
## trendminer_interface.objects.trend.trendhub_view.TrendHubEntry
```
TrendHubEntry = Tag | Attribute | TrendHubEntryGroup
```
## trendminer_interface.types.TrendHubViewTileMode
```
TrendHubViewTileMode = Literal['plot', 'statistics table']
```
## trendminer_interface.types.ValueBasedSearchMode
```
ValueBasedSearchMode = Literal['and', 'or']
```
## trendminer_interface.types.ValueBasedSearchOperator
```
ValueBasedSearchOperator = Literal[
"=", "!=", ">", "<", ">=", "<=", "in", "constant"
]
```
## trendminer_interface.types.ValueBasedSearchQuery
```
ValueBasedSearchQuery = (
tuple[
Tag, Literal["=", "!=", ">", "<", ">=", "<="], float
]
| tuple[Tag, Literal["="], str]
| tuple[Tag, Literal["in"], list[str]]
| tuple[Tag, Literal["constant"]]
)
```
## trendminer_interface.types.WorkScope
```
WorkScope = Literal[
"my work", "shared", "favorites", "system"
]
```
## trendminer_interface.types.WorkSharePermission
```
WorkSharePermission = Literal['read', 'write', 'manage']
```
# API — exceptions
## trendminer_interface.exceptions.APIError
Bases: `TrendMinerError`
Unsuccessful REST API response
Used as base class for more specific API errors, or raised for failed response states for which no specific handling is implemented.
### response
```
response = response
```
## trendminer_interface.exceptions.AmbiguousResource
Bases: `TrendMinerError`
Two or more equally valid resources exist for given reference
This occurs when uniqueness is implicitly expected by the method, but not explicitly enforced on the appliance side. For example, when two work organizer objects have the same name, attempts to retrieve them by their name will result in this exception. It is up to the user to resolve this ambiguity on the appliance side, or use a more specific request to retrieve the correct resource (e.g., by identifier instead of name).
## trendminer_interface.exceptions.AuthenticationError
Bases: `APIError`
Authentication with the appliance failed. Raised on 401 Unauthorized response status code.
## trendminer_interface.exceptions.ConflictError
Bases: `APIError`
Attempted to create a resource which already exists, or update a resource in a way that causes a conflict
Raised on HTTP 409 responses.
## trendminer_interface.exceptions.PermissionDeniedError
Bases: `APIError`
User does not have permission to access the resource. Raised on HTTP 403 responses.
## trendminer_interface.exceptions.ResourceNotFound
Bases: `TrendMinerError`
Resource does not exist or is not accessible to the current user
Can be raised directly from the code (e.g. a results was expected from a search, but none was found), or through a 404 Not Found response from the API.
## trendminer_interface.exceptions.ServerError
Bases: `APIError`
Server error. Raised on HTTP 5xx responses.
## trendminer_interface.exceptions.TrendMinerError
Bases: `Exception`
Base class for all TrendMiner SDK exceptions.
## trendminer_interface.exceptions.ValidationError
Bases: `APIError`
Raised for 400 and 422 response status codes, indicating invalid request parameters or payload
## trendminer_interface.exceptions.VersionMismatchWarning
Bases: `UserWarning`
SDK version does not explicitly support TrendMiner version