データのイテレーター

NNabla では学習のためのデータ使用に関する様々なユーティリティを提供しています。

DataSource

class nnabla.utils.data_source.DataSource(shuffle=False, rng=None)[ソース]

ベースクラス: object

本クラスはデータソース用の様々なプロパティとメソッドを含んでおり、 DataIterator で利用されます。

パラメータ:

shuffle (bool) -- データセットがシャッフルされるか否かを示します。
rng (None or numpy.random.RandomState) -- Numpy 乱数ジェネレーター。

apply_order()[ソース]: This function is called when a batch is finished and an epoch is finished. It is time for update the order if shuffle is true.

property position

現在のエポックでのデータの位置。

戻り値:: データの位置
戻り値の型:: int

property shuffle

データセットがシャッフルされたか否か。

戻り値:: データセットがシャッフルされた否か。
戻り値の型:: bool

property variables

データの変数名。

戻り値:: 変数名のタプル
戻り値の型:: tuple

class nnabla.utils.data_source.DataSourceWithFileCache(data_source, cache_dir=None, cache_file_name_prefix='cache', shuffle=False, rng=None)[ソース]

ベースクラス: DataSource

本クラスはキャッシュファイルから読み取ることができるデータソース用の様々なプロパティとメソッドを含んでおり、データのイテレーターで利用されます。

パラメータ:

data_source (DataSource) -- データを提供する DataSource クラスのインスタンスです。
cache_dir (str) -- file_cache の場所。この値が None の場合、 data_source.DataSourceWithFileCache がファイルキャッシュを暗黙的に一時ディレクトリに作成し、data_iterator 終了時にすべて消去します。そうでない場合は、 data_source.DataSourceWithFileCache がキャッシュファイルを生成し続けます。デフォルトは None です。
cache_file_name_prefix (str) -- キャッシュファイルのファイル名の先頭文字列です。デフォルトは 'cache' です。
shuffle (bool) -- データセットがシャッフルされるか否かを示します。
rng (None or numpy.random.RandomState) -- Numpy 乱数ジェネレーター。

apply_order(): This function is called when a batch is finished and an epoch is finished. It is time for update the order if shuffle is true.

property position

現在のエポックでのデータの位置。

戻り値:: データの位置
戻り値の型:: int

property shuffle

データセットがシャッフルされたか否か。

戻り値:: データセットがシャッフルされた否か。
戻り値の型:: bool

property variables

データの変数名。

戻り値:: 変数名のタプル
戻り値の型:: tuple

class nnabla.utils.data_source.DataSourceWithMemoryCache(data_source, shuffle=False, rng=None)[ソース]

ベースクラス: DataSource

本クラスはメモリキャッシュから読み取ることができるデータソース用の様々なプロパティとメソッドを含んでおり、データのイテレーターで利用されます。

パラメータ:

data_source (DataSource) -- データを提供する DataSource クラスのインスタンスです。
shuffle (bool) -- データセットがシャッフルされるか否かを示します。
rng (None or numpy.random.RandomState) -- Numpy 乱数ジェネレーター。

apply_order(): This function is called when a batch is finished and an epoch is finished. It is time for update the order if shuffle is true.

property position

現在のエポックでのデータの位置。

戻り値:: データの位置
戻り値の型:: int

property shuffle

データセットがシャッフルされたか否か。

戻り値:: データセットがシャッフルされた否か。
戻り値の型:: bool

property variables

データの変数名。

戻り値:: 変数名のタプル
戻り値の型:: tuple

DataIterator

class nnabla.utils.data_iterator.DataIterator(data_source, batch_size, rng=None, use_thread=True, epoch_begin_callbacks=[], epoch_end_callbacks=[], stop_exhausted=False)[ソース]

ベースクラス: object

data_source からデータを収集し、大量のデータを生成します。

パラメータ:

data_source (DataSource) -- 本クラスにデータを提供する DataSource クラスのインスタンスです。
batch_size (int) -- データユニットのサイズ。
rng (None or numpy.random.RandomState) -- Numpy 乱数ジェネレーター。
use_thread (bool) -- If use_thread is set to True, iterator will use another thread to fetch data. If use_thread is set to False, iterator will use current thread to fetch data.
epoch_begin_callbacks (list of functions) -- 1 つの項目が 1 つの関数であり、エポックインデックスを引数として取ります。これらはエポックの開始時に呼び出されます。
epoch_end_callbacks (list of functions) -- 1 つの項目が 1 つの関数であり、エポックインデックスを引数として取ります。これらはエポックの終了時に呼び出されます。
stop_exhausted (bool) -- If stop_exhausted is set to False, iterator will be reset so that iteration can be continued. If stop_exhausted is set to True, iterator will raise StopIteration to stop the loop.

property batch_size

next() が返す学習のサンプル数。

戻り値:: 学習のサンプル数
戻り値の型:: int

property epoch

The number of times position() returns to zero.

戻り値:: epoch
戻り値の型:: int

next()[ソース]

データのタプルを生成します。

例えば、もし self._variables == ('x', 'y')() である場合、このメソッドは :py:meth:` ( [[X] * batch_size], [[Y] * batch_size] )` を返します。

戻り値:: numpy.ndarray にあるミニバッチ用のデータのタプル
戻り値の型:: tuple

property position

現在のエポックでのデータの位置。

戻り値:: データの位置
戻り値の型:: int

register_epoch_begin_callback(callback)[ソース]

エポック開始時のコールバックを登録します。

パラメータ:: callback (function) -- 関数はエポックインデックスを引数として取ります。

register_epoch_end_callback(callback)[ソース]

エポック終了時のコールバックを登録します。

パラメータ:: callback (function) -- 関数はエポックインデックスを引数として取ります。

property size

DataIterator が生成するデータサイズ。 self._data_source.size() を超えない batch_size の整数倍の最大値を表します。

戻り値:: データサイズ
戻り値の型:: int

slice(rng, num_of_slices=None, slice_pos=None, slice_start=None, slice_end=None, cache_dir=None, use_cache=False, drop_last=False)[ソース]

データのイテレーターをスライスすることで、新しく生成されたデータのイテレーターが元データの限定部分へアクセスできるようになります。

パラメータ:

rng (numpy.random.RandomState) -- Initializer の乱数ジェネレーター。
num_of_slices (int) -- 生成するスライスの合計数。slice_pos と共に使う必要があります。
slice_pos (int) -- 新しいデータのイテレーターに割り当てられたスライスの位置。 num_of_slices と共に使う必要があります。
slice_start (int) -- 新しいデータのイテレーターにスライスされる範囲の開始位置。 slice_end と共に使う必要があります。
slice_end (int) -- 新しいデータのイテレーターにスライスされる範囲の終了位置。 slice_start と共に使う必要があります。
cache_dir (str) -- Directory to save cache files. if cache_dir is None and use_cache is True, will used memory cache.
use_cache (bool) -- Whether use cache for data_source.
drop_last (bool) -- If it is True, the samples if the number of samples cannot be evenly divisible are dropped, If it is False, the samples are duplicated so that it is evenly divisible.

例:

from nnabla.utils.data_iterator import data_iterator_simple
import numpy as np

def load_func1(index):
    d = np.ones((2, 2)) * index
    return d

di = data_iterator_simple(load_func1, 1000, batch_size=3)

di_s1 = di.slice(None, num_of_slices=10, slice_pos=0)
di_s2 = di.slice(None, num_of_slices=10, slice_pos=1)

di_s3 = di.slice(None, slice_start=100, slice_end=200)
di_s4 = di.slice(None, slice_start=300, slice_end=400)

property variables

データの変数名。

戻り値:: 変数名のタプル
戻り値の型:: tuple

ユーティリティ

nnabla.utils.data_iterator.data_iterator(data_source, batch_size, rng=None, use_thread=True, with_memory_cache=True, with_file_cache=False, cache_dir=None, epoch_begin_callbacks=[], epoch_end_callbacks=[], stop_exhausted=False)[ソース]

DataSource を使うための Helper メソッド。

データソースの簡単な実装のため、独自の DataSource と共に DataIterator を使うことができます。

例えば、

ds = YourOwnImplementationOfDataSource()
batch = data_iterator(ds, batch_size)

パラメータ:

data_source (DataSource) -- データを提供する DataSource クラスのインスタンスです。
batch_size (int) -- バッチサイズ。
rng (None or numpy.random.RandomState) -- Numpy 乱数ジェネレーター。
use_thread (bool) -- If use_thread is set to True, iterator will use another thread to fetch data. If use_thread is set to False, iterator will use current thread to fetch data.
with_memory_cache (bool) -- True の場合、 data_source をラップするため data_source.DataSourceWithMemoryCache を使用します。data_source がオンメモリデータを提供しない限り、この値を True に設定することを推奨します。デフォルトは True です。
with_file_cache (bool) -- True の場合、 data_source をラップするため data_source.DataSourceWithFileCache を使用します。data_source が遅い場合、このオプションを有効にすることをおすすめします。デフォルトは False です。
cache_dir (str) -- file_cache の場所。この値が None の場合、 data_source.DataSourceWithFileCache がファイルキャッシュを暗黙的に一時ディレクトリに作成し、data_iterator 終了時にすべて消去します。そうでない場合は、 data_source.DataSourceWithFileCache がキャッシュファイルを生成し続けます。デフォルトは None です。
epoch_begin_callbacks (list of functions) -- 1 つの項目が 1 つの関数となり、エポックインデックスを引数として取ります。これらはエポックの開始時に呼び出されます。
epoch_end_callbacks (list of functions) -- 1 つの項目が 1 つの関数となり、エポックインデックスを引数として受取ります。これらはエポックの終了時に呼び出されます。
stop_exhausted (bool) -- If stop_exhausted is set to False, iterator will be reset so that iteration can be continued. If stop_exhausted is set to True, iterator will raise StopIteration to stop the loop.

戻り値:

DataIterator のインタンス

戻り値の型:

DataIterator

nnabla.utils.data_iterator.data_iterator_simple(load_func, num_examples, batch_size, shuffle=False, rng=None, use_thread=True, with_memory_cache=False, with_file_cache=False, cache_dir=None, epoch_begin_callbacks=[], epoch_end_callbacks=[], stop_exhausted=False)[ソース]

load_func に定義されている通り、ミニバッチデータをタプルとして 生成する ジェネレーターです。提供されたデータからのクエリーにより、随時、無制限にミニバッチを生成します。

パラメータ:

load_func (function) -- 単一の引数 i 、読み込まれるデータセットの例のインデックスを取り、データのタプルを返します。どのインデックス i から呼ばれる場合も毎回同じ形状の配列のタプルを返す必要があります。
num_examples (int) -- データセットにある例の数を表します。この数に従ってインデックスのランダムシーケンスが生成されます。
batch_size (int) -- データユニットのサイズ。
shuffle (bool) -- データセットがシャッフルされたか否かを表します。デフォルトは False です。
rng (None or numpy.random.RandomState) -- Numpy 乱数ジェネレーター。
use_thread (bool) -- If use_thread is set to True, iterator will use another thread to fetch data. If use_thread is set to False, iterator will use current thread to fetch data.
with_memory_cache (bool) -- If True, use data_source.DataSourceWithMemoryCache to wrap data_source. It is a good idea to set this as true unless data_source provides on-memory data. Default value is False.
with_file_cache (bool) -- True の場合、 data_source をラップするため data_source.DataSourceWithFileCache を使用します。data_source が遅い場合、このオプションを有効にすることをおすすめします。デフォルトは False です。
cache_dir (str) -- file_cache の場所。この値が None の場合、 data_source.DataSourceWithFileCache がファイルキャッシュを暗黙的に一時ディレクトリに作成し、data_iterator 終了時にすべて消去します。そうでない場合は、 data_source.DataSourceWithFileCache がキャッシュファイルを生成し続けます。デフォルトは None です。
epoch_begin_callbacks (list of functions) -- 1 つの項目が 1 つの関数となり、エポックインデックスを引数として取ります。これらはエポックの開始時に呼び出されます。
epoch_end_callbacks (list of functions) -- 1 つの項目が 1 つの関数となり、エポックインデックスを引数として受取ります。これらはエポックの終了時に呼び出されます。
stop_exhausted (bool) -- If stop_exhausted is set to False, iterator will be reset so that iteration can be continued. If stop_exhausted is set to True, iterator will raise StopIteration to stop the loop.

戻り値:

DataIterator のインタンス

戻り値の型:

DataIterator

以下に画像と分類ラベルのデータセットを返す load_func の例を示します。

import numpy as np
from nnabla.utils.image_utils import imread
image_paths = load_image_paths()
labels = load_labels()
def my_load_func(i):
    '''
    Returns:
        image: c x h x w array
        label: 0-shape array
    '''
    img = imread(image_paths[i]).astype('float32')
    return np.rollaxis(img, 2), np.array(labels[i])

nnabla.utils.data_iterator.data_iterator_csv_dataset(uri, batch_size, shuffle=False, rng=None, use_thread=True, normalize=True, with_memory_cache=True, with_file_cache=True, cache_dir=None, epoch_begin_callbacks=[], epoch_end_callbacks=[], stop_exhausted=False)[ソース]

CSV ファイルで提供されたデータセットから直接データを取得します。

ローカルファイルシステムや http サーバー、Amazon AWS S3 ストレージ等に配置されたファイルを読み込むことができます。

例えば、

batch = data_iterator_csv_dataset('CSV_FILE.csv', batch_size, shuffle=True)

パラメータ:

uri (str) -- CSV ファイルとなるデータセットの場所。
batch_size (int) -- データユニットのサイズ。
shuffle (bool) -- データセットがシャッフルされたか否かを表します。デフォルトは False です。
rng (None or numpy.random.RandomState) -- Numpy 乱数ジェネレーター。
use_thread (bool) -- If use_thread is set to True, iterator will use another thread to fetch data. If use_thread is set to False, iterator will use current thread to fetch data.
normalize (bool) -- True の場合、データにあるそれぞれのサンプルは 255 の係数で正規化されます。デフォルトは True です。
with_memory_cache (bool) -- True の場合、 data_source をラップするため data_source.DataSourceWithMemoryCache を使用します。data_source がオンメモリデータを提供しない限り、この値を True に設定することを推奨します。デフォルトは True です。
with_file_cache (bool) -- True の場合、 data_source をラップするため data_source.DataSourceWithFileCache を使用します。data_source が遅い場合、このオプションを有効にすることをおすすめします。デフォルトは False です。
cache_dir (str) -- file_cache の場所。この値が None の場合、 data_source.DataSourceWithFileCache がファイルキャッシュを暗黙的に一時ディレクトリに作成し、data_iterator 終了時にすべて消去します。そうでない場合は、 data_source.DataSourceWithFileCache がキャッシュファイルを生成し続けます。デフォルトは None です。
epoch_begin_callbacks (list of functions) -- 1 つの項目が 1 つの関数となり、エポックインデックスを引数として取ります。これらはエポックの開始時に呼び出されます。
epoch_end_callbacks (list of functions) -- 1 つの項目が 1 つの関数となり、エポックインデックスを引数として受取ります。これらはエポックの終了時に呼び出されます。
stop_exhausted (bool) -- If stop_exhausted is set to False, iterator will be reset so that iteration can be continued. If stop_exhausted is set to True, iterator will raise StopIteration to stop the loop.

戻り値:

DataIterator のインタンス

戻り値の型:

DataIterator

nnabla.utils.data_iterator.data_iterator_cache(uri, batch_size, shuffle=False, rng=None, use_thread=True, normalize=True, with_memory_cache=True, epoch_begin_callbacks=[], epoch_end_callbacks=[], stop_exhausted=False)[ソース]

キャッシュディレクトリーからデータを取得します。

ローカルファイルシステムからキャッシュファイルを読み込みます。

例えば、

batch = data_iterator_cache('CACHE_DIR', batch_size, shuffle=True)

パラメータ:

uri (str) -- キャッシュファイルのあるディレクトリの場所。
batch_size (int) -- データユニットのサイズ。
shuffle (bool) -- データセットがシャッフルされたか否かを表します。デフォルトは False です。
rng (None or numpy.random.RandomState) -- Numpy 乱数ジェネレーター。
use_thread (bool) -- If use_thread is set to True, iterator will use another thread to fetch data. If use_thread is set to False, iterator will use current thread to fetch data.
normalize (bool) -- True の場合、データにあるそれぞれのサンプルは 255 の係数で正規化されます。デフォルトは True です。
with_memory_cache (bool) -- True の場合、 data_source をラップするため data_source.DataSourceWithMemoryCache を使用します。data_source がオンメモリデータを提供しない限り、この値を True に設定することを推奨します。デフォルトは True です。
epoch_begin_callbacks (list of functions) -- 1 つの項目が 1 つの関数となり、エポックインデックスを引数として取ります。これらはエポックの開始時に呼び出されます。
epoch_end_callbacks (list of functions) -- 1 つの項目が 1 つの関数となり、エポックインデックスを引数として受取ります。これらはエポックの終了時に呼び出されます。
stop_exhausted (bool) -- If stop_exhausted is set to False, iterator will be reset so that iteration can be continued. If stop_exhausted is set to True, iterator will raise StopIteration to stop the loop.

戻り値:

DataIterator のインタンス

戻り値の型:

DataIterator

nnabla.utils.data_iterator.data_iterator_concat_datasets(data_source_list, batch_size, shuffle=False, rng=None, use_thread=True, with_memory_cache=True, with_file_cache=False, cache_dir=None, epoch_begin_callbacks=[], epoch_end_callbacks=[], stop_exhausted=False)[ソース]

複数のデータセットからデータを取得します。

例えば、

batch = data_iterator_concat_datasets([DataSource0, DataSource1, ...], batch_size)

パラメータ:

data_source_list (list of DataSource) -- データセットのリスト。
batch_size (int) -- データユニットのサイズ。
shuffle (bool) -- データセットがシャッフルされたか否かを表します。デフォルトは False です。
rng (None or numpy.random.RandomState) -- Numpy 乱数ジェネレーター。
use_thread (bool) -- If use_thread is set to True, iterator will use another thread to fetch data. If use_thread is set to False, iterator will use current thread to fetch data.
with_memory_cache (bool) -- True の場合、 data_source をラップするため data_source.DataSourceWithMemoryCache を使用します。data_source がオンメモリデータを提供しない限り、この値を True に設定することを推奨します。デフォルトは True です。
with_file_cache (bool) -- True の場合、 data_source をラップするため data_source.DataSourceWithFileCache を使用します。data_source が遅い場合、このオプションを有効にすることをおすすめします。デフォルトは False です。
cache_dir (str) -- file_cache の場所。この値が None の場合、 data_source.DataSourceWithFileCache がファイルキャッシュを暗黙的に一時ディレクトリに作成し、data_iterator 終了時にすべて消去します。そうでない場合は、 data_source.DataSourceWithFileCache がキャッシュファイルを生成し続けます。デフォルトは None です。
epoch_begin_callbacks (list of functions) -- 1 つの項目が 1 つの関数となり、エポックインデックスを引数として取ります。これらはエポックの開始時に呼び出されます。
epoch_end_callbacks (list of functions) -- 1 つの項目が 1 つの関数となり、エポックインデックスを引数として受取ります。これらはエポックの終了時に呼び出されます。
stop_exhausted (bool) -- If stop_exhausted is set to False, iterator will be reset so that iteration can be continued. If stop_exhausted is set to True, iterator will raise StopIteration to stop the loop.

戻り値:

DataIterator のインタンス

戻り値の型:

DataIterator