import_category

相関パターン抽出に用いるカテゴリ定義を登録します。

実行方式は JSON-RPC v2.0 を利用します。

リクエスト例

import_category は分析 API の一種であり、プロべナンス API の process メソッドに api_method="import_category" を指定することで実行できます。以下は、プロべナンスのセッションを開始して、import_category を実行し、セッションを終了する例です。

import json
import xdata_prov.client import Api
api = Api()
api.begin_session()

api.process(api_method="import_category", api_params={
    "output_ddc": "ddc:jartic_xrain_category",
    "category_json": json.dumps([
        { "item": "agg_jartic_max_length", "min":   10, "max":  100, "category": "cl10"   },
        { "item": "agg_jartic_max_length", "min":  100, "max":  300, "category": "cl100"  },
        { "item": "agg_jartic_max_length", "min":  300, "max":  600, "category": "cl300"  },
        { "item": "agg_xrain_max_value", "min":  0.1, "max":  1, "category": "rf01" },
        { "item": "agg_xrain_max_value", "min":  1  , "max":  5, "category": "rf1"  },
        { "item": "agg_xrain_max_value", "min":  5  , "max": 10, "category": "rf5"  }
    ])
})

api.commit()
api.end_session()

パラメータ

process メソッドを api_method="import_category" として呼び出す場合、api_params は以下のキーを含む dict を受け取ります。既定値が空欄のものは必須のパラメータとなります。

キー	説明	既定値
output_ddc	登録先 ddc
output_mode	出力モード (`overwrite` または `error`)	`error`
category_json	カテゴリ定義 (JSON 形式)

入力データ

カテゴリ定義

category_json で指定されるカテゴリ定義は、JSON オブジェクトを要素とする JSON 配列です。配列の各要素は以下のキーを持つ必要があります。

キー	型	説明
item	string	カラム名
min	number	最小値 (指定した値を含む)
max	number	最大値 (指定した値を含まない)
category	string	カテゴリ文字列

カテゴリ定義の解釈

カテゴリ定義は extract_items で利用されます。 extract_items は、入力のトランザクションの各レコードに対して、カテゴリ定義にしたがって記号情報に変換します。

変換の規則は以下のとおりです。

item で指定されたカラムの値が min 以上 max 未満のとき、category に指定された記号を出力する
min が指定されない場合は、最小値は制限なしとする
max が指定されない場合は、最大値は制限なしとする

item カラムでは、%field の形で、timestamp 型のカラムから特定のフィールドを抽出できます。たとえば start_datetime%hour と記述すると、start_datetime カラムの時間 (0 から 23) を対象に変換を適用します。具体的には、これは SQL の extract(hour from start_datetime) と解釈されます。 hour 以外にも、SQL の extract に指定可能なフィールドを記述できます。

category カラムに %value の文字列が含まれると、その部分がカラムの値に置換されます。この記法により、item で指定されるカラムが離散値を含む場合にそのままカテゴリとすることができます。

% の記法を用いたカテゴリ定義例を示します。

{ "item": "start_datetime%hour", "max": 12, "category": "am" }
- start_datetime の時間フィールドが 12 未満であれば am カテゴリを付与
{ "item": "start_datetime%dow", "category": "dow%value" }
- start_datetime の曜日をカテゴリとして付与 (日曜日: dow0 から土曜日: dow6)

出力データ

カテゴリ定義テーブル

output_ddc で指定される出力先 ddc に、「カテゴリ定義テーブル」が出力されます。このテーブルは、以下のスキーマを持ちます。

カラム名	データ型	説明
item	text	カラム名
min	double precision	最小値 (指定した値を含む)
max	double precision	最大値 (指定した値を含まない)
category	text	カテゴリ文字列

戻り値

import_category は、出力先 ddc の ddc 情報を戻します。これは、プロべナンス API の process メソッドの仕様で定められた動作です。