assetframe-lib および ibm-watson-studio-lib ライブラリーのセットアップ

Python用ライブラリ「assetframe-lib」はプリインストールされており、watsonx.aiStudioのノートブックに直接インポートすることができます。 ただし、 ibm-watson-studio-lib ライブラリーに依存します。 以下のステップでは、両方のライブラリーをセットアップする方法について説明します。

プロジェクト・トークンをノートブックに挿入するには、以下のようにします。

1. ノートブックのツールバーにある「その他」アイコンをクリックして、「プロジェクト・トークンの挿入」をクリックします。

   プロジェクト・トークンが存在している場合、以下の情報が含まれたセルがノートブックに追加されます。

   from ibm_watson_studio_lib import access_project_or_space
   wslib = access_project_or_space({"token":"<ProjectToken>"})
   

   <ProjectToken> は、プロジェクト・トークンの値です。

   プロジェクト・トークンが存在しないというメッセージが表示された場合は、メッセージ内のリンクをクリックして、プロジェクトの「アクセス制御」ページにリダイレクトします。このページで、プロジェクト・トークンを作成できます。 プロジェクト・トークンを作成する資格がなければなりません。

   プロジェクト・トークンを作成するには、以下のようにします。

   1. 「管理」タブで、「アクセス制御」ページを選択し、「アクセス・トークン」の下の「新規アクセス・トークン」をクリックします。
   2. 名前を入力し、プロジェクトの「エディター」ロールを選択し、トークンを作成します。
   3. ノートブックに戻り、ノートブック・ツールバーの「その他」アイコンをクリックして、「プロジェクト・トークンの挿入」をクリックします。

2. assetframe-lib をインポートし、作成した ibm-watson-studio-lib インスタンスで初期化します。

   from assetframe_lib import AssetFrame
   AssetFrame._wslib = wslib
   

assetframe-lib の関数とメソッド

assetframe-lib ライブラリーは、以下のようにグループ化された関数およびメソッドのセットを公開します。

• アセット・フレームの作成
• フィーチャーの作成、取得、および削除
• フィーチャー属性の指定
  • 役割
  • 説明
  • 好ましい結果と好ましくない結果の公平性情報
  • モニター対象グループと参照グループの公平性情報
  • 値の説明
  • レシピ
  • タグ
• データのプレビュー
• 公平性情報の取得

アセット・フレームの作成

資産フレームは、既存のデータ資産または pandas DataFrame上のフィーチャー・グループ・メタデータを定義するために使用されます。 資産ごとに 1 つのフィーチャー・グループのみを持つことができます。 pandasDataFrame,上にアセットフレームを作成すると、フィーチャグループのメタデータと共に pandasDataFrameをデータアセットとしてプロジェクトに保存することができます。

以下のいずれかの機能を使用して、アセット・フレームを作成できます。

• AssetFrame.from_data_asset(asset_name, create_default_features=False)

  この機能は、プロジェクト内の既存のデータ資産をラップする新しい資産フレームを作成します。 この資産のフィーチャー・グループが既に存在する場合 (例えば、ユーザー・インターフェースで作成されている場合)、そのフィーチャー・グループは資産メタデータから読み取られます。

  IBM Knowledge Catalog などで、アセットに列の説明や列タグがすでに定義されている場合、この情報は作成されたフィーチャーで自動的に利用できるようになります。

  パラメーター:

  • asset_name: (必須) プロジェクト内のデータ・アセットの名前。
  • create_default_features: (オプション) データ資産内のすべての列に対してフィーチャーを作成します。

• AssetFrame.from_pandas(name, dataframe, create_default_features=False)

  この関数は、pandas DataFrameをラップする新規アセット・フレームを作成します。

  パラメーター:

  • name: (必須) アセット・フレームの名前。 この名前は、後のステップでフィーチャー・グループをプロジェクトに保管する場合に、データ資産の名前として使用されます。

  • dataframe: (必須) フィーチャー・グループ情報とともに保管する pandas の DataFrame 。

  • create_default_features: (オプション) データ・フレーム内のすべての列に対してフィーチャーを作成します。

    pandasDataFrame:からアセットフレームを作成する例：

    # Create an asset frame from a pandas DataFrame and set
    # the name of the asset frame.
    af = AssetFrame.from_pandas(dataframe=credit_risk_df, name="Credit Risk Training Data")
    

フィーチャーの作成、取得、および削除

フィーチャーは、下流のwatsonx.aiランタイムタスクで使用できるメタデータを定義します。 データ・セット内の列ごとに 1 つのフィーチャーを作成できます。

以下のいずれかの関数を使用して、資産フレームの列を作成、取得、または削除できます。

• add_feature(column_name, role='Input')

  この機能により、指定された役割を持つアセット・フレームに新しいフィーチャーが追加されます。

  パラメーター:

  • column_name: (必須) フィーチャーを作成する対象の列の名前。

  • role: (オプション) この機能の役割。 デフォルトは 「入力」です。
    

    有効な役割は以下のとおりです。
    

    • 「入力」: 機械学習モデルの入力
      
    • 「ターゲット」: 予測モデルのターゲット
      
    • ID: データ・セット内の行の ID。
      

• create_default_features()

  この関数は、データ・セット内のすべての列に対してフィーチャーを作成します。 特徴量の役割は、デフォルトで 「入力」になります。

• get_features()

  この関数は、資産フレームのすべてのフィーチャーを取得します。

• get_feature(column_name)

  この関数は、指定された列名のフィーチャーを取得します。

  パラメーター:

  • column_name: (必須) フィーチャーを作成する対象の列のストリング名。

• get_features_by_role(role)

  この関数は、指定された役割を持つデータ・フレームのすべてのフィーチャーを取得します。

  パラメーター:

  • role: (必須) フィーチャーが持つ必要がある役割。 これは、 「入力」、 「ターゲット」 、または 「ID」のいずれかです。

• remove_feature(feature_or_column_name)

  この機能により、資産フレームからフィーチャーが削除されます。

  パラメーター:

  • feature_or_column_name: (必須) フィーチャー、またはフィーチャーを削除する対象の列の名前。

データ・セット内のすべての列に対してフィーチャーを作成し、さらに指定するためにそれらの列の 1 つを取得する例を以下に示します。

# Create features for all columns in the data set and retrieve a column
# for further specifications.
af.create_default_features()
risk_feat = af.get_feature('Risk')

フィーチャー属性の指定

フィーチャーは、下流のwatsonx.aiRuntime タスクで使用される可能性のあるカラムの追加メタデータを指定します。

以下の関数を使用して、フィーチャーが定義されている列を取得できます。

• get_column_name()

  この関数は、フィーチャーが定義されている列名を取得します。

# Set the role of the feature 'Risk' to 'Target' to use it as a target in a prediction model.
risk_feat = af.get_feature('Risk')
risk_feat.set_roles('Target')

# Set favorable and unfavorable labels for the target feature 'Risk'.
risk_feat = af.get_feature('Risk')
risk_feat.set_favorable_labels("No Risk")
risk_feat.set_unfavorable_labels("Risk")

# Set monitored and reference groups for the features 'Sex' and 'Age'.
sex_feat = af.get_feature("Sex")
sex_feat.set_reference_groups("male")
sex_feat.set_monitored_groups("female")

age_feat = af.get_feature("Age")
age_feat.set_monitored_groups("[0,25]")
age_feat.set_reference_groups("[26,80]")

plan_feat = af.get_feature("InstallmentPlans")
val_descriptions = [
    {'value': 'stores',
     'description': 'customer has additional business installment plan'},
    {'value': 'bank',
     'description': 'customer has additional personal installment plan'},
    {'value': 'none',
     'description': 'customer has no additional installment plan'}
]
plan_feat.set_value_descriptions(val_descriptions)

データのプレビュー

公平性情報などの特徴量に関する追加情報を使用して、データ資産またはパンダ DataFrame のデータをプレビューできます。

データは、フィーチャーの役割、説明、またはレシピに関するオプションのヘッダー情報とともに、pandas DataFrame のように表示されます。 公平性情報は、好ましいラベルまたは好ましくないラベル、モニター対象グループ、および参照グループの色分けとともに表示されます。

現時点では、1 つのデータ資産に対して最大 100 行のサンプル・データを取得できます。

データをプレビューするには、以下の機能を使用します。

• head(num_rows=5, display_options=['role'])

  この関数は、pandas DataFrame内のデータ・セットの最初の num_rows 行を返します。

  パラメーター:

  • num_rows : (オプション) 取得する行の数。

  • display_options: (オプション) 列ヘッダーには、データ・セット内の列に関する追加情報を表示できます。

    フィーチャー属性を表示するには、以下のオプションを使用します。

    • role: この列の機能の役割を表示します。
    • description: この列の機能の説明を表示します。
    • recipe: この列のフィーチャーのレシピを表示します。

公平性情報の取得

資産フレーム内のすべての特徴量の公平性情報を Python 辞書として取得できます。 これには、保護属性としてモニター対象グループまたは参照グループ (あるいはその両方) を含むすべての特徴量と、好ましいラベルまたは好ましくないラベルを持つターゲット特徴量が含まれます。

公平性情報を持つ列のデータ・タイプが数値の場合、ラベルとグループの値は、可能であれば数値に変換されます。

フェアネス情報は、AutoAIまたはAIフェアネス360で直接使用することができます。

以下の関数を使用して、資産フレームの公平性情報を取得できます。

• get_fairness_info(target=None)

  この関数は、ターゲット列の好ましいラベルと好ましくないラベル、およびモニター対象グループと参照グループを持つ保護属性を含む Python ディクショナリーを返します。

  パラメーター:

  • target: (オプション) ターゲット・フィーチャー。 役割 Targetを持つ機能が 1 つしかない場合は、その機能が自動的に使用されます。

    公平性情報を取得する方法を示す例:

    af.get_fairness_info()
    

    公平性情報を示す出力:

    {
    'favorable_labels': ['No Risk'],
    'unfavorable_labels': ['Risk'],
    'protected_attributes': [
        {'feature': 'Sex',
        'monitored_group': ['female'],
        'reference_group': ['male']},
        {'feature': 'Age',
        'monitored_group': [[0.0, 25]],
        'reference_group': [[26, 80]]
        }]
    }
    

フィーチャー・グループ情報の保存

フィーチャーを完全に指定または更新した後、フィーチャー・グループ定義全体をデータ資産のメタデータとして保存できます。

pandasDataFrame,からアセットフレームを作成した場合、プロジェクトストレージにアセットフレームの名前で新しいデータアセットが作成されます。

フィーチャー・グループ情報を保管するには、以下の方法を使用できます。

• to_data_asset(overwrite_data=False)

  このメソッドは、フィーチャー・グループ情報を資産メタデータに保存します。 資産フレームが pandas DataFrameから作成された場合は、新しいデータ資産が作成されます。

  パラメーター:

  • overwrite_data: (オプション) アセット・フレームからのデータでアセット・コンテンツも上書きします。 デフォルトは Falseです。

もっと見る

リソース・ハブの「 フィーチャー・ストア・データの作成および使用 」サンプル・プロジェクトを参照してください。

親トピック: ノートブックでのデータのロードとアクセス