pandas.read_stata

pandas.read_stata(filepath_or_buffer, *, convert_dates=True, convert_categoricals=True, index_col=None, convert_missing=False, preserve_dtypes=True, columns=None, order_categoricals=True, chunksize=None, iterator=False, compression='infer', storage_options=None)

将 Stata 文件读取到 DataFrame 中。

Parameters:

filepath_or_bufferstr、path 对象或文件类对象

任何有效的字符串路径都可以接受。字符串可以是 URL。有效的 URL 方案包括 http、ftp、s3 和 file。对于文件 URL，需要主机名。本地文件可以是：file://localhost/path/to/table.dta。

如果要传入路径对象，pandas 接受任何 os.PathLike。

我们所说的“类文件对象”指的是具有 read() 方法的对象，例如文件句柄（例如通过内置 open 函数）或 StringIO。

convert_datesbool, default True

将日期变量转换为 DataFrame 时间值。

convert_categoricalsbool, default True

读取值标签并将列转换为 Categorical/Factor 变量。

index_colbool, default False

要设置为索引的列。

convert_missingbool，默认 False

指示是否将缺失值转换为其 Stata 表示形式的标志。如果为 False，则将缺失值替换为 nan。如果为 True，则包含缺失值的列将返回 object 数据类型，并且缺失值将由 StataMissingValue 对象表示。

preserve_dtypesbool, default True

保留 Stata 数据类型。如果为 False，则数值数据将被提升为 pandas 外部数据的默认类型（float64 或 int64）。

columnslist or None

要保留的列。将按给定顺序返回列。None 返回所有列。

order_categoricalsbool, default True

指示转换后的分类数据是否排序的标志。

chunksizeint，默认 None

返回 StataReader 对象进行迭代，以给定行数返回块。

iteratorbool，默认 False

返回 StataReader 对象。

compressionstr or dict, default ‘infer’

对磁盘上的数据进行即时解压缩。如果为 ‘infer’ 且 ‘filepath_or_buffer’ 是类路径，则根据以下扩展名检测压缩：’.gz’, ‘.bz2’, ‘.zip’, ‘.xz’, ‘.zst’, ‘.tar’, ‘.tar.gz’, ‘.tar.xz’ 或 ‘.tar.bz2’（否则不进行压缩）。如果使用 ‘zip’ 或 ‘tar’，ZIP 文件必须只包含一个要读取的数据文件。设置为 None 表示不解压缩。也可以是一个字典，其中键 'method' 设置为 {'zip', 'gzip', 'bz2', 'zstd', 'xz', 'tar'} 中的一个，其他键值对将转发到 zipfile.ZipFile, gzip.GzipFile, bz2.BZ2File, zstandard.ZstdDecompressor, lzma.LZMAFile 或 tarfile.TarFile。例如，可以传递以下内容以使用自定义压缩字典进行 Zstandard 解压缩：compression={'method': 'zstd', 'dict_data': my_compression_dict}。

在 1.5.0 版本加入: 增加了对 .tar 文件的支持。

storage_optionsdict, 可选

适用于特定存储连接的额外选项，例如主机、端口、用户名、密码等。对于 HTTP(S) URL，键值对将作为标头选项转发给 urllib.request.Request。对于其他 URL（例如，以 “s3://”, 和 “gcs://” 开头的 URL），键值对将转发给 fsspec.open。更多详情请参阅 fsspec 和 urllib，有关存储选项的更多示例，请参阅 here 。

Returns:

DataFrame 或 pandas.api.typing.StataReader

参见

io.stata.StataReader

Stata 数据文件的低级读取器。

DataFrame.to_stata

导出 Stata 数据文件。

Notes

通过迭代器读取的分类变量可能具有不同的类别和 dtype。当 DTA 文件中存储的变量关联的标签值不完整，仅标记了严格子集的值时，会发生这种情况。

Examples

创建一个虚拟 stata 以供此示例使用

>>> df = pd.DataFrame({'animal': ['falcon', 'parrot', 'falcon', 'parrot'],
...                     'speed': [350, 18, 361, 15]})  
>>> df.to_stata('animals.dta')  

读取 Stata dta 文件：

>>> df = pd.read_stata('animals.dta')  

以 10000 行的块读取 Stata dta 文件：

>>> values = np.random.randint(0, 10, size=(20_000, 1), dtype="uint8")  
>>> df = pd.DataFrame(values, columns=["i"])  
>>> df.to_stata('filename.dta')  

>>> with pd.read_stata('filename.dta', chunksize=10000) as itr: 
>>>     for chunk in itr:
...         # Operate on a single chunk, e.g., chunk.mean()
...         pass