scrapbook
1.0.0
スクラップブックライブラリは、ノートブックのデータ値と生成されたビジュアル コンテンツを「スクラップ」として記録します。記録されたスクラップは後で読み取ることができます。
スクラップブックの使用方法の詳細については、スクラップブックのドキュメントを参照してください。
ノートブックのユーザーは、ノートブックの実行中に生成されたデータを記録したい場合があります。この記録されたデータであるスクラップは、後で使用したり、ワークフローで入力として別のノートブックに渡すことができます。
つまり、スクラップブックを使用すると次のことが可能になります。
データを永続化し、ビジュアルコンテンツをスクラップとしてノートブックに表示します
永続化されたデータのスクラップをすべて呼び出す
ノートのコレクションを要約する
このライブラリの長期サポート対象は Python 3.6 以降です。現在、Python 2 が 2020 年にサポート終了になるまで、Python 2.7 もサポートしています。この日以降、Python 2 のサポートは停止され、3.x バージョンのみが維持されます。
pip使用してインストールします。
pip install scrapbookオプションの IO 依存関係をインストールするには、 s3やazureなどの個別のストア バンドルを指定できます。
pip install scrapbook[s3]またはallを使用します:
pip install scrapbook[all]Scrapbook では次の項目が定義されます。
スクラップ: 文字列、オブジェクトのリスト、パンダのデータフレーム、チャート、画像、データ参照などのシリアル化可能なデータ値と視覚化。
Notebook : スクラップと対話するための追加メソッドを備えた、ラップされた nbformat ノートブック オブジェクト。
スクラップブック: コレクションについて質問するためのインターフェイスを備えたノートブックのコレクション。
エンコーダ: ノートブックのストレージ形式への、またはノートブックのストレージ形式からのデータの登録済みトランスレータ。
scrapモデルscrapモデルには、次のようないくつかの主要な属性がタプルに格納されています。
name : スクラップの名前
data : スクラップブック API 呼び出しによってキャプチャされた任意のデータ
encoder : ノートブックとの間でデータをエンコード/デコードするために使用されるエンコーダーの名前
display : ビジュアルコンテンツを表示するために IPython によって使用される表示データ
Scrapbook には、データの保存と取得を可能にするいくつかの基本的な API コマンドが追加されています。
表示出力の有無にかかわらずスクラップを保持するためのglue
read_notebook 1 つのノートブックを読み取ります
scrapsすべてのスクラップを名前で検索できる辞書を提供します
別のノートブックから現在のノートブックにスクラップをコピーするreglue
read_notebooks指定されたパスから多くのノートブックを読み取ります
scraps_report収集されたスクラップに関するレポートを表示します
papermill_dataframeとpapermill_metrics 、非推奨の 2 つの製紙工場機能の下位互換性を実現します。
次のセクションでは、これらの API コマンドについて詳しく説明します。
glue指定されたノートブックのセルにscrap (データまたは表示値) を記録します。
scrap (記録された値) は、出力されたノートブックを後で検査するときに取得できます。
"""データ値を記録するためのグルーの例"""スクラップブックを sbsb.glue("hello", "world")sb.glue("number", 123)sb.glue("some_list", [1, 3, 5])sb.glue("some_dict", {"a": 1, "b": 2})sb.glue("non_json", df, 'arrow')スクラップブック ライブラリは、後で出力ノートブックからscraps復元するために使用できます。
# ノートブックを読んで以前に記録したスクラップを取得するnb = sb.read_notebook('notebook.ipynb')nb.scrapsスクラップブックは、登録されたデータ エンコーダーの値のタイプによってストレージ形式を暗黙的に示します。あるいは、 encoder引数を特定のエンコーダの登録名 (例: "json" ) に設定することで、暗黙のエンコード形式を上書きすることもできます。
このデータは、コンテンツのエンコード形式とデータを識別する特別なメディア タイプで表示出力を生成することによって保持されます。これらの出力はノートブックのレンダリングでは常に表示されるわけではありませんが、ドキュメント内には依然として存在します。 Scrapbook は、これらのセル出力を読み取ることで、将来的にノートブックに関連付けられたデータを再表示できます。
名前付きスクラップを表示出力とともに表示するには、スクラップが直接レンダリング可能であることを示す必要があります。
これは、 display引数を切り替えることで実行できます。
# 入力文字列とともに UI メッセージを記録しますb.glue("hello", "Hello World", display=True)この呼び出しにより、Scrap オブジェクトのデータと表示属性が保存され、元のデータがエンコードされるだけでなく、表示されるようになります。これは、 IPython.core.formatters.format_display_data関数を利用して、ノートブック カーネルが解析するためにデータ オブジェクトを表示およびメタデータ辞書に変換します。
使用できるもう 1 つのパターンは、元のオブジェクトではなく、表示データのみを保存するように指定することです。これは、エンコーダをdisplayに設定することによって実現されます。
# 元の入力オブジェクトなしで画像を記録しますb.glue("sharable_png", IPython.display.Image(filename="sharable.png"), encoder='display')最後に、リスト、タプル、または dict オブジェクトを表示引数として渡すことによって、生成されるメディア タイプを制御できます。
sb.glue("media_as_text_only", media_obj, encoder='display', display=('text/plain',) # これは [text/plain] を format_display_data の include 引数に渡します)sb.glue("media_without_text", media_obj, encoder ='display', display={'exclude': 'text/plain'} # 転送先format_display_data の kwargs)データ スクラップと同様に、これらはスクラップのdisplay属性にアクセスすることで後で取得できます。ただし、通常は Notebook のreglueメソッド (後述) を使用するだけです。
read_notebook 1 つのノートブックを読み取りますpathで指定された場所からロードされた Notebook オブジェクトを読み取ります。この関数が上記の API 呼び出しの例でどのように使用されるかはすでに説明しましたが、本質的にこれは、スクラップブックのスクラップを抽出する機能を備えたnbformatの NotebookNode の薄いラッパーを提供します。
nb = sb.read_notebook('notebook.ipynb')この Notebook オブジェクトは nbformat の json スキーマに準拠しており、必要なフィールドへのアクセスが可能です。
nb.cells # ノートブックのセルnb.metadatanb.nbformatnb.nbformat_minor
追加のメソッドがいくつか提供されており、そのほとんどについては以下で詳しく説明します。
nb.scrapsnb.reglue
また、抽象化により、保存されたコンテンツを各キーとソースを参照するデータフレームとして利用できるようになります。これらのメソッドの多くは、今後のバージョンで利用できるようになる予定です。
# ["name"、"data"、"encoder"、"display"、"filename"] を列として持つデータ フレームを生成しますnb.scrap_dataframe # 警告: データまたは表示が大きい場合、これは大きなオブジェクトになる可能性があります
Notebook オブジェクトには、製紙工場の Notebook オブジェクト モデルとの下位互換性を保つためのレガシー関数もいくつかあります。その結果、製紙工場の実行統計やスクラップブックの抽象化を読み取るために使用できます。
nb.cell_timing # セル順序内のセル実行タイミングのリストnb.execution_counts # セル順序内のセル実行回数のリストnb.papermill_metrics # セルの実行回数と時間のデータフレームnb.papermill_record_dataframe # ノートブック レコードのデータフレーム (データのみのスクラップ)nb.parameter_dataframe #ノートブック パラメーターのデータフレームnb.papermill_dataframe # ノートブック パラメーターとセル スクラップのデータフレーム
ノートブック リーダーは、製紙工場の登録済み iorw に依存して、S3、Azure、Google Cloud など (ただしこれらに限定されない) さまざまなソースへのアクセスを可能にします。
scraps名前を提供します -> スクラップ検索scrapsメソッドを使用すると、特定のノートブック内のすべてのスクラップにアクセスできます。
nb = sb.read_notebook('notebook.ipynb')nb.scraps # すべてのスクラップの辞書を名前別に出力しますこのオブジェクトには、変換と実行に便利な追加のメソッドもいくつかあります。
nb.scraps.data_scraps # `data` を持つスクラップのみにフィルタリングしますnb.scraps.data_dict # `data_scraps` を `name` -> `data` にマップしますnb.scraps.display_scraps # `display` を持つスクラップのみにフィルタリングしますnb. craps.display_dict # `display_scraps` を `name` にマップします-> `display` dictnb.scraps.dataframe # ["name", "data", "encoder", "display"] を列として含むデータフレームを生成します
これらのメソッドを使用すると、モデルの抽象化を詳しく調べる必要のない単純なユースケースが可能になります。
reglueスクラップを現在のノートブックにコピーしますreglue使用すると、1 つのノートに貼り付けられたスクラップを取り込み、現在のノートに貼り付けることができます。
nb = sb.read_notebook('notebook.ipynb')nb.reglue("table_scrap") # これにより、データと表示の両方がコピーされますすべてのデータまたは表示情報は、ユーザーが元のソース上で再びglue呼び出したかのように、現在実行中のノートブックにそのままコピーされます。
途中でスクラップの名前を変更することも可能です。
nb.reglue("テーブルスクラップ", "古いテーブルスクラップ")そして最後に、存在を確認せずに再接着を試みたい場合は、失敗時にメッセージを表示するようにraise_on_missing設定できます。
nb.reglue("maybe_missing", raise_on_missing=False)# => "このノートブックには「maybe_missing」という名前のスクラップは見つかりませんでした"read_notebooks多くのノートブックを読み取ります指定されたpathにあるすべてのノートブックを Scrapbook オブジェクトに読み取ります。
# `book`book = sb.read_notebooks('path/to/notebook/collection/')という名前のスクラップブックを作成します# 基になるノートブックを listbook.notebooks として取得します # または `book.values`このパスは、製紙工場の登録済みiorw再利用して、さまざまなソースからファイルをリストし、読み取ります。これにより、ローカル以外の URL でデータをロードできるようになります。
# `book`book = sb.read_notebooks('s3://bucket/key/prefix/to/notebook/collection/') という名前のスクラップブックを作成しますスクラップブック (この例ではbook ) を使用して、ノートブックのコレクション全体のすべてのスクラップを呼び出すことができます。
book.notebook_scraps # 形状 `notebook` -> (`name` -> `scrap`)book.scraps # 形状 `name` -> `scrap` の辞書を結合
scraps_report収集されたスクラップに関するレポートを表示しますScrapbook コレクションを使用すると、コレクションのすべてのスクラップについて、マークダウン構造の出力としてscraps_report生成できます。
book.scraps_report()
この表示では、スクラップ名とノートブック名をフィルターしたり、表示全体のヘッダーを有効または無効にしたりできます。
book.scraps_report(scrap_names=["scrap1", "scrap2"], Notebook_names=["result1"], # `/notebook/collections/result1.ipynb` パスのノートブックに一致します ヘッダー=False)
デフォルトでは、レポートには視覚的な要素のみが入力されます。データ要素についてもレポートするには、include_data を設定します。
book.scraps_report(include_data=True)
最後に、スクラップブックは、非推奨のpapermill機能に対して下位互換性のある 2 つの機能を提供します。
book.papermill_dataframebook.papermill_metrics
エンコーダーは、 encoders.registryオブジェクトに対して登録された Encoder オブジェクトにキー名によってアクセスできます。新しいデータ エンコーダを登録するには、次を呼び出すだけです。
エンコーダから encoder_registry としてレジストリをインポート # registryencoder_registry.register("custom_encoder_name", MyCustomEncoder()) にエンコーダを追加しますencode クラスは、 encodeとdecode 2 つのメソッドを実装する必要があります。
class MyCustomEncoder(object):def encode(self,scrap):# scrap.data は任意の型で、通常はエンコーダのネームパスに固有です # `data` 型を持つ `Scrap` を返します [None, list, dict, *six] のいずれかの型を返します.integer_types, *six.string_types]def decode(self,crack):#scrap.data は [None, list, dict, *six.integer_types, *six.string_types]pass # `data` 型の `Scrap` を任意の型として返します（通常はエンコーダ名に固有）
これにより、変換スクラップをその内容または場所を表す json オブジェクトに読み取り、それらの文字列を元のデータ オブジェクトにロードして戻すことができます。
textデータを Python 文字列として保存する基本的な文字列保存形式。
sb.glue("こんにちは", "世界", "テキスト")json sb.glue("foo_json", {"foo": "bar", "baz": 1}, "json")pandas sb.glue("pandas_df",pd.DataFrame({'col1': [1, 2], 'col2': [3, 4]}), "pandas")record機能スクラップブックは、堅牢で柔軟な記録スキーマを提供します。このライブラリは、製紙工場の既存のrecord機能を置き換えます。
製紙工場のrecordに関するドキュメントは ReadTheDocs にあります。簡単に言うと、非推奨のrecord関数は次のとおりです。
pm.record(name, value) : 値をノートブックに保存できるようにします [API ドキュメント]
pm.record("hello", "world")pm.record("number", 123)pm.record("some_list", [1, 3, 5])pm.record("some_dict", {"a" : 1、「b」: 2}) pm.read_notebook(notebook) : 後でパンダを使用して、出力ノートブックをデータフレームに読み取ることで記録された値を回復できます。例えば：
nb = pm.read_notebook('notebook.ipynb')nb.dataframerecord廃止の根拠Papermill のrecord機能は、次の制限と課題のため非推奨になりました。
record機能は、ノートブックを直線的に実行する製紙工場のパターンに従っていませんでした。 record製紙工場の追加機能として説明するのはぎこちなく、実際には 2 つ目のあまり開発されていないライブラリを説明しているように感じました。
記録/読み取りに必要なデータはすべて JSON に変換されます。これはデータフレームにとって退屈で面倒なプロセスです。
記録された値をデータフレームに読み取ると、データフレームの形状が直感的ではなくなります。
カスタム オペレーターを登録できる他の製紙工場コンポーネントに比べて、モジュール性と柔軟性が低くなります。
Papermill のこれらの制限を克服するために、 Scrapbook を作成することが決定されました。
