Views

Data validation is done by the auth, data and requests modules.

Signals module

Copyright 2023 Searis AS

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

class pyclarify.views.signals.Signal(*, name: str, description: str = '', labels: Dict[pydantic.types.ConstrainedStrValue, List[str]] = {}, sourceType: pyclarify.fields.constraints.SourceTypeSignal = SourceTypeSignal.measurement, valueType: pyclarify.fields.constraints.TypeSignal = TypeSignal.numeric, engUnit: str = '', enumValues: Dict[str, str] = {}, sampleInterval: datetime.timedelta = None, gapDetection: datetime.timedelta = None, annotations: Dict[pydantic.types.ConstrainedStrValue, str] = None)

Bases: pyclarify.views.signals.SignalInfo

Model for sending Signal metadata to Clarify.

Parameters

  • name (string(len:1-128)) – A human-readable name for the resource.

  • description (string(len:0-1000)) – A free-form description of the resource.

  • labels (Labels) – A map of custom classification attributes. Filtering is done on label keys (labels.<key>).

  • sourceType (string(enum)) – Classification of the data source. The value must be “aggregate”, “measurement” or “prediction”.

  • valueType (string(enum)) – How to interpret time-series data points. The value must be “enum” or “numeric”.

  • engUnit (string) – Engineering unit for time-series data in numeric representations.

  • enumValues (map(string => string(len:1-128))) – Map of numeric values to display text in enum representations. The key must represent an integer in range 0-9999.

  • sampleInterval (Fixed Duration, null) – The expected distance between data points.

  • gapDetection (Fixed Duration, null) – The maximum distance between two data-points before considering it to be a gap.

  • annotations (Annotations) – A key-value store where integrations can store programmatic meta-data about the resource instance. Filtering is done on member fields.

Example

>>> from pyclarify import Signal

Creating a signal a minimal signal.

>>> signal = Signal(name="My new signal")

Creating a signal with all attributes set.

>>> signal = Signal(
...     name="My new signal"
...     description="This signal is an example."
...     labels={
...         "environment": ["dev", "mocking"],
...         "unit":["cloud"]
...     }
...     engUnit="℃"
...     sampleInterval="PT30S"
...     gapDetection="PT5M"
... )

Creating an enum signal.

>>> signal = Signal(
...     name="My new enum signal"
...     description="This enum signal is an example."
...     labels={
...         "environment": ["dev", "mocking"],
...         "unit":["cloud"]
...     }
...     valueType="enum"
...     enumValues={
...         "0" : "Wind",
...         "1" : "Rain",
...         "2" : "Cloudy"
...     }
...     sampleInterval="PT30S"
...     gapDetection="PT5M"
... )
annotations: Optional[Dict[pydantic.types.ConstrainedStrValue, str]]

Items module

Copyright 2023 Searis AS

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

class pyclarify.views.items.Item(*, name: str, description: str = '', labels: Dict[pydantic.types.ConstrainedStrValue, List[str]] = {}, sourceType: pyclarify.fields.constraints.SourceTypeSignal = SourceTypeSignal.measurement, valueType: pyclarify.fields.constraints.TypeSignal = TypeSignal.numeric, engUnit: str = '', enumValues: Dict[str, str] = {}, sampleInterval: datetime.timedelta = None, gapDetection: datetime.timedelta = None, visible: bool = False)

Bases: pyclarify.views.items.ItemInfo

Item model for sending Item meta data to Clarify.

Parameters

  • name (string(len:1-128)) – A human-readable name for the resource.

  • description (string(len:0-1000)) – A free-form description of the resource.

  • labels (Dict[LabelsKey, List[str]]) – A map of custom classification attributes. Filtering is done on label keys (labels.<key>). LabelsKey is alphanumeric string up to 128 chars.

  • sourceType (string(enum)) – Classification of the data source. The value must be “aggregate”, “measurement” or “prediction”.

  • valueType (string(enum)) – How to interpret time-series data points. The value must be “enum” or “numeric”.

  • engUnit (string) – Engineering unit for time-series data in numeric representations.

  • enumValues (map(string => string(len:1-128))) – Map of numeric values to display text in enum representations. The key must represent an integer in range 0-9999.

  • sampleInterval (Fixed Duration, null) – The expected distance between data points.

  • gapDetection (Fixed Duration, null) – The maximum distance between two data-points before considering it to be a gap.

  • visible (bool) – Whether the item should be visible for your entire organization within Clarify or not.

  • annotations (Dict[AnnotationKey, str]) – A key-value store where integrations can store programmatic meta-data about the resource instance. Filtering is done one member fields. AnnotationKey is alphanumeric string up to 128 chars.

Example

>>> from pyclarify import Item

Creating a minimal item.

>>> item = Item(name="My new item")

Creating a item with all attributes set.

>>> item = Item(
...     name="My new item"
...     description="This item is an example."
...     labels={
...         "environment": ["dev", "mocking"],
...         "unit":["cloud"]
...     }
...     engUnit="℃"
...     sampleInterval="PT30S"
...     gapDetection="PT5M"
... )

Creating an enum item.

>>> item = Item(
...     name="My new enum item"
...     description="This enum item is an example."
...     labels={
...         "environment": ["dev", "mocking"],
...         "unit":["cloud"]
...     }
...     valueType="enum"
...     enumValues={
...         "0" : "Wind",
...         "1" : "Rain",
...         "2" : "Cloudy"
...     }
...     sampleInterval="PT30S"
...     gapDetection="PT5M"
... )

Tip

Items are hidden by default. If you want them to be visible you can add the attribute visible and set it to True

>>> item = Item(name="My new item", visible=True)

DataFrame module

Copyright 2023 Searis AS

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

class pyclarify.views.dataframe.DataFrame(*, times: List[datetime.datetime] = None, series: Dict[pydantic.types.ConstrainedStrValue, List[Optional[Union[float, int]]]] = None)

Bases: pydantic.main.BaseModel

DataFrame structure maps to data structure used in the API for saving time series. Supports merging with other Clarify DataFrame objects and can convert to and from Pandas.DataFrame.

Parameters

  • series (Dict[InputID, List[Union[None, float, int]]]) – Map of inputid to Array of data points to insert by Input ID. The length of each array must match that of the times array. To omit a value for a given timestamp in times, use the value null.

  • times (List of timestamps) – Either as a python datetime or as YYYY-MM-DD[T]HH:MM[:SS[.ffffff]][Z or [±]HH[:]MM]]] to insert.

Example

>>> from pyclarify import DataFrame
>>> data = DataFrame(
...     series={"INPUT_ID_1": [1, 2], "INPUT_ID_2": [3, 4]},
...     times=["2021-11-01T21:50:06Z",  "2021-11-02T21:50:06Z"]
... )
classmethod convert_numpy_to_native(v)
classmethod from_dict(data)

Converts dictionary to pyclarify.DataFrame. Handles series and flat dictionaries. No need to define time column as only one time column is accepted.

classmethod from_pandas(df, time_col=None)

Convert a pandas DataFrame into a Clarify DataFrame.

Parameters

  • df (pandas.DataFrame) – The pandas.DataFrame object to cast to pyclarify.DataFrame.

  • time_col (str, default None) – A string denoting the column containing the time axis. If no string is given it is assumed to be the index of the DataFrame.

Returns

pyclarify.DataFrame

Return type

The Clarify DataFrame representing this instance.

Example

>>> from pyclarify import DataFrame
>>> import pandas as pd
>>> df = pd.DataFrame(data={"INPUT_ID_1": [1, 2], "INPUT_ID_2": [3, 4]})
>>> df.index = ["2021-11-01T21:50:06Z",  "2021-11-02T21:50:06Z"]
>>> DataFrame.from_pandas(df)
... DataFrame(
...     times=[
...         datetime.datetime(2021, 11, 1, 21, 50, 6, tzinfo=datetime.timezone.utc),
...         datetime.datetime(2021, 11, 2, 21, 50, 6, tzinfo=datetime.timezone.utc)],
...     series={
...         'INPUT_ID_1': [1.0, 2.0],
...         'INPUT_ID_2': [3.0, 4.0]
...     }
... )

With specific time column.

>>> from pyclarify import DataFrame
>>> import pandas as pd
>>> df = pd.DataFrame(data={
...     "INPUT_ID_1": [1, 2],
...     "INPUT_ID_2": [3, 4],
...     "timestamps": ["2021-11-01T21:50:06Z",  "2021-11-02T21:50:06Z"]
...})
>>> DataFrame.from_pandas(df, time_col="timestamps")
... DataFrame(
...     times=[
...         datetime.datetime(2021, 11, 1, 21, 50, 6, tzinfo=datetime.timezone.utc),
...         datetime.datetime(2021, 11, 2, 21, 50, 6, tzinfo=datetime.timezone.utc)],
...     series={
...         'INPUT_ID_1': [1.0, 2.0],
...         'INPUT_ID_2': [3.0, 4.0]
...     }
... )
classmethod merge(data_frames) → pyclarify.views.dataframe.DataFrame

Method for merging 2 or more Clarify Data Frames. Mapping overlapping signal names to single series. Concatenates timestamps of all data frames. Inserts none value to series not containing entry at a given timestamp.

Parameters

data_frames (List[DataFrame]) – A Clarify DataFrame or a list of Clarify Data_Frames

Returns

DataFrame – Merged data frame of all input data frames and self

Return type

DataFrame

Example

Merging two data frames.

>>> df1 = DataFrame(
...     series={"INPUT_ID_1": [1, 2], "INPUT_ID_2": [3, 4]},
...     times=["2021-11-01T21:50:06Z",  "2021-11-02T21:50:06Z"]
... )
>>> df2 = DataFrame(
...     series={"INPUT_ID_1": [5, 6], "INPUT_ID_3": [7, 8]},
...     times=["2021-11-01T21:50:06Z",  "2021-11-03T21:50:06Z"]
... )
>>> merged_df = DataFrame.merge([df1, df2])
>>> merged_df.to_pandas()
...                            INPUT_ID_2  INPUT_ID_1  INPUT_ID_3
... 2021-11-01 21:50:06+00:00         3.0         5.0         7.0
... 2021-11-02 21:50:06+00:00         4.0         2.0         NaN
... 2021-11-03 21:50:06+00:00         NaN         6.0         8.0

Warning

Notice from the example above that when time series have overlapping timestamps the last data frame overwrites the first.

>>> df1 = DataFrame(
...     series={"INPUT_ID_1": [1, 2]},
...     times=["2021-11-01T21:50:06Z",  "2021-11-02T21:50:06Z"]
... )
>>> df2 = DataFrame(
...     series={"INPUT_ID_1": [5, 6]},
...     times=["2021-11-01T21:50:06Z",  "2021-11-03T21:50:06Z"]
... )
>>> DataFrame.merge([df1, df2])
...                             INPUT_ID_1
... 2021-11-01 21:50:06+00:00         5.0   <--
... 2021-11-02 21:50:06+00:00         2.0
... 2021-11-03 21:50:06+00:00         6.0
>>> DataFrame.merge([df2, df1])
...                             INPUT_ID_1
... 2021-11-01 21:50:06+00:00         1.0   <--
... 2021-11-02 21:50:06+00:00         2.0
... 2021-11-03 21:50:06+00:00         6.0
series: Dict[pydantic.types.ConstrainedStrValue, List[Optional[Union[float, int]]]]
times: List[datetime.datetime]
to_pandas()

Convert the instance into a pandas DataFrame.

Returns

pandas.DataFrame

Return type

The pandas DataFrame representing this instance.

Example

>>> from pyclarify import DataFrame
>>> data = DataFrame(
...     series={"INPUT_ID_1": [1, 2], "INPUT_ID_2": [3, 4]},
...     times=["2021-11-01T21:50:06Z",  "2021-11-02T21:50:06Z"]
... )
>>> data.to_pandas()
...                            INPUT_ID_1  INPUT_ID_2
... 2021-11-01 21:50:06+00:00         1.0         3.0
... 2021-11-02 21:50:06+00:00         2.0         4.0

Evaluate module

Copyright 2023 Searis AS

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

class pyclarify.views.evaluate.Calculation(*, formula: str, alias: pydantic.types.ConstrainedStrValue)

Bases: pydantic.main.BaseModel

Model for creating a calculation to be used in evaluate endpoint.

Parameters

  • formula (str) – The formula to be applied. Current legal calculations are found here.

  • alias (string) – A short alias to use in formulas as well as in the data frame results.

Example

>>> from pyclarify import Calculation

Creating a calculation assuming we have items with aliases “i1” and “i2”.

>>> calc = Calculation(
...     formula="i1 + i2"
...     alias="c1"
... )

Creating a calculation using other calculations.

>>> calc1 = Calculation(
...     formula="i1 + i2"
...     alias="c1"
... )
>>> calc2 = Calculation(
...     formula="c1**2 + i1"
...     alias="c1"
... )
alias: pydantic.types.ConstrainedStrValue
formula: str
class pyclarify.views.evaluate.ItemAggregation(*, id: pydantic.types.ConstrainedStrValue, aggregation: pyclarify.fields.constraints.DataAggregation, state: pydantic.types.ConstrainedIntValue = None, lead: pydantic.types.ConstrainedIntValue = None, lag: pydantic.types.ConstrainedIntValue = None, alias: pydantic.types.ConstrainedStrValue)

Bases: pydantic.main.BaseModel

Model for creating item aggregations to be used in evaluate endpoint.

Parameters

  • id (ResourceID (r"^[a-v0-9]{20}$")) – The ID of the item to be aggregated.

  • aggregation (str) – The aggregation type to be done. Current legal aggregations are found here.

  • state (int[0:9999]) – The integer denoting the state to be used in the aggregation. Only necessary when using state based aggregation.

  • lead (int[-1000:1000]) – Shift buckets backwards by N.

  • lag (int[-1000:1000]) – Shift buckets forwards by N.

  • alias (string) – A short alias to use in formulas as well as in the data frame results.

Example

>>> from pyclarify import ItemAggregation

Creating a signal a minimal item aggregation.

>>> itemAgg = ItemAggregation(
...     id="cbpmaq6rpn52969vfl0g",
...     aggregation="avg",
...     alias="i2"
... )

Creating a item aggregation with all attributes set.

>>> item = ItemAggregation(
...     id="cbpmaq6rpn52969vfl00",
...     aggregation="max",
...     state=1,
...     lead=1,
...     lag=1,
...     alias="i1"
... )
aggregation: pyclarify.fields.constraints.DataAggregation
alias: pydantic.types.ConstrainedStrValue
id: pydantic.types.ConstrainedStrValue
lag: Optional[pydantic.types.ConstrainedIntValue]
lead: Optional[pydantic.types.ConstrainedIntValue]
state: Optional[pydantic.types.ConstrainedIntValue]

Filter module

Copyright 2023 Searis AS

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

class pyclarify.query.filter.DataFilter(*, gte: Optional[Union[str, datetime.datetime]] = None, lt: Optional[Union[str, datetime.datetime]] = None, series: List[str] = [])

Bases: pydantic.main.BaseModel

Pydantic model for handeling filtering. The model has a to_query() method used internally to convert model to MongoDB format.

Parameters

  • gte (string(ISO 8601 timestamp) or python datetime, optional, default <now - 7 days>) – An RFC3339 time describing the inclusive start of the window.

  • lt (string(ISO 8601 timestamp) or python datetime, optional, default <now + 7 days>) – An RFC3339 time describing the exclusive end of the window.

Example

>>> from pyclarify import query
>>> data_filter = query.DataFilter(gte='2022-08-01T16:00:20Z',lt='2022-08-02T16:00:20Z')
>>> data_filter.to_query()
... {'times': {'$gte': '2022-08-01T16:00:20Z', '$lt': '2022-08-02T16:00:20Z'}}
classmethod field_must_reflect_operator(values)
gte: Optional[Union[str, datetime.datetime]]
lt: Optional[Union[str, datetime.datetime]]
series: Optional[List[str]]
to_query()
class pyclarify.query.filter.Filter(*, and_list: List[Filter] = None, or_list: List[Filter] = None, fields: Dict[str, Union[str, pyclarify.fields.query.Comparison]] = None)

Bases: pydantic.main.BaseModel

Pydantic model for handling filtering. The filter supports pythons built in “&” and “|” operators for chaining filters. The model has a to_query() method used internally to convert model to MongoDB format.

Parameters

fields (dict[str, Comparison]) – A dictionary of the key to be filtered on and a logical comparison.

Example

>>> from pyclarify import query
>>> f1 = query.Filter(fields={"name": query.NotEqual(value="Lufttemperatur")})
>>> f2 = query.Filter(fields={"labels.unit-type": query.NotIn(value=["Flåte", "Merde 5"])})
>>> f1.to_query()
... {'name': {'$ne': 'Lufttemperatur'}}
>>> f3 = f1 & f2
>>> f3.to_query()
... {
...     '$and': [
...         {'name': {'$ne': 'Lufttemperatur'}},
...         {'labels.unit-type': {'$nin': ['Flåte', 'Merde 5']}}
...     ]
... }

  • Equal

  • NotEqual

  • Regex

  • In

  • NotIn

  • LessThan

  • Greater

  • GreaterOrEqual

and_list: Optional[List[Filter]]
field_to_query(field)
fields: Optional[Dict[str, Union[str, pyclarify.fields.query.Comparison]]]
or_list: Optional[List[Filter]]
to_query()