Databricks AutoMLのマニュアル

[Databricks AutoML \| Databricks on AWS](https://docs.databricks.com/applications/machine-learning/automl.html) [2022/7/14時点]の翻訳です。

> [Databricksクイックスタートガイド](https://qiita.com/taka_yayoi/items/125231c126a602693610)のコンテンツです。

Databricks AutoMLを活用することで、データセットに対して自動で機械学習を適用することができます。モデルのトレーニングのためにデータセットを準備し、一連の実験を実施、記録し、複数のモデルに対して、作成、チューニング、評価を行います。結果の表示に加えて、中身を確認し、再現、修正できるようにそれぞれの実験のソースコードをPythonノートブック形式で提供します。また、AutoMLはデータセットの統計情報を計算し、後ほど確認できるようにノートブックの中に情報を記録します。

AutoMLはハイパーパラメーターチューニングのトライアルを自動でクラスターのワーカーノードに分散します。

それぞれのモデルは、scikit-learnやXGBoostなどのオープンソースコンポーネントから構築され、容易に修正でき、既存の機械学習パイプラインに組み込むことができます。回帰、分類、予測問題に対してDatabricks AutoMLを活用できます。[scikit\-learn](https://scikit-learn.org/stable/)、[xgboost](https://xgboost.readthedocs.io/en/latest/)、[LightGBM](https://lightgbm.readthedocs.io/en/latest/index.html)パッケージのアルゴリズムに基づきモデルを評価します。

[UI](#automl-ui)あるいは[Python API](#automl-python-api)でAutoMLを実行することができます。

:::note
**注意**
AutoMLは[passthrough clusters](https://docs.databricks.com/security/credential-passthrough/iam-passthrough.html)や[テーブルACLが有効化されたクラスター](https://qiita.com/taka_yayoi/items/a30b474cd07e2ef8a7eb)では利用できません。
:::

# 要件

- Databricksランタイム 8.3 ML以降が必要です。GAバージョンに関しては、atabricksランタイム 10.4 LTS ML以降が必要です。 
- 時系列予測に対しては、Databricksランタイム 10.0 ML以降が必要です。
- DatabricksライタイムMLに同梱されている以外のライブラリをクラスターにインストールすることはできません。
- [ハイコンカレンシークラスター](https://qiita.com/taka_yayoi/items/8d951b660cd87c6c5f18#high-concurrency%E3%82%AF%E3%83%A9%E3%82%B9%E3%82%BF%E3%83%BC)において、AutoMLは[テーブルアクセスコントロール](https://qiita.com/taka_yayoi/items/f0b999e69b9fef5065d8)や[クレディンシャルパススルー](https://docs.databricks.com/security/credential-passthrough/index.html)とは互換性がありません。
- AutoMLで[Unity Catalog](https://qiita.com/taka_yayoi/items/15aede468bdca58ec6a3)を使用するには、[クラスターセキュリティモード](https://qiita.com/taka_yayoi/items/065706136dcd2ad9df33#%E3%82%AF%E3%83%A9%E3%82%B9%E3%82%BF%E3%83%BC%E3%82%BB%E3%82%AD%E3%83%A5%E3%83%AA%E3%83%86%E3%82%A3%E3%83%A2%E3%83%BC%E3%83%89)が**Single User**であり、あなたがクラスターに割り当てられる単一のユーザーである必要があります。

# AutoMLのアルゴリズム

Databricks AutoMLでは、以下のアルゴリズムに基づいてモデルを作成、評価します。

- 分類モデル
    - scikit-learnモデル
        - [決定木](https://scikit-learn.org/stable/modules/tree.html#classification)
        - [ランダムフォレスト](https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.RandomForestClassifier.html#sklearn.ensemble.RandomForestClassifier)
        - [ロジスティック回帰](https://scikit-learn.org/stable/modules/linear_model.html#logistic-regression)
    - [XGBoost](https://xgboost.readthedocs.io/en/latest/python/python_api.html#xgboost.XGBClassifier)
    - [LightGBM](https://lightgbm.readthedocs.io/en/latest/pythonapi/lightgbm.LGBMClassifier.html)
- 回帰モデル
    - scikit-learnモデル
        - [Stochastic gradient descent \(SGD\)による線形回帰](https://scikit-learn.org/stable/modules/sgd.html)
        - [決定木](https://scikit-learn.org/stable/modules/tree.html#regression)
        - [ランダムフォレスト](https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.RandomForestRegressor.html#sklearn.ensemble.RandomForestRegressor)
    - [XGBoost](https://xgboost.readthedocs.io/en/latest/python/python_api.html#xgboost.XGBRegressor)
    - [LightGBM](https://lightgbm.readthedocs.io/en/latest/pythonapi/lightgbm.LGBMRegressor.html)
- 予測モデル
    - [Prophet](https://facebook.github.io/prophet/docs/quick_start.html#python-api)
    - [Auto\-ARIMA](https://alkaline-ml.com/pmdarima/modules/generated/pmdarima.arima.auto_arima.html) (Databricks 10.3ML以降で利用できます)

## 大規模データセットのサンプリング

:::note
**注意**
サンプリングは予測問題では適用されません。
:::

AutoMLはハイパーパラメーターチューニングのトライアルをクラスターのワーカーノードに自動で分散しますが、それぞれのモデルは単一のワーカーノードでトレーニングされます。

AutoMLは自動でデータセットのロードとトレーニングに必要なメモリー量を推定し、必要に応じてサンプリングを行います。

Databricksランタイム9.1 LTS MLからDatabricksランタイム10.5MLでは、サンプリングの割合は、クラスターのノードタイプやそれぞれのノードのメモリー料に依存しません。

Databricksランタイム11.0ML以降では、

- コアごとのメモリー量が多いワーカーノードに対してはサンプリングの割合を増加させます。**memory optimized**インスタンスタイプを選択することでサンpリングのサイズを増加させることができます。
- クラスターのSpark設定`spark.task.cpus`で大きな値を選択することで、さらにサンプリングの割合を増加させることができます。デフォルトの設定値は1です。最大値はワーカーノードのCPU数となります。この値を増加させるとサンプルサイズは大きくなりますが、並列で実行されるトライアルの数は減ります。例えば、4コア、RAMが64GBのマシンでは、デフォルトは`spark.task.cpus=1`であり、それぞれのトライアルではワーカーあたり4つのトライアルが実行されRAMは16GBに制限されます。`spark.task.cpus=4`に設定すると、それぞれのワーカーは1トライアルのみを実行しますが、64GBのRAMを使用することができます。
- AutoMLがデータセットをサンプリングした場合、サンプリングの割合がUIの**Overview**タブに表示されます。

分類問題においては、ターゲットのラベルの分布を保存する様に階層化サンプリングを行うために、AutoMLはPySparkの`sampleBy`[メソッド](https://spark.apache.org/docs/latest/api/python/reference/api/pyspark.sql.DataFrameStatFunctions.sampleBy.html)を使用します。

回帰問題においては、AutoMLはPySparkの`sample`[メソッド](https://spark.apache.org/docs/latest/api/python/reference/api/pyspark.sql.DataFrame.sample.html)を使用します。

## セマンティックタイプの検知

:::note
**注意**
- セマンティックタイプの検知は予測問題では適用されません。
- AutoMLは、[カスタムの注入メソッド](#欠損値の注入)が指定されているカラムに対してセマンティックタイプの検知を行いません。
:::

Databricksランタイム9.1ML LTS以降では、AutoMLはテーブルスキーマにおいてSparkやpandasのデータ型と異なるセマンティックタイプのカラムを持っているかどうかを検知しようとします。AutoMLはこれらのカラムを検知したセマンティックタイプとして取り扱います。これらの検知はベストエフォートであり、時には既存のセマンティックタイプを見逃す場合があります。あるいは、カラムのセマンティックタイプを手動で指定するか、[アノテーションを用いて](#セマンティックタイプのアノテーション)AutoMLにセマンティックタイプの検知を行わないように指示することができます。

特に、AutoMLは以下の変換を行います。

- 日付やタイムスタンプデータを表現する文字列、整数型のカラムはタイムスタンプ型に変換します。
- 数値データを表現する文字列カラムは数値型に変換します。

Databricksランタイム10.1 ML以降では、AutoMLは以下の調整も行います。

- カテゴリカルなIDを含む数値カラムはカテゴリカルな特徴量として取り扱われます。
- 英語テキストを含む文字列カラムはテキストの特徴量として取り扱われます。

### セマンティックタイプのアノテーション

Databricksランタイム10.1 ML以降では、カラムに対してセマンティックタイプのアノテーションを指定することで、セマンティックタイプを手動でコントロールすることができます。カラム`<column_name>`のセマンティックタイプを`<semantic_type>`として手動でアノテーションするには以下の文法を使用します。

```py:Python
metadata_dict = df.schema["<column_name>"].metadata
metadata_dict["spark.contentAnnotation.semanticType"] = "<semantic_type>"
df = df.withMetadata("<column_name>", metadata_dict)
```

`<semantic_type>`は以下のいずれかとなります。

- `categorical`: カテゴリカルな値を含むカラム(例えば、IDとして取り扱われる数値)です。
- `numeric`: 数値を含むカラム(例えば、数値にパースできる文字列)です。
- `datetime`: タイムスタンプの値を含むカラム(タイムスタンプに変換できる文字列、数値、日付の値)です。
- `text`: 英語テキストを含む文字列カラムです。

カラムに対するセマンティックタイプ検知を無効化するには、特殊なキーワードアノテーションである`native`を指定します。

## モデルの説明可能性のためのShapley値(SHAP)

AutoMLの回帰、分類ランによって生成されるノートブックには、[Shapley値](https://shap.readthedocs.io/en/latest/example_notebooks/overviews/An%20introduction%20to%20explainable%20AI%20with%20Shapley%20values.html#)を計算するコードが含まれています。Shapley値はゲーム理論に基づいており、モデルの予測に対するそれぞれの特徴量の重要度を推定します。

Shapley値を計算するためにAutoMLのノートブックでは[SHAP package](https://shap.readthedocs.io/en/latest/overviews.html)を使用します。これらの計算処理は非常にメモリーを消費するので、デフォルトではこの計算は行われません。

Shapley値を計算して、表示するには:

- AutoMLが生成したトライアルノートブックの**Feature importance**セクションに移動します。
- `shap_enabled = True`を設定します。
- ノートブックを再実行します。

## トレーニング/バリデーション/テストスプリットの制御

Databricksランタイム10.1 ML以降では、分類、回帰問題におけるトレーニング/バリデーション/テストスプリットで使用される時間カラムを指定することができます。このカラムを指定すると、データセットは時間に基づいてトレーニング/バリデーション/テストセットに分割します。最も古いデータポイントがトレーニングに使用され、次に古いものがバリデーション、最新のデータセットがテストセットに使用されます。

Databricksランタイム10.1では、時間のカラムはtimestampかintegerのカラムである必要があります。Databricksランタイム10.2 ML以降では文字列カラムも選択することができます。

## 時系列データの集約

予測問題において、時系列データのタイムスタンプに対して複数の値がある場合、AutoMLはこれらの値の平均値を使用します。

合計を使用するには、ソースコードのノートブックを編集します。**Aggregate data by …** セルで、以下のように`.agg(y=(target_col, "avg"))`を`.agg(y=(target_col, "sum"))`に変更します。

```py:Python
group_cols = [time_col] + id_cols
df_aggregation = df_loaded \
  .groupby(group_cols) \
  .agg(y=(target_col, "sum")) \
  .reset_index() \
  .rename(columns={ time_col : "ds" })
```

# AutoML UI

:::note
**訳者注**
- ラン(run)/トライアル(trial): MLflowで管理される一回のモデルのトレーニング。
- エクスペリメント(experiment): MLflowで管理されるランのコレクション。ノートブックに付随するエクスペリメントと独立したエクスペリメントが存在します。
- アーティファクト(artifact): MLflowで管理される任意のファイル(画像やpickleファイルなど)
:::

AutoML UIを利用することで、データセットに対してモデルをトレーニングするステップを踏むことができます。UIにアクセスするには以下の操作を行います。

1. 左上の[ペルソナスイッチ](https://qiita.com/taka_yayoi/items/91d4496adc138e88e90f)から**Machine Learning**を選択します。
1. サイドバーで、**Create > AutoML Experiment**をクリックします。

    また、[エクスペリメントページ](https://docs.databricks.com/applications/machine-learning/experiments-page.html)からAutoMLエクスペリメントを作成することもできます。

    AutoMLエクスペリメント設定ページが表示されます。このページでは、AutoMLのプロセス、データセットの指定、問題の種類、予測するカラム、評価のためのメトリクス、エクスペリメントのスコア、停止条件を指定できます。

## UIにおける分類、回帰問題のセットアップ

1. **Compute**フィールドで、稼働しているDatabricksランタイム 8.3 ML以降のクラスターを選択します。
1. **ML problem type**ドロップダウンメニューから、**Regression**と**Classification**を選択します。それぞれの観測に対して、年収などの連続値を予測するのであればregression(回帰)を選択します。それぞれの観測に対して、クレジットリスクあり・なしなどの明確なクラスを識別するのであれば、classification(分類)を選択します。
1. **Dataset**では、**Browse Tables**をクリックします。利用できるデータベース、テーブルの一覧を示すダイアログが表示されます。利用したいテーブルを選択して**Select**をクリックします。テーブルのスキーマが表示されます。

   トレーニングにどのカラムを含めるのか、カスタム注入メソッドを指定することができます。[データセットの修正](#データセットの修正)をご覧ください。

1. **Prediction target**をクリックします。スキーマのカラムの一覧のドロップダウンが表示されます。予測したいカラムを選択します。
1. **Experiment name**にはデフォルト名が表示されます。変更する際には、フィールドに名前を指定します。

また、[追加の設定オプション](#高度な設定)を指定することができます。

## UIにおける予測問題のセットアップ

1. **Compute**フィールドで、稼働しているDatabricksランタイム 10.0 ML以降のクラスターを選択します。
1. **ML problem type**ドロップダウンメニューから**Forecasting**を選択します。
1. **Dataset**では、**Browse Tables**をクリックします。利用できるデータベース、テーブルの一覧を示すダイアログが表示されます。利用したいテーブルを選択して**Select**をクリックします。テーブルのスキーマが表示されます。
1. **Prediction target**をクリックします。スキーマのカラムの一覧のドロップダウンが表示されます。予測したいカラムを選択します。
1. **Time column**フィールドをクリックします。　`timestamp`あるいは`date`型のカラムの一覧のドロップダウンが表示されます。時系列データの時間を示すカラムを選択します。
1. 複数の時系列データの予測においては、**Time series identifiers**ドロップダウンからそれぞれの時系列データを識別するカラムを選択します。AutoMLはこれらのカラムでデータを異なる時系列データとしてグルーピングし、それぞれの時系列データに対してモデルを独立にトレーニングします。このフィールドを空にした場合、AutoMLはデータセットには単一の時系列データが含まれていると仮定します。
1. **Forecast horizon and frequency**フィールドでは、AutoMLが予測値として計算すべき未来の期間を指定します。左のボックスでは、予測する期間の整数値を指定します。右側のボックスでは単位を指定します。
1. Databricksランタイム 10.5ML以降では、予測結果を保存することができます。これを行うには、**Output Database**フィールドでデータベースを指定します。**Browse**をクリックしてダイアログからデータベースを選択します。AutoMLによって予測結果がデータベースのテーブルとして書き込まれます。
1. **Experiment name**にはデフォルト名が表示されます。変更する際には、フィールドに名前を指定します。

また、[追加の設定オプション](#高度な設定)を指定することができます。

## 高度な設定

これらのパラメーターにアクセスするには、**Advanced configuration (optional)** を開きます。

- エクスペリメントのスコアリングに使われる評価メトリクスが[primary metric](#パラメーター)となります。
- Databricksランタイム10.3 ML以降では、使用するトレーニングフレームワークを除外することができます。デフォルトでは、AutoMLは[AutoMLのアルゴリズム](#automlのアルゴリズム)にあるトレーニングフレームワークのモデルを対象とします。
- デフォルトの停止条件を変更することができます。デフォルト値は以下のようになります。
    - 予測のエクスペリメントでは120分後に停止します。
    - Databricksランタイム10.5ML以前では、分類と回帰のエクスペリメントにおいては、デフォルトでは60分あるいは200回のエクスペリメント、どちらかの条件を満たした場合に停止します。Databricksランタイム11.0ML以降では、トライアルの数は停止条件として使用されません。
    - Databricksランタイム10.1ML以降では、分類と回帰エクスペリメントにおいては、AutoMLは早期停止(アーリーストッピング)を活用します。検証メトリックが改善されなくなったらトレーニングとチューニングを停止します。
- Databricksランタイム10.1 ML以降では、トレーニング、バリデーション、テストセット時系列順に分割するための[時間カラム](#トレーニングバリデーションテストスプリットの制御)を指定することができます。
- **Data directory**フィールドでは、AutoMLプロセスの際に作成される[DBFS](https://qiita.com/taka_yayoi/items/e16c7272a7feb5ec9a92)における場所を指定できます。フィールドをブランクにすると、ノートブックは[MLflowのアーティファクト](https://docs.databricks.com/security/access-control/workspace-acl.html#mlflow-artifact-permissions)として保存されま

## データセットの修正

データセットを選択した後にテーブルのスキーマが表示されます。分類と回帰問題においては、トレーニングにどのカラムを含めるのか、カスタムの注入メソッドを指定することができます。

### カラムの選択

Databricksランタイム10.3ML以降では、AutoMLがトレーニングに使用すべきカラムを指定することができます。カラムを除外するには、**Include**カラムでチェックを外します。カラムのチェックを外すことは[AutoML Python API](#Python APIの仕様)で`exclude_columns`を設定することと同じことになります。

予測ターゲットとして選択されたカラムを除外することや、データの分割に使用している[時間カラム](#トレーニングバリデーションテストスプリットの制御)を除外することはできません。

デフォルトでは全てのカラムが含まれています。

### 欠損値の注入

Databricksランタイム10.4 LTS ML以降では、null値に対してどのように注入するのかを指定することができます。UIで、テーブルスキーマの**Impute with**カラムのドロップダウンからメソッドを選択します。あるいは、[AutoML Python API](#Python APIの仕様)で`imputers`パラメーターを使用します。

デフォルトでは、AutoMLがカラムのタイプと内容に基づいて注入メソッドを選択します。

:::note info
**注意**
デフォルトではない注入メソッドを選択した場合、AutoMLは[セマンティックタイプの検知](#セマンティックタイプの検知)を行いません。
:::

## エクスペリメントの実行、結果のモニタリング

1. AutoMLエクスペリメントを実行するには**Start AutoML**をクリックします。エクスペリメントが実行され、AutoMLトレーニングページが表示されます。実行テーブルを更新するには、![](https://docs.databricks.com/_images/automl-refresh-button.png)をクリックします。

    このページでは以下の操作を行うことができます。
    - 任意のタイミングでのエクスペリメントの停止
    - データ探索用ノートブック(data exploration notebook)のオープン
    - エクスペリメント実行(ラン)のモニタリング
    - 過去のランの詳細ページへのナビゲーション

Databricksランタイム10.1 ML以降では、AutoMLはサポートされていないカラムタイプやカーディナリティの高いカラムのように、データセットにおける潜在的アラートを表示します。

:::note
**注意**
Databricksは潜在的なエラーや問題を適切に表示するためにベストを尽くします。しかし、みなさまが探している問題やエラーをを捕捉できず、包括的なものにならない場合があります。ご自身でもレビューを行うようにしてください。
:::

データセットに対するアラートを参照するには、トレーニングページ、あるいはエクスペリメントが完了した後のエクスペリメントページの**Warnings**タブをクリックします。
![](https://docs.databricks.com/_images/automl-alerts.png)

エクスペリメントが終了すると、以下の操作を行うことができます。

- MLflowによる[モデルの登録とデプロイ](#automl-uiからのモデル登録とデプロイ)
- ベストモデルの確認および生成されたノートブックの編集のために**Edit Best model**をクリック
- データ探索用ノートブックのオープン
- ランテーブルでランを検索、フィルタリング、並び替え
- ランの詳細表示
    - ランのソースコードを含むノートブックを開くには**Source**列をクリック
    - ランの詳細ページを表示するには**Start Time**列をクリック
    - 作成されたモデルの情報を参照するには**Model**列をクリック

後でAutoMLエクスペリメントに戻ってくるには、[Experimentsページ](https://qiita.com/taka_yayoi/items/e9f6d6628fbad209770b)のテーブルを参照します。データ探索ノートブック、トレーニングノートブックを含むそれぞれのAutoMLエクスペリメントの結果は、エクスペリメントを実行したユーザーの[ホームフォルダー](https://docs.databricks.com/workspace/workspace-objects.html#home-folder)配下の`databricks_automl`フォルダーに格納されます。

## AutoML UIからのモデル登録とデプロイ

1. モデルを登録するには**Models**列のリンクをクリックします。ランの実行が完了した際には、最初の行に(primary metricに基づく)ベストモデルが表示されます。

    当該モデルを作成した[ランのページ](https://qiita.com/taka_yayoi/items/ba0c7f46ff7c3dbf87bb)のアーティファクトのセクションが表示されます。
1. [モデルレジストリ](https://qiita.com/taka_yayoi/items/e7a4bec6420eb7069995)にモデルを登録するには![](https://docs.databricks.com/_images/register-model-button.png)をクリックします。
1. モデルレジストリに移動するにはサイドバーの![](https://docs.databricks.com/_images/models-icon.png)をクリックします。
1. モデルテーブル上のモデル名をクリックします。[登録モデルページ](https://qiita.com/taka_yayoi/items/e7a4bec6420eb7069995#%E7%99%BB%E9%8C%B2%E3%83%A2%E3%83%87%E3%83%AB%E3%83%9A%E3%83%BC%E3%82%B8)が表示されます。このページから[モデルをサーブ](https://qiita.com/taka_yayoi/items/b5a5f83beb4c532cf921)することも可能です。

# AutoML Python API

1. [ノートブックを作成](https://qiita.com/taka_yayoi/items/c306161906d6d34e8bd5#%E3%83%8E%E3%83%BC%E3%83%88%E3%83%96%E3%83%83%E3%82%AF%E3%81%AE%E4%BD%9C%E6%88%90)し、Databricksランタイム 8.3 ML以降が動作しているクラスターにアタッチします。
1. 既存のデータセットからSpark/pandasデータフレームを作成、あるいは[DBFSにデータをアップロード](https://qiita.com/taka_yayoi/items/4fa98b343a91b8eaa480#%E3%83%87%E3%83%BC%E3%82%BF%E3%81%AE%E3%82%A4%E3%83%B3%E3%83%9D%E3%83%BC%E3%83%88)してデータをノートブックにデータを読み込みます。

    ```python:Python
    df = spark.read.parquet("<folder-path>")
    ```

1. AutoMLを実行するには、データフレームをAutoMLに渡します。詳細は[APIドキュメント](https://docs.databricks.com/applications/machine-learning/automl.html#automl-python-api)を参照ください。
1. AutoMLがスタートすると、コンソールにはMLflowエクスペリメントのURLが表示されます。AutoML実行の真力をモニタリングするためにこのURLを使用します。欄の終了に応じて、MLflowのエクスペリメントが更新されます。
1. AutoMLのランが完了すると以下のことが可能になります。
    - MLflowのエクスペリメントやベストな結果を生み出したノートブックにナビゲートするために、出力結果サマリーのリンクを使用します。
    - AutoMLに渡したデータに関する洞察を得るために、データ探索用ノートブックへのリンクを使用します。結果を再現、あるいは追加のデータ分析をするために、このノートブックを同じクラスターにアタッチして再実行することができます。
    - 実験の詳細を探るため、あるいは特定のトレーニングで得られたモデルをロードするために、AutoML呼び出しから得られるサマリーオブジェクトを使用します。詳細は[APIドキュメント](https://docs.databricks.com/applications/machine-learning/automl.html#automl-python-api)を参照ください。
    - トレーニングで生成されたノートブックをコピーし、同じクラスターにアタッチして結果を再現できます。必要な修正を加えて追加のモデルをトレーニングするために再度実行し、同じエクスペリメントに結果を記録することができます。

# Python APIの仕様

Python APIは分類、回帰AutoMLのランを開始するための関数を提供します。それぞれの関数呼び出しで、一連のモデルをトレーニングし、それぞれのモデルのトレーニングノートブックを生成します。

## 分類

:::note info
**注意**
Databricksランタイム10.3 ML - 10.5 MLで`max_trials`パラメーターは非推奨となり、Databricksランタイム10.0 ML以降ではサポートされません。AutoMLの実行時間を制御するには`timeout_minutes`を使ってください。
:::

```python:Python
databricks.automl.classify(
  dataset: Union[pyspark.DataFrame, pandas.DataFrame],
  *,
  target_col: str,
  data_dir: Optional[str] = None,
  exclude_columns: Optional[List[str]] = None,                      # <DBR> 10.3 ML and above
  exclude_frameworks: Optional[List[str]] = None,                   # <DBR> 10.3 ML and above
  experiment_dir: Optional[str] = None,                             # <DBR> 10.4 LTS ML and above
  imputers: Optional[Dict[str, Union[str, Dict[str, Any]]]] = None, # <DBR> 10.4 LTS ML and above
  max_trials: Optional[int] = None,                                 # <DBR> 10.5 ML and below
  pos_label: Optional[Union[int, bool, str] = None,                 # <DBR> 11.1 ML and above
  primary_metric: str = "f1",
  time_col: Optional[str] = None,
  timeout_minutes: Optional[int] = None,
) -> AutoMLSummary
```

## 回帰

:::note info
**注意**
Databricksランタイム10.3 ML - 10.5 MLで`max_trials`パラメーターは非推奨となり、Databricksランタイム10.0 ML以降ではサポートされません。AutoMLの実行時間を制御するには`timeout_minutes`を使ってください。
:::

```python:Python
databricks.automl.regress(
  dataset: Union[pyspark.DataFrame, pandas.DataFrame],
  *,
  target_col: str,
  data_dir: Optional[str] = None,
  exclude_columns: Optional[List[str]] = None,                      # <DBR> 10.3 ML and above
  exclude_frameworks: Optional[List[str]] = None,                   # <DBR> 10.3 ML and above
  experiment_dir: Optional[str] = None,                             # <DBR> 10.4 LTS ML and above
  imputers: Optional[Dict[str, Union[str, Dict[str, Any]]]] = None, # <DBR> 10.4 LTS ML and above
  max_trials: Optional[int] = None,                                 # <DBR> 10.5 ML and below
  primary_metric: str = "r2",
  time_col: Optional[str] = None,
  timeout_minutes: Optional[int] = None,
) -> AutoMLSummary
```

## 予測

```python:Python
databricks.automl.forecast(
  dataset: Union[pyspark.sql.dataframe.DataFrame, pandas.core.frame.DataFrame, pyspark.pandas.DataFrame],
  *,
  target_col: str,
  time_col: str,
  data_dir: Optional[str] = None,
  exclude_frameworks: Optional[List[str]] = None,
  experiment_dir: Optional[str] = None,
  frequency: str = "D",
  horizon: int = 1,
  identity_col: Optional[Union[str, List[str]]] = None,
  output_database: Optional[str] = None,                            # <DBR> 10.5 ML and above
  primary_metric: str = "smape",
  timeout_minutes: Optional[int] = None,
) -> AutoMLSummary
```


## パラメーター

### 分類、回帰

| フィールド名 | タイプ | 説明 |
|:--|:--|:--|
| dataset   | pyspark.DataFrame/pandas.DataFrame  | トレーニングする特徴量と目的変数を含む入力データフレーム  |
| target_col  |str   |目的変数の列名  |
| data_dir  | `dbfs:/<folder-name>`形式でのstr  |中間結果を格納するためのDBFSパス。このバスはドライバーノード、ワーカーノードからアクセスできる必要があります。空の場合は、AutoMLはデータをMLflowのアーティファクトとして格納します。   |
| exclude_columns  |List[str]   |AutoMLの計算で無視するカラムのリストです。デフォルトは[]です。   |
| exclude_frameworks  |List[str]   |モデルを構築する際にAutoMLの考慮から除外するアルゴリズムフレームワークのリストです。受け入れられる値は、空のリスト、あるいは“sklearn”、“lightgbm”、“xgboost”からなるリストです。デフォルトは[]です。この場合、全てのフレームワークが考慮されます。   |
| experiment_dir  |str   |(オプション)生成されたノートブックとエクスペリメントを保存するためのワークスペース上のディレクトリへのパスです。<br><br>デフォルト: `/Users/<username>/databricks_automl/`   |
| imputers  |Dict[str, Union[str, Dict[str, Any]]]   |(オプション)それぞれのキーがカラム名、値は注入戦略を示す文字列あるいはディクショナリーとなります。文字列が指定される場合、値は“mean”, “median”, “most_frequent”のいずれかでなくてはなりません。既知の値で注入するにはディクショナリー{“strategy”: “constant”, value: <desired value>}を指定します。また、{“strategy”: “mean”}のようにディクショナリーとして文字列のオプションを指定することができます。<br><br>デフォルト: {}  |
| max_trials  |int   |トライアル実行回数の最大回数(オプション)。このパラメーターはDatabricksランタイム10.5ML以前で利用できますが、ランタイム10.3ML以降は非推奨となり、ランタイム11.0ML以降ではサポートされません。デフォルトは20。timeout=Noneの場合、最大回数分だけトライアルが実行されます。   |
| pos_label  |Union[int, bool, str]   |(分類のみ)ポジティブクラスです。これは、精度や再現率のようなメトリクスを計算する際に有用です。2値分類問題の時のみ指定されるべきです。   |
| primary_metric  | str  |モデルの性能を評価し、ランキングするためのメトリック。回帰でサポートされているメトリック："r2(デフォルト)"、"mae"、"rmse"、"mse"。分類でサポートされているメトリック："f1(デフォルト)"、"log_loss"、"precision"、"accuracy"、"roc_auc"   |
| time_col  |str   |Databricksランタイム10.1 ML以降で利用可能。<br><br>(オプション)時間カラムの名称<br><br>指定された場合、AutoMLはデータセットを時系列順にトレーニング、バリデーション、テストセットに分割します。最も古いデータポイントがトレーニングデータ、最新のデータがテストデータになります。<br><br>受け付けるカラムタイプはtimestampとintegerです。Databricksランタイム10.2 ML以降では文字列カラムもサポートされています。カラムが文字列タイプの場合、AutoMLはセマンティック検知を用いてtimestampに変換しようとします。変換に失敗するとAutoMLのランも失敗します。   |
| timeout_minutes  | int  |AutoMLのトライアル実行を完了する最長の時間(オプション)。指定されない場合は、AutoML時間の制約なしに処理を行います(デフォルト)。指定された値が5分未満、一回のトライアルを実行するのに十分でなかった場合は例外が発生します。長いタイムアウト時間を設定すれば、それだけ多くのトライアルが実行され、高い精度のモデルが得られます。  |

### 予測

| フィールド名 | タイプ | 説明 |
|:--|:--|:--|
| dataset   | pyspark.DataFrame/pandas.DataFrame  | トレーニングする特徴量と目的変数を含む入力データフレーム  |
| target_col   | str  | ターゲットラベルのカラム名  |
| time_col |str|予測に使用する時刻のカラム |
| frequency |str|予測を行う時系列の間隔。イベントが予期される期間となります。取りうる値は以下の通りです。<br>“W” (weeks)　<br><br>“D” / “days” / “day”<br><br>“hours” / “hour” / “hr” / “h”<br><br>“m” / “minute” / “min” / “minutes” / “T”<br><br>“S” / “seconds” / “sec” / “second” |
| horizon | int |予測すべき未来の期間を数で指定します。単位は上のfrequencyとなります。 |
| data_dir | `dbfs:/<folder-name>`形式のstr |(オプション)トレーニングデータセットを保存するために使うDBFSパスです。このパスはドライバーノード、ワーカーノードの両方から参照できます。空の場合、AutoMLはトレーニングデータセットをMLflowアーティファクトとして保存します。 |
| exclude_frameworks  |List[str]   |モデルを構築する際にAutoMLの考慮から除外するアルゴリズムフレームワークのリストです。受け入れられる値は、空のリスト、あるいは“prophet”、“arima”から構成されるリストです。デフォルトは[]です。この場合、全てのフレームワークが考慮されます。   |
| experiment_dir  |str  |(オプション)生成されたノートブックとエクスペリメントを保存するためのワークスペース上のディレクトリへのパスです。<br><br>デフォルト: `/Users/<username>/databricks_automl/`   |
| identity_col |Union[str, list]|(オプション)複数時系列データの予測で時系列を識別するカラム。AutoMLはこれらのカラムと時刻のカラムを用いてグルーピングを行います。 |
| output_database |str|(オプション)指定すると、AutoMLはベストモデルの予測結果を指定されたデータベースの新規テーブルとして保存します。<br><br>デフォルト: 予測結果は保存されません。 |
| primary_metric  | str  |モデルの性能を評価し、ランキングするためのメトリック:"smape(デフォルト)"、"mse"、"rmse"、"mae"、"mdape"   |
| timeout_minutes  | int  |AutoMLのトライアル実行を完了する最長の時間(オプション)。長いタイムアウト時間を設定すれば、それだけ多くのトライアルが実行され、高い精度のモデルが得られます。<br><br>デフォルトはNone(時間制限なし)<br><br>最小値は5分<br><br>1回のトライアルが完了しないほど短すぎるタイムアウト時間が指定された場合にはエラーがレポートされます。 |

| max_trials  |int   |トライアル実行回数の最大回数(オプション)。デフォルトは20。timeout=Noneの場合、最大回数分だけトライアルが実行されます。   |

## 戻り値

**AutoMLSummary**

AutoML分類実行によるサマリーオブジェクトは、トライアルにおけるメトリクス、パラメーター、そのほかの詳細情報を格納します。このオブジェクトを使用して、特定のトライアルによってトレーニングされたモデルをロードすることもできます。

| プロパティ | タイプ | 説明 |
|:--|:--|:--|
| experiment  |mlflow.entities.Experiment  | トライアルを記録するのに用いられたMLflowエクスペリメント  |
| trials  |  	List[TrialInfo] |実行されたトライアルのリスト   |
| best_trial  |TrialInfo   |primary metricに基づいてベストと判断されたトライアル   |
| metric_distribution  | 	str  |全てのトライアルにおいて重み付けされたスコアの分布   |
| output_table_name  | 	str  |予測問題の場合でoutput_databaseが指定された場合のみです。モデルの予測結果を含むoutput_databaseのテーブル名です。   |

**TrialInfo**

それぞれのトライアルのサマリーオブジェクト。

| プロパティ | タイプ | 説明 |
|:--|:--|:--|
| notebook_path  | str  |トライアルで生成されたノートブックのワークスペース上のパス   |
| notebook_url  | str  | 生成されたノートブックのURL  |
| mlflow_run_id  | str  | トライアルに紐づけられたMLflowのランID  |
| metrics  | Dict[str, float]  |トライアルで記録されたメトリクス   |
| params  |  Dict[str, float] | トライアルで記録されたパラメーター  |
| model_path  | str  | トライアルでトレーニングされたモデルのMLflowアーティファクトURL  |
| model_description  |  str |モデル、ハイパーパラメーターに関する説明   |
| duration  |  str |トレーニング時間(分)   |
| preprocessors  |  str |モデルトレーニング前に実行された前処理の説明   |
| evaluation_metric_score  | float  |検証用データセットで評価されたprimary metricのスコア   |

| メソッド | 説明 |
|:--|:--|
| load_model()  |MLflowアーティファクトとして、当該トライアルで生成されたモデルをロード   |

# APIのサンプル

以下のノートブックを参考にしてください。

## AutoML分類のサンプルノートブック

[Databricks AutoML回帰サンプルノートブック](https://github.com/taka-yayoi/public_repo/tree/main/AutoML_regression)

## AutoML回帰のサンプルノートブック

[Databricks AutoML分類サンプルノートブック](https://github.com/taka-yayoi/public_repo/tree/main/AutoML_classification)

## AutoML予測のサンプルノートブック

[Databricks AutoML予測サンプルノートブック](https://github.com/taka-yayoi/public_repo/tree/main/AutoML_forecast)

# `databricks-automl-runtime`パッケージ

Databricksランタイム 9.1 LTS ML以降では、AutoMLはAutoML以外の有用なコンポーネントを含む`databricks-automl-runtime`に依存し、AutoMLトレーニングによって生成されるノートブックをシンプルにする支援を行います。`databricks-automl-runtime`は[PyPI](https://pypi.org/project/databricks-automl-runtime/)から利用できます。

# 制限

- 分類と回帰のみのサポートとなります。
- 以下の特徴量タイプのみをサポートしています。
    - 数値(ByteType, ShortType, IntegerType, LongType, FloatType, DoubleType)
    - ブール値
    - 文字列(カテゴリ変数のみ)
    - タイムスタンプ(TimestampType, DateType)
    - ArrayType[Numeric] (Databricks Runtime 10.4 LTS ML以降)
- 上記以外の画像のような特徴量タイプはサポートされていません。
- 同じ名称をカラムが複数あるデータセットはサポートされていません。
- Databricksランタイム9.0ML以下では、AutoMLのトレーニングはシングルノードで実行されます。トレーニングデータセットは単体のワーカーノードのメモリーに収まる必要があります。アウトオブメモリー問題に遭遇した場合には、より大きいメモリーを搭載するワーカーノードを使用してください。詳細は[クラスターの作成](https://qiita.com/taka_yayoi/items/d36a469a1e0c0cebaf1b)を参照ください。

    あるいは、可能な場合には、シングルワーカーノードのメモリーにデータセットが収まらない場合に自動でサンプリングを行うDatabricksランタイム 9.1 LTS ML以降を使用してください。

- Auto-ARIMAを使用するには、時系列データは定期的な頻度で生成されている必要があります(すなわち、時系列におけるいかなる2つのデータポイントは同じ間隔で発生する必要があります)。頻度はAPI呼び出しあるいはAutoMLのUIで指定される頻度ユニットとマッチする必要があります。AutoMLは欠損値がある場合、以前の値で補完することで欠損値に対応します。

### Databricks 無料トライアル

[Databricks 無料トライアル](https://databricks.com/jp/try-databricks)