データフレーム分析ジョブAPIの作成

データフレーム分析ジョブをインスタンス化します。

リクエスト

PUT _ml/data_frame/analytics/<data_frame_analytics_id>

前提条件

次の権限が必要です：

  • クラスター: manage_ml（machine_learning_admin ビルトインロールがこの権限を付与します）
  • ソースインデックス: read, view_index_metadata
  • デスティネーションインデックス: read, create_index, manage および index

データフレーム分析ジョブは、作成時にそのジョブを作成したユーザーが持っていたロールを記憶します。ジョブを開始すると、それらの同じロールを使用して分析を実行します。セカンダリアイソリューションヘッダーを提供した場合、それらの資格情報が代わりに使用されます。

説明

このAPIは、ソースインデックスに対して分析を実行し、その結果をデスティネーションインデックスに保存するデータフレーム分析ジョブを作成します。

デスティネーションインデックスが存在しない場合、ジョブを開始すると自動的に作成されます。データフレーム分析ジョブの開始を参照してください。

回帰または分類パラメータのサブセットのみを提供した場合、ハイパーパラメータ最適化が行われます。未定義の各パラメータの値が決定されます。

パスパラメータ

  • <data_frame_analytics_id>
  • （必須、文字列）データフレーム分析ジョブの識別子。この識別子は、小文字の英数字（a-zおよび0-9）、ハイフン、アンダースコアを含むことができます。英数字で始まり、英数字で終わる必要があります。

データフレーム分析ジョブAPIの作成

データフレーム分析ジョブをインスタンス化します。

例

前処理アクションの例

以下の例は、分析の範囲を特定のフィールドに制限し、宛先インデックスで除外するフィールドを指定し、分析前にデータをフィルタリングするためのクエリを使用する方法を示しています。

Python

  1. resp = client.ml.put_data_frame_analytics(
  2.    id="model-flight-delays-pre",
  3.    source={
  4.    "index": [
  5.    "kibana_sample_data_flights"
  6.    ],
  7.    "query": {
  8.    "range": {
  9.    "DistanceKilometers": {
  10.    "gt": 0
  11.    }
  12.    }
  13.    },
  14.    "_source": {
  15.    "includes": [],
  16.    "excludes": [
  17.    "FlightDelay",
  18.    "FlightDelayType"
  19.    ]
  20.    }
  21.    },
  22.    dest={
  23.    "index": "df-flight-delays",
  24.    "results_field": "ml-results"
  25.    },
  26.    analysis={
  27.    "regression": {
  28.    "dependent_variable": "FlightDelayMin",
  29.    "training_percent": 90
  30.    }
  31.    },
  32.    analyzed_fields={
  33.    "includes": [],
  34.    "excludes": [
  35.    "FlightNum"
  36.    ]
  37.    },
  38.    model_memory_limit="100mb",
  39. )
  40. print(resp)

Js

  1. const response = await client.ml.putDataFrameAnalytics({
  2.   id: "model-flight-delays-pre",
  3.   source: {
  4.    index: ["kibana_sample_data_flights"],
  5.    query: {
  6.    range: {
  7.    DistanceKilometers: {
  8.    gt: 0,
  9.    },
  10.    },
  11.    },
  12.    _source: {
  13.    includes: [],
  14.    excludes: ["FlightDelay", "FlightDelayType"],
  15.    },
  16.   },
  17.   dest: {
  18.    index: "df-flight-delays",
  19.    results_field: "ml-results",
  20.   },
  21.   analysis: {
  22.    regression: {
  23.    dependent_variable: "FlightDelayMin",
  24.    training_percent: 90,
  25.    },
  26.   },
  27.   analyzed_fields: {
  28.    includes: [],
  29.    excludes: ["FlightNum"],
  30.   },
  31.   model_memory_limit: "100mb",
  32. });
  33. console.log(response);

コンソール

  1. PUT _ml/data_frame/analytics/model-flight-delays-pre
  2. {
  3.   "source": {
  4.    "index": [
  5.    "kibana_sample_data_flights"
  6.    ],
  7.    "query": {
  8.    "range": {
  9.    "DistanceKilometers": {
  10.    "gt": 0
  11.    }
  12.    }
  13.    },
  14.    "_source": {
  15.    "includes": [],
  16.    "excludes": [
  17.    "FlightDelay",
  18.    "FlightDelayType"
  19.    ]
  20.    }
  21.   },
  22.   "dest": {
  23.    "index": "df-flight-delays",
  24.    "results_field": "ml-results"
  25.   },
  26.   "analysis": {
  27.   "regression": {
  28.    "dependent_variable": "FlightDelayMin",
  29.    "training_percent": 90
  30.    }
  31.   },
  32.   "analyzed_fields": {
  33.    "includes": [],
  34.    "excludes": [
  35.    "FlightNum"
  36.    ]
  37.   },
  38.   "model_memory_limit": "100mb"
  39. }
分析するソースインデックス。
このクエリは、宛先インデックスに存在しない全体のドキュメントをフィルタリングします。
_source オブジェクトは、宛先インデックスに含まれるか除外されるデータセットのフィールドを定義します。
_source オブジェクトで指定されたソースインデックスのフィールドと分析結果を含む宛先インデックスを定義します。また、results_field の名前も定義します。
分析に含めるか除外するフィールドを指定します。これは、フィールドが宛先インデックスに存在するかどうかには影響せず、分析に使用されるかどうかにのみ影響します。

この例では、FlightDelay と FlightDelayType を除外フィールドとして excludes パラメータで定義しているため、ソースインデックスのすべてのフィールドが宛先インデックスに含まれています。FlightNum フィールドは宛先インデックスに含まれていますが、analyzed_fields オブジェクトの excludes パラメータで明示的に除外フィールドとして指定されているため、分析には含まれていません。

外れ値検出の例

以下の例は、loganalytics データフレーム分析ジョブを作成します。分析タイプは outlier_detection です。

Python

  1. resp = client.ml.put_data_frame_analytics(
  2.    id="loganalytics",
  3.    description="Outlier detection on log data",
  4.    source={
  5.    "index": "logdata"
  6.    },
  7.    dest={
  8.    "index": "logdata_out"
  9.    },
  10.    analysis={
  11.    "outlier_detection": {
  12.    "compute_feature_influence": True,
  13.    "outlier_fraction": 0.05,
  14.    "standardization_enabled": True
  15.    }
  16.    },
  17. )
  18. print(resp)

Js

  1. const response = await client.ml.putDataFrameAnalytics({
  2.   id: "loganalytics",
  3.   description: "Outlier detection on log data",
  4.   source: {
  5.    index: "logdata",
  6.   },
  7.   dest: {
  8.    index: "logdata_out",
  9.   },
  10.   analysis: {
  11.    outlier_detection: {
  12.    compute_feature_influence: true,
  13.    outlier_fraction: 0.05,
  14.    standardization_enabled: true,
  15.    },
  16.   },
  17. });
  18. console.log(response);

コンソール

  1. PUT _ml/data_frame/analytics/loganalytics
  2. {
  3.   "description": "Outlier detection on log data",
  4.   "source": {
  5.    "index": "logdata"
  6.   },
  7.   "dest": {
  8.    "index": "logdata_out"
  9.   },
  10.   "analysis": {
  11.    "outlier_detection": {
  12.    "compute_feature_influence": true,
  13.    "outlier_fraction": 0.05,
  14.    "standardization_enabled": true
  15.    }
  16.   }
  17. }

APIは次の結果を返します:

コンソール-結果

  1. {
  2.   "id" : "loganalytics",
  3.   "create_time" : 1656364565517,
  4.   "version" : "8.4.0",
  5.   "authorization" : {
  6.    "roles" : [
  7.    "superuser"
  8.    ]
  9.   },
  10.   "description" : "Outlier detection on log data",
  11.   "source" : {
  12.    "index" : [
  13.    "logdata"
  14.    ],
  15.    "query" : {
  16.    "match_all" : { }
  17.    }
  18.   },
  19.   "dest" : {
  20.    "index" : "logdata_out",
  21.    "results_field" : "ml"
  22.   },
  23.   "analysis" : {
  24.    "outlier_detection" : {
  25.    "compute_feature_influence" : true,
  26.    "outlier_fraction" : 0.05,
  27.    "standardization_enabled" : true
  28.    }
  29.   },
  30.   "model_memory_limit" : "1gb",
  31.   "allow_lazy_start" : false,
  32.   "max_num_threads" : 1
  33. }

回帰の例

以下の例は、house_price_regression_analysis データフレーム分析ジョブを作成します。分析タイプは regression です。

Python

  1. resp = client.ml.put_data_frame_analytics(
  2.    id="house_price_regression_analysis",
  3.    source={
  4.    "index": "houses_sold_last_10_yrs"
  5.    },
  6.    dest={
  7.    "index": "house_price_predictions"
  8.    },
  9.    analysis={
  10.    "regression": {
  11.    "dependent_variable": "price"
  12.    }
  13.    },
  14. )
  15. print(resp)

Js

  1. const response = await client.ml.putDataFrameAnalytics({
  2.   id: "house_price_regression_analysis",
  3.   source: {
  4.    index: "houses_sold_last_10_yrs",
  5.   },
  6.   dest: {
  7.    index: "house_price_predictions",
  8.   },
  9.   analysis: {
  10.    regression: {
  11.    dependent_variable: "price",
  12.    },
  13.   },
  14. });
  15. console.log(response);

コンソール

  1. PUT _ml/data_frame/analytics/house_price_regression_analysis
  2. {
  3.   "source": {
  4.    "index": "houses_sold_last_10_yrs"
  5.   },
  6.   "dest": {
  7.    "index": "house_price_predictions"
  8.   },
  9.   "analysis":
  10.    {
  11.    "regression": {
  12.    "dependent_variable": "price"
  13.    }
  14.    }
  15. }

APIは次の結果を返します:

コンソール-結果

  1. {
  2.   "id" : "house_price_regression_analysis",
  3.   "create_time" : 1656364845151,
  4.   "version" : "8.4.0",
  5.   "authorization" : {
  6.    "roles" : [
  7.    "superuser"
  8.    ]
  9.   },
  10.   "source" : {
  11.    "index" : [
  12.    "houses_sold_last_10_yrs"
  13.    ],
  14.    "query" : {
  15.    "match_all" : { }
  16.    }
  17.   },
  18.   "dest" : {
  19.    "index" : "house_price_predictions",
  20.    "results_field" : "ml"
  21.   },
  22.   "analysis" : {
  23.    "regression" : {
  24.    "dependent_variable" : "price",
  25.    "prediction_field_name" : "price_prediction",
  26.    "training_percent" : 100.0,
  27.    "randomize_seed" : -3578554885299300212,
  28.    "loss_function" : "mse",
  29.    "early_stopping_enabled" : true
  30.    }
  31.   },
  32.   "model_memory_limit" : "1gb",
  33.   "allow_lazy_start" : false,
  34.   "max_num_threads" : 1
  35. }

以下の例は、ジョブを作成し、トレーニングパーセントを指定します：

Python

  1. resp = client.ml.put_data_frame_analytics(
  2.    id="student_performance_mathematics_0.3",
  3.    source={
  4.    "index": "student_performance_mathematics"
  5.    },
  6.    dest={
  7.    "index": "student_performance_mathematics_reg"
  8.    },
  9.    analysis={
  10.    "regression": {
  11.    "dependent_variable": "G3",
  12.    "training_percent": 70,
  13.    "randomize_seed": 19673948271
  14.    }
  15.    },
  16. )
  17. print(resp)

Js

  1. const response = await client.ml.putDataFrameAnalytics({
  2.   id: "student_performance_mathematics_0.3",
  3.   source: {
  4.    index: "student_performance_mathematics",
  5.   },
  6.   dest: {
  7.    index: "student_performance_mathematics_reg",
  8.   },
  9.   analysis: {
  10.    regression: {
  11.    dependent_variable: "G3",
  12.    training_percent: 70,
  13.    randomize_seed: 19673948271,
  14.    },
  15.   },
  16. });
  17. console.log(response);

コンソール

  1. PUT _ml/data_frame/analytics/student_performance_mathematics_0.3
  2. {
  3.  "source": {
  4.    "index": "student_performance_mathematics"
  5.  },
  6.  "dest": {
  7.    "index":"student_performance_mathematics_reg"
  8.  },
  9.  "analysis":
  10.    {
  11.    "regression": {
  12.    "dependent_variable": "G3",
  13.    "training_percent": 70,
  14.    "randomize_seed": 19673948271
  15.    }
  16.    }
  17. }
モデルのトレーニングに使用されるデータセットの割合。
トレーニングに使用されるデータをランダムに選択するために使用されるシード。

以下の例では、カスタムフィーチャープロセッサを使用して、DestWeather のカテゴリカル値をワンホット、ターゲット平均、および頻度エンコーディング技術を使用して数値値に変換します：

Python

  1. resp = client.ml.put_data_frame_analytics(
  2.    id="flight_prices",
  3.    source={
  4.    "index": [
  5.    "kibana_sample_data_flights"
  6.    ]
  7.    },
  8.    dest={
  9.    "index": "kibana_sample_flight_prices"
  10.    },
  11.    analysis={
  12.    "regression": {
  13.    "dependent_variable": "AvgTicketPrice",
  14.    "num_top_feature_importance_values": 2,
  15.    "feature_processors": [
  16.    {
  17.    "frequency_encoding": {
  18.    "field": "DestWeather",
  19.    "feature_name": "DestWeather_frequency",
  20.    "frequency_map": {
  21.    "Rain": 0.14604811155570188,
  22.    "Heavy Fog": 0.14604811155570188,
  23.    "Thunder & Lightning": 0.14604811155570188,
  24.    "Cloudy": 0.14604811155570188,
  25.    "Damaging Wind": 0.14604811155570188,
  26.    "Hail": 0.14604811155570188,
  27.    "Sunny": 0.14604811155570188,
  28.    "Clear": 0.14604811155570188
  29.    }
  30.    }
  31.    },
  32.    {
  33.    "target_mean_encoding": {
  34.    "field": "DestWeather",
  35.    "feature_name": "DestWeather_targetmean",
  36.    "target_map": {
  37.    "Rain": 626.5588814585794,
  38.    "Heavy Fog": 626.5588814585794,
  39.    "Thunder & Lightning": 626.5588814585794,
  40.    "Hail": 626.5588814585794,
  41.    "Damaging Wind": 626.5588814585794,
  42.    "Cloudy": 626.5588814585794,
  43.    "Clear": 626.5588814585794,
  44.    "Sunny": 626.5588814585794
  45.    },
  46.    "default_value": 624.0249512020454
  47.    }
  48.    },
  49.    {
  50.    "one_hot_encoding": {
  51.    "field": "DestWeather",
  52.    "hot_map": {
  53.    "Rain": "DestWeather_Rain",
  54.    "Heavy Fog": "DestWeather_Heavy Fog",
  55.    "Thunder & Lightning": "DestWeather_Thunder & Lightning",
  56.    "Cloudy": "DestWeather_Cloudy",
  57.    "Damaging Wind": "DestWeather_Damaging Wind",
  58.    "Hail": "DestWeather_Hail",
  59.    "Clear": "DestWeather_Clear",
  60.    "Sunny": "DestWeather_Sunny"
  61.    }
  62.    }
  63.    }
  64.    ]
  65.    }
  66.    },
  67.    analyzed_fields={
  68.    "includes": [
  69.    "AvgTicketPrice",
  70.    "Cancelled",
  71.    "DestWeather",
  72.    "FlightDelayMin",
  73.    "DistanceMiles"
  74.    ]
  75.    },
  76.    model_memory_limit="30mb",
  77. )
  78. print(resp)

Js

  1. const response = await client.ml.putDataFrameAnalytics({
  2.   id: "flight_prices",
  3.   source: {
  4.    index: ["kibana_sample_data_flights"],
  5.   },
  6.   dest: {
  7.    index: "kibana_sample_flight_prices",
  8.   },
  9.   analysis: {
  10.    regression: {
  11.    dependent_variable: "AvgTicketPrice",
  12.    num_top_feature_importance_values: 2,
  13.    feature_processors: [
  14.    {
  15.    frequency_encoding: {
  16.    field: "DestWeather",
  17.    feature_name: "DestWeather_frequency",
  18.    frequency_map: {
  19.    Rain: 0.14604811155570188,
  20.    "Heavy Fog": 0.14604811155570188,
  21.    "Thunder & Lightning": 0.14604811155570188,
  22.    Cloudy: 0.14604811155570188,
  23.    "Damaging Wind": 0.14604811155570188,
  24.    Hail: 0.14604811155570188,
  25.    Sunny: 0.14604811155570188,
  26.    Clear: 0.14604811155570188,
  27.    },
  28.    },
  29.    },
  30.    {
  31.    target_mean_encoding: {
  32.    field: "DestWeather",
  33.    feature_name: "DestWeather_targetmean",
  34.    target_map: {
  35.    Rain: 626.5588814585794,
  36.    "Heavy Fog": 626.5588814585794,
  37.    "Thunder & Lightning": 626.5588814585794,
  38.    Hail: 626.5588814585794,
  39.    "Damaging Wind": 626.5588814585794,
  40.    Cloudy: 626.5588814585794,
  41.    Clear: 626.5588814585794,
  42.    Sunny: 626.5588814585794,
  43.    },
  44.    default_value: 624.0249512020454,
  45.    },
  46.    },
  47.    {
  48.    one_hot_encoding: {
  49.    field: "DestWeather",
  50.    hot_map: {
  51.    Rain: "DestWeather_Rain",
  52.    "Heavy Fog": "DestWeather_Heavy Fog",
  53.    "Thunder & Lightning": "DestWeather_Thunder & Lightning",
  54.    Cloudy: "DestWeather_Cloudy",
  55.    "Damaging Wind": "DestWeather_Damaging Wind",
  56.    Hail: "DestWeather_Hail",
  57.    Clear: "DestWeather_Clear",
  58.    Sunny: "DestWeather_Sunny",
  59.    },
  60.    },
  61.    },
  62.    ],
  63.    },
  64.   },
  65.   analyzed_fields: {
  66.    includes: [
  67.    "AvgTicketPrice",
  68.    "Cancelled",
  69.    "DestWeather",
  70.    "FlightDelayMin",
  71.    "DistanceMiles",
  72.    ],
  73.   },
  74.   model_memory_limit: "30mb",
  75. });
  76. console.log(response);

コンソール

  1. PUT _ml/data_frame/analytics/flight_prices
  2. {
  3.   "source": {
  4.    "index": [
  5.    "kibana_sample_data_flights"
  6.    ]
  7.   },
  8.   "dest": {
  9.    "index": "kibana_sample_flight_prices"
  10.   },
  11.   "analysis": {
  12.    "regression": {
  13.    "dependent_variable": "AvgTicketPrice",
  14.    "num_top_feature_importance_values": 2,
  15.    "feature_processors": [
  16.    {
  17.    "frequency_encoding": {
  18.    "field": "DestWeather",
  19.    "feature_name": "DestWeather_frequency",
  20.    "frequency_map": {
  21.    "Rain": 0.14604811155570188,
  22.    "Heavy Fog": 0.14604811155570188,
  23.    "Thunder & Lightning": 0.14604811155570188,
  24.    "Cloudy": 0.14604811155570188,
  25.    "Damaging Wind": 0.14604811155570188,
  26.    "Hail": 0.14604811155570188,
  27.    "Sunny": 0.14604811155570188,
  28.    "Clear": 0.14604811155570188
  29.    }
  30.    }
  31.    },
  32.    {
  33.    "target_mean_encoding": {
  34.    "field": "DestWeather",
  35.    "feature_name": "DestWeather_targetmean",
  36.    "target_map": {
  37.    "Rain": 626.5588814585794,
  38.    "Heavy Fog": 626.5588814585794,
  39.    "Thunder & Lightning": 626.5588814585794,
  40.    "Hail": 626.5588814585794,
  41.    "Damaging Wind": 626.5588814585794,
  42.    "Cloudy": 626.5588814585794,
  43.    "Clear": 626.5588814585794,
  44.    "Sunny": 626.5588814585794
  45.    },
  46.    "default_value": 624.0249512020454
  47.    }
  48.    },
  49.    {
  50.    "one_hot_encoding": {
  51.    "field": "DestWeather",
  52.    "hot_map": {
  53.    "Rain": "DestWeather_Rain",
  54.    "Heavy Fog": "DestWeather_Heavy Fog",
  55.    "Thunder & Lightning": "DestWeather_Thunder & Lightning",
  56.    "Cloudy": "DestWeather_Cloudy",
  57.    "Damaging Wind": "DestWeather_Damaging Wind",
  58.    "Hail": "DestWeather_Hail",
  59.    "Clear": "DestWeather_Clear",
  60.    "Sunny": "DestWeather_Sunny"
  61.    }
  62.    }
  63.    }
  64.    ]
  65.    }
  66.   },
  67.   "analyzed_fields": {
  68.    "includes": [
  69.    "AvgTicketPrice",
  70.    "Cancelled",
  71.    "DestWeather",
  72.    "FlightDelayMin",
  73.    "DistanceMiles"
  74.    ]
  75.   },
  76.   "model_memory_limit": "30mb"
  77. }

これらのカスタムフィーチャープロセッサはオプションです。すべてのカテゴリカルフィーチャに対して自動フィーチャエンコーディングが引き続き行われます。

分類の例

以下の例は、loan_classification データフレーム分析ジョブを作成します。分析タイプは classification です。

Python

  1. resp = client.ml.put_data_frame_analytics(
  2.    id="loan_classification",
  3.    source={
  4.    "index": "loan-applicants"
  5.    },
  6.    dest={
  7.    "index": "loan-applicants-classified"
  8.    },
  9.    analysis={
  10.    "classification": {
  11.    "dependent_variable": "label",
  12.    "training_percent": 75,
  13.    "num_top_classes": 2
  14.    }
  15.    },
  16. )
  17. print(resp)

Js

  1. const response = await client.ml.putDataFrameAnalytics({
  2.   id: "loan_classification",
  3.   source: {
  4.    index: "loan-applicants",
  5.   },
  6.   dest: {
  7.    index: "loan-applicants-classified",
  8.   },
  9.   analysis: {
  10.    classification: {
  11.    dependent_variable: "label",
  12.    training_percent: 75,
  13.    num_top_classes: 2,
  14.    },
  15.   },
  16. });
  17. console.log(response);

コンソール

  1. PUT _ml/data_frame/analytics/loan_classification
  2. {
  3.   "source" : {
  4.    "index": "loan-applicants"
  5.   },
  6.   "dest" : {
  7.    "index": "loan-applicants-classified"
  8.   },
  9.   "analysis" : {
  10.    "classification": {
  11.    "dependent_variable": "label",
  12.    "training_percent": 75,
  13.    "num_top_classes": 2
  14.    }
  15.   }
  16. }