如何在Fuel项目中贡献新数据集：以Iris数据集为例

引言

Fuel是一个用于机器学习的数据处理框架，它提供了高效的数据加载和预处理功能。本文将详细介绍如何在Fuel项目中贡献一个新的数据集，我们将以经典的Iris（鸢尾花）数据集为例，展示从数据下载到最终集成的完整流程。

数据集贡献概述

在Fuel中贡献一个新数据集需要完成三个主要部分：

1. 数据下载代码：实现从原始来源获取数据的逻辑
2. 数据转换代码：将原始数据转换为Fuel可用的格式
3. 数据集子类：提供与Fuel框架交互的接口

准备工作

在开始之前，我们需要了解Iris数据集的基本情况：

• 包含150个样本，分为3类（每类50个样本）
• 每个样本有4个特征（花萼长度、花萼宽度、花瓣长度、花瓣宽度）
• 我们将数据集划分为：训练集（100个）、验证集（20个）和测试集（30个）

第一步：实现数据下载功能

Fuel使用fuel-download脚本来管理数据下载。我们需要创建一个下载器模块：

from fuel.downloaders.base import default_downloader

def fill_subparser(subparser):
    subparser.set_defaults(
        urls=['https://archive.ics.uci.edu/ml/machine-learning-databases/iris/iris.data'],
        filenames=['iris.data'])
    return default_downloader

这段代码做了以下几件事：

1. 指定了数据文件的URL和本地保存名称
2. 使用default_downloader作为默认下载函数
3. 通过fill_subparser函数将配置传递给下载脚本

然后需要在fuel.downloaders包的__init__.py中注册这个下载器：

from fuel.downloaders import iris

all_downloaders = (
    ('iris', iris.fill_subparser),
    # 其他下载器...
)

第二步：数据转换处理

下载的原始数据需要转换为HDF5格式，这是Fuel推荐的数据存储格式。我们创建一个转换器模块：

import os
import h5py
import numpy
from fuel.converters.base import fill_hdf5_file

def convert_iris(directory, output_directory, output_filename='iris.hdf5'):
    output_path = os.path.join(output_directory, output_filename)
    h5file = h5py.File(output_path, mode='w')
    
    # 类别映射
    classes = {'Iris-setosa': 0, 'Iris-versicolor': 1, 'Iris-virginica': 2}
    
    # 加载并处理数据
    data = numpy.loadtxt(
        os.path.join(directory, 'iris.data'),
        converters={4: lambda x: classes[x]},
        delimiter=',')
    numpy.random.shuffle(data)
    
    # 划分数据集
    features = data[:, :-1].astype('float32')
    targets = data[:, -1].astype('uint8')
    train_features = features[:100]
    train_targets = targets[:100]
    valid_features = features[100:120]
    valid_targets = targets[100:120]
    test_features = features[120:]
    
    # 填充HDF5文件
    data = (
        ('train', 'features', train_features),
        ('train', 'targets', train_targets),
        ('valid', 'features', valid_features),
        ('valid', 'targets', valid_targets),
        ('test', 'features', test_features)
    )
    fill_hdf5_file(h5file, data)
    
    # 设置维度标签
    h5file['features'].dims[0].label = 'batch'
    h5file['features'].dims[1].label = 'feature'
    h5file['targets'].dims[0].label = 'batch'
    h5file['targets'].dims[1].label = 'index'
    
    h5file.flush()
    h5file.close()
    return (output_path,)

def fill_subparser(subparser):
    return convert_iris

同样需要在fuel.converters包的__init__.py中注册这个转换器：

from fuel.converters import iris

all_converters = (
    ('iris', iris.fill_subparser),
    # 其他转换器...
)

第三步：实现数据集子类

最后，我们需要创建一个继承自H5PYDataset的子类来提供数据集接口：

from fuel.datasets import H5PYDataset
from fuel.utils import find_in_data_path

class Iris(H5PYDataset):
    filename = 'iris.hdf5'

    def __init__(self, which_sets, **kwargs):
        kwargs.setdefault('load_in_memory', True)
        super(Iris, self).__init__(
            file_or_path=find_in_data_path(self.filename),
            which_sets=which_sets, **kwargs)

这个子类非常简单，主要做了两件事：

1. 指定了HDF5文件名
2. 默认将整个数据集加载到内存中（因为Iris数据集很小）

使用新数据集

完成上述步骤后，就可以像使用内置数据集一样使用Iris数据集了：

1. 下载数据：

fuel-download iris

2. 转换数据：

fuel-convert iris

3. 在代码中使用：

from fuel.datasets.iris import Iris

train_set = Iris(('train',))
print(train_set.axis_labels['features'])  # 输出: ('batch', 'feature')
print(train_set.axis_labels['targets'])  # 输出: ('batch', 'index')

handle = train_set.open()
data = train_set.get_data(handle, slice(0, 10))
train_set.close(handle)

高级主题：独立分发数据集

如果你想将数据集作为独立包分发，而不是合并到Fuel主项目中，可以这样做：

1. 创建自己的包结构：

my_fuel/
├── downloaders/
│   ├── iris.py
│   └── __init__.py
└── converters/
    ├── iris.py
    └── __init__.py

2. 在配置文件中指定额外路径：

# ~/.fuelrc
extra_downloaders: ['my_fuel.downloaders']
extra_converters: ['my_fuel.converters']

或者通过环境变量设置：

export FUEL_EXTRA_DOWNLOADERS=my_fuel.downloaders
export FUEL_EXTRA_CONVERTERS=my_fuel.converters

总结

本文详细介绍了在Fuel项目中贡献新数据集的完整流程，从数据下载到最终集成。通过这个例子，你可以了解到Fuel数据处理的标准化流程，以及如何将自己的数据集适配到这个框架中。这种模块化设计使得Fuel能够灵活支持各种不同类型的数据集，同时也方便社区贡献新的数据集。