pandas互換性

FireDucksはpandasと同じAPI（クラス名やメソッド名，属性名）を提供し，インポート文の変更だけで利用できるという観点での互換性を目指しています．

互換性の考え方

以下のような観点での互換性は目指していません．

  • クラス名の完全な一致
    • FireDucksはfireducks.pandasというモジュールでpandas互換のAPIを提供します．モジュール名まで含めた完全なクラス名はpandasとは異なります．
    • 例えばデータフレーム型は，pandasではpandas.DataFrameですが，FireDucksではfireducks.pandas.DataFrameであり，完全には一致しません．そのためisinstance(df, pandas.DataFrame)といったpandasのDataFrameであるか否かの明示的なテストはFalseを返します．import fireducks.pandas as pd; isinstance(df, pd.DataFrame)であれば，Trueを返します．
  • エラーやWarningの完全な互換性
    • FireDucksは遅延実行を行っているため，エラーやWarningが発生するタイミングがpandasとは異なります．
    • エラーメッセージを一致させることは目標としていません（Exceptionクラスの一致は目標としています）．
    • WarningはFireDucksでは不要な場合もあるため，Warningが発生するか否かそのものがpandasと異なる動作となる場合があります．
  • 未定義動作やバグの完全な再現
    • いわゆる未定義動作やバグは，環境によって，またpandasの内部実装によって結果が異なる場合があります．そのようなpandasの内部実装に依存した動作の再現は目標としていません．
    • 特に，pandasではコピーを返すのか参照を返すのかが未定義な場合があり，どちらかに依存したコードを書くことはお薦めしません．Why does assignment fail when using chained indexing? も参照してください．
  • pandasの内部APIやExperimentalな機能
    • アンダースコア（_）から始まるメソッドや，pandasのドキュメントでExperimentalとされている機能の提供は目標としていません．
  • pandasを拡張する機能
    • Extending pandasで説明されているpandasを拡張する機能は現在のところ対象外です．
    • DataFrameやSeriesのサブクラスを作る機能や，ユーザー独自のデータ型を定義する機能などのことです．
  • merge/join結果における行の順序のpandasとの一致
    • FireDucksでは処理速度を優先しているため，merge/joinの結果の行の順序はpandasと一致しない場合があります．必要に応じてソートしましょう．

pandasとの併用

pandasの内部では，上で述べた内部APIやisinstanceによるチェックが頻繁に使われています．したがって，pandasとFireDucksの併用は大抵の場合うまく動きません． 全てのインポート文を書き換えるか，インポートフックによる自動変換を利用し，FireDucksに統一することをお薦めします．

何らかの理由でpandasと併用したり，pandasのDataFrameやSeriesを受け取るライブラリにpandasのデータとして渡したい場合には，pandasとの変換機能を利用してください．

import somelib
import fireducks.pandas as pd

df = pd.read_csv(...)
somelib.process_pandas_dataframe(df.to_pandas())