企业官网建设流程全解析

gs-quant 时间序列日期处理：month() 函数提取月度分量与时间序列日期运算实战指南

【免费下载链接】gs-quantPython toolkit for quantitative finance项目地址: https://gitcode.com/GitHub_Trending/gs/gs-quant

导读

month()是 gs-quant（Goldman Sachs 开源的 Python 量化金融工具包）时间序列日期/时间工具模块中的一个核心函数，用于将时间序列索引中的日期逐一转换为对应的月份数值（1–12），从而支持按月份切片、季节性分析、月度聚合与回测研究。读完本文，你将掌握month()的完整 API 语义、底层 pandas 实现原理、与其配套的day()、year()、quarter()、weekday()等日期分量函数，以及它们在真实量化分析场景中的组合用法。

month是 gs-quant 中gs_quant.timeseries.datetime模块（源码位于 datetime.py）提供的公开函数，对应的 API 文档页为 month.rst，该页通过 Sphinx 的autofunction指令直接从函数 docstring 生成文档，因此本文内容以源码 docstring 与实际实现为准。

month() 函数签名与核心语义

函数签名

month(x: pd.Series) -> pd.Series

month定义在 datetime.py 中，并通过gs_quant/timeseries/__init__.py中的from .datetime import *导出，因此可以直接通过gs_quant.timeseries.month或from gs_quant.timeseries import month的方式引入使用。

参数与返回值

数学定义

函数的行为可用如下公式描述：

Y_t = month(t)

即对于序列中的每个观测点t，取其日期索引的月份数（1 月为 1，12 月为 12）作为输出值。函数 docstring 中特别注明："Month of the time or date is the integer month number, e.g. 1-12"（日期/时间的月份为整数月数，例如 1–12）。

底层实现原理（源码级分析）

month()的实现极其简洁，整个函数体只有一行：

return pd.Series(pd.to_datetime(x.index.to_series()).dt.month, dtype=np.int64)

其执行链路可以拆解为三步：

1. x.index.to_series()：将序列的索引转换为以索引值为内容的 Series，便于后续向量化处理；
2. pd.to_datetime(...)：将索引中的日期/时间戳统一转换为 pandas 的DatetimeIndex语义，保证无论输入索引是datetime.date、字符串日期还是Timestamp，都能被正确解析；
3. .dt.month：pandas 的.dtaccessor 提取时间戳的月份分量，最终用pd.Series(..., dtype=np.int64)封装为整数类型的输出序列。

值得注意的一点是：month()返回的序列索引与输入完全一致（只是值被替换为月份数字），这意味着你可以在保持原始时间对齐的前提下，用结果序列与原始序列进行groupby、resample或条件筛选等后续操作。

装饰器@plot_function

month()与模块内其他函数一样带有@plot_function装饰器。该装饰器定义于 helper.py，其作用仅为在函数上打上fn.plot_function = True标记，指示 Chart Service 将该函数作为纯函数导出到绘图工具（plottool）中。也就是说，month()不仅可以在 Python 代码中调用，还被 gs-quant 的图表服务登记为可用的绘图函数，可以无缝出现在可视化表达式中。

完整使用示例

基础用法：提取每月数值

from gs_quant.timeseries import generate_series, month series = generate_series(100) # 生成 100 个观测值的示例序列 months = month(series) # 返回每个观测点对应的月份（1-12）

构造带日期索引的序列并提取月份

import datetime as dt import pandas as pd from gs_quant.timeseries import month dates = [ dt.date(2019, 1, 1), dt.date(2019, 2, 1), dt.date(2019, 3, 1), dt.date(2019, 4, 1), ] x = pd.Series([1.0, 2.0, 3.0, 4.0], index=dates) result = month(x) # 输出：索引仍为 2019-01-01 ... 2019-04-01，值为 [1, 2, 3, 4]

与生成器、绘图联动

month()常与generate_series()配合用于快速验证：

from gs_quant.timeseries import generate_series, month series = generate_series(100) months = month(series) # 每个观测点对应月份

由于@plot_function的标记，month也可直接出现在 Chart Service / plottool 表达式中，对任意时间序列求月度分量并绘制。

与日期分量函数家族协同使用

month()并不是孤立存在的，它属于gs_quant.timeseries.datetime模块中的一组"日期分量提取"函数。在 datetime.py 中，紧邻month()的还有四个语义完全对称的兄弟函数，它们共享相同的实现模式（pd.to_datetime(...).dt.<分量>）：

各函数 docstring 的 "See also" 部分互相交叉引用（例如month的 See also 指向day与year），暗示了它们常被一起使用来完成日期维度的特征工程。

典型应用场景：在季节性因子研究中，可同时提取month、weekday作为分组键，例如计算"过去 5 年每年 1 月与 7 月的平均收益率"，或统计特定星期几的成交量分布；在回归建模中，这些日期分量可作为哑变量特征输入。

测试用例对行为的验证

month()的语义在仓库测试 test_datetime.py 中得到严格验证：

def test_month(): dates = [ dt.date(2019, 1, 1), dt.date(2019, 2, 1), dt.date(2019, 3, 1), dt.date(2019, 4, 1), ] x = pd.Series([1.0, 2.0, 3.0, 4.0], index=dates) result = month(x) expected = pd.Series([1, 2, 3, 4], index=dates) assert_series_equal(result, expected, obj="Month")

从测试可以确认两个关键行为：

1. 输出序列的索引与输入完全一致（assert_series_equal同时校验值与索引）；
2. 返回值就是日期所在月份的整数值：2019-01 → 1、2019-02 → 2、2019-03 → 3、2019-04 → 4，跨越月份边界时正确递增。

同文件中的test_day、test_weekday、test_year、test_quarter等测试采用了完全一致的断言模式，进一步印证了这组日期分量函数"输入序列索引 → 输出整数值序列"的统一契约。

与其他日期/时间工具的衔接

month()所在的gs_quant.timeseries.datetime模块在 timeseries.rst 文档中被归类为 "Date / Time" 能力组，与以下函数并列：

• 日期对齐与插值：align、interpolate、value
• 日期分量提取：day、weekday、month、year、quarter
• 日期区间与拼接：date_range、prepend、union
• 周期聚合：bucketize（可按AggregatePeriod的week/month/quarter/year分桶聚合）

在实际研究流程中，month()可与bucketize形成互补：bucketize负责把序列按月份分桶并施加聚合函数（如AggregateFunction.MEAN），而month()则把逐日/逐周观测映射为月份标签，适合做逐点的月份归属判断。两者结合可以覆盖"按月份重采样聚合"与"按月份逐点标注"两种典型需求。

使用注意事项与限制

1. 输入必须是时间序列：month()直接操作x.index，如果传入普通数值索引的 Series，pd.to_datetime的解析结果将无法正确表达月份语义；docstring 明确将参数类型声明为pd.Series。
2. 返回类型为整数：输出是dtype=np.int64的整型 Series，如需作为月份标签参与字符串拼接（如'2020-01'），需自行格式化。
3. 不依赖市场数据会话：与align_calendar等标注了@requires_session的函数不同，month()是纯本地向量化计算，无网络与数据权限依赖，可在任意环境中直接运行。

小结

month()是 gs-quant 时间序列日期工具中最基础的"日期分量提取"函数之一：一行实现、向量化处理、保持索引对齐，与day()、weekday()、year()、quarter()共同构成完整的日期特征提取家族。其 API 文档、源码实现与单元测试三者在 month.rst、datetime.py 与 test_datetime.py 中一一对应，是理解 gs-quant 时间序列模块设计风格（docstring 即文档、纯函数即绘图函数）的绝佳入口。对于需要在量化研究中做季节性分析、月度切片或因子分组的研究者，建议将month与year、quarter、bucketize组合使用，构建完整的日期维度特征管道。

【免费下载链接】gs-quantPython toolkit for quantitative finance项目地址: https://gitcode.com/GitHub_Trending/gs/gs-quant