Functions の時系列

Functions は時系列プロパティに対する操作に対応しています。このページでは、関数で時系列プロパティを設定して使用する方法を説明します。

初期セットアップ

Functions で時系列を使用するには、オントロジーに時系列をすでに保存している必要があります。はじめるには、こちらに記載されている手順に沿って進めてください。

オントロジーに時系列を保存したら、時系列の Functions 用にコードリポジトリを作成します。このリポジトリでは、まずオントロジータイプをインポートして、これらのオントロジータイプに保存された時系列を参照できるようにします。

これで、Functions で時系列を扱う準備ができました。

Functions で時系列を扱う

Functions で時系列にアクセスするには、まずコードリポジトリにオブジェクトベースの関数を作成します。これらの関数は、オントロジーの時系列プロパティに直接アクセスできます。関数を記述したら、新しい関数を実行する方法は2つあります。ライブプレビューで関数をテストするか、関数を公開して、プラットフォーム全体のほかのアプリケーションで使用しはじめることができます。

Python 関数

データにアクセスする

Python オントロジー SDK を使用すると、時系列プロパティ（TSP）からデータポイントを pandas または Polars の DataFrame に読み込めます。

DataFrame には2列が含まれます。

Copied!
1
2
3
4
5
@function
def aircraft_altimeter_mean(aircraft: Aircraft) -> float:
    """指定されたオントロジーの航空機オブジェクトの高度計の測定値の平均を取得します。"""
    df = aircraft.altimeter.to_pandas(all_time=True)
    return df["value"].mean()

Copied!
1
2
3
4
5
@function
def aircraft_altimeter_mean(aircraft: Aircraft) -> float:
    """指定されたオントロジーの航空機オブジェクトの高度計の測定値の平均を取得します。"""
    df = aircraft.altimeter.to_polars(all_time=True)
    return df.select(pl.col("value").mean()).item()

時系列を返す

Python 関数から時系列データを返すには、timeseries_sdk ライブラリをインポートし、TimeSeries.serialize メソッドを使用して、返す DataFrame を list[bytes] 形式にします。その後、Quiver のコード関数時系列カードを使用して、このデータを可視化できます。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
import pandas as pd
from timeseries_sdk.functions.types import TimeSeries
from ontology_sdk.ontology.objects import Aircraft

@function
def sample_series() -> list[bytes]:
    df = pandas.DataFrame({
        "timestamp": [
            pd.Timestamp("2025-03-19 08:00:00"),
            pd.Timestamp("2025-03-19 09:00:00"),
            pd.Timestamp("2025-03-19 10:00:00")
        ],
        "value": [1.0, 2.0, 2.5]
    })
    return TimeSeries.serialize(df)

@function
def normalized_altimeter_rate(aircraft: Aircraft) -> list[bytes]:
    """
    航空機の高度計の時系列プロパティ（TSP）を読み込み、平滑化して変化率を計算し、
    次に変化率の絶対値の最大値で正規化します。
    """
    df = aircraft.altimeter.to_pandas(all_time=True)
    if df.empty:
        return TimeSeries.serialize(df)

    df["value"] = df["value"].rolling(window=10, min_periods=1).mean()

    time_diff_seconds = df["timestamp"].diff().dt.total_seconds()
    df["value"] = (df["value"].diff() / time_diff_seconds).fillna(0)

    max_abs_rate = df["value"].abs().max()
    if max_abs_rate > 0:
        df["value"] = df["value"] / max_abs_rate

    return TimeSeries.serialize(df)

TypeScript 関数

以降のセクションでは、一般的な TypeScript 関数の操作の例を紹介します。

最初または最後のポイントを返す

関数には時系列ポイント用の組み込みデータ型がないため、代わりに値またはタイムスタンプを返すことができます。たとえば、次の関数は機械の最新の温度を読み取ります。

Copied!
1
2
3
4
5
    @Function()
    public async getLatestTemperature(machine: MachineRoot): Promise<Double | undefined> {
        const latest = await machine.temperatureId?.getLastPointV2();
        return latest?.value;
    }

同様に、次の関数で最初の温度測定値を取得できます。

Copied!
1
2
3
4
5
    @Function()
    public async getEarliestTemperature(machine: MachineRoot): Promise<Double | undefined> {
        const earliest = await machine.temperatureId?.getFirstPointV2();
        return earliest?.value;
    }

時系列を集計する

便利な集計の1つに、ある範囲のポイントの平均を計算する方法があります。例として、ある機械の平均温度を取得する次の関数を見てみましょう。

Copied!
1
2
3
4
5
6
7
8
    @Function()
    public async getAverageTemperature(machine: MachineRoot): Promise<Double | undefined> {
        const aggregation = await machine.temperatureId?.aggregate()
            .overEntireRange()
            .mean()
            .compute();
        return aggregation?.mean!;
    }

微分する

上記の例を応用して、次の計算関数を使用すると、同じ機械の温度の平均変化も取得できます。

Copied!
1
2
3
4
5
6
7
8
9
    @Function()
    public async getAverageTemperature(machine: MachineRoot): Promise<Double | undefined> {
        const aggregation = await machine.temperatureId?.derivative()
            .aggregate()
            .overEntireRange()
            .mean()
            .compute();
        return aggregation?.mean;
    }

時間範囲を指定する

時系列には、微分以外の変換も適用できます。次の例では、タイムスタンプのパラメーターを時系列の範囲として適用する方法を示します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
    @Function()
    public async getAverageTemperatureOverRange(
        machine: MachineRoot,
        start: Timestamp,
        end: Timestamp): Promise<Double | undefined>
    {
        const latest = await machine.temperatureId?.timeRange({min: start, max: end})
            .aggregate()
            .overEntireRange()
            .mean()
            .compute();
        return latest?.mean;
    }

TypeScript V2 関数

次のセクションでは、一般的な TypeScript V2 関数の操作の例を紹介します。

時系列ポイントを読み込む

時系列プロパティのすべてのポイントをストリーミングします。範囲が指定されている場合は、指定された範囲内のポイントのみが返されます。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
import { Osdk } from "@osdk/client";
import { ObjectTypeEx } from "@ontology/sdk";
import { TimeSeriesPoint } from "@osdk/api";

function timeSeriesExample(obj: Osdk.Instance<ObjectTypeEx>) {
  //   const obj = await client(ObjectTypeEx).fetchOne("someObjectPk"); この方法でも obj を取得できます

  const allPointsPromise = obj.timeseriesProp?.getAllPoints();

  const relativeTimeRangePromise = obj.timeseriesProp?.getAllPoints({
    $before: 1, // before または after を使用できます
    $unit: "hours",
  }); // 選択肢は milliseconds, seconds, minutes, hours, days, weeks, months, years です

  const absoluteTimeRangePromise = obj.timeseriesProp?.getAllPoints({
    $startTime: "2022-08-13T12:34:56Z",
    $endTime: "2022-08-14T12:34:56Z",
  });

  const firstPointPromise = obj.timeseriesProp?.getFirstPoint();

  const lastPointPromise = obj.timeseriesProp?.getLastPoint();

  // 変数を読み込む例
  const [relativeTimeRange, firstPoint] = await Promise.all([
    relativeTimeRangePromise,
    firstPointPromise,
  ]);

  const ts: TimeSeriesPoint<number> | undefined = firstPoint;
  relativeTimeRange?.forEach((point) => {
    console.log(point.value);
    console.log(point.time); // "2022-08-13T12:34:56Z" ISO 8601 形式のタイムスタンプ文字列
  });
}