时间戳

首页 > 解决方案 > 如何在文档字符串中指定 Pandas DataFrame 架构/结构？

pandas - 如何在文档字符串中指定 Pandas DataFrame 架构/结构？

问题描述

我想描述一下我的 Python 函数所期望的 DataFrame 结构，以及如下的口头描述：

def myfun(input):
    """ Does a thing.
    Parameters
    ----------
    input : pandas.DataFrame
        column 1 is called 'thing1' and it is of dtype 'i4'"
    """
    ...

感觉容易出错。有没有一种传统的方式来描述它？我在 Pandas 文档字符串文档中看不到任何内容。

标签： pandasdataframedocstring

解决方案

由于没有官方标准，我的回答是必然的，固执己见。

回答

我建议使用基于系列的 repr() 的描述，因为每个数据帧都可以描述为系列的集合。它还应该基于面向开发人员的 pandas 文档字符串指南。

def myfun(input):
    """ Does a thing.
    Parameters
    ----------
    input : pandas.DataFrame
        Index:
            RangeIndex
        Columns:
            Name: Date, dtype: datetime64[ns]
            Name: Integer, dtype: int64
            Name: Float, dtype: float64
            Name: Object, dtype: object

    """

示例数据框：

data = [[pd.Timestamp(2020, 1, 1), 1, 1.1, "A"],
        [pd.Timestamp(2020, 1, 2), 2, 2.2, "B"]]
input = pd.DataFrame.from_records(data=data, columns=['Date', 'Integer', 'Float', 'Object'])

输出：

    Date        Integer     Float   Object
0   2020-01-01  1           1.1     A
1   2020-01-02  2           2.2     B

一般定义

<dataframe name>: pandas.DataFrame
    Index:
        <__repr__ of Index>
            <Optional: Description of index data>
    Columns:
        <last line of __repr__ of pd.Series object of first column>
            <Optional: Description of column data>
        ...
        <last line of __repr__ of pd.Series object of last column>
            <Optional: Description of column data>

解释

详细讨论了如何标准化表数据。从这次讨论中，出现了ISO/IEC 11179、JSON 表模式和W3C 表格数据模型等标准。但是，它们对于在文档字符串中描述数据框并不完美。例如，您需要考虑与其他表的关系，这对于数据库应用程序很重要，但对于 Pandas 数据框则不重要。

我提出的基于 repr 的方法有几个优点：

  • 它尊重 Pandas 核心开发者的意见。repr 是我们应该看到的关于对象的内容。
  • 它是有效的。让我们面对现实吧，文档很难。使用这种方法，自动化非常简单。可以在下面找到一个示例。
  • 它正在发展。如果 repr 发生变化，则文档字符串也会发生变化。
  • 它是可扩展的。如果您想包含其他元数据，数据框对象有更多可以包含的属性。

带有附加元数据的自动生成的文档字符串示例：

df = input.copy()
df = df.set_index('Date')
docstring = 'Index:\n'
docstring = docstring + f'    {df.index}\n'
docstring = docstring + 'Columns:\n'
for col in df.columns:    
    docstring = docstring + f'    Name: {df[col].name}, dtype={df[col].dtype}, nullable: {df[col].hasnans}\n'

输出：

Index:
    DatetimeIndex(['2020-01-01', '2020-01-02'], dtype='datetime64[ns]', name='Date', freq=None)
Columns:
    Name: Integer, dtype=int64, nullable: False
    Name: Float, dtype=float64, nullable: False
    Name: Object, dtype=object, nullable: False

推荐阅读