meridian-model-building

Meridian モデル構築スキル

このスキルでは、Meridian モデルを作成するプロセスを案内し、 コードを Python スクリプトにまとめます。

基本ワークフロー

対話型チェックポイントのルール

このワークフローでは、重要な対話型 チェックポイントが複数回あります。各チェックポイントでは、必ず次の操作を行ってください。

1. 現在の設定案、パラメーター、マッピング、スクリプトの パス、またはステータスをユーザーに提示し、承認を求めます。
2. 利用可能なユーザー対話ツール（例：ask_question）を使用して、 多肢選択式の質問として、続行する準備ができているかユーザーに尋ねます。生のチャットテキストは使用しないでください。
3. 続行する前に、ユーザーの回答を待ちます。
   • 必須: 最初のプロンプトの指示にかかわらず、すべてのチェックポイントで必ず 一時停止してください（ユーザーのリクエストに「自律的に実行」 「直接実行」「自律的に修正」などの表現が含まれている場合も同様です）。 最初のリクエストによって、これらの対話型チェックポイントを省略することはできません。
   • 注: チェックポイントで「続行して」「最善だと思う方法で進めて」などの一般的な承認をユーザーが返した場合は、提案したデフォルトを使用して続行してください。

Python 環境と Meridian のソース

Python を実行する前に、google-meridian がインストールされている環境のインタープリターを選び、以下のすべてのコマンドとスクリプトで使用してください。

1. ユーザーが環境を指定した場合は、それを使用してください。指定がなく、仮想環境がすでにアクティブな場合（VIRTUAL_ENV または CONDA_PREFIX が設定されている場合）は、 python3 を使用してください。それ以外の場合、プロジェクトディレクトリ（現在の作業ディレクトリ）に仮想環境（.venv/ または venv/）がある場合は、 そのインタープリター（例：.venv/bin/python3）を使用してください。それ以外の場合は、python3 を使用してください。
2. <interpreter> -c "import meridian" で確認してください。失敗した場合は、マシン内を検索したり、許可なくパッケージをインストールしたりせず、代わりにどの環境を使用するかユーザーに尋ねてください。

以下の手順では、引数名やデフォルト値を確認するために、Meridian モジュール（例：meridian.model.spec）を読み取るよう求められます。ユーザーは通常、Meridian を PyPI からインストールするため（pip install google-meridian）、ソースはプロジェクトフォルダー内にはありません。インストール済みパッケージを見つけてそのファイルを読むか、inspect でシグネチャと docstring を出力してください。

<interpreter> -c "import meridian, os; print(os.path.dirname(meridian.__file__))"

---

1. 初期設定

• 入力 CSV ファイルのパス、生成する Python スクリプトの保存先、EDA HTML レポートの出力先、および保存するモデルのパス（デフォルトは meridian_model.binpb）をユーザーに尋ねます。出力先のパスが指定されていない場合は、スクリプトとすべての出力（meridian_model.binpb、eda.html）の保存先として、アクティブなプロジェクトディレクトリ（または入力データディレクトリからの相対パス）に model_build/ を設定します。
• 重要な対話型チェックポイント: データを読み込む前に、収集したパスをユーザーに提示し、確認を得ます。

2. データ読み込みと列マッピングのコードを追加する

• 対象モジュール: meridian.data.data_frame_input_data_builder
• アクション:
  • CSV 形式を確認する: データを読み込む前に、CSV データが正しい形式であることを確認します。meridian-doc-consultant スキルを使って、データ内で確認された列に合致する developers.google.com/meridian のデータ読み込みガイドを見つけます（例:「リーチとフリークエンシーを含まない地域レベルのデータを読み込む」または「オーガニックデータと非メディアデータを含む地域レベルのデータを読み込む」ガイド）。期待される列とデータ型を把握するために、references/csv_format_reference.md で期待される行・列の構造とデータ品質のガードレールを確認します。形式が正しくない場合や必須列がない場合は、確信が持てずユーザーへの確認が必要な場合を除き、ユーザーのためにデータセットを期待される形式に自動変換することを試みます（例: 列名の変更、構造の再編成）。
  • Python を使って、提供された CSV のヘッダー行を読み取り、列名を取得します。
  • 列のキーワードに基づいてヒューリスティックなマッピングを提案します（例: 'sales' → kpi_col、'spend' → media_spend_cols）。また、列に基づいて kpi_type（'revenue' または 'non_revenue'）を推定します（例: 'revenue' や 'sales' は 'revenue' を示し、'conversions' や 'leads' は 'non_revenue' を示します）。
  • 堅牢なマッピング: ユーザーのプロンプトで、CSV に存在しない列名へのマッピングが指定されている場合、その名前が説明のように見えるなら、文字どおりの列名だと決めつけないでください（例: 'media_impressions' と 'ChannelX_impression'）。ヒューリスティックを使って一致する列を見つけ、そのまま処理を進めます。
  • 提案するマッピングをユーザーに提示します。
  • 重要な対話チェックポイント: 提案する列マッピングをユーザーに提示し、モデル設定に進む前に承認を得ます。
  • meridian.data.data_frame_input_data_builder.DataFrameInputDataBuilder とその with_* メソッド（例: with_kpi、with_media）を使って、データ読み込みコードを組み立てます。data_builder_template.md を参照してください。

3. モデル設定コードを追加する

• 対象モジュール: meridian.model.spec、meridian.model.model
• アクション:
  • meridian.model.spec の ModelSpec と PriorDistribution の定義を読みます。
  • 設定についてユーザーを案内し、ソースコードの docstring に基づいて各値の目的を説明しながら、関連する値を尋ねます。
  • 重要な対話チェックポイント: 提案するモデル仕様のパラメーターをユーザーに提示し、続行する前に承認を得ます。
  • meridian.model.spec.ModelSpec と meridian.model.model.Meridian を初期化するコードを組み立てます。model_spec_template.md を参照してください。
  • コード mmm.sample_prior() を組み立てます。

4. 探索的データ分析（EDA）コードを追加する

• 対象モジュール: meridian.model.eda.meridian_eda
• アクション:
  • generate_and_save_report メソッドを確認するために、meridian_eda.py またはモジュールの docstring を読みます。
  • meridian_eda.MeridianEDA を初期化し、ユーザーが指定したパスを使って generate_and_save_report(filepath) を呼び出すコードを組み立てます。
  • 重要な対話チェックポイント: EDA の出力パス設定をユーザーに提示し、モデルのフィッティングに進む前に承認を得ます。

5. モデルフィッティングコードを追加する

• 対象モジュール： meridian.model.model
• 操作：
  • meridian.model.model の sample_posterior メソッドを読み、パラメーターを確認します。
  • MCMC パラメーター n_chains、n_adapt、n_burnin、n_keep をユーザーに確認します。
  • 重要な対話型チェックポイント：モデルフィッティングコードのコンパイルに進む前に、MCMC パラメーターをユーザーに提示して承認を得ます。
  • コードを追加します：mmm.sample_posterior(...)

6. モデル保存コードを追加する

• 対象モジュール： meridian.schema.serde.meridian_serde
• 操作：
  • meridian_serde.save_meridian() を使って、ユーザー指定のパス（またはデフォルトのパス）にモデルを保存するコードを生成します。script_template.md を参照してください。
  • デフォルトのファイル名：保存するモデルのデフォルトのファイル名は meridian_model.binpb（model_build/ ディレクトリ内）です。ユーザーがモデルのファイル名を指定しない場合、スクリプトファイルの名前が異なっていても、このファイル名を使用します。
  • サンプリングをスキップする場合の処理：ユーザーがフィッティングまたは事後サンプリングのスキップを希望した場合でも、初期化済みの Meridian モデルオブジェクトを使って、モデル保存の手順（meridian_serde.save_meridian(mmm, save_path)）を含め、出力モデルファイルが必ず作成されるようにします。
  • 警告： 非推奨の meridian.model.model.save_mmm 関数は使用しないでください。meridian_serde.save_meridian のみを使用します。
  • 重要な対話型チェックポイント：スクリプトの実行に進む前に、モデルの保存先パスとファイル名をユーザーに提示して承認を得ます。

7. 実行とスクリプトの設定

• 操作：
  • 作成した Python スクリプトをユーザー指定のパスに書き込みます。ファイル書き込みツールでユーザーに書き込んだファイルの確認を求められる場合は、その確認を求めないでください。次のチェックポイントで承認を求めるため、確認を追加するとワークフローが中断されます。
  • 重要な対話型チェックポイント：モデル構築スクリプトを今すぐ実行してよいか、ユーザーに最終確認を求めます。
  • 成果物の保持：スクリプト、モデル、レポートなど、出力の生成を伴うタスクを完了する際は、ターンの終了時に生成した成果物を削除しないでください。これらはユーザーが求めた納品物です。必要な場合に限り、本当に一時的な作業ファイルを削除します。
    • 出力パスの処理：生成するスクリプトでは、ステップ 1 で確認した出力パスを、スクリプトの実行元であるプロジェクトディレクトリからの相対パス（または絶対パス）として使用します。
  • スクリプトを実行する：
    • 相対パスが確認どおりに解決されるよう、スクリプトは必ずサブディレクトリではなくプロジェクトディレクトリを作業ディレクトリとして実行します。
    • 上記の「Python 環境と Meridian のソース」で選択したインタープリターを使用します。
    • コマンドの例：.venv/bin/python3 model_build/my_model.py
  • 長時間実行の処理：実行時間のためにコマンドがバックグラウンドに送られた場合は、バックグラウンドタスクが完了するまで待ち、最終出力を確認して実行時エラーを検出します。
  • エラーの種類に応じた処理：
    • 構文エラーまたはインポートエラーの場合は、関連するソースコードを読み、正しい使い方やインターフェースを確認します。
    • ValueError またはパラメーター制約違反（例：knots が大きすぎる）の場合は、クラスや関数のdocstringを確認するか、meridian-doc-consultant スキルを参照して、ドキュメントに記載された有効な値を確認します。
    • 自律性：修正に設定変更が必要な場合は、ユーザーに確認を求めます。ユーザーの応答で自律的な対応が認められた場合は、修正を進めます。

8. 結論

• アクション：
  • 実行が成功し、成果物が生成されたことを確認します。