gs-quant Timeseries 包全解析从代数运算、计量经济指标到技术分析的一站式时序量化工具【免费下载链接】gs-quantPython toolkit for quantitative finance项目地址: https://gitcode.com/GitHub_Trending/gs/gs-quant导读gs_quant.timeseries是 gs-quant 开源 Python 量化工具包中面向金融时序数据以pandas.Series为核心载体的完整函数库。本文以官方 API 文档 docs/timeseries.rst 为主线骨架逐模块讲解其 Algebra代数、Analysis分析、Backtesting回测、Date/Time日期时间、Econometrics计量经济、Statistics统计、Technical Analysis技术分析七大子库的全部公开函数与类并结合 gs_quant/timeseries/ 下的真实源码说明每个 API 的签名、默认参数、底层实现与典型用法。读完本文你将能够使用这些 API 完成价格序列的清洗与对齐、收益率与波动率计算、滚动回归与分位数分析、均线与 MACD 等指标构建以及简单组合回测。一、模块总览与统一设计约定1.1 七个公开子模块gs_quant/timeseries/__init__.py通过from .xxx import *将各子模块的公开符号统一暴露到gs_quant.timeseries命名空间因此实际使用中既可直接from gs_quant.timeseries import returns也可以按子模块导入。官方文档将全部 API 划分为七组子模块文档章节核心定位gs_quant.timeseries.algebraAlgebra数值与代数运算加减乘除、指数对数、逻辑运算、加权求和gs_quant.timeseries.analysisAnalysis序列属性分析差分、滞后、首尾值、观测计数gs_quant.timeseries.backtestingBacktesting篮子序列回测与 Basket 类gs_quant.timeseries.datetimeDate / Time日期时间处理、对齐、插值与聚合gs_quant.timeseries.econometricsEconometrics金融计量收益、波动、相关性、Beta、夏普、回撤gs_quant.timeseries.statisticsStatistics通用统计均值、中位数、分位数、回归、流行病学模型gs_quant.timeseries.technicalsTechnical Analysis技术指标均线、布林带、RSI、MACD、季节性分解1.2 三个贯穿全库的关键抽象Window窗口定义在 helper.py。由w窗口大小与rramp-up 预热值默认等于窗口大小组成两者都既可以是观测数整数如22也可以是相对时间字符串如1m、1w。几乎所有滚动类函数volatility、correlation、mean、moving_average等都接受Window、int或相对日期字符串三种形式内部由normalize_window统一归一。Interpolate插值/对齐方式枚举值包括intersect、step、nan、zero、time。intersect只保留两序列日期交集nan/zero在并集上分别以 NaN/0 填充缺失值step用前向有效值填充time则按时间间隔线性插值要求DateTimeIndex。该枚举用于align、interpolate、add、compare等函数。plot_function装饰器各模块的公开函数大多以plot_function装饰表明这些函数可被 gs-quant 的图表服务/PlotTool 直接调用函数 docstring 即其可解析的文档契约见各模块文件头部注释。二、Algebra时序代数运算对应源码 gs_quant/timeseries/algebra.py。这是最基础的数值运算层绝大多数函数接受「序列或标量」的混合输入。2.1 四则运算与幂运算add、subtract、multiply、divide、floordiv签名完全一致f(x, y, methodInterpolate.STEP)。当x、y都是实数时直接返回标量结果否则先调用align(x, y, method)对齐索引再执行元素级运算algebra.py。默认插值为step即按并集索引、缺失处用前向值填充。文档给出的对齐行为表Method行为intersect结果只保留两序列日期交集上的值nan结果在并集上有值仅在单侧出现的日期另一侧按 NaN 处理zero结果在并集上有值仅在单侧出现的日期另一侧按 0 处理step结果在并集上有值缺失处按 step 函数插值time结果在日期/时间并集上被有效值包围的缺失点按区间长度线性插值输入须为DateTimeIndexexp/log分别对应np.exp与np.log自然对数互为逆运算power(x, y1)对每个元素求X_t^ysqrt对序列做np.sqrt对纯标量则用math.sqrt并在结果为整数时返回整型algebra.py。注意floor/ceil语义与数学上的下取整/上取整不同——它们是对序列做上下限截断floor(x, value0)返回max(X_t, value)ceil(x, value0)返回min(X_t, value)且要求索引单调递增algebra.py。2.2 过滤函数filter_(x, operatorNone, valueNone)按FilterOperatorLESS/GREATER/L_EQUALS/G_EQUALS/EQUALS/N_EQUALS与阈值value删除满足条件的值不传参数时默认dropna()删除缺失值algebra.py。filter_dates(x, operatorNone, datesNone)按日期过滤EQUALS/N_EQUALS支持日期列表而GREATER/LESS等只支持单一日期否则抛出MqValueErroralgebra.py。2.3 逻辑运算and_、or_、not_、if_面向 0/1 布尔型序列。内部通过_sum_boolean_series校验每个输入序列取值只能是 0 或 1and_要求全部为 1、or_要求至少一个为 1、not_做 0↔1 替换if_(flags, x, y)则对flags1的位置取x的值否则取y的值支持标量或序列。if_的 docstring 给出了 PlotTool 表达式示例if(SPX.spot() 4000, SPX.spot(), GSTHHVIP.spot())algebra.py。2.4 加权求和weighted_sum(series, weights)计算篮子式加权和取所有输入序列的日期交集作为共同日历按权重归一化求和algebra.py。文档示例prices1 generate_series(100) prices2 generate_series(100) mybasket weighted_sum([prices1, prices2], [0.7, 0.3])三、Analysis序列结构与差分分析对应源码 gs_quant/timeseries/analysis.py共 6 个公开函数。first(x)返回以原索引展开的「首值序列」R_t X_0last(x)返回末值序列last_value(x)返回末值标量空序列时抛MqValueErroranalysis.py。count(x)滚动累积计数等价于x.rolling(x.size, 0).count()记录非 NaN 观测数随时间累积。diff(x, obs1)差分R_t X_t - X_{t-obs}obs可以是观测数、Window或相对日期如3d、1w、1m内部调用laganalysis.py。lag(x, obs1, modeLagMode.EXTEND)滞后函数。obs为非零整数或相对日期字符串如1yLagMode.TRUNCATE截断到原序列末尾LagMode.EXTEND会把索引向未来扩展要求日级别分辨率索引。源码对含bbusiness day的字符串显式报错提示工作日索引应改用整数偏移analysis.py。lag与diff是后面收益率的基石——econometrics.returns正是lag(series, obs, LagMode.TRUNCATE)后做除法/对数差实现的。四、Date / Time日期时间对齐、插值与重采样对应源码 gs_quant/timeseries/datetime.py。文档列出的 11 个函数 Window类覆盖了时序索引的几乎所有常规操作。4.1 对齐与插值align(x, y, methodInterpolate.INTERSECT)对齐两条序列或序列与标量的索引返回对齐后的二元组。源码实现intersect→x.align(y, inner)nan→outerzero→outer fill_value0step→outer后ffill().bfill()time→outer后interpolate(time, limit_areainside)datetime.py。这是所有双序列代数运算的底层对齐原语。interpolate(x, datesNone, methodInterpolate.INTERSECT)把序列x插值到指定日期/时间数组或另一条序列的索引上step模式由内部__interpolate_step实现「前向填充、首值回填」。value(x, date, methodInterpolate.STEP)取指定日期的值缺失时默认返回最近前值返回标量或None。4.2 日期属性提取与切片day、month、year、quarter、weekday分别把索引转为日1-31、月1-12、年、季度1-4、星期0周一0-6的整型序列date_range(x, start_date, end_date, weekdays_onlyFalse)按日期切片start_date/end_date既可以是绝对日期也可以是相对首尾的观测数整数weekdays_onlyTrue时剔除周末。4.3 序列拼接与填充prepend(series_list)把历史较短的「高质量」序列拼在历史较长的序列之前前一段数据取至下一段首日之前。append(series_list)依次拼接后一段只取前一段最后日期之后的数据。union(series_list)用后面的序列填充前面序列的缺失日期等价于combine_first链式调用。4.4 重采样bucketize(series, aggregate_function, period)按AggregatePeriodweek/month/quarter/year分桶并对每桶应用AggregateFunctionmax/min/mean/sum/first/last结果以每桶结束日索引。示例bucketize(x, AggregateFunction.MEAN, AggregatePeriod.MONTH)得到月度均值序列。五、Econometrics金融计量核心对应源码 gs_quant/timeseries/econometrics.py。这是整个包中最「金融」的子库文档列出的 11 个函数全部围绕收益、波动、相关与风险度量。5.1 收益与价格互转returns(series, obs1, typeReturns.SIMPLE)支持三种收益类型econometrics.pyType公式适用场景simple默认Y_t X_t / X_{t-obs} - 1可跨资产加总logarithmicY_t log(X_t) - log(X_{t-obs})可跨时间加总absoluteY_t X_t - X_{t-obs}绝对价差prices(series, initial1, typeReturns.SIMPLE)为其逆运算简单收益用product(1 series) * initial累乘对数收益用product(series.apply(math.exp)) * initial绝对收益用sum_(series) initial。两者互为往返可验证数据一致性。5.2 归一化index(x, initial1)做几何归一化Y_t initial * X_t / X_0要求首个有效值非零否则报除零错误change(x)做算术归一化Y_t X_t - X_0。5.3 波动率族volatility(x, wWindow(None,0), returns_typeReturns.SIMPLE, annualization_factorNone, assume_zero_meanFalse)是核心函数w支持Window(22, 10)、整数22或相对日期1m窗口默认覆盖全序列。returns_typeNone表示输入本身就是收益序列不做转换annualization_factorNone时按平均观测间隔自动推断日 252 / 周 52 / 半月 26 / 月 12 / 季 4 / 年 1由_get_annualization_factor依据平均日期间隔的阈值区间判断。assume_zero_meanTrue使用总体公式N 为分母的 RMS这是方差互换/相关互换的行业惯例默认False使用样本公式N-1 分母。返回值单位为百分数20% 年化波动返回20.0。annualize(x)依据观测频率推断年化因子后x * sqrt(F)vol_swap_volatility与corr_swap_correlation分别是面向波动率互换/相关互换定价的零均值口径专用函数对数收益 N 分母Window(n_days, n_days-1)约定。5.4 相关性、Beta 与夏普correlation(x, y, w, type_SeriesType.PRICES, returns_typeReturns.SIMPLE, assume_zero_meanFalse)滚动 Pearson 相关returns_type还支持传二元组为两条序列分别指定收益类型内部会剔除重复索引并做对齐dropna()econometrics.py。beta(x, b, w, pricesTrue)滚动 Beta Cov(R,S)/Var(S)pricesFalse时输入视为收益序列源码对前 3 个样本点置 NaN 以防小样本极端值econometrics.py。sharpe_ratio(series, currencyRiskFreeRateCurrency.USD, wNone, curve_typeCurveType.PRICES, methodInterpolate.NAN)滚动夏普比率。底层通过excess_returns_Actual/360 日计数、风险免费率取对应货币的 Marquee 资产计算超额收益再年化收益除以窗口波动率并乘 100。该函数带plot_session_function需要会话/数据访问能力。max_drawdown(x, w)滚动最大回撤峰谷比如 20% 回撤返回-0.2整数窗口用x.rolling(w.w,0).max()求滚动峰值再对(x/rolling_max - 1)取滚动最小值。六、Statistics统计与回归、模型类对应源码 gs_quant/timeseries/statistics.py文档列出 16 个函数和 4 个类。6.1 滚动统计函数min_/max_/mean/median/mode/sum_/product/std/var/cov/range_遵循统一签名f(x, wWindow(None,0))w为整数窗口、Window或相对日期字符串w字符串支持y/m/w/d/h频率年/月/周/日/小时。特别地mean支持MeanType.QUADRATIC对x²求滚动均值再开方即 RMS是零均值波动率的基础statistics.py。std/var/cov均采用 N-1 无偏估计docstring 明确标注 unbiased estimator。exponential_std(x, beta0.75)指数加权标准差beta为对更远过去的权重0 闭区间到 1 开区间实现为x.ewm(alpha1-beta, adjustFalse).std()。zscores(x, w)滚动 z-score(X_t-μ)/σwinsorize(x, limit2.5, w)对 z-score 超过limit的极值按μ±σ·limit截断用ceil/floor实现见 statistics.py。percentile(x, n, wNone)n须在 [0,100]无窗口时返回全序列分位数标量有窗口时返回滚动分位数序列。percentiles(x, yNone, w)y中每个值在x的滚动历史分布中的百分位排名scipy.stats.percentileofscorekindmean。generate_series(length, directionDirection.START_TODAY)按R~N(0,1)随机游走生成测试用价格序列起点 100END_TODAY时以今天为最后一天——这是所有文档示例中反复出现的测试数据来源。6.2 回归模型类LinearRegression(X, y, fit_interceptTrue)基于 statsmodels OLS 的多元线性回归。X可为单序列或序列列表自动剔除 NaN/inf并与y按日期取交集对齐。提供coefficient(i)0 为截距、r_squared()、fitted_values()、predict(X_predict)、standard_deviation_of_errors()statistics.py。RollingLinearRegression(X, y, w, fit_interceptTrue)滚动 OLSstatsmodelsRollingOLS窗口w必须大于解释变量个数系数与 R² 输出为逐窗序列各窗口参数存于窗口末statistics.py。6.3 流行病学模型类SIRModel与SEIRModel封装了 gs_quant/models/epidemiology.py 中的仓室模型用于传染病传播建模。SIRModel(beta, gamma, s, i, r, n100, fitTrue, fit_periodNone)的 S/I/R 仓室可由序列或标量给出fitTrue时自动标定beta易感→感染传播率默认初值 0.9、gamma感染→康复率默认初值 0.01SEIRModel额外引入暴露仓室e与参数sigma潜伏→感染率默认初值 0.2。标定后可通过s0()/i0()/r0()/beta()/gamma()/predict_s()/predict_i()/predict_r()SEIR 另加e0()/sigma()/predict_e()取得参数与逐日预测序列statistics.py。七、Technical Analysis技术指标库对应源码 gs_quant/timeseries/technicals.py共 9 个公开函数全部基于前文基础函数组合实现。函数默认参数说明与底层实现moving_average(x, w)wNone简单算术移动平均等价于mean文档明确标注 Equivalent tomeansmoothed_moving_average(x, w)wNone修正移动平均MMA/RMAP_t ((N-1)·P_{t-1} X_t)/N递归实现exponential_moving_average(x, beta0.75)beta0.75EMAY_t β·Y_{t-1} (1-β)·X_tewm(alpha1-beta, adjustFalse)bollinger_bands(x, w, k2)k2返回含lower、upper两列的 DataFrameμ ± k·σrelative_strength_index(x, w14)w14RSI上涨均值/下跌均值转 0-100无下跌时为 100macd(x, m12, n26, s1)m12,n26,s1EMA(X,m) - EMA(X,n)后再做 spans 的 EMA 平滑s1等价于不平滑exponential_volatility(x, beta0.75)beta0.75收益的指数加权 std 后年化 ×100等价于annualize(exponential_std(returns(x), beta)).mul(100)exponential_spread_volatility(x, beta0.75)beta0.75对diff(x,1)做指数加权 std 再年化seasonally_adjusted(x, methodadditive, freqyear)—基于 statsmodelsseasonal_decompose去除季节成分输入需含至少两个完整周期trend(x, methodadditive, freqyear)—同一分解的长期趋势分量技术指标调用示例prices generate_series(100) ma moving_average(prices, 22) # 22 日简单均线 bb_low, bb_high bollinger_bands(prices, 20, 2) # 20 日布林带2 倍标准差 rsi relative_strength_index(prices, 14) # 14 日 RSI macd_line macd(prices, 12, 26) # 经典 12/26 MACD注意seasonally_adjusted/trend要求至少两年两个完整周期数据technicals.py示例用generate_series(1000)。八、Backtesting篮子序列与 Basket 类对应源码 gs_quant/timeseries/backtesting.py文档列出一个函数与一个类。8.1basket_seriesbasket_series(series, weightsNone, costsNone, rebal_freqRebalFreq.DAILY, return_typeReturnType.EXCESS_RETURN)计算篮子收益序列输入各成分价格序列、权重默认等权、交易成本十进制如 5bps0.0005、再平衡频率Daily/Weekly/Monthly。底层backtest_basket以初始净值 100 起步在日历交集上按日更新净值并在再平衡日扣除Σ costs·|目标权重-实际权重|·净值的交易成本backtesting.py。文档示例prices1 generate_series(100) prices2 generate_series(100) mybasket basket_series([prices1, prices2], [0.7, 0.3], [0.0005, 0.001], RebalFreq.MONTHLY)8.2Basket类Basket(stocks, weightsNone, rebal_freqRebalFreq.DAILY)构造股票篮子输入 Bloomberg ID 列表bbids通过GsAssetApi解析为 Marquee ID重复资产取 rank 更高者在DataContext定义的日期范围内拉取 spot 数据并执行backtest_basket。公开方法get_returns()/get_actual_weights()/get_spot_data()回测净值、实际权重与成分价格。price()加权平均价格序列。average_implied_volatility(tenor, strike_reference, relative_strike)按实际权重加权的平均隐含波动率支持 tenor 如1m。average_realized_volatility(tenor, returns_typeReturns.LOGARITHMIC)加权已实现波动。average_realized_correlation(w)成分两两相关按权重乘积加权的平均相关。average_forward_vol(tenor, forward_start_date, ...)远期波动率由两个期限的方差线性插值得出。这些方法带requires_session与plot_method需要配置 gs-quant 会话GsSession才能访问 Marquee 数据。九、实战串联示例将上述模块组合成一条完整分析流水线假设已配置GsSessionfrom gs_quant.timeseries import ( generate_series, returns, volatility, correlation, sharpe_ratio, moving_average, bollinger_bands, relative_strength_index, zscores, winsorize, align, bucketize, AggregateFunction, AggregatePeriod, Window, basket_series ) # 1. 生成测试数据或替换为真实行情序列 px_a generate_series(365, end_today) px_b generate_series(365, end_today) # 2. 收益与对齐 ret_a returns(px_a) # 简单日收益 px_a2, px_b2 align(px_a, px_b, intersect) # 取共同交易日 # 3. 风险度量 vol22 volatility(px_a, 22) # 22 日年化波动百分数 corr correlation(px_a, px_b, 22) # 22 日滚动相关 sr sharpe_ratio(px_a, USD, 22) # 22 日滚动夏普 # 4. 技术指标 ma moving_average(px_a, Window(22, 10)) bb bollinger_bands(px_a, 20, 2) rsi relative_strength_index(px_a, 14) # 5. 统计清洗 z zscores(ret_a, 22) # 滚动 z-score clean winsorize(ret_a, 2.5, 22) # 极端值截断 # 6. 重采样与回测 monthly bucketize(px_a, AggregateFunction.LAST, AggregatePeriod.MONTH) basket basket_series([px_a, px_b], [0.7, 0.3], [0.0005, 0.001], monthly)十、相关资源与延伸阅读API 文档总入口docs/timeseries.rst各函数逐条页位于 docs/functions/如 gs_quant.timeseries.econometrics.volatility.rst。类文档Window、Basket、LinearRegression、SIRModel等docs/classes/。官方笔记本教程gs_quant/documentation/下含大量实例其中回测与组合示例见 gs_quant/documentation/04_backtesting/ 与 gs_quant/documentation/03_portfolios/。单元测试gs_quant/test/timeseries/ 共 32 个测试文件覆盖各函数边界条件空序列、窗口溢出、相对日期窗口等。时间序列的 measure 体系基于Asset.get_data_series()拉取真实市场数据的入口见 gs_quant/timeseries/measures.py 及各measures_*.py。结语gs_quant.timeseries以pandas.Series为统一数据契约通过Interpolate对齐、Window滚动与plot_function装饰器三大约定把代数运算、计量指标、统计检验与技术分析整合为可直接在量化研究/回测中复用的一站式函数库。理解其模块划分与每个 API 的默认参数语义即可高效地将其嵌入到自己的策略研究与风险度量流程中。【免费下载链接】gs-quantPython toolkit for quantitative finance项目地址: https://gitcode.com/GitHub_Trending/gs/gs-quant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考