Pandas 2.2 中文文档（二十九）

原文：pandas.pydata.org/docs/

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’, ‘replace’, ‘append’}，默认为 ‘fail’

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

• fail: 引发 ValueError。

• replace: 在插入新值之前删除表。

• append: 将新值插入到现有表中。

index布尔值，默认为 True

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

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

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

chunksize整数，可选

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

dtype字典或标量，可选

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

method{None, ‘multi’, callable}，可选

控制使用的 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，可选

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

返回：

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, 117, 118, 119, None}，默认为 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

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

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{默认’raise’，‘drop’}，可选

如果箱边不唯一，则引发 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{默认为 ‘raise’，‘drop’}，可选

如果 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{‘ffill’, None}，默认为 None

数据的插值方法。

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

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

how{‘left’, ‘right’, ‘outer’, ‘inner’}，默认为‘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