features.md

FeatureConnector

tfds.features.FeatureConnector API:

• 最終的な tf.data.Dataset の構造、形状、dtypes を定義します。

• ディスクとの間のシリアル化を抽象化します。

• 追加メタデータ（ラベル名、音声サンプルレートなど）を公開します。

概要

tfds.features.FeatureConnector は、データセットの特徴量の構造を定義します（tfds.core.DatasetInfo 内）:

tfds.core.DatasetInfo(
    features=tfds.features.FeaturesDict({
        'image': tfds.features.Image(shape=(28, 28, 1), doc='Grayscale image'),
        'label': tfds.features.ClassLabel(
            names=['no', 'yes'],
            doc=tfds.features.Documentation(
                desc='Whether this is a picture of a cat',
                value_range='yes or no'
            ),
        ),
        'metadata': {
            'id': tf.int64,
            'timestamp': tfds.features.Scalar(
                tf.int64,
                doc='Timestamp when this picture was taken as seconds since epoch'),
            'language': tf.string,
        },
    }),
)

特徴量は、テキストによる説明（doc='description'）を使用するか、tfds.features.Documentation を直接使用してさらに詳細な特徴量の説明を提供することで、文書化できます。

以下のような特徴量を含められます。

• スカラー値: tf.bool、tf.string、tf.float32 など。特徴量を文書化する場合、tfds.features.Scalar(tf.int64, doc='description') も使用できます。

• tfds.features.Audio、tfds.features.Video など（使用可能な特徴量のリストをご覧ください）

• 特徴量のネストされた dict: {'metadata': {'image': Image(), 'description': tf.string}} など

• ネストされた tfds.features.Sequence: Sequence({'image': ..., 'id': ...})、 Sequence(Sequence(tf.int64)) など

生成中、この例は FeatureConnector.encode_example によって自動的にディスクに最適なフォーマットにシリアル化されます（現在は tf.train.Example プロトコルバッファ）。

yield {
    'image': '/path/to/img0.png',  # `np.array`, file bytes,... also accepted
    'label': 'yes',  # int (0-num_classes) also accepted
    'metadata': {
        'id': 43,
        'language': 'en',
    },
}

データセットを読み取る場合（tfds.load などを私用）、データは FeatureConnector.decode_example によって自動的にデコードされます。戻される tf.data.Dataset は、tfds.core.DatasetInfo に定義された dict 構造に一致します。

ds = tfds.load(...)
ds.element_spec == {
    'image': tf.TensorSpec(shape=(28, 28, 1), tf.uint8),
    'label': tf.TensorSpec(shape=(), tf.int64),
    'metadata': {
        'id': tf.TensorSpec(shape=(), tf.int64),
        'language': tf.TensorSpec(shape=(), tf.string),
    },
}

proto のシリアル化と逆シリアル化

TFDS は、例を tf.train.Example proto にシリアル化/逆シリアル化するための低レベル API を公開します。

dict[np.ndarray | Path | str | ...] を proto bytes にシリアル化するには、features.serialize_example を使用します。

with tf.io.TFRecordWriter('path/to/file.tfrecord') as writer:
  for ex in all_exs:
    ex_bytes = features.serialize_example(data)
    f.write(ex_bytes)

proto bytes を tf.Tensor に逆シリアル化するには、features.deserialize_example を使用します。

ds = tf.data.TFRecordDataset('path/to/file.tfrecord')
ds = ds.map(features.deserialize_example)

メタデータにアクセスする

特徴量メタデータ（ラベル名、形状、dtype など）にアクセスするには、基礎ドキュメントをご覧ください。以下に例を示します。

ds, info = tfds.load(..., with_info=True)

info.features['label'].names  # ['cat', 'dog', ...]
info.features['label'].str2int('cat')  # 0

独自の tfds.features.FeatureConnector を作成する

利用可能な特徴量に特徴量が見当たらない場合は、新しい課題を送信してください。

独自の特徴量コネクタを作成するには、tfds.features.FeatureConnector から継承し、抽象メソッドを実装する必要があります。

• 特徴量が単一のテンソル値である場合、tfds.features.Tensor から継承して、必要に応じて super() を使用するのが最善です。例については、tfds.features.BBoxFeature のソースコードをご覧ください。

• 特徴量が複数のテンソルのコンテナである場合、tfds.features.FeaturesDict から継承して、super() を使用して自動的にサブコネクタをエンコードするのが最善です。

tfds.features.FeatureConnector オブジェクトは、特徴慮がユーザーに提供される方法から、特徴量をディスクにエンコードする方法を抽象化します。次の図は、データセットの抽象レイヤーと、生のデータセットファイルから tf.data.Dataset オブジェクトへの変換を示します。

独自の特徴量コネクタを作成するには、tfds.features.FeatureConnector をサブクラス化し、抽象メソッドを実装します。

• encode_example(data): ジェネレータ _generate_examples() に指定されたデータを tf.train.Example 対応データにエンコードする方法を定義します。単一の値、または複数の値の dict を返します。

• decode_example(data): tf.train.Example から読み取られたテンソルから tf.data.Dataset が返すユーザーテンソルにデータをデコードする方法を定義します。

• get_tensor_info(): tf.data.Dataset によって返されたテンソルの形状/dtype を示します。別の tfds.features から継承する場合はオプションの場合があります。

• （オプション）get_serialized_info(): get_tensor_info() から返された情報がディスクに実際に書き込まれたものと異なる場合、get_serialized_info() を、tf.train.Example の仕様に一致するにように上書きする必要があります。

• to_json_content/from_json_content: これは、元のソースコードなしでデータセットを読み込む場合に必須です。例については、音声特徴量をご覧ください。

注意: 作成した特徴量コネクタは、self.assertFeature と tfds.testing.FeatureExpectationItem を使って必ずテストしてください。テスト例をご覧ください。

詳細については、tfds.features.FeatureConnector ドキュメントをご覧ください。実際の例を見ることもお勧めします。