pandas.json_normalize の使い方とトラブルシューティング

2025-01-18

pandas.json_normalize の解説

pandas.json_normalize は、pandas ライブラリにおいて、複雑な JSON データをフラットな DataFrame に変換する便利な関数です。この関数を使うことで、JSON データをより扱いやすく、分析しやすい形式に変換することができます。

基本的な使い方

import pandas as pd

# JSON データの例
data = [
    {'id': 1, 'name': 'Alice', 'address': {'street': '123 Main St', 'city': 'New York'}},
    {'id': 2, 'name': 'Bob', 'address': {'street': '456 Elm St', 'city': 'Los Angeles'}}
]

# JSON データを DataFrame に変換
df = pd.json_normalize(data)

このコードを実行すると、以下の DataFrame が生成されます:

idnameaddress.streetaddress.city
01Alice123 Main StNew York
12Bob456 Elm StLos Angeles

主なパラメータ

  • sep: ネストされたキーをフラット化する際のセパレータを指定します。
  • meta: レコードパス以外の情報を DataFrame の列として追加します。
  • record_path: JSON データ内のリストや辞書のパスを指定します。
data = [
    {'id': 1, 'name': 'Alice', 'orders': [{'product': 'A', 'quantity': 2}, {'product': 'B', 'quantity': 1}]},
    {'id': 2, 'name': 'Bob', 'orders': [{'product': 'C', 'quantity': 3}]}
]

# レコードパスを指定してネストされたデータをフラット化
df = pd.json_normalize(data, record_path=['orders'], meta=['id', 'name'])
productquantityidname
0A21Alice
1B11Alice
2C32Bob


pandas.json_normalize のよくあるエラーとトラブルシューティング

pandas.json_normalize は強力なツールですが、複雑な JSON 構造やデータの不整合により、エラーが発生することがあります。以下に、一般的なエラーとトラブルシューティングの方法を説明します。

KeyError

  • 解決方法
    • JSON データの構造を再度確認し、レコードパスの指定が正しいかを確認してください。
    • meta パラメータを使用して、必要な情報を抽出してください。
  • 原因
    指定したレコードパスが存在しない場合に発生します。

ValueError

  • 解決方法
    • JSON データの構文エラーがないか確認してください。
    • レコードパスの指定が正しいか確認してください。
    • 必要に応じて、JSON データを前処理して正しいフォーマットに整形してください。
  • 原因
    JSON データが不正なフォーマットである場合や、レコードパスが適切に指定されていない場合に発生します。

TypeError

  • 解決方法
    • レコードパスの指定が正しいか確認してください。
    • データ型が一致するように、必要に応じてデータ変換を行ってください。
  • 原因
    データ型が一致しない場合や、レコードパスが適切に指定されていない場合に発生します。
  • デバッグの活用
    • デバッガを使用して、コードの実行をステップごとに追跡し、問題を特定してください。
    • print 文を使用して、変数の値を確認してください。
  • 段階的なアプローチ
    • 複雑な JSON データを段階的に処理し、問題を特定しやすくしてください。
    • 小さな部分から始めて、徐々に複雑な処理に移行してください。
  • エラーメッセージの確認
    • エラーメッセージをよく読み、原因を特定してください。
    • スタックトレースを確認することで、エラーが発生したコードの箇所を特定できます。
  • JSON データの検査
    • JSON データの構造を理解し、レコードパスを適切に指定してください。
    • JSONLint などのツールを使用して、JSON データの構文エラーをチェックしてください。


pandas.json_normalize の具体的なコード例

基本的な例

import pandas as pd

# JSON データ
data = [
    {'id': 1, 'name': 'Alice', 'address': {'street': '123 Main St', 'city': 'New York'}},
    {'id': 2, 'name': 'Bob', 'address': {'street': '456 Elm St', 'city': 'Los Angeles'}}
]

# JSON データを DataFrame に変換
df = pd.json_normalize(data)

print(df)

このコードは、ネストされた JSON データをフラットな DataFrame に変換します。出力は次のようになります:

idnameaddress.streetaddress.city
01Alice123 Main StNew York
12Bob456 Elm StLos Angeles

ネストされたリストの処理

data = [
    {'id': 1, 'name': 'Alice', 'orders': [{'product': 'A', 'quantity': 2}, {'product': 'B', 'quantity': 1}]},
    {'id': 2, 'name': 'Bob', 'orders': [{'product': 'C', 'quantity': 3}]}
]

# レコードパスを指定してネストされたデータをフラット化
df = pd.json_normalize(data, record_path=['orders'], meta=['id', 'name'])

print(df)

このコードは、orders リスト内の各要素を個別の行として展開し、idname をメタデータとして保持します。出力は次のようになります:

productquantityidname
0A21Alice
1B11Alice
2C32Bob
data = [
    {'id': 1, 'name': 'Alice', 'items': [{'product': 'A', 'price': 10}, {'product': 'B', 'price': 20}]},
    {'id': 2, 'name': 'Bob', 'items': [{'product': 'C', 'price': 15}]}
]

# レコードパスとメタデータを指定してフラット化
df = pd.json_normalize(data, record_path=['items'], meta=['id', 'name'])

print(df)
productpriceidname
0A101Alice
1B201Alice
2C152Bob


pandas.json_normalize 以外の代替方法

pandas.json_normalize は JSON データを DataFrame に変換する強力なツールですが、場合によっては、他の方法も検討することができます。以下に、いくつかの代替方法を紹介します。

手動での DataFrame 作成

  • シンプルで直接的なアプローチ
    • JSON データを解析し、必要な情報を抽出して、直接 DataFrame を作成します。
    • 複雑な JSON 構造の場合、コードが冗長になる可能性があります。
import pandas as pd

data = [
    {'id': 1, 'name': 'Alice', 'address': {'street': '123 Main St', 'city': 'New York'}},
    {'id': 2, 'name': 'Bob', 'address': {'street': '456 Elm St', 'city': 'Los Angeles'}}
]

df = pd.DataFrame(columns=['id', 'name', 'street', 'city'])
for item in data:
    df = df.append({'id': item['id'], 'name': item['name'], 'street': item['address']['street'], 'city': item['address']['city']}, ignore_index=True)

print(df)

Python の標準ライブラリ

  • 柔軟性のあるアプローチ
    • json モジュールを使用して JSON データを解析し、必要な情報を抽出して、リストや辞書に変換します。
    • その後、pandas.DataFrame() を使用して DataFrame を作成します。
import json
import pandas as pd

with open('data.json', 'r') as f:
    data = json.load(f)

df = pd.DataFrame(data)

print(df)
  • 特定のユースケースに特化したアプローチ
    • jq
      コマンドラインツールで、JSON データをフィルタリング、変換、フォーマットすることができます。
    • jsonpath-ng
      Python ライブラリで、JSON データをXPathのようにクエリすることができます。