文本适配器 ¶

内容

文本适配器

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')])

文本适配器¶

方法¶

基本用法¶

高级用法¶

文本适配器 ¶

方法 ¶

基本用法 ¶

高级用法 ¶