文本适配器¶
TextAdapter 模块读取 CSV 数据并生成一个包含解析数据的 NumPy 数组。目前实现了以下功能:
- TextAdapter 引擎是用 C 编写的,以确保解析文本的速度与从源读取数据的速度一样快。文本以小块读取和解析,而不是一次将整个数据读入内存,这使得读取和解析非常大的文件而不会耗尽内存。
- Python 切片符号可用于指定要从数据源读取的记录子集以及字段子集。
- 可以通过以下三种方式中的任何一种来指定字段:通过分隔符、使用固定字段宽度或通过正则表达式。这使得可以解析更多种类的 CSV 类和其他类型的文本文件。
- 无需先解压缩即可解析 gzipped 文件。解析速度与同一文件的未压缩版本大致相同。
- 可以构建文件中记录偏移量的索引以允许对记录进行快速随机访问。此索引可以保存到磁盘并稍后再次加载。
- 可以指定转换器函数将解析的文本转换为适当的 dtype 以存储在 NumPy 数组中。
- TextAdapter 引擎具有自动类型推断,因此用户不必指定输出数组的 dtypes。如果需要,用户仍然可以手动指定 dtypes。
- 可以读取存储在 Amazon S3 中的远程数据。可以使用 S3 数据构建和存储索引。索引可以远程读取,允许随机访问 S3 数据。
方法¶
TextAdapter 模块包含以下用于创建 TextAdapter 对象的工厂方法:
- text_adapter (source, parser='csv', compression=None, comment='#',
- quote='”', num_records=0, header=0, field_names=True, indexing=False, index_name=None, encoding='utf-8')创建用于读取 CSV、JSON 或固定宽度的文本适配器文本文件,或由正则表达式定义的文本文件。source - 文件名、文件对象、StringIO 对象、BytesIO 对象、S3 密钥、http url 或 python 生成器parser - 用于解析文本的解析器类型。有效的解析器类型是“csv”、“固定宽度”、“regex”和“json”。encoding - 字符编码类型(支持当前的 ascii 和 utf8)压缩 - 数据压缩类型(目前仅支持 gzip)注释 - 用于表示注释行的字符quote - 用于引用字段的字符num_records - 将解析限制为指定数量的记录;默认为所有记录header - 文件头中的行数;解析时跳过这些行页脚 - 文件页脚中的行数;解析时跳过这些行索引 - 在读取字符时动态创建记录索引index_name - 要写入索引的文件名output - 输出对象的类型(numpy 数组或 Pandas 数据帧)
- 如果解析器设置为 'csv',附加参数包括:
- delimiter - 用于定义数据源中的字段的分隔符。默认为“,”。
- 如果解析器设置为“fixed_width”,附加参数包括:
- field_widths - 字段宽度列表
- 如果解析器设置为“regex”,附加参数包括:
- regex - 用于定义数据源中的记录和字段的正则表达式。请参阅高级用法部分中的正则表达式示例。
- s3_text_adapter(access_key、secret_key、bucket_name、key_name、remote_s3_index=False)
- parser='csv',compression=None,comment='#',quote='"',num_records=0,header=0,field_names=True,indexing=False,index_name=None,encoding='utf-8')创建用于从 S3 读取文本文件的文本适配器。文本文件可以CSV、JSON、固定宽度或由正则表达式定义
除了上面为 text_adapter 函数描述的参数之外,s3_text_adapter 函数还具有以下参数:
access_key - AWS 访问密钥secret_key - AWS 密钥bucket_name - S3 存储桶的名称key_name - S3 存储桶中的密钥名称remote_s3_index - 使用远程 S3 索引(索引名称必须是键名 + '.idx' 扩展名)
text_adapter 工厂方法返回的 TextAdapter 对象包含以下方法:
- set_converter(字段,转换器)
- 为字段设置转换器功能field - 应用转换器功能的字段转换器 - python 函数对象
- set_missing_values (missing_values)
- 为每个表示缺失值的字段设置字符串missing_values - 字段名称或数字的字典,以及缺失值字符串列表
默认缺失值:'NA'、'NaN'、'inf'、'-inf'、'None'、'none'、''
- set_fill_values(填充值,松散=假)
- 为每个字段设置填充值fill_values - 字段名称或数字的字典,以及填充值松散 - 如果值无法转换,并且值与任何缺失值都不匹配,则无论如何替换为填充值。
每种数据类型的默认填充值: | 整数 - 0 | 浮动- numpy.nan | 字符 - 0 | bool - 错误 | 对象- numpy.nan | 字符串 - numpy.nan
- 创建索引(索引名称=无,密度=1)
- 在文件中创建记录偏移的索引index_name - 磁盘上用于存储索引的文件名。如果没有,索引将在内存中创建但不保存。密度 - 指数的密度。值为 1 将索引每条记录,值为 2 将索引每隔一条记录,依此类推。
- to_array ()
- 解析整个数据源并将数据作为 NumPy 数组对象返回
- to_dataframe ()
- 解析整个数据源并将数据作为 Pandas DataFrame 对象返回
TextAdapter 对象包含以下属性:
- 大小(只读)
- 数据源中的记录数。仅当整个数据源已被读取或索引,或者在创建对象时在 text_adapter 工厂方法中指定了记录数时,才会设置此值。
- field_count(只读)
- 每条记录中的字段数
- 字段名称
- 创建输出 NumPy 数组时要使用的字段名称。字段名称可以在读取数据之前或在带有 field_names 参数的 text_adapter 函数中设置。
- 字段类型
- 每个字段的 NumPy 数据类型,指定为字段和关联数据类型的字典。(例如:{0:'u4', 1:'f8', 2:'S10'})
- 字段过滤器
- 要解析的数据源中的字段,指定为字段编号或名称的列表(示例:[0, 1, 2] 或 ['f1', 'f3', 'f5'])。该过滤器一直有效,直到它被重置为空列表,或者被数组切片覆盖(例如:适配器 [[0, 1, 3, 4]][:])。
- 有关更多详细信息,请参阅 NumPy 数据类型文档:
- http://docs.continuum.io/anaconda/numpy/reference/arrays.dtypes.html
TextAdapter 对象支持数组切片:
读取所有记录:adapter[:]读取前 100 条记录:adapter[0:100]读取最后一条记录(仅当数据已被索引或整个数据集之前已被读取一次):adapter[-1]通过指定字段编号读取所有记录中的第一个字段:adapter[0][:]通过指定字段名称读取所有记录中的第一个字段:adapter['f0'][:]读取所有记录中的第一个和第三个字段:adapter[[0, 2]][:]
基本用法¶
为数据源创建 TextAdapter 对象:
>>> import iopro
>>> adapter = iopro.text_adapter('data.csv', parser='csv')
使用切片符号解析文本并将记录存储在 NumPy 数组中:
>>> # read all records
>>> array = adapter[:]
>>> # read first ten records
>>> array = adapter[0:10]
>>> # read last record
>>> array = adapter[-1]
>>> # read every other record
>>> array = adapter[::2]
高级用法¶
字段 0 的用户定义转换器函数:
>>> import iopro
>>> import io
>>> data = '1, abc, 3.3\n2, xxx, 9.9'
>>> adapter = iopro.text_adapter(io.StringIO(data), parser='csv', field_names=False)
>>> # Override default converter for first field
>>> adapter.set_converter(0, lambda x: int(x)*2)
>>> adapter[:]
array([(2L, ' abc', 3.3), (4L, ' xxx', 9.9)],
dtype=[('f0', '<u8'), ('f1', 'S4'), ('f2', '<f8')])
覆盖默认的缺失值和填充值:
>>> import iopro
>>> import io
>>> data = '1,abc,inf\n2,NA,9.9'
>>> adapter = iopro.text_adapter(io.StringIO(data), parser='csv', field_names=False)
>>> # Define field dtypes (example: set field 1 to string object and field 2 to float)
>>> adapter.field_types = {1:'O', 2:'f4'}
>>> # Define list of strings for each field that represent missing values
>>> adapter.set_missing_values({1:['NA'], 2:['inf']})
>>> # Set fill value for missing values in each field
>>> adapter.set_fill_values({1:'xxx', 2:999.999})
>>> adapter[:]
array([(' abc', 999.9990234375), ('xxx', 9.899999618530273)],
dtype=[('f0', 'O'), ('f1', '<f4')])
为 gzip 文件创建和保存索引数组的元组,并重新加载索引:
>>> import iopro
>>> adapter = iopro.text_adapter('data.gz', parser='csv', compression='gzip')
>>> # Build index of records and save index to disk.
>>> adapter.create_index(index_name='index_file')
>>> # Create new adapter object and load index from disk.
>>> adapter = iopro.text_adapter('data.gz', parser='csv', compression='gzip', indexing=True, index_name='index_file')
>>> # Read last record
>>> adapter[-1]
array([(100, 101, 102)],dtype=[('f0', '<u4'), ('f1', '<u4'), ('f2', '<u4')])
使用正则表达式更好地控制提取数据:
>>> import iopro
>>> import io
>>> # Define regular expression to extract dollar amount, percentage, and month.
>>> # Each set of parentheses defines a field.
>>> data = '$2.56, 50%, September 20 1978\n$1.23, 23%, April 5 1981'
>>> regex_string = '([0-9]\.[0-9][0-9]+)\,\s ([0-9]+)\%\,\s ([A-Za-z]+)'
>>> adapter = iopro.text_adapter(io.StringIO(data), parser='regex', regex_string=regex_string, field_names=False, infer_types=False)
>>> # set dtype of field to float
>>> adapter.field_types = {0:'f4', 1:'u4', 2:'S10'}
>>> adapter[:]
array([(2.56, 50L, 'September'), (1.23, 23L, 'April')],
dtype=[('f0', '<f8'), ('f1', '<u8'), ('f2', 'S9')])