Pandas-2-2-中文文档-十七-

Pandas 2.2 中文文档（十七）

原文：pandas.pydata.org/docs/

`pandas.HDFStore.put`

原文：pandas.pydata.org/docs/reference/api/pandas.HDFStore.put.html

HDFStore.put(key, value, format=None, index=True, append=False, complib=None, complevel=None, min_itemsize=None, nan_rep=None, data_columns=None, encoding=None, errors='strict', track_times=True, dropna=False)

在 HDFStore 中存储对象。

参数：

keystr

value

format‘fixed(f)|table(t)’，默认为‘fixed’

存储对象在 HDFStore 中使用的格式。值可以是以下之一：

'fixed'

固定格式。快速写入/读取。不可追加，也不可搜索。

'table'

表格格式。写入为 PyTables 表格结构，可能性能较差，但允许更灵活的操作，如搜索/选择数据子集。

indexbool，默认为 True

将 DataFrame 索引写入为列。

appendbool，默认为 False

这将强制使用表格格式，将输入数据追加到现有数据中。

data_columns列的列表或 True，默认为 None

要创建为数据列的列的列表，或者 True 以使用所有列。参见这里。

encodingstr，默认为 None

为字符串提供编码。

track_timesbool，默认为 True

参数传递给‘PyTables’的‘create_table’方法。如果设置为 False，则可以在创建时间独立地拥有相同的 h5 文件（相同的哈希值）。

dropnabool，默认为 False，可选

删除缺失值。

示例

>>> df = pd.DataFrame([[1, 2], [3, 4]], columns=['A', 'B'])
>>> store = pd.HDFStore("store.h5", 'w')  
>>> store.put('data', df)

`pandas.HDFStore.append`

原文：pandas.pydata.org/docs/reference/api/pandas.HDFStore.append.html

HDFStore.append(key, value, format=None, axes=None, index=True, append=True, complib=None, complevel=None, columns=None, min_itemsize=None, nan_rep=None, chunksize=None, expectedrows=None, dropna=None, data_columns=None, encoding=None, errors='strict')

追加到文件中的表。

节点必须已经存在并且是表格式。

参数：

key 字符串

value {Series, DataFrame}

format‘table’ 是默认格式

在将对象存储在 HDFStore 中时使用的格式。值可以是以下之一：

'table'

表格格式。写为 PyTables 表结构，可能性能较差，但允许更灵活的操作，如搜索/选择数据子集。

index 布尔值，默认为 True

将 DataFrame 索引写为列。

append 布尔值，默认为 True

将输入数据追加到现有数据中。

data_columns 列的列表，或 True，默认为 None

要创建为磁盘查询的索引数据列的列的列表，或者使用所有列的 True。默认情况下，只有对象的轴被索引。请参见这里。

min_itemsize 指定最小字符串大小的列的字典

nan_rep 用作字符串 nan 表示的字符串

chunksize 写入时分块的大小

expectedrows 此表的预期总行大小

encoding 默认为 None，为字符串提供编码

dropna 布尔值，默认为 False，可选

不要将所有 nan 行写入存储，可通过选项 ‘io.hdf.dropna_table’ 设置。

注意

不检查要追加的数据是否与表中现有数据重叠，所以要小心

示例

>>> df1 = pd.DataFrame([[1, 2], [3, 4]], columns=['A', 'B'])
>>> store = pd.HDFStore("store.h5", 'w')  
>>> store.put('data', df1, format='table')  
>>> df2 = pd.DataFrame([[5, 6], [7, 8]], columns=['A', 'B'])
>>> store.append('data', df2)  
>>> store.close()  
 A  B
0  1  2
1  3  4
0  5  6
1  7  8

`pandas.HDFStore.get`

原文：pandas.pydata.org/docs/reference/api/pandas.HDFStore.get.html

HDFStore.get(key)

从文件中检索存储的 pandas 对象。

参数：

keystr

对象

与文件中存储的对象相同类型。

示例

>>> df = pd.DataFrame([[1, 2], [3, 4]], columns=['A', 'B'])
>>> store = pd.HDFStore("store.h5", 'w')  
>>> store.put('data', df)  
>>> store.get('data')  
>>> store.close()

`pandas.HDFStore.select`

原文：pandas.pydata.org/docs/reference/api/pandas.HDFStore.select.html

HDFStore.select(key, where=None, start=None, stop=None, columns=None, iterator=False, chunksize=None, auto_close=False)

根据 where 条件从文件中检索 pandas 对象。

警告

Pandas 使用 PyTables 来读写 HDF5 文件，允许在使用“fixed”格式时使用 pickle 对象数据进行序列化。从不受信任的来源加载 pickled 数据可能不安全。

更多信息请参见：docs.python.org/3/library/pickle.html

参数：

keystr

从文件中检索的对象。

wherelist 或 None

Term（或可转换）对象的列表，可选。

startint 或 None

开始选择的行号。

stopint，默认为 None

停止选择的行号。

columnslist 或 None

一个列的列表，如果不是 None，将限制返回的列。

iteratorbool 或 False

返回一个迭代器。

chunksizeint 或 None

包括在迭代中的行数，返回一个迭代器。

auto_closebool 或 False

完成后应自动关闭存储。

对象

从文件中检索到的对象。

示例

>>> df = pd.DataFrame([[1, 2], [3, 4]], columns=['A', 'B'])
>>> store = pd.HDFStore("store.h5", 'w')  
>>> store.put('data', df)  
>>> store.get('data')  
>>> print(store.keys())  
['/data1', '/data2']
>>> store.select('/data1')  
 A  B
0  1  2
1  3  4
>>> store.select('/data1', where='columns == A')  
 A
0  1
1  3
>>> store.close()

`pandas.HDFStore.info`

原文：pandas.pydata.org/docs/reference/api/pandas.HDFStore.info.html

HDFStore.info()

打印商店的详细信息。

str

示例

>>> df = pd.DataFrame([[1, 2], [3, 4]], columns=['A', 'B'])
>>> store = pd.HDFStore("store.h5", 'w')  
>>> store.put('data', df)  
>>> print(store.info())  
>>> store.close()  
<class 'pandas.io.pytables.HDFStore'>
File path: store.h5
/data    frame    (shape->[2,2])

`pandas.HDFStore.keys`

原文：pandas.pydata.org/docs/reference/api/pandas.HDFStore.keys.html

HDFStore.keys(include='pandas')

返回一个与存储在 HDFStore 中的对象对应的键列表。

参数：

includestr，默认为‘pandas’

当 kind 等于 ‘pandas’ 时返回 pandas 对象。当 kind 等于 ‘native’ 时返回本机 HDF5 表对象。

列表

绝对路径名列表（例如，具有前导‘/’）。

抛出：

如果 kind 具有非法值，则引发 ValueError

示例

>>> df = pd.DataFrame([[1, 2], [3, 4]], columns=['A', 'B'])
>>> store = pd.HDFStore("store.h5", 'w')  
>>> store.put('data', df)  
>>> store.get('data')  
>>> print(store.keys())  
['/data1', '/data2']
>>> store.close()

`pandas.HDFStore.groups`

原文：pandas.pydata.org/docs/reference/api/pandas.HDFStore.groups.html

HDFStore.groups()

返回所有顶层节点的列表。

返回的每个节点都不是 pandas 存储对象。

列表

对象列表。

示例

>>> df = pd.DataFrame([[1, 2], [3, 4]], columns=['A', 'B'])
>>> store = pd.HDFStore("store.h5", 'w')  
>>> store.put('data', df)  
>>> print(store.groups())  
>>> store.close()  
[/data (Group) ''
 children := ['axis0' (Array), 'axis1' (Array), 'block0_values' (Array),
 'block0_items' (Array)]]

`pandas.HDFStore.walk`

原文：pandas.pydata.org/docs/reference/api/pandas.HDFStore.walk.html

HDFStore.walk(where='/')

遍历 pandas 对象的 pytables 组层次结构。

此生成器将为每个组产出组路径、子组和 pandas 对象名称。

任何非 pandas PyTables 对象且不是组的对象将被忽略。

首先列出 where 组本身（先序），然后遍历每个子组（按字母数字顺序），遵循相同的过程。

参数：

where字符串，默认为“/”

开始遍历的组。

产出：

路径字符串

组的完整路径（不包括末尾的‘/’）。

groups列表

路径中包含的组的名称（字符串）。

leaves列表

路径中包含的 pandas 对象的名称（字符串）。

示例

>>> df1 = pd.DataFrame([[1, 2], [3, 4]], columns=['A', 'B'])
>>> store = pd.HDFStore("store.h5", 'w')  
>>> store.put('data', df1, format='table')  
>>> df2 = pd.DataFrame([[5, 6], [7, 8]], columns=['A', 'B'])
>>> store.append('data', df2)  
>>> store.close()  
>>> for group in store.walk():  
...     print(group)  
>>> store.close()

`pandas.read_feather`

原文：pandas.pydata.org/docs/reference/api/pandas.read_feather.html

pandas.read_feather(path, columns=None, use_threads=True, storage_options=None, dtype_backend=_NoDefault.no_default)

从文件路径加载羽毛格式对象。

参数：

pathstr、路径对象或类文件对象

字符串、路径对象（实现os.PathLike[str]）或实现二进制read()函数的类文件对象。字符串可以是 URL。有效的 URL 方案包括 http、ftp、s3 和 file。对于文件 URL，期望有一个主机。本地文件可以是：file://localhost/path/to/table.feather。

columns序列，默认为 None

如果未提供，则读取所有列。

use_threadsbool，默认为 True

是否使用多线程并行读取。

storage_options字典，可选

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

dtype_backend，默认为 ‘numpy_nullable’

应用于结果DataFrame的后端数据类型（仍处于实验阶段）。行为如下：

"numpy_nullable"：返回支持可空数据类型的DataFrame（默认）。
"pyarrow"：返回由 pyarrow 支持的可空ArrowDtype DataFrame。

新版本 2.0 中新增。

文件中存储的对象类型

示例

>>> df = pd.read_feather("path/to/file.feather")

`pandas.DataFrame.to_feather`

原文：pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_feather.html

DataFrame.to_feather(path, **kwargs)

将 DataFrame 写入二进制 Feather 格式。

参数：

路径str、路径对象、类文件对象

字符串、路径对象（实现os.PathLike[str]）、或实现二进制write()函数的类文件对象。如果是字符串或路径，则在写入分区数据集时将用作根目录路径。

**kwargs

传递给 pyarrow.feather.write_feather() 的额外关键字。这包括压缩、压缩级别、块大小和版本关键字。

注释

此函数将 dataframe 写入 feather 文件。需要默认索引。要使用支持自定义索引的方法保存带有自定义索引的 DataFrame，例如 to_parquet。

示例

>>> df = pd.DataFrame([[1, 2, 3], [4, 5, 6]])
>>> df.to_feather("file.feather")

`pandas.read_parquet`

原文：pandas.pydata.org/docs/reference/api/pandas.read_parquet.html

pandas.read_parquet(path, engine='auto', columns=None, storage_options=None, use_nullable_dtypes=_NoDefault.no_default, dtype_backend=_NoDefault.no_default, filesystem=None, filters=None, **kwargs)

从文件路径加载 parquet 对象，返回一个 DataFrame。

参数：

path字符串、路径对象或文件对象

字符串、路径对象（实现 os.PathLike[str]）、或者实现了二进制 read() 函数的文件对象。字符串可以是 URL。有效的 URL 方案包括 http、ftp、s3、gs 和 file。对于文件 URL，期望有一个主机。本地文件可以是：file://localhost/path/to/table.parquet。文件 URL 也可以是一个包含多个分区 parquet 文件的目录路径。pyarrow 和 fastparquet 都支持目录路径以及文件 URL。目录路径可以是：file://localhost/path/to/tables 或者 s3://bucket/partition_dir。

engine，默认为 ‘auto’

要使用的 Parquet 库。如果为 ‘auto’，则使用选项 io.parquet.engine。默认的 io.parquet.engine 行为是尝试 ‘pyarrow’，如果 ‘pyarrow’ 不可用，则回退到 ‘fastparquet’。

当使用 'pyarrow' 引擎且没有提供存储选项，且 pyarrow.fs 和 fsspec 都实现了文件系统时（例如 “s3://”），则首先尝试 pyarrow.fs 文件系统。如果希望使用其实现，则使用带有实例化 fsspec 文件系统的 filesystem 关键字。

columns列表，默认为 None

如果不是 None，则只从文件中读取这些列。

storage_options字典，可选

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

自版本 1.3.0 新增。

use_nullable_dtypes布尔值，默认为 False

如果为 True，则使用在生成的 DataFrame 中将 pd.NA 用作缺失值指示符的数据类型。（仅适用于 pyarrow 引擎）随着将来添加支持 pd.NA 的新数据类型，此选项的输出将更改为使用这些数据类型。注意：这是一个试验性选项，行为（例如额外支持的数据类型）可能会在不经通知的情况下发生变化。

自版本 2.0 起已弃用。

dtype_backend，默认为 ‘numpy_nullable’

应用于生成的 DataFrame 的后端数据类型（仍然是试验性的）。行为如下：

"numpy_nullable"：返回基于可为空的 dtype 的 DataFrame（默认）。
"pyarrow"：返回由 pyarrow 支持的可空 ArrowDtype DataFrame。

新版本 2.0 中新增。

filesystemfsspec 或 pyarrow 文件系统，默认为 None

在读取 parquet 文件时要使用的文件系统对象。仅对engine="pyarrow"实现。

新版本 2.1.0 中新增。

filtersList[Tuple] 或 List[List[Tuple]]，默认为 None

过滤数据。过滤器语法：[[(column, op, val), …],…]，其中 op 为 [==, =, >, >=, <, <=, !=, in, not in]。最内层元组通过 AND 操作转置为一组过滤器。外部列表通过 OR 操作组合这些过滤器集。也可以使用单个元组列表，意味着不进行过滤器集之间的 OR 操作。

使用此参数不会导致最终分区按行进行筛选，除非也指定了engine="pyarrow"。对于其他引擎，筛选仅在分区级别执行，即防止加载某些行组和/或文件。

新版本 2.1.0 中新增。

**kwargs

任何额外的 kwargs 都将传递给引擎。

DataFrame

另请参阅

DataFrame.to_parquet

创建序列化 DataFrame 的 Parquet 对象。

示例

>>> original_df = pd.DataFrame(
...     {"foo": range(5), "bar": range(5, 10)}
...    )
>>> original_df
 foo  bar
0    0    5
1    1    6
2    2    7
3    3    8
4    4    9
>>> df_parquet_bytes = original_df.to_parquet()
>>> from io import BytesIO
>>> restored_df = pd.read_parquet(BytesIO(df_parquet_bytes))
>>> restored_df
 foo  bar
0    0    5
1    1    6
2    2    7
3    3    8
4    4    9
>>> restored_df.equals(original_df)
True
>>> restored_bar = pd.read_parquet(BytesIO(df_parquet_bytes), columns=["bar"])
>>> restored_bar
 bar
0    5
1    6
2    7
3    8
4    9
>>> restored_bar.equals(original_df[['bar']])
True

该函数使用直接传递给引擎的 kwargs。在下面的示例中，我们使用 pyarrow 引擎的 filters 参数来过滤 DataFrame 的行。

由于 pyarrow 是默认引擎，我们可以省略引擎参数。请注意，filters 参数由 pyarrow 引擎实现，这可以从多线程中受益，并且在内存方面也可能更经济。

>>> sel = [("foo", ">", 2)]
>>> restored_part = pd.read_parquet(BytesIO(df_parquet_bytes), filters=sel)
>>> restored_part
 foo  bar
0    3    8
1    4    9

`pandas.DataFrame.to_parquet`

原文：pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_parquet.html

DataFrame.to_parquet(path=None, *, engine='auto', compression='snappy', index=None, partition_cols=None, storage_options=None, **kwargs)

将 DataFrame 写入二进制 parquet 格式。

此函数将数据框写入 parquet 文件。您可以选择不同的 parquet 后端，并选择是否压缩。有关更多详细信息，请参阅用户指南。

参数:

pathstr、path 对象、文件样对象或 None，默认为 None

字符串、路径对象（实现 os.PathLike[str]）或实现二进制 write() 函数的文件样对象。如果为 None，则结果将返回为 bytes。如果为字符串或路径，则将其用作写入分区数据集时的根目录路径。

engine，默认为 'auto'

要使用的 parquet 库。如果为 ‘auto’，则使用选项 io.parquet.engine。默认 io.parquet.engine 行为是尝试 ‘pyarrow’，如果 ‘pyarrow’ 不可用，则退回到 ‘fastparquet’。

compressionstr 或 None，默认为 'snappy'

要使用的压缩名称。使用 None 表示不压缩。支持的选项: ‘snappy’、‘gzip’、‘brotli’、‘lz4’、‘zstd’。

indexbool，默认为 None

如果为 True，则将数据框的索引(es)包含在文件输出中。如果为 False，则不会将其写入文件。如果为 None，类似于 True，将保存数据框的索引(es)。但是，而不是保存为值，RangeIndex 将作为元数据中的范围存储，因此不需要太多空间并且更快。其他索引将包含在文件输出中作为列。

partition_cols列表，可选，默认为 None

按照哪些列对数据集进行分区。按给定的顺序分区列。如果路径不是字符串，则必须为 None。

storage_options字典，可选

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

**kwargs

传递给 parquet 库的附加参数。有关更多详细信息，请参阅 pandas io。

如果未提供路径参数，则为 bytes，否则为 None

另请参见

read_parquet

读取一个 parquet 文件。

DataFrame.to_orc

写入 orc 文件。

DataFrame.to_csv

写入 csv 文件。

DataFrame.to_sql

写入到一个 SQL 表中。

DataFrame.to_hdf

写入到 hdf 中。

注意

此函数需要使用 fastparquet 或 pyarrow 库。

示例

>>> df = pd.DataFrame(data={'col1': [1, 2], 'col2': [3, 4]})
>>> df.to_parquet('df.parquet.gzip',
...               compression='gzip')  
>>> pd.read_parquet('df.parquet.gzip')  
 col1  col2
0     1     3
1     2     4

如果你想要获取一个 parquet 内容的缓冲区，你可以使用一个 io.BytesIO 对象，只要你不使用 partition_cols，这会创建多个文件。

>>> import io
>>> f = io.BytesIO()
>>> df.to_parquet(f)
>>> f.seek(0)
0
>>> content = f.read()

`pandas.read_orc`

原文：pandas.pydata.org/docs/reference/api/pandas.read_orc.html

pandas.read_orc(path, columns=None, dtype_backend=_NoDefault.no_default, filesystem=None, **kwargs)

从文件路径加载一个 ORC 对象，返回一个 DataFrame。

参数：

路径字符串，路径对象，或类文件对象

字符串，路径对象（实现os.PathLike[str]），或实现二进制read()函数的类文件对象。字符串可以是 URL。有效的 URL 方案包括 http，ftp，s3 和 file。对于文件 URL，期望有一个主机。本地文件可以是：file://localhost/path/to/table.orc。

列列表，默认为 None

如果不是 None，则只会从文件中读取这些列。输出始终遵循文件的顺序，而不是列列表。这与pyarrow.orc.ORCFile.read()的原始行为相同。

dtype 后端，默认为‘numpy_nullable’

应用于结果DataFrame的后端数据类型（仍处于实验阶段）。行为如下：

"numpy_nullable"：返回由可空 dtype 支持的DataFrame（默认）。
"pyarrow"：返回由 pyarrow 支持的可空ArrowDtype DataFrame。

版本 2.0 中的新功能。

文件系统fsspec 或 pyarrow 文件系统，默认为 None

读取 parquet 文件时要使用的文件系统对象。

版本 2.1.0 中的新功能。

**kwargs

任何额外的 kwargs 都会传递给 pyarrow。

DataFrame

注意事项

在使用此函数之前，您应该阅读关于 ORC 的用户指南和安装可选依赖项。

如果path是指向本地或远程文件的 URI 方案（例如“s3://”），将尝试使用pyarrow.fs文件系统来读取文件。您还可以将 pyarrow 或 fsspec 文件系统对象传递到 filesystem 关键字中，以覆盖此行为。

示例

>>> result = pd.read_orc("example_pa.orc")

`pandas.DataFrame.to_orc`

原文：pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_orc.html

DataFrame.to_orc(path=None, *, engine='pyarrow', index=None, engine_kwargs=None)

将 DataFrame 写入 ORC 格式。

自版本 1.5.0 新增。

参数：

pathstr，文件类对象或 None，默认为 None

如果是一个字符串，它将被用作写入分区数据集时的根目录路径。通过文件类对象，我们指的是具有 write() 方法的对象，比如文件句柄（例如通过内置的 open 函数）。如果路径为 None，则返回一个 bytes 对象。

engine，默认为 ‘pyarrow’

要使用的 ORC 库。

indexbool，可选

如果为 True，则在文件输出中包含数据框的索引(es)。如果为 False，则不会写入文件。如果为 None，类似于 infer，数据框的索引(es)将被保存。但是，不会保存为值，RangeIndex 将作为元数据中的范围存储，因此不需要太多空间，速度更快。其他索引将包含在文件输出中作为列。

engine_kwargsdict[str, Any] 或 None，默认为 None

传递给 pyarrow.orc.write_table() 的额外关键字参数。

如果没有提供路径参数，则返回 bytes，否则返回 None

引发：

未实现错误

一个或多个列的数据类型是类别、无符号整数、间隔、周期或稀疏。

值错误

引擎不是 pyarrow。

另请参见

read_orc

读取一个 ORC 文件。

DataFrame.to_parquet

写入一个 parquet 文件。

DataFrame.to_csv

写入一个 csv 文件。

DataFrame.to_sql

写入到一个 sql 表。

DataFrame.to_hdf

写入到 hdf。

注意

在使用此函数之前，您应该阅读关于 ORC 的用户指南和安装可选依赖项。
此函数需要 pyarrow 库。
支持的数据类型，请参考 Arrow 中支持的 ORC 特性。
当将数据框转换为 ORC 文件时，日期时间列中的时区目前不会被保留。

示例

>>> df = pd.DataFrame(data={'col1': [1, 2], 'col2': [4, 3]})
>>> df.to_orc('df.orc')  
>>> pd.read_orc('df.orc')  
 col1  col2
0     1     4
1     2     3

如果想要获取 orc 内容的缓冲区，可以将其写入 io.BytesIO

>>> import io
>>> b = io.BytesIO(df.to_orc())  
>>> b.seek(0)  
0
>>> content = b.read()

`pandas.read_sas`

原文：pandas.pydata.org/docs/reference/api/pandas.read_sas.html

pandas.read_sas(filepath_or_buffer, *, format=None, index=None, encoding=None, chunksize=None, iterator=False, compression='infer')

读取存储为 XPORT 或 SAS7BDAT 格式文件的 SAS 文件。

参数：

filepath_or_bufferstr，路径对象或类似文件的对象

字符串，路径对象（实现os.PathLike[str]），或实现二进制read()函数的类似文件对象。字符串可以是 URL。有效的 URL 方案包括 http，ftp，s3 和 file。对于文件 URL，期望有一个主机。本地文件可以是：file://localhost/path/to/table.sas7bdat。

formatstr {‘xport’，‘sas7bdat’}或 None

如果为 None，则从文件扩展名推断文件格式。如果为‘xport’或‘sas7bdat’，则使用相应的格式。

index索引列的标识符，默认为 None

应用作为 DataFrame 索引的列的标识符。

encodingstr，默认为 None

文本数据的编码。如果为 None，则文本数据存储为原始字节。

chunksizeint

每次读取文件块大小行，返回迭代器。

iteratorbool，默认为 False

如果为 True，则返回一个用于逐步读取文件的迭代器。

compressionstr 或 dict，默认为‘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 文件的支持。

如果 iterator=False 且 chunksize=None，则为 DataFrame，否则为 SAS7BDATReader

或 XportReader

示例

>>> df = pd.read_sas("sas_data.sas7bdat")

`pandas.read_spss`

原文：pandas.pydata.org/docs/reference/api/pandas.read_spss.html

pandas.read_spss(path, usecols=None, convert_categoricals=True, dtype_backend=_NoDefault.no_default)

从文件路径加载 SPSS 文件，返回一个 DataFrame。

参数：

path字符串或路径

文件路径。

usecols列表样式，可选

返回列的子集。如果为 None，则返回所有列。

convert_categoricals布尔值，默认为 True

将分类列转换为 pd.Categorical。

dtype_backend，默认为‘numpy_nullable’

应用于结果DataFrame的后端数据类型（仍处于实验阶段）。行为如下：

"numpy_nullable"：返回基于可空数据类型的DataFrame（默认）。
"pyarrow"：返回基于 pyarrow 的可空ArrowDtype DataFrame。

版本 2.0 中的新功能。

DataFrame

示例

>>> df = pd.read_spss("spss_data.sav")

`pandas.read_sql_table`

原文：pandas.pydata.org/docs/reference/api/pandas.read_sql_table.html

pandas.read_sql_table(table_name, con, schema=None, index_col=None, coerce_float=True, parse_dates=None, columns=None, chunksize=None, dtype_backend=_NoDefault.no_default)

将 SQL 数据库表读取到 DataFrame 中。

给定表名和 SQLAlchemy 可连接对象，返回一个 DataFrame。该函数不支持 DBAPI 连接。

参数：

table_name 字符串

数据库中 SQL 表的名称。

con SQLAlchemy 可连接对象或字符串

可以提供数据库 URI 作为字符串。不支持 SQLite DBAPI 连接模式。

schema 字符串，默认为 None

数据库模式中 SQL 表的名称，用于查询（如果数据库类型支持）。如果为 None（默认），则使用默认模式。

index_col 字符串或字符串列表，可选，默认为 None

设置为索引（MultiIndex）的列。

coerce_float 布尔值，默认为 True

尝试将非字符串、非数字对象（如 decimal.Decimal）的值转换为浮点数。可能导致精度丢失。

parse_dates列表或字典，默认为 None

要解析为日期的列名列表。
字典 {column_name: format string}，其中 format string 是与解析字符串时间兼容的 strftime 格式，或者在解析整数时间戳时是 (D, s, ns, ms, us) 中的一个。
字典 {column_name: arg dict}，其中 arg dict 对应于 pandas.to_datetime() 的关键字参数。特别适用于没有本地日期时间支持的数据库，如 SQLite。

columns 列表，默认为 None

从 SQL 表中选择的列名列表。

chunksize 整数，默认为 None

如果指定，则返回一个迭代器，其中 chunksize 是每个块中要包含的行数。

dtype_backend {‘numpy_nullable’，‘pyarrow’}，默认为 ‘numpy_nullable’

应用于结果 DataFrame 的后端数据类型（仍处于实验阶段）。行为如下：

"numpy_nullable"：返回空值类型支持的 DataFrame（默认）。
"pyarrow"：返回 pyarrow 支持的空值 ArrowDtype DataFrame。

版本 2.0 中的新功能。

DataFrame 或 Iterator[DataFrame]

将 SQL 表作为带有标签轴的二维数据结构返回。

另请参阅

read_sql_query

将 SQL 查询读取到 DataFrame 中。

read_sql

将 SQL 查询或数据库表读取到 DataFrame 中。

注意事项

任何带有时区信息的日期时间值将被转换为 UTC。

示例

>>> pd.read_sql_table('table_name', 'postgres:///db_name')

`pandas.read_sql_query`

原文：pandas.pydata.org/docs/reference/api/pandas.read_sql_query.html

pandas.read_sql_query(sql, con, index_col=None, coerce_float=True, params=None, parse_dates=None, chunksize=None, dtype=None, dtype_backend=_NoDefault.no_default)

将 SQL 查询读取到 DataFrame 中。

返回一个与查询字符串的结果集对应的 DataFrame。可选择提供 index_col 参数，将其中一列用作索引，否则将使用默认的整数索引。

参数：

sqlstr SQL 查询或 SQLAlchemy 可选择对象（select 或 text 对象）

要执行的 SQL 查询。

conSQLAlchemy 连接、str 或 sqlite3 连接

使用 SQLAlchemy 可以使用该库支持的任何数据库。如果是 DBAPI2 对象，则仅支持 sqlite3。

index_colstr 或 str 列表，可选，默认值：None

要设置为索引（MultiIndex）的列。

coerce_float布尔值，默认值 True

尝试将非字符串、非数值对象（如 decimal.Decimal）的值转换为浮点数。对 SQL 结果集很有用。

params列表、元组或映射，可选，默认值：None

要传递给 execute 方法的参数列表。用于传递参数的语法取决于数据库驱动程序。查看您的数据库驱动程序文档，了解支持的五种语法样式中的哪一种，这些样式在 PEP 249 的 paramstyle 中有描述。例如，对于 psycopg2，使用%(name)s，因此使用 params={'name'：'value'}。

parse_dates列表或字典，默认值：None

要解析为日期的列名列表。
{column_name: format string}的字典，其中 format string 在解析字符串时间时与 strftime 兼容，或者在解析整数时间戳时是(D、s、ns、ms、us)之一。
{column_name: arg dict}的字典，其中 arg dict 对应于pandas.to_datetime()的关键字参数。在没有本地 Datetime 支持的数据库中特别有用，比如 SQLite。

chunksizeint，默认值：None

如果指定，返回一个迭代器，其中 chunksize 是每个块中要包含的行数。

dtype类型名称或列的字典

数据或列的数据类型。例如，np.float64 或{'a': np.float64, 'b': np.int32, 'c': 'Int64'}。

版本 1.3.0 中的新功能。

dtype_backend，默认值‘numpy_nullable’

应用于结果DataFrame的后端数据类型（仍处于实验阶段）。行为如下：

"numpy_nullable"：返回由可空数据类型支持的DataFrame（默认值）。
"pyarrow"：返回由 pyarrow 支持的可空ArrowDtype DataFrame。

版本 2.0 中的新功能。

DataFrame 或 Iterator[DataFrame]

另请参阅

read_sql_table

将 SQL 数据库表读取到 DataFrame 中。

read_sql

将 SQL 查询或数据库表读取到 DataFrame 中。

注意

通过 parse_dates 参数解析带有时区信息的任何日期时间值将被转换为 UTC。

示例

>>> from sqlalchemy import create_engine  
>>> engine = create_engine("sqlite:///database.db")  
>>> with engine.connect() as conn, conn.begin():  
...     data = pd.read_sql_table("data", conn)

`pandas.read_sql`

原文：pandas.pydata.org/docs/reference/api/pandas.read_sql.html

pandas.read_sql(sql, con, index_col=None, coerce_float=True, params=None, parse_dates=None, columns=None, chunksize=None, dtype_backend=_NoDefault.no_default, dtype=None)

将 SQL 查询或数据库表读入 DataFrame。

此函数是 read_sql_table 和 read_sql_query 的便利包装器（用于向后兼容）。它将根据提供的输入委托给特定函数。SQL 查询将被路由到 read_sql_query，而数据库表名将被路由到 read_sql_table。请注意，被委托的函数可能有关于其功能的更具体说明，这里未列出。

参数：

sqlstr 或 SQLAlchemy Selectable（select 或 text 对象）

要执行的 SQL 查询或表名。

conADBC 连接、SQLAlchemy 可连接对象、str 或 sqlite3 连接

ADBC 提供了具有本机类型支持的高性能 I/O，如果可用。使用 SQLAlchemy 可以使用该库支持的任何 DB。如果是 DBAPI2 对象，则仅支持 sqlite3。用户负责处理 ADBC 连接和 SQLAlchemy 可连接对象的引擎处理和连接关闭；str 连接会自动关闭。请参阅这里。

index_colstr 或 str 列表，可选，默认值：None

要设置为索引（MultiIndex）的列。

coerce_float布尔值，默认为 True

尝试将非字符串、非数值对象（如 decimal.Decimal）的值转换为浮点数，对于 SQL 结果集很有用。

params列表、元组或字典，可选，默认值：None

要传递给 execute 方法的参数列表。用于传递参数的语法取决于数据库驱动程序。检查数据库驱动程序文档，了解 PEP 249 中描述的五种语法样式中的哪一种受支持。例如，对于 psycopg2，使用 %(name)s，因此使用 params={‘name’ : ‘value’}。

parse_dates列表或字典，默认值：None

要解析为日期的列名列表。
{column_name: format string} 的字典，其中 format string 在解析字符串时间时与 strftime 兼容，或者在解析整数时间戳时是 (D, s, ns, ms, us) 之一。
{column_name: arg dict} 的字典，其中 arg dict 对应于 pandas.to_datetime() 的关键字参数。在没有本地日期时间支持的数据库中特别有用，例如 SQLite。

columns列表，默认值：None

要从 SQL 表中选择的列名列表（仅在读取表时使用）。

chunksizeint, 默认为 None

如果指定，返回一个迭代器，其中 chunksize 是每个块中要包含的行数。

dtype_backend, 默认为 ‘numpy_nullable’

应用于结果 DataFrame 的后端数据类型（仍处于实验阶段）。行为如下：

"numpy_nullable"：返回支持可空数据类型的 DataFrame（默认）。
"pyarrow"：返回基于 pyarrow 的可空 ArrowDtype DataFrame。

从版本 2.0 开始。

dtype类型名称或列的字典

数据或列的数据类型。例如，np.float64 或 {'a'：np.float64，'b'：np.int32，'c'：'Int64'}。如果传递的是表而不是查询，则忽略该参数。

从版本 2.0.0 开始。

DataFrame 或 Iterator[DataFrame]

另请参见

read_sql_table

将 SQL 数据库表读入 DataFrame。

read_sql_query

将 SQL 查询读入 DataFrame。

示例

通过 SQL 查询或 SQL 表名从 SQL 中读取数据。仅在使用 SQLite 数据库时，才接受 SQL 查询，仅提供 SQL 表名将导致错误。

>>> from sqlite3 import connect
>>> conn = connect(':memory:')
>>> df = pd.DataFrame(data=[[0, '10/11/12'], [1, '12/11/10']],
...                   columns=['int_column', 'date_column'])
>>> df.to_sql(name='test_data', con=conn)
2

>>> pd.read_sql('SELECT int_column, date_column FROM test_data', conn)
 int_column date_column
0           0    10/11/12
1           1    12/11/10

>>> pd.read_sql('test_data', 'postgres:///db_name')

通过 parse_dates 参数对列应用日期解析 parse_dates 参数在提供的列上调用 pd.to_datetime。在字典格式中指定对列应用 pd.to_datetime 的自定义参数值：

>>> pd.read_sql('SELECT int_column, date_column FROM test_data',
...             conn,
...             parse_dates={"date_column": {"format": "%d/%m/%y"}})
 int_column date_column
0           0  2012-11-10
1           1  2010-11-12

从版本 2.2.0 开始：pandas 现在支持通过 ADBC 驱动程序进行读取

>>> from adbc_driver_postgresql import dbapi  
>>> with dbapi.connect('postgres:///db_name') as conn:  
...     pd.read_sql('SELECT int_column FROM test_data', conn)
 int_column
0           0
1           1

`pandas.DataFrame.to_sql`

原文：pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_sql.html

DataFrame.to_sql(name, con, *, schema=None, if_exists='fail', index=True, index_label=None, chunksize=None, dtype=None, method=None)

将存储在 DataFrame 中的记录写入 SQL 数据库。

支持 SQLAlchemy [1] 支持的数据库。可以新建表，追加或覆盖表。

参数：

name字符串

SQL 表的名称。

consqlalchemy.engine.(Engine or Connection) 或 sqlite3.Connection

使用 SQLAlchemy 可以使用该库支持的任何数据库。为 sqlite3.Connection 对象提供了传统支持。用户负责对 SQLAlchemy 可连接对象进行引擎处理和连接关闭。请参阅这里。如果传递的是已经处于事务中的 sqlalchemy.engine.Connection，则事务不会被提交。如果传递的是 sqlite3.Connection，则无法回滚记录插入。

schema字符串，可选

指定模式（如果数据库支持）。如果为 None，则使用默认模式。

if_exists，默认为 ‘fail’

如果表已经存在，应该如何处理。

fail: 引发 ValueError。
replace: 在插入新值之前删除表。
append: 将新值插入到现有表中。

index布尔值，默认为 True

将 DataFrame 索引写入作为列。使用 index_label 作为表中的列名。为该列创建表索引。

index_label字符串或序列，默认为 None

索引列的列标签。如果给定 None（默认值）并且 index 为 True，则使用索引名称。如果 DataFrame 使用 MultiIndex，则应该给出一个序列。

chunksize整数，可选

指定每次写入的批次中的行数。默认情况下，所有行将一次性写入。

dtype字典或标量，可选

为列指定数据类型。如果使用字典，键应该是列名，值应该是 SQLAlchemy 类型或 sqlite3 传统模式的字符串。如果提供了标量，它将应用于所有列。

method，可选

控制使用的 SQL 插入子句：

None：使用标准 SQL INSERT 子句（每行一个）。
‘multi’: 在单个 INSERT 子句中传递多个值。
具有签名 (pd_table, conn, keys, data_iter) 的可调用对象。

详细信息和示例可在 insert method 部分找到。

None 或整数

由 to_sql 影响的行数。如果传递给 method 的可调用对象不返回整数行数，则返回 None。

返回的受影响行数是 sqlite3.Cursor 或 SQLAlchemy 可连接对象的 rowcount 属性的总和，这可能不反映写入行数的确切数量，如 sqlite3 或 SQLAlchemy 中规定的。

版本 1.4.0 中的新功能。

引发：

ValueError

当表已经存在且 if_exists 为 'fail' 时（默认值）。

另请参阅

read_sql

从表中读取一个 DataFrame。

注意事项

如果数据库支持，时区感知的 datetime 列将被写入为 Timestamp with timezone 类型与 SQLAlchemy。否则，datetimes 将被存储为原始时区本地的无时区感知时间戳。

并非所有数据存储支持 method="multi"。例如，Oracle 不支持多值插入。

参考

[1]

docs.sqlalchemy.org

[2]

www.python.org/dev/peps/pep-0249/

示例

创建一个内存中的 SQLite 数据库。

>>> from sqlalchemy import create_engine
>>> engine = create_engine('sqlite://', echo=False)

从头开始创建一个包含 3 行的表。

>>> df = pd.DataFrame({'name' : ['User 1', 'User 2', 'User 3']})
>>> df
 name
0  User 1
1  User 2
2  User 3

>>> df.to_sql(name='users', con=engine)
3
>>> from sqlalchemy import text
>>> with engine.connect() as conn:
...    conn.execute(text("SELECT * FROM users")).fetchall()
[(0, 'User 1'), (1, 'User 2'), (2, 'User 3')]

也可以将 sqlalchemy.engine.Connection 传递给 con：

>>> with engine.begin() as connection:
...     df1 = pd.DataFrame({'name' : ['User 4', 'User 5']})
...     df1.to_sql(name='users', con=connection, if_exists='append')
2

允许这样做是为了支持需要整个操作使用相同的 DBAPI 连接的操作。

>>> df2 = pd.DataFrame({'name' : ['User 6', 'User 7']})
>>> df2.to_sql(name='users', con=engine, if_exists='append')
2
>>> with engine.connect() as conn:
...    conn.execute(text("SELECT * FROM users")).fetchall()
[(0, 'User 1'), (1, 'User 2'), (2, 'User 3'),
 (0, 'User 4'), (1, 'User 5'), (0, 'User 6'),
 (1, 'User 7')]

仅使用 df2 覆盖表。

>>> df2.to_sql(name='users', con=engine, if_exists='replace',
...            index_label='id')
2
>>> with engine.connect() as conn:
...    conn.execute(text("SELECT * FROM users")).fetchall()
[(0, 'User 6'), (1, 'User 7')]

使用 method 来定义一个可调用的插入方法，如果在 PostgreSQL 数据库的表上存在主键冲突，则不执行任何操作。

>>> from sqlalchemy.dialects.postgresql import insert
>>> def insert_on_conflict_nothing(table, conn, keys, data_iter):
...     # "a" is the primary key in "conflict_table"
...     data = [dict(zip(keys, row)) for row in data_iter]
...     stmt = insert(table.table).values(data).on_conflict_do_nothing(index_elements=["a"])
...     result = conn.execute(stmt)
...     return result.rowcount
>>> df_conflict.to_sql(name="conflict_table", con=conn, if_exists="append", method=insert_on_conflict_nothing)  
0

对于 MySQL，如果主键冲突，则更新列 b 和 c 的可调用方法。

>>> from sqlalchemy.dialects.mysql import insert
>>> def insert_on_conflict_update(table, conn, keys, data_iter):
...     # update columns "b" and "c" on primary key conflict
...     data = [dict(zip(keys, row)) for row in data_iter]
...     stmt = (
...         insert(table.table)
...         .values(data)
...     )
...     stmt = stmt.on_duplicate_key_update(b=stmt.inserted.b, c=stmt.inserted.c)
...     result = conn.execute(stmt)
...     return result.rowcount
>>> df_conflict.to_sql(name="conflict_table", con=conn, if_exists="append", method=insert_on_conflict_update)  
2

指定 dtype（对于具有缺失值的整数特别有用）。请注意，虽然 pandas 被强制将数据存储为浮点数，但数据库支持可空整数。在使用 Python 检索数据时，我们会得到整数标量。

>>> df = pd.DataFrame({"A": [1, None, 2]})
>>> df
 A
0  1.0
1  NaN
2  2.0

>>> from sqlalchemy.types import Integer
>>> df.to_sql(name='integers', con=engine, index=False,
...           dtype={"A": Integer()})
3

>>> with engine.connect() as conn:
...   conn.execute(text("SELECT * FROM integers")).fetchall()
[(1,), (None,), (2,)]

`pandas.read_gbq`

原文：pandas.pydata.org/docs/reference/api/pandas.read_gbq.html

pandas.read_gbq(query, project_id=None, index_col=None, col_order=None, reauth=False, auth_local_webserver=True, dialect=None, location=None, configuration=None, credentials=None, use_bqstorage_api=None, max_results=None, progress_bar_type=None)

从 Google BigQuery 加载数据。

自版本 2.2.0 起已弃用：请改用pandas_gbq.read_gbq。

此函数需要pandas-gbq 包。

请查看如何使用 Google BigQuery 进行身份验证指南以获取身份验证说明。

参数：

查询str

用于返回数据值的类似 SQL 的查询。

项目 IDstr，可选

Google BigQuery 帐户项目 ID。在环境中可用时可选。

索引列str，可选

结果 DataFrame 中用作索引的结果列的名称。

列顺序list(str)，可选

结果 DataFrame 中所需顺序的 BigQuery 列名列表。

重新认证bool，默认为 False

强制 Google BigQuery 重新对用户进行身份验证。如果使用多个帐户，则这很有用。

auth_local_webserverbool，默认为 True

在获取用户凭据时，使用本地 Web 服务器流而不是控制台流。

pandas-gbq 的 0.2.0 版本中新增。

在 1.5.0 版本中更改：默认值更改为True。Google 已弃用auth_local_webserver = False的“out of band”（复制粘贴）流程。

方言str，默认为‘legacy’

注意：默认值将在未来版本中更改为‘standard’。

要使用的 SQL 语法方言。值可以是以下之一：

'legacy'

使用 BigQuery 的传统 SQL 方言。更多信息请参见BigQuery 传统 SQL 参考。

'standard'

使用 BigQuery 的标准 SQL，符合 SQL 2011 标准。更多信息请参见BigQuery 标准 SQL 参考。

位置str，可选

查询作业应运行的位置。请参阅BigQuery 位置文档以获取可用位置列表。位置必须与查询中使用的任何数据集的位置��配。

pandas-gbq 的 0.5.0 版本中新增。

配置dict，可选

作业处理的查询配置参数。例如：

configuration = {‘query’: {‘useQueryCache’: False}}

更多信息请参见BigQuery REST API 参考。

凭据google.auth.credentials.Credentials，可选

用于访问 Google API 的凭据。使用此参数来覆盖默认凭据，例如直接使用 Compute Engine google.auth.compute_engine.Credentials 或 Service Account google.oauth2.service_account.Credentials。

在 pandas-gbq 的版本 0.8.0 中新增。

use_bqstorage_apibool，默认为 False

使用BigQuery Storage API快速下载查询结果，但成本增加。要使用此 API，请首先在 Cloud Console 中启用它。您还必须对您正在为其计费的项目具有bigquery.readsessions.create权限。

此功能需要pandas-gbq包的版本 0.10.0 或更高版本。还需要google-cloud-bigquery-storage和fastavro包。

max_resultsint，可选

如果设置，限制从查询结果中获取的最大行数。

progress_bar_type可选，str

如果设置，使用tqdm库在数据下载时显示进度条。安装tqdm包以使用此功能。

progress_bar_type的可能值包括：

None

没有进度条。

'tqdm'

使用 tqdm.tqdm()函数将进度条打印到sys.stderr。

'tqdm_notebook'

使用 tqdm.tqdm_notebook()函数在 Jupyter 笔记本小部件中显示进度条。

'tqdm_gui'

使用 tqdm.tqdm_gui()函数将进度条显示为图形对话框。

df：DataFrame

表示查询结果的 DataFrame。

另请参阅

pandas_gbq.read_gbq

这个函数在 pandas-gbq 库中。

DataFrame.to_gbq

将 DataFrame 写入 Google BigQuery。

示例

示例取自Google BigQuery 文档

>>> sql = "SELECT name FROM table_name WHERE state = 'TX' LIMIT 100;"
>>> df = pd.read_gbq(sql, dialect="standard")  
>>> project_id = "your-project-id"  
>>> df = pd.read_gbq(sql,
...                  project_id=project_id,
...                  dialect="standard"
...                  )

`pandas.read_stata`

原文：pandas.pydata.org/docs/reference/api/pandas.read_stata.html

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。

参数：

filepath_or_bufferstr，路径对象或类文件对象

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

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

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

convert_datesbool，默认为 True

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

convert_categoricalsbool，默认为 True

读取值标签并将列转换为分类/因子变量。

index_colstr，可选

要设置为索引的列。

convert_missingbool，默认为 False

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

preserve_dtypesbool，默认为 True

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

columnslist 或 None

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

order_categoricalsbool，默认为 True

标志，指示转换的分类数据是否有序。

chunksizeint，默认为 None

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

iteratorbool，默认为 False

返回 StataReader 对象。

compressionstr 或 dict，默认为 ‘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，可选

DataFrame 或 pandas.api.typing.StataReader

另请参阅

io.stata.StataReader

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

DataFrame.to_stata

导出 Stata 数据文件。

注意事项

通过迭代器读取的分类变量可能没有相同的类别和数据类型。当存储在 DTA 文件中的变量与仅标记值的不完整集合相关联时，就会发生这种情况。

示例

为此示例创建一个虚拟 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')

以 10,000 行块读取 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

`pandas.DataFrame.to_stata`

原文：pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_stata.html

DataFrame.to_stata(path, *, convert_dates=None, write_index=True, byteorder=None, time_stamp=None, data_label=None, variable_labels=None, version=114, convert_strl=None, compression='infer', storage_options=None, value_labels=None)

将 DataFrame 对象导出为 Stata dta 格式。

将 DataFrame 写入 Stata 数据集文件。“dta”文件包含一个 Stata 数据集。

参数：

path字符串，路径对象或缓冲区

字符串，路径对象（实现os.PathLike[str]），或实现二进制write()函数的文件对象。

convert_dates字典

将包含日期时间类型的列映射到写入日期时要使用的 Stata 内部格式的字典。选项为‘tc’、‘td’、‘tm’、‘tw’、‘th’、‘tq’、‘ty’。列可以是整数或名称。未指定转换类型的日期时间列将转换为‘tc’。如果日期时间列具有时区信息，则引发 NotImplementedError。

write_index布尔值

将索引写入 Stata 数据集。

byteorder字符串

可以是“>”、“<”、“little”或“big”。默认为 sys.byteorder。

time_stamp日期时间

用作文件创建日期的日期时间。默认为当前时间。

data_label字符串，可选

数据集的标签。必须是 80 个字符或更少。

variable_labels字典

包含列作为键和变量标签作为值的字典。每个标签必须是 80 个字符或更少。

version，默认为 114

输出 dta 文件中要使用的版本。设置为 None 以让 pandas 根据框架中的列数在 118 或 119 格式之间做出决定。版本 114 可被 Stata 10 及更高版本读取。版本 117 可被 Stata 13 或更高版本读取。版本 118 在 Stata 14 及更高版本中受支持。版本 119 在 Stata 15 及更高版本中受支持。版本 114 将字符串变量限制为 244 个字符或更少，而版本 117 及更高版本允许长度达到 2,000,000 个字符的字符串。版本 118 和 119 支持 Unicode 字符，版本 119 支持超过 32,767 个变量。

当变量数量超过 dta 格式 118 的容量时，通常应仅使用版本 119。以格式 119 导出较小的数据集可能会产生意想不到的后果，并且截至 2020 年 11 月，Stata SE 无法读取版本 119 文件。

convert_strl列表，可选

要转换为 Stata StrL 格式的字符串列的列名列表。仅在版本为 117 时可用。如果字符串超过 8 个字符且值重复，则将字符串存储为 StrL 格式可以生成更小的 dta 文件。

compression字符串或字典，默认为‘infer’

用于对输出数据进行即时压缩。如果‘infer’和‘path’是类似路径的，则从以下扩展名中检测压缩：‘.gz’、‘.bz2’、‘.zip’、‘.xz’、‘.zst’、‘.tar’、‘.tar.gz’、‘.tar.xz’或‘.tar.bz2’（否则不压缩）。设置为None表示不压缩。也可以是一个字典，其中键'method'设置为其中之一{'zip'、'gzip'、'bz2'、'zstd'、'xz'、'tar'}，其他键值对转发给zipfile.ZipFile、gzip.GzipFile、bz2.BZ2File、zstandard.ZstdCompressor、lzma.LZMAFile或tarfile.TarFile。例如，以下内容可用于更快的压缩和创建可重现的 gzip 存档：compression={'method': 'gzip', 'compresslevel': 1, 'mtime': 1}。

1.5.0 版中新增：添加了对 .tar 文件的支持。

在 1.4.0 版本中更改：Zstandard 支持。

storage_optionsdict, optional

value_labelsdict of dicts

包含列作为键和列值到标签的字典的字典。单个变量的标签必须小于 32,000 个字符。

1.4.0 版中的新功能。

引发：

NotImplementedError

如果日期时间包含时区信息
列的 dtype 无法在 Stata 中表示

ValueError

在 convert_dates 中列出的列既不是 datetime64[ns] 也不是 datetime.datetime
在 convert_dates 中列出的列不在 DataFrame 中
分类标签包含超过 32,000 个字符

另请参见

read_stata

导入 Stata 数据文件。

io.stata.StataWriter

用于 Stata 数据文件的低级写入器。

io.stata.StataWriter117

用于版本 117 文件的低级写入器。

示例

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

`pandas.io.stata.StataReader.data_label`

原文：pandas.pydata.org/docs/reference/api/pandas.io.stata.StataReader.data_label.html

property StataReader.data_label

返回 Stata 文件的数据标签。

Examples

>>> df = pd.DataFrame([(1,)], columns=["variable"])
>>> time_stamp = pd.Timestamp(2000, 2, 29, 14, 21)
>>> data_label = "This is a data file."
>>> path = "/My_path/filename.dta"
>>> df.to_stata(path, time_stamp=time_stamp,    
...             data_label=data_label,  
...             version=None)  
>>> with pd.io.stata.StataReader(path) as reader:  
...     print(reader.data_label)  
This is a data file.

`pandas.io.stata.StataReader.value_labels`

原文：pandas.pydata.org/docs/reference/api/pandas.io.stata.StataReader.value_labels.html

StataReader.value_labels()

返回一个嵌套字典，将每个变量名与其值和标签关联起来。

返回值：

字典

示例

>>> df = pd.DataFrame([[1, 2], [3, 4]], columns=["col_1", "col_2"])
>>> time_stamp = pd.Timestamp(2000, 2, 29, 14, 21)
>>> path = "/My_path/filename.dta"
>>> value_labels = {"col_1": {3: "x"}}
>>> df.to_stata(path, time_stamp=time_stamp,  
...             value_labels=value_labels, version=None)  
>>> with pd.io.stata.StataReader(path) as reader:  
...     print(reader.value_labels())  
{'col_1': {3: 'x'}}
>>> pd.read_stata(path)  
 index col_1 col_2
0       0    1    2
1       1    x    4

`pandas.io.stata.StataReader.variable_labels`

原文：pandas.pydata.org/docs/reference/api/pandas.io.stata.StataReader.variable_labels.html

StataReader.variable_labels()

返回一个将每个变量名与相应标签关联的字典。

字典

示例

>>> df = pd.DataFrame([[1, 2], [3, 4]], columns=["col_1", "col_2"])
>>> time_stamp = pd.Timestamp(2000, 2, 29, 14, 21)
>>> path = "/My_path/filename.dta"
>>> variable_labels = {"col_1": "This is an example"}
>>> df.to_stata(path, time_stamp=time_stamp,  
...             variable_labels=variable_labels, version=None)  
>>> with pd.io.stata.StataReader(path) as reader:  
...     print(reader.variable_labels())  
{'index': '', 'col_1': 'This is an example', 'col_2': ''}
>>> pd.read_stata(path)  
 index col_1 col_2
0       0    1    2
1       1    3    4

`pandas.io.stata.StataWriter.write_file`

原文：pandas.pydata.org/docs/reference/api/pandas.io.stata.StataWriter.write_file.html

StataWriter.write_file()

将 DataFrame 对象导出为 Stata dta 格式。

示例

>>> df = pd.DataFrame({"fully_labelled": [1, 2, 3, 3, 1],
...                    "partially_labelled": [1.0, 2.0, np.nan, 9.0, np.nan],
...                    "Y": [7, 7, 9, 8, 10],
...                    "Z": pd.Categorical(["j", "k", "l", "k", "j"]),
...                    })
>>> path = "/My_path/filename.dta"
>>> labels = {"fully_labelled": {1: "one", 2: "two", 3: "three"},
...           "partially_labelled": {1.0: "one", 2.0: "two"},
...           }
>>> writer = pd.io.stata.StataWriter(path,
...                                  df,
...                                  value_labels=labels)  
>>> writer.write_file()  
>>> df = pd.read_stata(path)  
>>> df  
 index fully_labelled  partially_labeled  Y  Z
0       0            one                one  7  j
1       1            two                two  7  k
2       2          three                NaN  9  l
3       3          three                9.0  8  k
4       4            one                NaN 10  j

通用函数

原文：pandas.pydata.org/docs/reference/general_functions.html

数据操作

`melt`(frame[, id_vars, value_vars, var_name, ...])	将 DataFrame 从宽格式转换为长格式，可选择保留标识符设置。
`pivot`(data, *, columns[, index, values])	返回按给定索引/列值组织的重塑后的 DataFrame。
`pivot_table`(data[, values, index, columns, ...])	创建一个类似电子表格样式的透视表作为 DataFrame。
`crosstab`(index, columns[, values, rownames, ...])	计算两个（或更多）因子的简单交叉制表。
`cut`(x, bins[, right, labels, retbins, ...])	将值分成离散的区间。
`qcut`(x, q[, labels, retbins, precision, ...])	基于分位数的离散化函数。
`merge`(left, right[, how, on, left_on, ...])	用数据库风格的连接合并 DataFrame 或命名 Series 对象。
`merge_ordered`(left, right[, on, left_on, ...])	执行有序数据的合并，可选填充/插值。
`merge_asof`(left, right[, on, left_on, ...])	按键距离执行合并。
`concat`(objs, *[, axis, join, ignore_index, ...])	沿特定轴连接 pandas 对象。
`get_dummies`(data[, prefix, prefix_sep, ...])	将分类变量转换为虚拟/指示变量。
`from_dummies`(data[, sep, default_category])	从虚拟变量的 DataFrame 创建一个分类 `DataFrame`。
`factorize`(values[, sort, use_na_sentinel, ...])	将对象编码为枚举类型或分类变量。
`unique`(values)	基于哈希表返回唯一值。
`lreshape`(data, groups[, dropna])	将宽格式数据重塑为长格式。
`wide_to_long`(df, stubnames, i, j[, sep, suffix])	将 DataFrame 从宽格式转换为长格式。

顶层缺失数据

`isna`(obj)	检测数组样式对象中的缺失值。
`isnull`(obj)	检测数组样式对象中的缺失值。
`notna`(obj)	检测数组样式对象中的非缺失值。
`notnull`(obj)	检测数组样式对象中的非缺失值。

处理数值数据的顶层函数

`to_numeric`(arg[, errors, downcast, ...])	将参数转换为数值类型。

处理日期时间数据的顶层函数

`to_datetime`(arg[, errors, dayfirst, ...])	将参数转换为日期时间格式。
`to_timedelta`(arg[, unit, errors])	将参数转换为时间间隔。
`date_range`([start, end, periods, freq, tz, ...])	返回固定频率的日期时间索引。
`bdate_range`([start, end, periods, freq, tz, ...])	返回固定频率的工作日为默认的日期时间索引。
`period_range`([start, end, periods, freq, name])	返回固定频率的周期索引。
`timedelta_range`([start, end, periods, freq, ...])	返回固定频率以天为默认的时间间隔索引。
`infer_freq`(index)	推断给定输入索引的最可能频率。

处理区间数据的顶层函数

`interval_range`([start, end, periods, freq, ...])	返回固定频率的区间索引。

顶层评估

`eval`(expr[, parser, engine, local_dict, ...])	使用不同的后端评估 Python 表达式字符串。

日期时间格式

`tseries.api.guess_datetime_format`(dt_str[, ...])	猜测给定日期时间字符串的日期时间格式。

哈希处理

`util.hash_array`(vals[, encoding, hash_key, ...])	给定一维数组，返回一组确定性整数。
`util.hash_pandas_object`(obj[, index, ...])	返回索引/系列/数据框的数据哈希值。

从其他 DataFrame 库导入

`api.interchange.from_dataframe`(df[, allow_copy])	从支持交换协议的任何 DataFrame 构建`pd.DataFrame`。

数据操作

`melt`(frame[, id_vars, value_vars, var_name, ...])	将 DataFrame 从宽格式转换为长格式，可选择保留标识符设置。
`pivot`(data, *, columns[, index, values])	返回按给定索引/列值组织的重塑 DataFrame。
`pivot_table`(data[, values, index, columns, ...])	创建一个类似电子表格的透视表作为 DataFrame。
`crosstab`(index, columns[, values, rownames, ...])	计算两个（或更多）因子的简单交叉制表。
`cut`(x, bins[, right, labels, retbins, ...])	将值分成离散区间。
`qcut`(x, q[, labels, retbins, precision, ...])	基于分位数的离散化函数。
`merge`(left, right[, how, on, left_on, ...])	用数据库风格的连接合并 DataFrame 或命名 Series 对象。
`merge_ordered`(left, right[, on, left_on, ...])	对有序数据执行合并，可选择填充/插值。
`merge_asof`(left, right[, on, left_on, ...])	按键距离执行合并。
`concat`(objs, *[, axis, join, ignore_index, ...])	沿特定轴连接 pandas 对象。
`get_dummies`(data[, prefix, prefix_sep, ...])	将分类变量转换为虚拟/指示变量。
`from_dummies`(data[, sep, default_category])	从虚拟变量的 DataFrame 创建一个分类`DataFrame`。
`factorize`(values[, sort, use_na_sentinel, ...])	将对象编码为枚举类型或分类变量。
`unique`(values)	基于哈希表返回唯一值。
`lreshape`(data, groups[, dropna])	将宽格式数据重塑为长格式。
`wide_to_long`	将宽格式的 DataFrame 重塑为长格式。

处理缺失数据的顶级函数

`isna`	检测类数组对象中的缺失值。
`isnull`	检测类数组对象中的缺失值。
`notna`	检测类数组对象中的非缺失值。
`notnull`	检测类数组对象中的非缺失值。

处理数值数据的顶级函数

`to_numeric`	将参数转换为数字类型。

处理日期时间数据的顶级函数

`to_datetime`	将参数转换为日期时间。
`to_timedelta`	将参数转换为时间增量。
`date_range`	返回固定频率的 DatetimeIndex。
`bdate_range`	返回以工作日为默认值的固定频率 DatetimeIndex。
`period_range`	返回固定频率的 PeriodIndex。
`timedelta_range`	返回以天为默认值的固定频率 TimedeltaIndex。
`infer_freq`	推断给定输入索引的最可能频率。

处理区间数据的顶级函数

`interval_range`	返回固定频率的 IntervalIndex。

顶级评估函数

`eval`	使用各种后端评估字符串形式的 Python 表达式。

日期时间格式

`tseries.api.guess_datetime_format`	猜测给定日期时间字符串的日期时间格式。

哈希处理

`util.hash_array`	给定一维数组，返回一组确定性整数。
`util.hash_pandas_object`(obj[, index, ...])	返回索引/系列/数据框的数据哈希。

导入其他数据框库

`api.interchange.from_dataframe`(df[, allow_copy])	从支持交换协议的任何数据框构建一个`pd.DataFrame`。

`pandas.melt`

原文：pandas.pydata.org/docs/reference/api/pandas.melt.html

pandas.melt(frame, id_vars=None, value_vars=None, var_name=None, value_name='value', col_level=None, ignore_index=True)

将 DataFrame 从宽格式转换为长格式，可选择保留标识符。

此函数可将 DataFrame 整理成一种格式，其中一个或多个列是标识符变量（id_vars），而所有其他列，被视为测量变量（value_vars），被“解开”到行轴，只留下两个非标识符列，'variable'和'value'。

参数：

id_vars标量、元组、列表或 ndarray，可选

用作标识符变量的列。

value_vars标量、元组、列表或 ndarray，可选

要解开的列。如果未指定，则使用所有未设置为 id_vars 的列。

var_name标量，默认为 None

用于'variable'列的名称。如果为 None，则使用frame.columns.name或'variable'。

value_name标量，默认为'value'

用于'value'列的名称，不能是现有的列标签。

col_level标量，可选

如果列是多级索引，则使用此级别进行解开。

ignore_index布尔值，默认为 True

如果为 True，则忽略原始索引。如果为 False，则保留原始索引。必要时将重复索引标签。

DataFrame

解开的 DataFrame。

另请参见

DataFrame.melt

相同的方法。

pivot_table

创建一个类似电子表格的透视表作为 DataFrame。

DataFrame.pivot

返回按给定索引/列值组织的重塑 DataFrame。

DataFrame.explode

将 DataFrame 从类似列表的列转换为长格式。

注意

参考用户指南获取更多示例。

示例

>>> df = pd.DataFrame({'A': {0: 'a', 1: 'b', 2: 'c'},
...                    'B': {0: 1, 1: 3, 2: 5},
...                    'C': {0: 2, 1: 4, 2: 6}})
>>> df
 A  B  C
0  a  1  2
1  b  3  4
2  c  5  6

>>> pd.melt(df, id_vars=['A'], value_vars=['B'])
 A variable  value
0  a        B      1
1  b        B      3
2  c        B      5

>>> pd.melt(df, id_vars=['A'], value_vars=['B', 'C'])
 A variable  value
0  a        B      1
1  b        B      3
2  c        B      5
3  a        C      2
4  b        C      4
5  c        C      6

可自定义'variable'和'value'列的名称：

>>> pd.melt(df, id_vars=['A'], value_vars=['B'],
...         var_name='myVarname', value_name='myValname')
 A myVarname  myValname
0  a         B          1
1  b         B          3
2  c         B          5

可以保留原始索引值：

>>> pd.melt(df, id_vars=['A'], value_vars=['B', 'C'], ignore_index=False)
 A variable  value
0  a        B      1
1  b        B      3
2  c        B      5
0  a        C      2
1  b        C      4
2  c        C      6

如果有多级索引列：

>>> df.columns = [list('ABC'), list('DEF')]
>>> df
 A  B  C
 D  E  F
0  a  1  2
1  b  3  4
2  c  5  6

>>> pd.melt(df, col_level=0, id_vars=['A'], value_vars=['B'])
 A variable  value
0  a        B      1
1  b        B      3
2  c        B      5

>>> pd.melt(df, id_vars=[('A', 'D')], value_vars=[('B', 'E')])
 (A, D) variable_0 variable_1  value
0      a          B          E      1
1      b          B          E      3
2      c          B          E      5

`pandas.pivot`

原文：pandas.pydata.org/docs/reference/api/pandas.pivot.html

pandas.pivot(data, *, columns, index=_NoDefault.no_default, values=_NoDefault.no_default)

返回根据给定索引/列值组织的重塑后的 DataFrame。

根据列值重塑数据（生成“透视”表）。使用指定索引/列的唯一值来形成结果 DataFrame 的轴。此函数不支持数据聚合，多个值将导致列中的多重索引。有关更多重塑信息，请参阅用户指南。

参数：

data：DataFrame

columns：str 或对象或 str 列表

用于创建新框架列的列。

index：str 或对象或 str 列表，可选

用于创建新框架索引的列。如果未给出，则使用现有索引。

values：str、object 或前述内容的列表，可选

用于填充新框架值的列。如果未指定，将使用所有剩余列，并且结果将具有分层索引的列。

DataFrame

返回重塑后的 DataFrame。

引发：

ValueError：

当存在具有多个值的索引、列组合时。需要对数据进行聚合时使用DataFrame.pivot_table。

另请参见

DataFrame.pivot_table

可以处理一个索引/列对的重复值的pivot的泛化。

DataFrame.unstack

基于索引值而不是列进行pivot。

wide_to_long

宽面板转换为长格式。比melt不太灵活，但更加用户友好。

注意

对于更精细的控制，请参阅分层索引文档以及相关的stack/unstack方法。

有关更多示例，请参考用户指南。

示例

>>> df = pd.DataFrame({'foo': ['one', 'one', 'one', 'two', 'two',
...                            'two'],
...                    'bar': ['A', 'B', 'C', 'A', 'B', 'C'],
...                    'baz': [1, 2, 3, 4, 5, 6],
...                    'zoo': ['x', 'y', 'z', 'q', 'w', 't']})
>>> df
 foo   bar  baz  zoo
0   one   A    1    x
1   one   B    2    y
2   one   C    3    z
3   two   A    4    q
4   two   B    5    w
5   two   C    6    t

>>> df.pivot(index='foo', columns='bar', values='baz')
bar  A   B   C
foo
one  1   2   3
two  4   5   6

>>> df.pivot(index='foo', columns='bar')['baz']
bar  A   B   C
foo
one  1   2   3
two  4   5   6

>>> df.pivot(index='foo', columns='bar', values=['baz', 'zoo'])
 baz       zoo
bar   A  B  C   A  B  C
foo
one   1  2  3   x  y  z
two   4  5  6   q  w  t

您还可以分配列名称列表或索引名称列表。

>>> df = pd.DataFrame({
...        "lev1": [1, 1, 1, 2, 2, 2],
...        "lev2": [1, 1, 2, 1, 1, 2],
...        "lev3": [1, 2, 1, 2, 1, 2],
...        "lev4": [1, 2, 3, 4, 5, 6],
...        "values": [0, 1, 2, 3, 4, 5]})
>>> df
 lev1 lev2 lev3 lev4 values
0   1    1    1    1    0
1   1    1    2    2    1
2   1    2    1    3    2
3   2    1    2    4    3
4   2    1    1    5    4
5   2    2    2    6    5

>>> df.pivot(index="lev1", columns=["lev2", "lev3"], values="values")
lev2    1         2
lev3    1    2    1    2
lev1
1     0.0  1.0  2.0  NaN
2     4.0  3.0  NaN  5.0

>>> df.pivot(index=["lev1", "lev2"], columns=["lev3"], values="values")
 lev3    1    2
lev1  lev2
 1     1  0.0  1.0
 2  2.0  NaN
 2     1  4.0  3.0
 2  NaN  5.0

如果存在任何重复项，则会引发ValueError。

>>> df = pd.DataFrame({"foo": ['one', 'one', 'two', 'two'],
...                    "bar": ['A', 'A', 'B', 'C'],
...                    "baz": [1, 2, 3, 4]})
>>> df
 foo bar  baz
0  one   A    1
1  one   A    2
2  two   B    3
3  two   C    4

注意，对于我们的索引和列参数，前两行是相同的。

>>> df.pivot(index='foo', columns='bar', values='baz')
Traceback (most recent call last):
  ...
ValueError: Index contains duplicate entries, cannot reshape

`pandas.pivot_table`

原文：pandas.pydata.org/docs/reference/api/pandas.pivot_table.html

pandas.pivot_table(data, values=None, index=None, columns=None, aggfunc='mean', fill_value=None, margins=False, dropna=True, margins_name='All', observed=_NoDefault.no_default, sort=True)

创建一个类似电子表格的透视表作为数据帧。

透视表中的级别将存储在结果数据帧的索引和列上的 MultiIndex 对象（分层索引）中。

参数:

data数据帧

values类似列表或标量，可选

要进行聚合的列。

index列、分组器、数组或先前的列表

透视表索引上要分组的键。如果传递了列表，则可以包含任何其他类型（除列表外）。如果传递了数组，则必须与数据的长度相同，并将以与列值相同的方式使用。

columns列、分组器、数组或先前的列表

透视表列上要分组的键。如果传递了列表，则可以包含任何其他类型（除列表外）。如果传递了数组，则必须与数据的长度相同，并将以与列值相同的方式使用。

aggfunc函数、函数列表、字典，默认为“mean”

如果传递了函数列表，则生成的透视表将具有分层列，其顶级是函数名称（从函数对象本身推断出）。如果传递了字典，则键是要聚合的列，值是函数或函数列表。如果 margin=True，则将使用 aggfunc 计算部分聚合。

fill_value标量，默认为 None

在聚合后的透视表中用来替换缺失值的值。

margins布尔型，默认为 False

如果 margins=True，则将添加特殊的 All 列和行，其中包含行和列上类别的部分组聚合。

dropna布尔型，默认为 True

不包括所有条目均为 NaN 的列。如果为 True，则在计算边缘之前将省略具有任何列中的 NaN 值的行。

margins_name字符串，默认为 ‘All’

当边际为 True 时，包含总计的行/列的名称。

observed布尔型，默认为 False

仅当任何分组器为 Categoricals 时才适用。如果为 True：仅显示分类分组器的观察值。如果为 False：显示分类分组器的所有值。

自 2.2.0 版弃用: False 的默认值已弃用，并将在将来的 pandas 版本中更改为 True。

sort布尔型，默认为 True

指定结果是否应该排序。

1.3.0 版新增。

数据帧

Excel 风格的透视表。

参见

DataFrame.pivot

无聚合的透视，可以处理非数值数据。

DataFrame.melt

将数据帧从宽格式转换为长格式，可选择保留标识符。

wide_to_long

宽格式面板转换为长格式。比 melt 更少灵活但更用户友好。

注意

更多示例，请参考用户指南。

示例

>>> df = pd.DataFrame({"A": ["foo", "foo", "foo", "foo", "foo",
...                          "bar", "bar", "bar", "bar"],
...                    "B": ["one", "one", "one", "two", "two",
...                          "one", "one", "two", "two"],
...                    "C": ["small", "large", "large", "small",
...                          "small", "large", "small", "small",
...                          "large"],
...                    "D": [1, 2, 2, 3, 3, 4, 5, 6, 7],
...                    "E": [2, 4, 5, 5, 6, 6, 8, 9, 9]})
>>> df
 A    B      C  D  E
0  foo  one  small  1  2
1  foo  one  large  2  4
2  foo  one  large  2  5
3  foo  two  small  3  5
4  foo  two  small  3  6
5  bar  one  large  4  6
6  bar  one  small  5  8
7  bar  two  small  6  9
8  bar  two  large  7  9

这个第一个示例通过求和来聚合值。

>>> table = pd.pivot_table(df, values='D', index=['A', 'B'],
...                        columns=['C'], aggfunc="sum")
>>> table
C        large  small
A   B
bar one    4.0    5.0
 two    7.0    6.0
foo one    4.0    1.0
 two    NaN    6.0

我们还可以使用 fill_value 参数填充缺失值。

>>> table = pd.pivot_table(df, values='D', index=['A', 'B'],
...                        columns=['C'], aggfunc="sum", fill_value=0)
>>> table
C        large  small
A   B
bar one      4      5
 two      7      6
foo one      4      1
 two      0      6

下一个示例通过计算多列的均值进行聚合。

>>> table = pd.pivot_table(df, values=['D', 'E'], index=['A', 'C'],
...                        aggfunc={'D': "mean", 'E': "mean"})
>>> table
 D         E
A   C
bar large  5.500000  7.500000
 small  5.500000  8.500000
foo large  2.000000  4.500000
 small  2.333333  4.333333

我们还可以计算给定值列的多种类型的聚合。

>>> table = pd.pivot_table(df, values=['D', 'E'], index=['A', 'C'],
...                        aggfunc={'D': "mean",
...                                 'E': ["min", "max", "mean"]})
>>> table
 D   E
 mean max      mean  min
A   C
bar large  5.500000   9  7.500000    6
 small  5.500000   9  8.500000    8
foo large  2.000000   5  4.500000    4
 small  2.333333   6  4.333333    2

`pandas.crosstab`

原文：pandas.pydata.org/docs/reference/api/pandas.crosstab.html

pandas.crosstab(index, columns, values=None, rownames=None, colnames=None, aggfunc=None, margins=False, margins_name='All', dropna=True, normalize=False)

计算两个（或更多）因素的简单交叉制表。

默认情况下，除非传递值数组和聚合函数，否则计算因素的频率表。

参数：

index类似数组，Series 或数组/Series 列表

要根据行进行分组的值。

columns类似数组，Series 或数组/Series 列表

列中要分组的值。

values类似数组，可选

要根据因素进行聚合的值数组。需要指定 aggfunc。

rownames序列，默认为 None

如果传递，必须与传递的行数组数量匹配。

colnames序列，默认为 None

如果传递，必须与传递的列数组数量匹配。

aggfunc函数，可选

如果指定，还需要指定值。

margins布尔值，默认为 False

添加行/列边距（小计）。

margins_name字符串，默认为‘All’

当 margins 为 True 时，将包含总计的行/列的名称。

dropna布尔值，默认为 True

不包括所有条目都是 NaN 的列。

normalize布尔值，{‘all’, ‘index’, ‘columns’}或{0,1}，默认为 False

通过将所有值除以值的总和来进行规范化。

如果传递‘all’或 True，将在所有值上进行规范化。
如果传递‘index’，将在每行上进行规范化。
如果传递‘columns’，将在每列上进行规范化。
如果 margins 为 True，则还会规范化边距值。

DataFrame

数据的交叉制表。

另请参见

DataFrame.pivot

根据列值重塑数据。

pivot_table

创建一个作为 DataFrame 的数据透视表。

注意

任何传递的 Series 将使用它们的 name 属性，除非为交叉制表指定了行或列名称。

任何包含分类数据的输入都将包含其所有类别在交叉制表中，即使实际数据不包含特定类别的任何实例。

如果没有重叠的索引，则将返回一个空的 DataFrame。

参考用户指南获取更多示例。

示例

>>> a = np.array(["foo", "foo", "foo", "foo", "bar", "bar",
...               "bar", "bar", "foo", "foo", "foo"], dtype=object)
>>> b = np.array(["one", "one", "one", "two", "one", "one",
...               "one", "two", "two", "two", "one"], dtype=object)
>>> c = np.array(["dull", "dull", "shiny", "dull", "dull", "shiny",
...               "shiny", "dull", "shiny", "shiny", "shiny"],
...              dtype=object)
>>> pd.crosstab(a, [b, c], rownames=['a'], colnames=['b', 'c'])
b   one        two
c   dull shiny dull shiny
a
bar    1     2    1     0
foo    2     2    1     2

这里的‘c’和‘f’在数据中没有表示，并且不会显示在输出中，因为默认情况下 dropna 为 True。设置 dropna=False 以保留没有数据的类别。

>>> foo = pd.Categorical(['a', 'b'], categories=['a', 'b', 'c'])
>>> bar = pd.Categorical(['d', 'e'], categories=['d', 'e', 'f'])
>>> pd.crosstab(foo, bar)
col_0  d  e
row_0
a      1  0
b      0  1
>>> pd.crosstab(foo, bar, dropna=False)
col_0  d  e  f
row_0
a      1  0  0
b      0  1  0
c      0  0  0

`pandas.cut`

原文：pandas.pydata.org/docs/reference/api/pandas.cut.html

pandas.cut(x, bins, right=True, labels=None, retbins=False, precision=3, include_lowest=False, duplicates='raise', ordered=True)

将值分箱为离散间隔。

当您需要将数据值分段并排序到箱中时，请使用 cut。此函数还可用于从连续变量转换为分类变量。例如，cut 可以将年龄转换为年龄范围的组。支持将值分箱为相等数量的箱，或预先指定的箱数组。

参数：

x类似数组

要进行分箱的输入数组。必须是一维的。

bins整数，标量序列或 IntervalIndex

按照什么标准进行分箱。

int：定义 x 范围内等宽箱的数量。x 的范围在每一侧扩展了 0.1％，以包括 x 的最小值和最大值。
标量序列：定义允许非均匀宽度的箱边。不会扩展 x 的范围。
IntervalIndex：定义要使用的确切箱。请注意，箱的 IntervalIndex 必须是不重叠的。

right布尔值，默认为 True

指示 bins 是否包括最右边的边缘。如果right == True（默认值），则 bins [1, 2, 3, 4] 表示 (1,2], (2,3], (3,4]。当 bins 为 IntervalIndex 时，此参数将被忽略。

labels数组或 False，默认为 None

指定返回箱的标签。必须与结果箱的长度相同。如果为 False，则仅返回箱的整数指示器。这会影响输出容器的类型（见下文）。当 bins 为 IntervalIndex 时，此参数将被忽略。如果为 True，则会引发错误。当 ordered=False 时，必须提供标签。

retbins布尔值，默认为 False

是否返回箱子。当 bins 作为标量提供时很有用。

precision整数，默认为 3

存储和显示箱标签的精度。

include_lowest布尔值，默认为 False

第一个间隔是否应该是左包含的。

duplicates，可选

如果箱边不唯一，则引发 ValueError 或删除非唯一项。

ordered布尔值，默认为 True

标签是否有序。适用于返回的类型 Categorical 和 Series（带有 Categorical dtype）。如果为 True，则生成的分类将是有序的。如果为 False，则生成的分类将是无序的（必须提供标签）。

out分类、系列或 ndarray

一个类似数组的对象，表示每个 x 值对应的相应箱子。其类型取决于标签的值。

None（默认）：对于 Series x 返回一个 Series，对于其他所有输入返回一个 Categorical。其中存储的值为 Interval 类型。
标量序列：对于 Series x 返回一个 Series，对于其他所有输入返回一个 Categorical。其中存储的值为序列中的类型。
False：返回一个整数的 ndarray。

binsnumpy.ndarray 或 IntervalIndex。

计算或指定的 bins。仅当 retbins=True 时返回。对于标量或序列 bins，这是一个包含计算的 bins 的 ndarray。如果设置 duplicates=drop，则 bins 将删除非唯一 bin。对于 IntervalIndex bins，这等于 bins。

另请参见

qcut

根据排名或基于样本分位数将变量分成大小相等的桶。

Categorical

用于存储来自固定值集的数据的数组类型。

Series

带有轴标签的一维数组（包括时间序列）。

IntervalIndex

Immutable Index 实现一个有序的、可切片的集合。

注

任何 NA 值在结果中都将是 NA。超出边界值在结果 Series 或 Categorical 对象中将是 NA。

查阅用户指南以获取更多示例。

示例

分成三个大小相等的 bins。

>>> pd.cut(np.array([1, 7, 5, 4, 6, 3]), 3)
... 
[(0.994, 3.0], (5.0, 7.0], (3.0, 5.0], (3.0, 5.0], (5.0, 7.0], ...
Categories (3, interval[float64, right]): [(0.994, 3.0] < (3.0, 5.0] ...

>>> pd.cut(np.array([1, 7, 5, 4, 6, 3]), 3, retbins=True)
... 
([(0.994, 3.0], (5.0, 7.0], (3.0, 5.0], (3.0, 5.0], (5.0, 7.0], ...
Categories (3, interval[float64, right]): [(0.994, 3.0] < (3.0, 5.0] ...
array([0.994, 3\.   , 5\.   , 7\.   ]))

发现相同的 bins，但将它们分配为特定的标签。请注意，返回的 Categorical 的 categories 是标签且是有序的。

>>> pd.cut(np.array([1, 7, 5, 4, 6, 3]),
...        3, labels=["bad", "medium", "good"])
['bad', 'good', 'medium', 'medium', 'good', 'bad']
Categories (3, object): ['bad' < 'medium' < 'good']

当传递标签时，ordered=False 将导致无序的类别。此参数可用于允许非唯一标签：

>>> pd.cut(np.array([1, 7, 5, 4, 6, 3]), 3,
...        labels=["B", "A", "B"], ordered=False)
['B', 'B', 'A', 'A', 'B', 'B']
Categories (2, object): ['A', 'B']

labels=False 表示你只想要回来的 bins。

>>> pd.cut([0, 1, 1, 2], bins=4, labels=False)
array([0, 1, 1, 3])

将 Series 作为输入传递将返回一个带有分类 dtype 的 Series：

>>> s = pd.Series(np.array([2, 4, 6, 8, 10]),
...               index=['a', 'b', 'c', 'd', 'e'])
>>> pd.cut(s, 3)
... 
a    (1.992, 4.667]
b    (1.992, 4.667]
c    (4.667, 7.333]
d     (7.333, 10.0]
e     (7.333, 10.0]
dtype: category
Categories (3, interval[float64, right]): [(1.992, 4.667] < (4.667, ...

将 Series 作为输入传递将返回一个带有映射值的 Series。它用于基于 bins 将数值映射到区间。

>>> s = pd.Series(np.array([2, 4, 6, 8, 10]),
...               index=['a', 'b', 'c', 'd', 'e'])
>>> pd.cut(s, [0, 2, 4, 6, 8, 10], labels=False, retbins=True, right=False)
... 
(a    1.0
 b    2.0
 c    3.0
 d    4.0
 e    NaN
 dtype: float64,
 array([ 0,  2,  4,  6,  8, 10]))

当 bins 不唯一时使用 drop 选项。

>>> pd.cut(s, [0, 2, 4, 6, 10, 10], labels=False, retbins=True,
...        right=False, duplicates='drop')
... 
(a    1.0
 b    2.0
 c    3.0
 d    3.0
 e    NaN
 dtype: float64,
 array([ 0,  2,  4,  6, 10]))

将 IntervalIndex 作为 bins 传递会导致这些类别完全一样。注意，不在 IntervalIndex 覆盖范围内的值将被设置为 NaN。0 在第一个 bin 的左侧（右侧关闭）上，而 1.5 位于两个 bin 之间。

>>> bins = pd.IntervalIndex.from_tuples([(0, 1), (2, 3), (4, 5)])
>>> pd.cut([0, 0.5, 1.5, 2.5, 4.5], bins)
[NaN, (0.0, 1.0], NaN, (2.0, 3.0], (4.0, 5.0]]
Categories (3, interval[int64, right]): [(0, 1] < (2, 3] < (4, 5]]

`pandas.qcut`

原文：pandas.pydata.org/docs/reference/api/pandas.qcut.html

pandas.qcut(x, q, labels=None, retbins=False, precision=3, duplicates='raise')

基于分位数的离散化函数。

根据排名或样本分位数将变量离散化为相等大小的桶。例如，对于 10 个分位数的 1000 个值，将产生一个 Categorical 对象，指示每个数据点的分位数成员资格。

参数：

x1 维 ndarray 或 Series

qint 或浮点数列表

分位数的数量。十分位数为 10，四分位数为 4，等等。也可以是分位数数组，例如 [0, .25, .5, .75, 1.] 代表四分位数。

labels数组或 False，默认为 None

用作结果 bins 的标签。必须与结果 bins 长度相同。如果为 False，则仅返回 bins 的整数指示器。如果为 True，则会引发错误。

retbins布尔值，可选

是否返回（bins, labels）或不返回。如果 bins 给定为标量，则可能很有用。

precision整数，可选

存储和显示 bins 标签的精度。

duplicates，可选

如果 bin 边界不唯一，则引发 ValueError 或删除非唯一值。

outCategorical 或 Series 或整数数组（如果 labels 为 False）

返回类型（Categorical 或 Series）取决于输入：如果输入为 Series，则返回类型为 category 的 Series，否则为 Categorical。当返回分类数据时，bins 被表示为类别。

bins浮点数的 ndarray

仅在 retbins 为 True 时返回。

注意

结果分类对象中超出范围的值将为 NA

示例

>>> pd.qcut(range(5), 4)
... 
[(-0.001, 1.0], (-0.001, 1.0], (1.0, 2.0], (2.0, 3.0], (3.0, 4.0]]
Categories (4, interval[float64, right]): [(-0.001, 1.0] < (1.0, 2.0] ...

>>> pd.qcut(range(5), 3, labels=["good", "medium", "bad"])
... 
[good, good, medium, bad, bad]
Categories (3, object): [good < medium < bad]

>>> pd.qcut(range(5), 4, labels=False)
array([0, 0, 1, 2, 3])

`pandas.merge`

原文：pandas.pydata.org/docs/reference/api/pandas.merge.html

pandas.merge(left, right, how='inner', on=None, left_on=None, right_on=None, left_index=False, right_index=False, sort=False, suffixes=('_x', '_y'), copy=None, indicator=False, validate=None)

用数据库风格的连接合并 DataFrame 或命名的 Series 对象。

命名的 Series 对象被视为具有单个命名列的 DataFrame。

连接是在列或索引上完成的。如果在列上连接列，则 DataFrame 索引将被忽略。否则，如果在索引上连接索引或在列或列上连接索引，则索引将被传递。在执行交叉合并时，不允许对要合并的列进行任何列规范。

警告

如果两个键列都包含键为 null 值的行，则这些行将相互匹配。这与通常的 SQL 连接行为不同，可能导致意外结果。

参数：

left DataFrame 或命名的 Series

right DataFrame 或命名的 Series

要合并的对象。

how {‘left’, ‘right’, ‘outer’, ‘inner’, ‘cross’}，默认为 ‘inner’

要执行的合并类型。

left：仅使用左侧框架中的键，类似于 SQL 中的左外连接；保留键的顺序。
right：仅使用右侧框架中的键，类似于 SQL 中的右外连接；保留键的顺序。
outer：使用两个框架中键的并集，类似于 SQL 中的完全外连接；按字典顺序排序键。
inner：使用两个框架中键的交集，类似于 SQL 中的内连接；保留左键的顺序。
cross：从两个框架创建笛卡尔积，保留左键的顺序。

on 标签或列表

要连接的列或索引级别名称。这些必须在两个 DataFrame 中找到。如果 on 为 None 并且不在索引上合并，则默认为两个 DataFrame 中列的交集。

left_on 标签或列表，或类似数组

要在左侧 DataFrame 中连接的列或索引级别名称。也可以是左侧 DataFrame 长度的数组或数组列表。这些数组被视为列。

right_on 标签或列表，或类似数组

要在右侧 DataFrame 中连接的列或索引级别名称。也可以是右侧 DataFrame 长度的数组或数组列表。这些数组被视为列。

left_index 布尔值，默认为 False

使用左侧 DataFrame 的索引作为连接键。如果它是 MultiIndex，则另一个 DataFrame 中的键的数量（索引或列数）必须与级别数相匹配。

right_index 布尔值，默认为 False

使用右侧 DataFrame 中的索引作为连接键。与 left_index 相同的注意事项。

sort 布尔值，默认为 False

在结果 DataFrame 中按字典顺序对连接键进行排序。如果为 False，则连接键的顺序取决于连接类型（如何关键字）。

suffixes 列表样式，默认为（“_x”，“_y”）

长度为 2 的序列，其中每个元素都可以是一个字符串，指示要添加到左侧和右侧重叠列名称中的后缀。将字符串的值设为 None 而不是字符串，以指示从左侧或右侧获取的列名应保持不变，不带后缀。至少其中一个值必须不为 None。

copybool，默认为 True

如果为 False，则尽量避免复制。

注意

在 pandas 3.0 中，copy 关键字的行为将发生变化。写时复制将默认启用，这意味着所有带有 copy 关键字的方法都将使用延迟复制机制来推迟复制并忽略 copy 关键字。copy 关键字将在 pandas 的未来版本中被移除。

你已经可以通过启用写时复制 pd.options.mode.copy_on_write = True 来获得未来的行为和改进。

indicatorbool 或 str，默认为 False

如果为 True，则向输出 DataFrame 添加一个名为 “_merge” 的列，其中包含每行来源的信息。可以通过提供一个字符串参数来指定不同的名称。该列将具有 Categorical 类型，对于只在左侧 DataFrame 中出现合并键的观测值，其值为 “left_only”，对于只在右侧 DataFrame 中出现合并键的观测值，其值为 “right_only”，如果观测值的合并键在两个 DataFrame 中都找到，则其值为 “both”。

validatestr，可选

如果指定了，则检查合并是否为指定类型。

“one_to_one” 或 “1:1”：检查合并键是否在左侧和右侧数据集中都唯一。
“one_to_many” 或 “1:m”：检查左侧数据集中合并键是否唯一。
“many_to_one” 或 “m:1”：检查右侧数据集中合并键是否唯一。
“many_to_many” 或 “m:m”：允许，但不进行检查。

DataFrame

两个合并对象的 DataFrame。

另请参阅

merge_ordered

合并时可选填充/插值。

merge_asof

在最近的键上合并。

DataFrame.join

使用类似的方法。

示例

>>> df1 = pd.DataFrame({'lkey': ['foo', 'bar', 'baz', 'foo'],
...                     'value': [1, 2, 3, 5]})
>>> df2 = pd.DataFrame({'rkey': ['foo', 'bar', 'baz', 'foo'],
...                     'value': [5, 6, 7, 8]})
>>> df1
 lkey value
0   foo      1
1   bar      2
2   baz      3
3   foo      5
>>> df2
 rkey value
0   foo      5
1   bar      6
2   baz      7
3   foo      8

在 lkey 和 rkey 列上合并 df1 和 df2。值列具有默认后缀 _x 和 _y。

>>> df1.merge(df2, left_on='lkey', right_on='rkey')
 lkey  value_x rkey  value_y
0  foo        1  foo        5
1  foo        1  foo        8
2  bar        2  bar        6
3  baz        3  baz        7
4  foo        5  foo        5
5  foo        5  foo        8

使用指定的左侧和右侧后缀合并 DataFrame df1 和 df2 中的数据。

>>> df1.merge(df2, left_on='lkey', right_on='rkey',
...           suffixes=('_left', '_right'))
 lkey  value_left rkey  value_right
0  foo           1  foo            5
1  foo           1  foo            8
2  bar           2  bar            6
3  baz           3  baz            7
4  foo           5  foo            5
5  foo           5  foo            8

合并 DataFrame df1 和 df2，但如果 DataFrame 有任何重叠列，则引发异常。

>>> df1.merge(df2, left_on='lkey', right_on='rkey', suffixes=(False, False))
Traceback (most recent call last):
...
ValueError: columns overlap but no suffix specified:
 Index(['value'], dtype='object')

>>> df1 = pd.DataFrame({'a': ['foo', 'bar'], 'b': [1, 2]})
>>> df2 = pd.DataFrame({'a': ['foo', 'baz'], 'c': [3, 4]})
>>> df1
 a  b
0   foo  1
1   bar  2
>>> df2
 a  c
0   foo  3
1   baz  4

>>> df1.merge(df2, how='inner', on='a')
 a  b  c
0   foo  1  3

>>> df1.merge(df2, how='left', on='a')
 a  b  c
0   foo  1  3.0
1   bar  2  NaN

>>> df1 = pd.DataFrame({'left': ['foo', 'bar']})
>>> df2 = pd.DataFrame({'right': [7, 8]})
>>> df1
 left
0   foo
1   bar
>>> df2
 right
0   7
1   8

>>> df1.merge(df2, how='cross')
 left  right
0   foo      7
1   foo      8
2   bar      7
3   bar      8

`pandas.merge_ordered`

原文：pandas.pydata.org/docs/reference/api/pandas.merge_ordered.html

pandas.merge_ordered(left, right, on=None, left_on=None, right_on=None, left_by=None, right_by=None, fill_method=None, suffixes=('_x', '_y'), how='outer')

对有序数据执行合并，可选填充/插值。

专为有序数据设计，如时间序列数据。可选执行分组合并（请参见示例）。

参数：

left数据框或命名系列

right数据框或命名系列

on标签或列表

要合并的字段名称。必须在两个数据框中找到。

left_on标签或列表，或类似数组

在左侧数据框中要合并的字段名称。可以是数据框长度的向量或向量列表，以使用特定向量作为连接键而不是列。

right_on标签或列表，或类似数组

在右侧数据框或左侧文档中每个向量/列表的字段名称。

left_by列名或列名列表

按组列对左侧数据框进行分组，并逐块与右侧数据框合并。如果左侧或右侧是系列，则必须为 None。

right_by列名或列名列表

按组列对右侧数据框进行分组，并逐块与左侧数据框合并。如果左侧或右侧是系列，则必须为 None。

fill_method，默认为 None

数据的插值方法。

suffixes类似列表，默认为（“_x”，“_y”）

一个长度为 2 的序列，每个元素都可以是一个字符串，指示要添加到左侧和右侧重叠列名的后缀。将字符串的值传递为 None，表示左侧或右侧的列名应保持不变，不添加后缀。至少一个值不能为 None。

how，默认为‘outer’

left: 仅使用左侧数据框的键（SQL: 左外连接）
right: 仅使用右侧数据框的键（SQL: 右外连接）
outer: 使用两个数据框的键的并集（SQL: 全外连接）
inner: 使用两个数据框键的交集（SQL: 内连接）。

DataFrame

如果‘left’是 DataFrame 的子类，则合并后的 DataFrame 输出类型将与‘left’相同。

参见

merge

与数据库风格的连接合并。

merge_asof

在最近的键上合并。

示例

>>> from pandas import merge_ordered
>>> df1 = pd.DataFrame(
...     {
...         "key": ["a", "c", "e", "a", "c", "e"],
...         "lvalue": [1, 2, 3, 1, 2, 3],
...         "group": ["a", "a", "a", "b", "b", "b"]
...     }
... )
>>> df1
 key  lvalue group
0   a       1     a
1   c       2     a
2   e       3     a
3   a       1     b
4   c       2     b
5   e       3     b

>>> df2 = pd.DataFrame({"key": ["b", "c", "d"], "rvalue": [1, 2, 3]})
>>> df2
 key  rvalue
0   b       1
1   c       2
2   d       3

>>> merge_ordered(df1, df2, fill_method="ffill", left_by="group")
 key  lvalue group  rvalue
0   a       1     a     NaN
1   b       1     a     1.0
2   c       2     a     2.0
3   d       2     a     3.0
4   e       3     a     3.0
5   a       1     b     NaN
6   b       1     b     1.0
7   c       2     b     2.0
8   d       2     b     3.0
9   e       3     b     3.0

`pandas.merge_asof`

原文：pandas.pydata.org/docs/reference/api/pandas.merge_asof.html

pandas.merge_asof(left, right, on=None, left_on=None, right_on=None, left_index=False, right_index=False, by=None, left_by=None, right_by=None, suffixes=('_x', '_y'), tolerance=None, allow_exact_matches=True, direction='backward')

通过键距离执行合并。

这类似于左连接，只是我们匹配最近的键而不是相等的键。两个 DataFrame 必须按键排序。

对于左侧 DataFrame 中的每一行：

“后向”搜索选择右侧 DataFrame 中最后一个‘on’键小于或等于左侧键的行。

“前向”搜索选择右侧 DataFrame 中第一行，其‘on’键大于或等于左侧键。

“最近”搜索选择右侧 DataFrame 中‘on’键与左侧键的绝对距离最近的行。

在使用‘on’进行搜索之前，可选择使用‘by’进行等效键的匹配。

参数：

leftDataFrame 或命名 Series

rightDataFrame 或命名 Series

on标签

要连接的字段名。必须在两个 DataFrame 中找到。数据必须是有序的。此外，这必须是一个数字列，例如 datetimelike、整数或浮点数。必须给出 on 或 left_on/right_on。

left_on标签

左侧 DataFrame 中要连接的字段名。

right_on标签

右侧 DataFrame 中要连接的字段名。

left_index布尔值

使用左侧 DataFrame 的索引作为连接键。

right_index布尔值

使用右侧 DataFrame 的索引作为连接键。

by列名或列名列表

在执行合并操作之前，匹配这些列。

left_by列名

左侧 DataFrame 中要匹配的字段名。

right_by列名

在右侧 DataFrame 中要匹配的字段名。

suffixes2-长度序列（元组、列表、…）

重叠列名在左侧和右侧的后缀分别应用。

tolerance整数或 Timedelta，可选，默认为 None

在此范围内选择 asof 容差；必须与合并索引兼容。

allow_exact_matches布尔值，默认为 True

如果为 True，则允许与相同的‘on’值匹配（即小于或等于 / 大于或等于）
如果为 False，则不匹配相同的‘on’值（即，严格小于 / 严格大于）。

direction‘backward’（默认）、‘forward’或‘nearest’

是否搜索之前、之后或最接近的匹配。

DataFrame

参见

merge

使用类似数据库的连接方式进行合并。

merge_ordered

使用可选的填充/插值进行合并。

示例

>>> left = pd.DataFrame({"a": [1, 5, 10], "left_val": ["a", "b", "c"]})
>>> left
 a left_val
0   1        a
1   5        b
2  10        c

>>> right = pd.DataFrame({"a": [1, 2, 3, 6, 7], "right_val": [1, 2, 3, 6, 7]})
>>> right
 a  right_val
0  1          1
1  2          2
2  3          3
3  6          6
4  7          7

>>> pd.merge_asof(left, right, on="a")
 a left_val  right_val
0   1        a          1
1   5        b          3
2  10        c          7

>>> pd.merge_asof(left, right, on="a", allow_exact_matches=False)
 a left_val  right_val
0   1        a        NaN
1   5        b        3.0
2  10        c        7.0

>>> pd.merge_asof(left, right, on="a", direction="forward")
 a left_val  right_val
0   1        a        1.0
1   5        b        6.0
2  10        c        NaN

>>> pd.merge_asof(left, right, on="a", direction="nearest")
 a left_val  right_val
0   1        a          1
1   5        b          6
2  10        c          7

我们也可以使用索引化的 DataFrame。

>>> left = pd.DataFrame({"left_val": ["a", "b", "c"]}, index=[1, 5, 10])
>>> left
 left_val
1         a
5         b
10        c

>>> right = pd.DataFrame({"right_val": [1, 2, 3, 6, 7]}, index=[1, 2, 3, 6, 7])
>>> right
 right_val
1          1
2          2
3          3
6          6
7          7

>>> pd.merge_asof(left, right, left_index=True, right_index=True)
 left_val  right_val
1         a          1
5         b          3
10        c          7

这是一个实际的时间序列示例

>>> quotes = pd.DataFrame(
...     {
...         "time": [
...             pd.Timestamp("2016-05-25 13:30:00.023"),
...             pd.Timestamp("2016-05-25 13:30:00.023"),
...             pd.Timestamp("2016-05-25 13:30:00.030"),
...             pd.Timestamp("2016-05-25 13:30:00.041"),
...             pd.Timestamp("2016-05-25 13:30:00.048"),
...             pd.Timestamp("2016-05-25 13:30:00.049"),
...             pd.Timestamp("2016-05-25 13:30:00.072"),
...             pd.Timestamp("2016-05-25 13:30:00.075")
...         ],
...         "ticker": [
...                "GOOG",
...                "MSFT",
...                "MSFT",
...                "MSFT",
...                "GOOG",
...                "AAPL",
...                "GOOG",
...                "MSFT"
...            ],
...            "bid": [720.50, 51.95, 51.97, 51.99, 720.50, 97.99, 720.50, 52.01],
...            "ask": [720.93, 51.96, 51.98, 52.00, 720.93, 98.01, 720.88, 52.03]
...     }
... )
>>> quotes
 time ticker     bid     ask
0 2016-05-25 13:30:00.023   GOOG  720.50  720.93
1 2016-05-25 13:30:00.023   MSFT   51.95   51.96
2 2016-05-25 13:30:00.030   MSFT   51.97   51.98
3 2016-05-25 13:30:00.041   MSFT   51.99   52.00
4 2016-05-25 13:30:00.048   GOOG  720.50  720.93
5 2016-05-25 13:30:00.049   AAPL   97.99   98.01
6 2016-05-25 13:30:00.072   GOOG  720.50  720.88
7 2016-05-25 13:30:00.075   MSFT   52.01   52.03

>>> trades = pd.DataFrame(
...        {
...            "time": [
...                pd.Timestamp("2016-05-25 13:30:00.023"),
...                pd.Timestamp("2016-05-25 13:30:00.038"),
...                pd.Timestamp("2016-05-25 13:30:00.048"),
...                pd.Timestamp("2016-05-25 13:30:00.048"),
...                pd.Timestamp("2016-05-25 13:30:00.048")
...            ],
...            "ticker": ["MSFT", "MSFT", "GOOG", "GOOG", "AAPL"],
...            "price": [51.95, 51.95, 720.77, 720.92, 98.0],
...            "quantity": [75, 155, 100, 100, 100]
...        }
...    )
>>> trades
 time ticker   price  quantity
0 2016-05-25 13:30:00.023   MSFT   51.95        75
1 2016-05-25 13:30:00.038   MSFT   51.95       155
2 2016-05-25 13:30:00.048   GOOG  720.77       100
3 2016-05-25 13:30:00.048   GOOG  720.92       100
4 2016-05-25 13:30:00.048   AAPL   98.00       100

默认情况下，我们采用了报价的 asof。

>>> pd.merge_asof(trades, quotes, on="time", by="ticker")
 time ticker   price  quantity     bid     ask
0 2016-05-25 13:30:00.023   MSFT   51.95        75   51.95   51.96
1 2016-05-25 13:30:00.038   MSFT   51.95       155   51.97   51.98
2 2016-05-25 13:30:00.048   GOOG  720.77       100  720.50  720.93
3 2016-05-25 13:30:00.048   GOOG  720.92       100  720.50  720.93
4 2016-05-25 13:30:00.048   AAPL   98.00       100     NaN     NaN

我们只在报价时间和交易时间之间的 2 毫秒内进行 asof 操作。

>>> pd.merge_asof(
...     trades, quotes, on="time", by="ticker", tolerance=pd.Timedelta("2ms")
... )
 time ticker   price  quantity     bid     ask
0 2016-05-25 13:30:00.023   MSFT   51.95        75   51.95   51.96
1 2016-05-25 13:30:00.038   MSFT   51.95       155     NaN     NaN
2 2016-05-25 13:30:00.048   GOOG  720.77       100  720.50  720.93
3 2016-05-25 13:30:00.048   GOOG  720.92       100  720.50  720.93
4 2016-05-25 13:30:00.048   AAPL   98.00       100     NaN     NaN

我们只在报价时间和交易时间之间的 10 毫秒内进行 asof 操作，并排除时间上的精确匹配。然而之前的数据将会向前传播。

>>> pd.merge_asof(
...     trades,
...     quotes,
...     on="time",
...     by="ticker",
...     tolerance=pd.Timedelta("10ms"),
...     allow_exact_matches=False
... )
 time ticker   price  quantity     bid     ask
0 2016-05-25 13:30:00.023   MSFT   51.95        75     NaN     NaN
1 2016-05-25 13:30:00.038   MSFT   51.95       155   51.97   51.98
2 2016-05-25 13:30:00.048   GOOG  720.77       100     NaN     NaN
3 2016-05-25 13:30:00.048   GOOG  720.92       100     NaN     NaN
4 2016-05-25 13:30:00.048   AAPL   98.00       100     NaN     NaN

`pandas.concat`

原文：pandas.pydata.org/docs/reference/api/pandas.concat.html

pandas.concat(objs, *, axis=0, join='outer', ignore_index=False, keys=None, levels=None, names=None, verify_integrity=False, sort=False, copy=None)

沿特定轴连接 pandas 对象。

允许沿其他轴进行可选的集合逻辑。

还可以在连接轴上添加一层分层索引，如果标签在传递的轴编号上相同（或重叠），这可能很有用。

参数：

objs序列或 Series 或 DataFrame 对象的映射

如果传递了映射，那么排序后的键将用作键参数，除非传递了值，否则将选择值（见下文）。除非它们全部为 None，否则任何 None 对象都将被静默丢弃，否则将引发 ValueError。

axis，默认为 0

要沿着连接的轴。

join，默认为 'outer'

如何处理其他轴（或轴）上的索引。

ignore_index布尔值，默认为 False

如果为 True，则不要使用连接轴上的索引值。结果轴将被标记为 0，…，n-1。如果您要连接的对象的连接轴没有有意义的索引信息，则这很有用。请注意，其他轴上的索引值仍然在连接中受到尊重。

keys序列，默认为 None

如果传递了多个级别，则应包含元组。使用传递的键构建分层索引作为最外层级别。

levels序列的列表，默认为 None

用于构造 MultiIndex 的特定级别（唯一值）。否则，它们将从键中推断出来。

names列表，默认为 None

结果分层索引的级别名称。

verify_integrity布尔值，默认为 False

检查新连接轴是否包含重复项。与实际数据连接相比，这可能非常昂贵。

sort布尔值，默认为 False

如果非连接轴尚未对齐，则对非连接轴进行排序。有一个例外情况，即当非连接轴是 DatetimeIndex 且 join='outer' 且轴尚未对齐时。在这种情况下，非连接轴始终按字典顺序排序。

copy布尔值，默认为 True

如果为 False，则不会不必要地复制数据。

对象，objs 的类型

当沿索引（axis=0）连接所有Series时，返回Series。当objs至少包含一个DataFrame时，返回DataFrame。当沿列（axis=1）连接时，返回DataFrame。

另请参阅

DataFrame.join

使用索引合并数据框。

DataFrame.merge

通过索引或列合并数据框。

注意事项

键、级别和名称参数都是可选的。

这里有一篇介绍这种方法如何与其他组合 pandas 对象的工具配合使用的文章。

不推荐使用 for 循环逐行添加单个行来构建 DataFrame。应该将行列表构建好，然后一次性使用 concat 函数创建 DataFrame。

示例

合并两个 Series。

>>> s1 = pd.Series(['a', 'b'])
>>> s2 = pd.Series(['c', 'd'])
>>> pd.concat([s1, s2])
0    a
1    b
0    c
1    d
dtype: object

通过将ignore_index选项设置为True，清除现有索引并在结果中重置索引。

>>> pd.concat([s1, s2], ignore_index=True)
0    a
1    b
2    c
3    d
dtype: object

使用keys选项在数据的最外层级别添加分层索引。

>>> pd.concat([s1, s2], keys=['s1', 's2'])
s1  0    a
 1    b
s2  0    c
 1    d
dtype: object

使用names选项为创建的索引键添加标签。

>>> pd.concat([s1, s2], keys=['s1', 's2'],
...           names=['Series name', 'Row ID'])
Series name  Row ID
s1           0         a
 1         b
s2           0         c
 1         d
dtype: object

将两个具有相同列的 DataFrame 对象合并。

>>> df1 = pd.DataFrame([['a', 1], ['b', 2]],
...                    columns=['letter', 'number'])
>>> df1
 letter  number
0      a       1
1      b       2
>>> df2 = pd.DataFrame([['c', 3], ['d', 4]],
...                    columns=['letter', 'number'])
>>> df2
 letter  number
0      c       3
1      d       4
>>> pd.concat([df1, df2])
 letter  number
0      a       1
1      b       2
0      c       3
1      d       4

将具有重叠列的 DataFrame 对象组合在一起，并返回所有内容。交集之外的列将填充为NaN值。

>>> df3 = pd.DataFrame([['c', 3, 'cat'], ['d', 4, 'dog']],
...                    columns=['letter', 'number', 'animal'])
>>> df3
 letter  number animal
0      c       3    cat
1      d       4    dog
>>> pd.concat([df1, df3], sort=False)
 letter  number animal
0      a       1    NaN
1      b       2    NaN
0      c       3    cat
1      d       4    dog

通过将join关键字参数设置为inner，将具有重叠列的 DataFrame 对象组合在一起，并仅返回共享的列。

>>> pd.concat([df1, df3], join="inner")
 letter  number
0      a       1
1      b       2
0      c       3
1      d       4

通过传递axis=1参数，在 x 轴上水平合并 DataFrame 对象。

>>> df4 = pd.DataFrame([['bird', 'polly'], ['monkey', 'george']],
...                    columns=['animal', 'name'])
>>> pd.concat([df1, df4], axis=1)
 letter  number  animal    name
0      a       1    bird   polly
1      b       2  monkey  george

使用verify_integrity选项可以防止结果包含重复的索引值。

>>> df5 = pd.DataFrame([1], index=['a'])
>>> df5
 0
a  1
>>> df6 = pd.DataFrame([2], index=['a'])
>>> df6
 0
a  2
>>> pd.concat([df5, df6], verify_integrity=True)
Traceback (most recent call last):
  ...
ValueError: Indexes have overlapping values: ['a']

将单行附加到 DataFrame 对象的末尾。

>>> df7 = pd.DataFrame({'a': 1, 'b': 2}, index=[0])
>>> df7
 a   b
0   1   2
>>> new_row = pd.Series({'a': 3, 'b': 4})
>>> new_row
a    3
b    4
dtype: int64
>>> pd.concat([df7, new_row.to_frame().T], ignore_index=True)
 a   b
0   1   2
1   3   4

`pandas.get_dummies`

原文：pandas.pydata.org/docs/reference/api/pandas.get_dummies.html

pandas.get_dummies(data, prefix=None, prefix_sep='_', dummy_na=False, columns=None, sparse=False, drop_first=False, dtype=None)

将分类变量转换为虚拟/指示变量。

每个变量都转换为与不同值一样多的 0/1 变量。输出中的列名每个都以一个值命名；如果输入是 DataFrame，则原始变量的名称将被预置到该值之前。

参数：

data类数组、Series 或 DataFrame

要获取虚拟指示符的数据。

prefix字符串、字符串列表或字符串字典，默认为 None

附加到 DataFrame 列名称的字符串。在对 DataFrame 调用 get_dummies 时，传递一个与列数相等的长度的列表。或者，prefix 可以是将列名称映射到前缀的字典。

prefix_sep字符串，默认为‘_’

如果附加前缀，则使用的分隔符。或者像前缀一样传递一个列表或字典。

dummy_na布尔值，默认为 False

添加一列以指示 NaN，如果为 False，则忽略 NaN。

columns列表样式，默认为 None

要编码的 DataFrame 中的列名。如果 columns 为 None，则所有具有 object、string 或 category 数据类型的列将被转换。

sparse布尔值，默认为 False

虚拟编码列是否应由SparseArray（True）或常规 NumPy 数组（False）支持。

drop_first布尔值，默认为 False

是否通过删除第一个级别来从 k 个分类级别中获取 k-1 个虚拟变量。

dtype数据类型，默认为布尔值

新列的数据类型。只允许一个单一数据类型。

DataFrame

虚拟编码的数据。如果数据包含除虚拟编码列之外的其他列，则这些列将不经修改地预置到结果中。

另请参见

Series.str.get_dummies

将字符串系列转换为虚拟编码。

from_dummies()

将虚拟编码转换为分类DataFrame。

注意事项

参考用户指南以获取更多示例。

示例

>>> s = pd.Series(list('abca'))

>>> pd.get_dummies(s)
 a      b      c
0   True  False  False
1  False   True  False
2  False  False   True
3   True  False  False

>>> s1 = ['a', 'b', np.nan]

>>> pd.get_dummies(s1)
 a      b
0   True  False
1  False   True
2  False  False

>>> pd.get_dummies(s1, dummy_na=True)
 a      b    NaN
0   True  False  False
1  False   True  False
2  False  False   True

>>> df = pd.DataFrame({'A': ['a', 'b', 'a'], 'B': ['b', 'a', 'c'],
...                    'C': [1, 2, 3]})

>>> pd.get_dummies(df, prefix=['col1', 'col2'])
 C  col1_a  col1_b  col2_a  col2_b  col2_c
0  1    True   False   False    True   False
1  2   False    True    True   False   False
2  3    True   False   False   False    True

>>> pd.get_dummies(pd.Series(list('abcaa')))
 a      b      c
0   True  False  False
1  False   True  False
2  False  False   True
3   True  False  False
4   True  False  False

>>> pd.get_dummies(pd.Series(list('abcaa')), drop_first=True)
 b      c
0  False  False
1   True  False
2  False   True
3  False  False
4  False  False

>>> pd.get_dummies(pd.Series(list('abc')), dtype=float)
 a    b    c
0  1.0  0.0  0.0
1  0.0  1.0  0.0
2  0.0  0.0  1.0

`pandas.from_dummies`

原文：pandas.pydata.org/docs/reference/api/pandas.from_dummies.html

pandas.from_dummies(data, sep=None, default_category=None)

从虚拟变量的DataFrame创建分类DataFrame。

反转get_dummies()执行的操作。

版本 1.5.0 中的新功能。

参数：

dataDataFrame

数据包含以整数列形式表示的虚拟编码变量，取值为 1 或 0。

sepstr，默认为 None

用于虚拟类别列的列名中使用的分隔符是指示分类名称与前缀之间分隔的字符。例如，如果您的列名为'prefix_A'和'prefix_B'，您可以通过指定 sep='_'来去除下划线。

default_categoryNone、可散列对象或可散列对象的字典，默认为 None

默认类别是当一个值没有列出的任何类别时的隐含类别，即如果一行中的所有虚拟变量都为零。可以是所有变量的单个值，也可以是直接将默认类别映射到变量前缀的字典。

DataFrame

从虚拟输入数据解码的分类数据。

引发：

ValueError

当输入的DataFrame data包含 NA 值时。
当输入的DataFrame data包含具有与使用sep指定的分隔符不匹配的分隔符的列名时。
当传递给default_category的dict不包含每个前缀的隐含类别时。
当data中的某个值分配给多个类别时。
当default_category=None且data中的某个值没有分配给任何类别时。

TypeError

当输入的data不是DataFrame类型时。
当输入的DataFrame data包含非虚拟数据时。
当传递的sep是错误数据类型时。
当传递的default_category是错误数据类型时。

另请参阅

get_dummies()

将Series或DataFrame转换为虚拟编码。

Categorical

代表经典分类变量。

注意

传递的虚拟数据的列应仅包括 1 或 0，或布尔值。

示例

>>> df = pd.DataFrame({"a": [1, 0, 0, 1], "b": [0, 1, 0, 0],
...                    "c": [0, 0, 1, 0]})

>>> pd.from_dummies(df)
0     a
1     b
2     c
3     a

>>> df = pd.DataFrame({"col1_a": [1, 0, 1], "col1_b": [0, 1, 0],
...                    "col2_a": [0, 1, 0], "col2_b": [1, 0, 0],
...                    "col2_c": [0, 0, 1]})

>>> df
 col1_a  col1_b  col2_a  col2_b  col2_c
0       1       0       0       1       0
1       0       1       1       0       0
2       1       0       0       0       1

>>> pd.from_dummies(df, sep="_")
 col1    col2
0    a       b
1    b       a
2    a       c

>>> df = pd.DataFrame({"col1_a": [1, 0, 0], "col1_b": [0, 1, 0],
...                    "col2_a": [0, 1, 0], "col2_b": [1, 0, 0],
...                    "col2_c": [0, 0, 0]})

>>> df
 col1_a  col1_b  col2_a  col2_b  col2_c
0       1       0       0       1       0
1       0       1       1       0       0
2       0       0       0       0       0

>>> pd.from_dummies(df, sep="_", default_category={"col1": "d", "col2": "e"})
 col1    col2
0    a       b
1    b       a
2    d       e

`pandas.factorize`

原文：pandas.pydata.org/docs/reference/api/pandas.factorize.html

pandas.factorize(values, sort=False, use_na_sentinel=True, size_hint=None)

将对象编码为枚举类型或分类变量。

当所有重要的是识别不同值时，此方法对于获取数组的数值表示很有用。factorize 可作为顶级函数pandas.factorize()和方法Series.factorize()以及Index.factorize()。

参数：

values序列

一个 1-D 序列。不是 pandas 对象的序列在因子化之前被强制转换为 ndarrays。

sortbool，默认为 False

对 uniques 进行排序并洗牌 codes 以保持关系。

use_na_sentinelbool，默认为 True

如果为 True，则 NaN 值将使用哨兵-1。如果为 False，则 NaN 值将被编码为非负整数，并且不会从值的 uniques 中删除 NaN。

1.5.0 版中的新功能。

size_hintint，可选

哈希表大小提示。

codesndarray

一个整数 ndarray，用作 uniques 的索引器。uniques.take(codes)将具有与 values 相同的值。

uniquesndarray、Index 或 Categorical

唯一的有效值。当值为 Categorical 时，uniques 是一个 Categorical。当值为其他 pandas 对象时，返回一个 Index。否则，返回一个 1-D ndarray。

注意

即使值中有缺失值，uniques 也不会包含其条目��

另请参见

cut

将连续值数组离散化。

unique

在数组中查找唯一值。

注意事项

参考用户指南获取更多示例。

示例

这些示例都显示了 factorize 作为类似pd.factorize(values)的顶级方法。对于类似Series.factorize()的方法，结果是相同的。

>>> codes, uniques = pd.factorize(np.array(['b', 'b', 'a', 'c', 'b'], dtype="O"))
>>> codes
array([0, 0, 1, 2, 0])
>>> uniques
array(['b', 'a', 'c'], dtype=object)

当sort=True时，uniques 将被排序，codes 将被洗牌，以保持关系。

>>> codes, uniques = pd.factorize(np.array(['b', 'b', 'a', 'c', 'b'], dtype="O"),
...                               sort=True)
>>> codes
array([1, 1, 0, 2, 1])
>>> uniques
array(['a', 'b', 'c'], dtype=object)

当use_na_sentinel=True（默认值）时，在代码中用哨兵值-1表示缺失值，并且缺失值不包括在 uniques 中。

>>> codes, uniques = pd.factorize(np.array(['b', None, 'a', 'c', 'b'], dtype="O"))
>>> codes
array([ 0, -1,  1,  2,  0])
>>> uniques
array(['b', 'a', 'c'], dtype=object)

到目前为止，我们只对列表进行了因子化（这些列表在内部被强制转换为 NumPy 数组）。当对 pandas 对象进行因子化时，uniques 的类型将不同。对于 Categoricals，将返回一个 Categorical。

>>> cat = pd.Categorical(['a', 'a', 'c'], categories=['a', 'b', 'c'])
>>> codes, uniques = pd.factorize(cat)
>>> codes
array([0, 0, 1])
>>> uniques
['a', 'c']
Categories (3, object): ['a', 'b', 'c']

注意，'b'在uniques.categories中，尽管在cat.values中不存在。

对于所有其他 pandas 对象，将返回适当类型的 Index。

>>> cat = pd.Series(['a', 'a', 'c'])
>>> codes, uniques = pd.factorize(cat)
>>> codes
array([0, 0, 1])
>>> uniques
Index(['a', 'c'], dtype='object')

如果值中有 NaN，并且我们希望在值的 uniques 中包含 NaN，则可以通过设置use_na_sentinel=False来实现。

>>> values = np.array([1, 2, 1, np.nan])
>>> codes, uniques = pd.factorize(values)  # default: use_na_sentinel=True
>>> codes
array([ 0,  1,  0, -1])
>>> uniques
array([1., 2.])

>>> codes, uniques = pd.factorize(values, use_na_sentinel=False)
>>> codes
array([0, 1, 0, 2])
>>> uniques
array([ 1.,  2., nan])

`pandas.unique`

原文：pandas.pydata.org/docs/reference/api/pandas.unique.html

pandas.unique(values)

基于哈希表返回唯一值。

唯一值按出现顺序返回。这不会排序。

对于足够长的序列，比 numpy.unique 快得多。包括 NA 值。

参数：

values1d 类似数组

numpy.ndarray 或 ExtensionArray

返回可以是：

索引：当输入为索引时
分类：当输入为分类数据类型时
ndarray：当输入为 Series/ndarray 时

返回 numpy.ndarray 或 ExtensionArray。

另请参阅

Index.unique

从索引返回唯一值。

Series.unique

返回 Series 对象的唯一值。

示例

>>> pd.unique(pd.Series([2, 1, 3, 3]))
array([2, 1, 3])

>>> pd.unique(pd.Series([2] + [1] * 5))
array([2, 1])

>>> pd.unique(pd.Series([pd.Timestamp("20160101"), pd.Timestamp("20160101")]))
array(['2016-01-01T00:00:00.000000000'], dtype='datetime64[ns]')

>>> pd.unique(
...     pd.Series(
...         [
...             pd.Timestamp("20160101", tz="US/Eastern"),
...             pd.Timestamp("20160101", tz="US/Eastern"),
...         ]
...     )
... )
<DatetimeArray>
['2016-01-01 00:00:00-05:00']
Length: 1, dtype: datetime64[ns, US/Eastern]

>>> pd.unique(
...     pd.Index(
...         [
...             pd.Timestamp("20160101", tz="US/Eastern"),
...             pd.Timestamp("20160101", tz="US/Eastern"),
...         ]
...     )
... )
DatetimeIndex(['2016-01-01 00:00:00-05:00'],
 dtype='datetime64[ns, US/Eastern]',
 freq=None)

>>> pd.unique(np.array(list("baabc"), dtype="O"))
array(['b', 'a', 'c'], dtype=object)

无序分类将按出现顺序返回类别。

>>> pd.unique(pd.Series(pd.Categorical(list("baabc"))))
['b', 'a', 'c']
Categories (3, object): ['a', 'b', 'c']

>>> pd.unique(pd.Series(pd.Categorical(list("baabc"), categories=list("abc"))))
['b', 'a', 'c']
Categories (3, object): ['a', 'b', 'c']

有序分类保留类别顺序。

>>> pd.unique(
...     pd.Series(
...         pd.Categorical(list("baabc"), categories=list("abc"), ordered=True)
...     )
... )
['b', 'a', 'c']
Categories (3, object): ['a' < 'b' < 'c']

一个元组数组

>>> pd.unique(pd.Series([("a", "b"), ("b", "a"), ("a", "c"), ("b", "a")]).values)
array([('a', 'b'), ('b', 'a'), ('a', 'c')], dtype=object)

`pandas.lreshape`

原文：pandas.pydata.org/docs/reference/api/pandas.lreshape.html

pandas.lreshape(data, groups, dropna=True)

将宽格式数据重塑为长格式。DataFrame.pivot 的广义逆。

接受一个名为groups的字典，其中每个键是一个新列名，每个值是一个将作为重塑的一部分“融合”在新列名下的旧列名列表。

参数：

dataDataFrame

宽格式的 DataFrame。

groups字典

{new_name : list_of_columns}。

dropna布尔值，默认为 True

不包括所有条目都是 NaN 的列。

DataFrame

重塑后的 DataFrame。

另请参阅

melt

将 DataFrame 从宽格式转换为长格式，可选择保留标识符。

pivot

创建一个类似电子表格的数据透视表作为 DataFrame。

DataFrame.pivot

可处理非数值数据的无聚合透视。

DataFrame.pivot_table

可处理一个索引/列对的重复值的透视的泛化。

DataFrame.unstack

基于索引值而不是列进行数据透视。

wide_to_long

宽面板到长格式。比 melt 更灵活但更用户友好。

示例

>>> data = pd.DataFrame({'hr1': [514, 573], 'hr2': [545, 526],
...                      'team': ['Red Sox', 'Yankees'],
...                      'year1': [2007, 2007], 'year2': [2008, 2008]})
>>> data
 hr1  hr2     team  year1  year2
0  514  545  Red Sox   2007   2008
1  573  526  Yankees   2007   2008

>>> pd.lreshape(data, {'year': ['year1', 'year2'], 'hr': ['hr1', 'hr2']})
 team  year   hr
0  Red Sox  2007  514
1  Yankees  2007  573
2  Red Sox  2008  545
3  Yankees  2008  526

`pandas.wide_to_long`

原文：pandas.pydata.org/docs/reference/api/pandas.wide_to_long.html

pandas.wide_to_long(df, stubnames, i, j, sep='', suffix='\\d+')

将 DataFrame 从宽格式转换为长格式。

比 melt 更灵活但更用户友好。

使用存根名称[‘A’, ‘B’]，此函数期望找到一个或多个具有格式 A-suffix1、A-suffix2、…、B-suffix1、B-suffix2、…的列组。您可以使用 j 指定在生成的长格式中称此后缀为什么（例如 j=’year’）

假定这些宽变量的每一行都由 i 唯一标识（可以是单个列名或列名列表）

数据框中的所有剩余变量保持不变。

参数：

dfDataFrame

宽格式 DataFrame。

存根名称str 或类似列表

存根名称。假定宽格式变量以存根名称开头。

istr 或类似列表

用作 id 变量的列。

jstr

子观察变量的名称。您希望在长格式中命名后缀的内容。

分隔符str，默认为“”

表示宽格式变量名称之间的分隔符的字符，在长格式中从名称中剥离。例如，如果您的列名是 A-suffix1、A-suffix2，您可以通过指定 sep=’-’来去除连字符。

后缀str，默认为‘\d+’

捕获所需后缀的正则表达式。‘\d+’捕获数字后缀。没有数字的后缀可以使用否定字符类‘\D+’指定。您还可以进一步消除后缀的歧义，例如，如果您的宽变量的形式为 A-one、B-two，..，并且您有一个无关的列 A-rating，您可以通过指定 suffix=’(!?one|two)’来忽略最后一个。当所有后缀都是数字时，它们被转换为 int64/float64。

DataFrame

一个包含每个存根名称作为变量的 DataFrame，带有新的索引（i，j）。

参见

melt

将 DataFrame 从宽格式转换为长格式，可选择保留标识符设置。

pivot

创建一个类似电子表格的透视表作为 DataFrame。

DataFrame.pivot

可处理非数值数据的无聚合的 pivot。

DataFrame.pivot_table

可处理一个索引/列对的重复值的 pivot 的泛化。

DataFrame.unstack

基于索引值而不是列的 pivot。

注意事项

所有额外变量保持不变。这只是在内部使用 pandas.melt，但在典型情况下硬编码为“做正确的事情”。

示例

>>> np.random.seed(123)
>>> df = pd.DataFrame({"A1970" : {0 : "a", 1 : "b", 2 : "c"},
...                    "A1980" : {0 : "d", 1 : "e", 2 : "f"},
...                    "B1970" : {0 : 2.5, 1 : 1.2, 2 : .7},
...                    "B1980" : {0 : 3.2, 1 : 1.3, 2 : .1},
...                    "X"     : dict(zip(range(3), np.random.randn(3)))
...                   })
>>> df["id"] = df.index
>>> df
 A1970 A1980  B1970  B1980         X  id
0     a     d    2.5    3.2 -1.085631   0
1     b     e    1.2    1.3  0.997345   1
2     c     f    0.7    0.1  0.282978   2
>>> pd.wide_to_long(df, ["A", "B"], i="id", j="year")
... 
 X  A    B
id year
0  1970 -1.085631  a  2.5
1  1970  0.997345  b  1.2
2  1970  0.282978  c  0.7
0  1980 -1.085631  d  3.2
1  1980  0.997345  e  1.3
2  1980  0.282978  f  0.1

具有多个 id 列

>>> df = pd.DataFrame({
...     'famid': [1, 1, 1, 2, 2, 2, 3, 3, 3],
...     'birth': [1, 2, 3, 1, 2, 3, 1, 2, 3],
...     'ht1': [2.8, 2.9, 2.2, 2, 1.8, 1.9, 2.2, 2.3, 2.1],
...     'ht2': [3.4, 3.8, 2.9, 3.2, 2.8, 2.4, 3.3, 3.4, 2.9]
... })
>>> df
 famid  birth  ht1  ht2
0      1      1  2.8  3.4
1      1      2  2.9  3.8
2      1      3  2.2  2.9
3      2      1  2.0  3.2
4      2      2  1.8  2.8
5      2      3  1.9  2.4
6      3      1  2.2  3.3
7      3      2  2.3  3.4
8      3      3  2.1  2.9
>>> l = pd.wide_to_long(df, stubnames='ht', i=['famid', 'birth'], j='age')
>>> l
... 
 ht
famid birth age
1     1     1    2.8
 2    3.4
 2     1    2.9
 2    3.8
 3     1    2.2
 2    2.9
2     1     1    2.0
 2    3.2
 2     1    1.8
 2    2.8
 3     1    1.9
 2    2.4
3     1     1    2.2
 2    3.3
 2     1    2.3
 2    3.4
 3     1    2.1
 2    2.9

从长格式返��到宽格式只需巧妙地使用 unstack

>>> w = l.unstack()
>>> w.columns = w.columns.map('{0[0]}{0[1]}'.format)
>>> w.reset_index()
 famid  birth  ht1  ht2
0      1      1  2.8  3.4
1      1      2  2.9  3.8
2      1      3  2.2  2.9
3      2      1  2.0  3.2
4      2      2  1.8  2.8
5      2      3  1.9  2.4
6      3      1  2.2  3.3
7      3      2  2.3  3.4
8      3      3  2.1  2.9

处理较难处理的列名

>>> np.random.seed(0)
>>> df = pd.DataFrame({'A(weekly)-2010': np.random.rand(3),
...                    'A(weekly)-2011': np.random.rand(3),
...                    'B(weekly)-2010': np.random.rand(3),
...                    'B(weekly)-2011': np.random.rand(3),
...                    'X' : np.random.randint(3, size=3)})
>>> df['id'] = df.index
>>> df 
 A(weekly)-2010  A(weekly)-2011  B(weekly)-2010  B(weekly)-2011  X  id
0        0.548814        0.544883        0.437587        0.383442  0   0
1        0.715189        0.423655        0.891773        0.791725  1   1
2        0.602763        0.645894        0.963663        0.528895  1   2

>>> pd.wide_to_long(df, ['A(weekly)', 'B(weekly)'], i='id',
...                 j='year', sep='-')
... 
 X  A(weekly)  B(weekly)
id year
0  2010  0   0.548814   0.437587
1  2010  1   0.715189   0.891773
2  2010  1   0.602763   0.963663
0  2011  0   0.544883   0.383442
1  2011  1   0.423655   0.791725
2  2011  1   0.645894   0.528895

如果我们有许多列，我们也可以使用正则表达式来找到我们的 stubnames，并将该列表传递给 wide_to_long。

>>> stubnames = sorted(
...     set([match[0] for match in df.columns.str.findall(
...         r'[A-B]\(.*\)').values if match != []])
... )
>>> list(stubnames)
['A(weekly)', 'B(weekly)']

以上所有示例都有整数作为后缀。也可以使用非整数作为后缀。

>>> df = pd.DataFrame({
...     'famid': [1, 1, 1, 2, 2, 2, 3, 3, 3],
...     'birth': [1, 2, 3, 1, 2, 3, 1, 2, 3],
...     'ht_one': [2.8, 2.9, 2.2, 2, 1.8, 1.9, 2.2, 2.3, 2.1],
...     'ht_two': [3.4, 3.8, 2.9, 3.2, 2.8, 2.4, 3.3, 3.4, 2.9]
... })
>>> df
 famid  birth  ht_one  ht_two
0      1      1     2.8     3.4
1      1      2     2.9     3.8
2      1      3     2.2     2.9
3      2      1     2.0     3.2
4      2      2     1.8     2.8
5      2      3     1.9     2.4
6      3      1     2.2     3.3
7      3      2     2.3     3.4
8      3      3     2.1     2.9

>>> l = pd.wide_to_long(df, stubnames='ht', i=['famid', 'birth'], j='age',
...                     sep='_', suffix=r'\w+')
>>> l
... 
 ht
famid birth age
1     1     one  2.8
 two  3.4
 2     one  2.9
 two  3.8
 3     one  2.2
 two  2.9
2     1     one  2.0
 two  3.2
 2     one  1.8
 two  2.8
 3     one  1.9
 two  2.4
3     1     one  2.2
 two  3.3
 2     one  2.3
 two  3.4
 3     one  2.1
 two  2.9

`pandas.isna`

原文：pandas.pydata.org/docs/reference/api/pandas.isna.html

pandas.isna(obj)

检测数组类对象中的缺失值。

此函数接受标量或数组类对象，并指示值是否缺失（数值数组中的 NaN，对象数组中的 None 或 NaN，datetimelike 中的 NaT）。

参数：

obj 标量或数组类对象

要检查空值或缺失值的对象。

布尔值或布尔值数组

对于标量输入，返回标量布尔值。对于数组输入，返回一个布尔数组，指示每个对应元素是否缺失。

另请参见

pandas.isna 的布尔值取反。

在 Series 中检测缺失值。

在 DataFrame 中检测缺失值。

检测索引中的缺失值。

示例

标量参数（包括字符串）将导致标量布尔值。

>>> pd.isna('dog')
False

>>> pd.isna(pd.NA)
True

>>> pd.isna(np.nan)
True

ndarrays 将导致布尔值的 ndarray。

>>> array = np.array([[1, np.nan, 3], [4, 5, np.nan]])
>>> array
array([[ 1., nan,  3.],
 [ 4.,  5., nan]])
>>> pd.isna(array)
array([[False,  True, False],
 [False, False,  True]])

对于索引，返回布尔值的 ndarray。

>>> index = pd.DatetimeIndex(["2017-07-05", "2017-07-06", None,
...                           "2017-07-08"])
>>> index
DatetimeIndex(['2017-07-05', '2017-07-06', 'NaT', '2017-07-08'],
 dtype='datetime64[ns]', freq=None)
>>> pd.isna(index)
array([False, False,  True, False])

对于 Series 和 DataFrame，返回相同类型，包含布尔值。

>>> df = pd.DataFrame([['ant', 'bee', 'cat'], ['dog', None, 'fly']])
>>> df
 0     1    2
0  ant   bee  cat
1  dog  None  fly
>>> pd.isna(df)
 0      1      2
0  False  False  False
1  False   True  False

>>> pd.isna(df[1])
0    False
1     True
Name: 1, dtype: bool

`pandas.isnull`

原文：pandas.pydata.org/docs/reference/api/pandas.isnull.html

pandas.isnull(obj)

检测类数组对象中的缺失值。

此函数接受标量或类数组对象，并指示值是否缺失（数值数组中的 NaN，对象数组中的 None 或 NaN，datetimelike 中的 NaT）。

参数：

obj 标量或类数组

要检查是否为 null 或缺失值的对象。

布尔值或布尔类数组

对于标量输入，返回一个标量布尔值。对于数组输入，返回一个布尔数组，指示每个对应元素是否缺失。

另请参阅

notna

pandas.isna 的布尔逆。

Series.isna

检测 Series 中的缺失值。

DataFrame.isna

检测 DataFrame 中的缺失值。

Index.isna

检测 Index 中的缺失值。

示例

标量参数（包括字符串）会导致标量布尔值。

>>> pd.isna('dog')
False

>>> pd.isna(pd.NA)
True

>>> pd.isna(np.nan)
True

ndarray 导致布尔数组。

>>> array = np.array([[1, np.nan, 3], [4, 5, np.nan]])
>>> array
array([[ 1., nan,  3.],
 [ 4.,  5., nan]])
>>> pd.isna(array)
array([[False,  True, False],
 [False, False,  True]])

对于索引，返回布尔数组。

>>> index = pd.DatetimeIndex(["2017-07-05", "2017-07-06", None,
...                           "2017-07-08"])
>>> index
DatetimeIndex(['2017-07-05', '2017-07-06', 'NaT', '2017-07-08'],
 dtype='datetime64[ns]', freq=None)
>>> pd.isna(index)
array([False, False,  True, False])

对于 Series 和 DataFrame，返回相同类型，包含布尔值。

>>> df = pd.DataFrame([['ant', 'bee', 'cat'], ['dog', None, 'fly']])
>>> df
 0     1    2
0  ant   bee  cat
1  dog  None  fly
>>> pd.isna(df)
 0      1      2
0  False  False  False
1  False   True  False

>>> pd.isna(df[1])
0    False
1     True
Name: 1, dtype: bool

`pandas.notna`

原文：pandas.pydata.org/docs/reference/api/pandas.notna.html

pandas.notna(obj)

检测类数组对象的非缺失值。

此函数接受标量或类数组对象，并指示值是否有效（不缺失，在数值数组中为 NaN，在对象数组中为 None 或 NaN，在日期时间类中为 NaT）。

参数：

obj 类似数组或对象值

要检查非空或非缺失值的对象。

返回值：

布尔值或布尔类数组

对于标量输入，返回标量布尔值。对于数组输入，返回一个布尔数组，指示每个对应元素是否有效。

另请参阅

isna

pandas.notna 的布尔值反转。

Series.notna

检测 Series 中的有效值。

DataFrame.notna

检测 DataFrame 中的有效值。

Index.notna

检测 Index 中的有效值。

示例

标量参数（包括字符串）会导致标量布尔值。

>>> pd.notna('dog')
True

>>> pd.notna(pd.NA)
False

>>> pd.notna(np.nan)
False

ndarrays 导致一个布尔值的 ndarray。

>>> array = np.array([[1, np.nan, 3], [4, 5, np.nan]])
>>> array
array([[ 1., nan,  3.],
 [ 4.,  5., nan]])
>>> pd.notna(array)
array([[ True, False,  True],
 [ True,  True, False]])

对于索引，返回一个布尔值的 ndarray。

>>> index = pd.DatetimeIndex(["2017-07-05", "2017-07-06", None,
...                          "2017-07-08"])
>>> index
DatetimeIndex(['2017-07-05', '2017-07-06', 'NaT', '2017-07-08'],
 dtype='datetime64[ns]', freq=None)
>>> pd.notna(index)
array([ True,  True, False,  True])

对于 Series 和 DataFrame，返回相同类型的包含布尔值的对象。

>>> df = pd.DataFrame([['ant', 'bee', 'cat'], ['dog', None, 'fly']])
>>> df
 0     1    2
0  ant   bee  cat
1  dog  None  fly
>>> pd.notna(df)
 0      1     2
0  True   True  True
1  True  False  True

>>> pd.notna(df[1])
0     True
1    False
Name: 1, dtype: bool

posted @ 2024-06-26 10:31 绝不原创的飞龙阅读(6) 评论(0) 编辑收藏举报

会员力量，点亮园子希望

刷新页面返回顶部

龙哥盟

掠夺·扩张·投机·博弈

Pandas-2-2-中文文档-十七-

Pandas 2.2 中文文档（十七）

pandas.HDFStore.put

pandas.HDFStore.append

pandas.HDFStore.get

pandas.HDFStore.select

pandas.HDFStore.info

pandas.HDFStore.keys

pandas.HDFStore.groups

pandas.HDFStore.walk

pandas.read_feather

pandas.DataFrame.to_feather

pandas.read_parquet

pandas.DataFrame.to_parquet

pandas.read_orc

pandas.DataFrame.to_orc

pandas.read_sas

pandas.read_spss

pandas.read_sql_table

pandas.read_sql_query

pandas.read_sql

pandas.DataFrame.to_sql

pandas.read_gbq

pandas.read_stata

pandas.DataFrame.to_stata

pandas.io.stata.StataReader.data_label

pandas.io.stata.StataReader.value_labels

pandas.io.stata.StataReader.variable_labels

pandas.io.stata.StataWriter.write_file

通用函数

数据操作

顶层缺失数据

处理数值数据的顶层函数

处理日期时间数据的顶层函数

处理区间数据的顶层函数

顶层评估

日期时间格式

哈希处理

从其他 DataFrame 库导入

数据操作

处理缺失数据的顶级函数

处理数值数据的顶级函数

处理日期时间数据的顶级函数

处理区间数据的顶级函数

顶级评估函数

日期时间格式

哈希处理

导入其他数据框库

pandas.melt

pandas.pivot

pandas.pivot_table

pandas.crosstab

pandas.cut

pandas.qcut

pandas.merge

pandas.merge_ordered

pandas.merge_asof

pandas.concat

pandas.get_dummies

pandas.from_dummies

pandas.factorize

pandas.unique

pandas.lreshape

pandas.wide_to_long

pandas.isna

pandas.isnull

pandas.notna

公告

`pandas.HDFStore.put`

`pandas.HDFStore.append`

`pandas.HDFStore.get`

`pandas.HDFStore.select`

`pandas.HDFStore.info`

`pandas.HDFStore.keys`

`pandas.HDFStore.groups`

`pandas.HDFStore.walk`

`pandas.read_feather`

`pandas.DataFrame.to_feather`

`pandas.read_parquet`

`pandas.DataFrame.to_parquet`

`pandas.read_orc`

`pandas.DataFrame.to_orc`

`pandas.read_sas`

`pandas.read_spss`

`pandas.read_sql_table`

`pandas.read_sql_query`

`pandas.read_sql`

`pandas.DataFrame.to_sql`

`pandas.read_gbq`

`pandas.read_stata`

`pandas.DataFrame.to_stata`

`pandas.io.stata.StataReader.data_label`

`pandas.io.stata.StataReader.value_labels`

`pandas.io.stata.StataReader.variable_labels`

`pandas.io.stata.StataWriter.write_file`

`pandas.melt`

`pandas.pivot`

`pandas.pivot_table`

`pandas.crosstab`

`pandas.cut`

`pandas.qcut`

`pandas.merge`

`pandas.merge_ordered`

`pandas.merge_asof`

`pandas.concat`

`pandas.get_dummies`

`pandas.from_dummies`

`pandas.factorize`

`pandas.unique`

`pandas.lreshape`

`pandas.wide_to_long`

`pandas.isna`

`pandas.isnull`

`pandas.notna`