gs_quant 宏观经济风险模型MacroRiskModel完全指南敏感性分析、模型定价与数据运维【免费下载链接】gs-quantPython toolkit for quantitative finance项目地址: https://gitcode.com/GitHub_Trending/gs/gs-quant导读本文围绕 gs_quant 中的MacroRiskModel宏观风险模型展开系统讲解如何在量化工作流中使用它完成资产对宏观因子及因子类别的敏感性分析get_universe_sensitivity、拟合优度评估get_r_squared、公允价值缺口get_fair_value_gap、因子 Z 分数get_factor_z_score与模型价格get_model_price等核心查询并覆盖模型的创建、持久化、日历管理、因子元数据维护与数据上传等全生命周期操作。读完本文你将掌握MacroRiskModel的完整 API 能力并了解其底层实现与测试验证方式可直接在组合风险归因和宏观情景分析中落地使用。MacroRiskModel是 gs_quant 风险模型体系中专用于敏感性分析sensitivity analysis的模型类型其 API 参考文档位于 docs/classes/gs_quant.models.risk_model.MacroRiskModel.rst核心实现位于 gs_quant/models/risk_model.py 的MacroRiskModel类约第 2966 行起。一、类定位与继承体系1.1 宏观风险模型是什么在 gs_quant 中风险模型被划分为多种类型RiskModelType其中Macro类型对应MacroRiskModel。源码类注释直接给出了它的定位class MacroRiskModel(MarqueeRiskModel): Macro Risk Model used for sensitivity analysis也就是说宏观风险模型的核心用途是敏感性分析给定一组资产回答这些资产对哪些宏观因子或宏观因子类别敏感、敏感程度如何这类问题并进一步输出 R²、公允价值缺口、因子 Z 分数、模型价格等衍生度量。1.2 三层继承结构从 gs_quant/models/risk_model.py 的源码可以看到完整的继承链RiskModel基类仅持有id与name两个不可变核心属性提供字符串化能力MarqueeRiskModel(RiskModel)引入type、vendor、version、coverage、universe_identifier、term、universe_size、entitlements、description、expected_update_time等属性并实现save、delete、get_dates、get_calendar、upload_calendar、get_data、upload_data等通用数据与生命周期方法MacroRiskModel(MarqueeRiskModel)固定typeRiskModelType.Macro并新增get_universe_sensitivity、get_r_squared、get_fair_value_gap、get_factor_z_score、get_model_price等宏观特有方法。同层级的还有FactorRiskModel因子风险模型与ThematicRiskModel主题风险模型三者共享MarqueeRiskModel的通用能力但查询语义各自不同。二、模型对象的创建与获取2.1 直接构造__init__MacroRiskModel.__init__的签名如下MacroRiskModel( id_: str, # 风险模型 ID创建后不可修改 name: str, # 风险模型名称 coverage: CoverageType, # 模型资产池覆盖范围 term: Term, # 模型期限类型 universe_identifier: UniverseIdentifier, # 上传资产池所使用的标识符不可修改 vendor: str, # 模型供应商 version: float, # 模型版本号 universe_size: int None, # 期望资产池规模向上取整到 1k entitlements: dict | Entitlements None, # 模型访问权限 description: str None, # 模型描述 expected_update_time: dt.time None, # 每日数据预计上传时间 )各枚举的可选值定义在 gs_quant/target/risk_models.py参数枚举允许值coverageRiskModelCoverageCountry、Global、Market Type、RegiontermRiskModelTermTrading、Daily、Short、Medium、Longuniverse_identifierRiskModelUniverseIdentifiersedol、bcid、cusip、gsid、isin2.2 从 Marquee 拉取模型get/get_many推荐方式是通过类方法从 Marquee 平台获取已存在的模型对象from gs_quant.models.risk_model import MacroRiskModel model MacroRiskModel.get(MODEL_ID) # 按 ID 获取单个模型get_many支持按ids、terms、vendors、names、coverages组合过滤并可通过limit限制返回数量。其内部调用GsRiskModelApi.get_risk_models(...)时强制传入types[RiskModelType.Macro.value]保证返回结果全部是宏观模型。2.3 目标对象转换from_target/from_many_targetsfrom_target将底层RiskModelBuilder数据对象转换为MacroRiskModel实例转换过程中对coverage、term、universe_identifier做了字符串到枚举的兼容处理并对expected_update_time执行%H:%M:%S格式解析from_many_targets则批量完成同样工作。这两个方法通常由get/get_many内部调用一般不直接使用。三、宏观专属的四大分析度量这是MacroRiskModel区别于其他风险模型的核心能力区。所有数据查询都依赖DataAssetsRequest指定资产与标识符类型from gs_quant.models.risk_model import MacroRiskModel, DataAssetsRequest, \ RiskModelUniverseIdentifierRequest as UniverseIdentifier, ReturnFormat, Unit import datetime as dt model MacroRiskModel.get(MODEL_ID) start_date dt.date(2022, 1, 1) end_date dt.date(2022, 5, 2) assets DataAssetsRequest(UniverseIdentifier.bbid, [GS UN])RiskModelUniverseIdentifierRequest查询用标识符支持gsid、bbid、bcid、cusip、sedol、ric、ticker、primeId、isin、barraId、axiomaId、assetId、secMasterId等多种类型。3.1 资产池敏感性get_universe_sensitivity这是宏观模型最核心的接口用于获取资产对宏观因子的敏感性数据sensitivity model.get_universe_sensitivity( start_date, end_date, DataAssetsRequest(UniverseIdentifier.bbid, [GS UN]), factor_typeFactorType.Factor, # Factor 或 Category get_factors_by_nameFalse, # 是否以因子名称而非 ID 作为键 formatReturnFormat.DATA_FRAME, # DATA_FRAME 或 JSON )当factor_typeFactorType.Factor时返回因子级敏感性当为FactorType.Category时源码会先取因子级数据再通过因子数据中的factorCategoryId或factorCategory将各因子归组聚合成类别级敏感性按行求和并支持pd.MultiIndex多级列输出。3.2 拟合优度get_r_squared返回每个资产在指定时间窗内的 R² 值衡量宏观模型对该资产收益的解释程度r_squared_df model.get_r_squared(start_date, end_date, DataAssetsRequest(UniverseIdentifier.bbid, [GS UN])) # 以 dict 返回 r_squared_dict model.get_r_squared(start_date, end_date, DataAssetsRequest(UniverseIdentifier.bbid, [GS UN]), formatReturnFormat.JSON)3.3 公允价值缺口get_fair_value_gap衡量资产当前价格相对模型公允价值的偏离程度可指定返回单位# 默认以标准差为单位 fvg_df model.get_fair_value_gap(start_date, end_date, DataAssetsRequest(UniverseIdentifier.bbid, [GS UN])) # 以百分比为单位 fvg_pct model.get_fair_value_gap(start_date, end_date, DataAssetsRequest(UniverseIdentifier.bbid, [GS UN]), fair_value_gap_unitUnit.PERCENT)源码中Unit.STANDARD_DEVIATION与Unit.PERCENT分别映射到Measure.Fair_Value_Gap_Standard_Deviation与Measure.Fair_Value_Gap_Percent。3.4 因子 Z 分数get_factor_z_score返回指定因子的标准化 Z 分数可按键名或按 ID 区分因子factor_z_score model.get_factor_z_score( start_date, end_date, factors[factor1, factor2], # 空列表则返回全部因子 factors_by_nameTrue, # True 传因子名False 传因子 ID formatReturnFormat.DATA_FRAME, )3.5 模型价格get_model_price返回宏观模型给出的模型价格序列用于与实际市场价格对比model_price model.get_model_price(start_date, end_date, DataAssetsRequest(UniverseIdentifier.bbid, [GS UN]))3.6 底层实现度量到查询的映射以上四个度量方法最终都收敛到MarqueeRiskModel._get_asset_data_measure或_get_factor_data_measure进而调用统一的get_data(...)向GsFactorRiskModelApi.get_risk_model_data发起查询。例如get_r_squared的核心就是return self._get_asset_data_measure(Measure.R_Squared, start_date, end_date, assets, format)这解释了为什么这些方法的参数风格高度一致start_date必填、end_date可选默认为空即查询到最新、assets用DataAssetsRequest描述、format控制返回 DataFrame 还是 dict。四、通用数据查询能力继承自 MarqueeRiskModel以下方法并非宏观模型独有但同样是MacroRiskModel对象可用的关键查询接口。4.1 日期与日历管理get_dates(start_date, end_date, event_type)返回存在模型数据的所有日期含端点可按RiskModelEventType过滤get_calendar(start_date, end_date)返回RiskModelCalendarbusiness_dates列表不传日期时返回完整日历否则通过get_closest_date_index做边界裁剪起始日取之后最近、结束日取之前最近get_missing_dates(start_date, end_date)对比日历与已发布数据找出缺失日期end_date缺省时为 T-1get_most_recent_date_from_calendar()返回按日历计算的 T-1 日期。4.2 资产池与因子查询get_asset_universe(start_date, end_date, assets, format)获取模型覆盖的资产池注意当assets.universe为空时start_date必须等于end_dateget_factor(name, ...)按名称返回Factor对象名称不存在时抛出MqValueErrorget_many_factors(start_date, end_date, factor_names, factor_ids, factor_type)批量获取因子对象factor_type可指定FactorType.Factor或FactorType.Categoryget_factor_data(start_date, end_date, identifiers, include_performance_curve, category_filter, name_filter, factor_type, format)获取因子原始数据支持按 ID、类别、名称过滤当factor_typeFactorType.Category时自动注入[Aggregations]类别此时不允许再传category_filterget_factor_returns_by_name(...)/get_factor_returns_by_id(...)分别以因子名称或 ID 为键返回因子收益序列get_factor_standard_deviation(...)返回因子标准差1 sigma 值get_intraday_factor_data(...)默认返回最近 3 小时的日内因子数据支持按因子名、因子 ID、类别过滤及数据源选择。4.3 资产级风险度量get_universe_exposure(start_date, end_date, assets, factors, get_factors_by_name, format)资产对因子的暴露度get_factors_by_nameTrue时用build_factor_id_to_name_map做 ID 到名称的映射get_specific_risk(...)资产特异性风险get_data(measures, start_date, end_date, assets, factors, limit_factors)通用多度量查询入口请求过大时HTTP 499会抛出带考虑分批请求提示的MqRequestError。五、模型生命周期与数据运维5.1 保存与删除save()将当前对象上传到 Marquee。源码会先尝试create_risk_model若抛出MqRequestError则回退为update_risk_model因此新建与更新共用同一方法delete()删除 Marquee 上的模型调用GsRiskModelApi.delete_risk_model(self.id)。5.2 日历与数据上传upload_calendar(calendar)上传RiskModelCalendar声明模型数据预期发布的日期upload_data(data, max_asset_batch_size10000, aws_uploadTrue, asset_data_patchesNone)上传某日期的完整或部分模型数据。数据可包含factorData、assetData、covarianceMatrix、issuerSpecificCovariance、factorPortfolios、currencyRatesData。当目标资产池规模超过max_asset_batch_size或数据不完整时会自动按因子数据 → 资产数据按 10000 分批→ 发行人特异性协方差按 5000 分批→ 因子组合按 5000 分批的顺序拆分为多个请求batch_and_upload_partial_dataupdate_partial_data(date, data, ...)仅支持assetData的补丁式更新——只对输入universe列出的资产做拉取现有数据 → 字段级合并新值覆盖、未列字段保留→ 重传且不允许包含factorExposure与specificRisk这两者由服务端生成日期无存量数据时抛出 404MqRequestErrorupload_partial_data(...)该 API 自 0.9.42 版本起被标记为弃用deprecated官方建议改用upload_dataupload_asset_coverage_data(dateNone, batch_size100)将资产池覆盖信息上传到覆盖数据集date缺省取模型最后有数据的一天在最近 5 天内发布覆盖数据可使模型出现在 Marquee UI 的模型下拉列表中。5.3 因子元数据管理save_factor_metadata(factor_metadata)为因子添加/更新元数据内部同样先尝试 update失败则 createdelete_factor_metadata(factor_id)删除指定因子的元数据。六、与 PortfolioManager 的集成MacroRiskModel的典型消费场景是组合层面的宏观暴露分析。在 gs_quant/markets/portfolio_manager.py 中PortfolioManager.get_macro_exposure(model, start_date, end_date, ...)接收一个MacroRiskModel实例返回组合及资产对宏观因子或因子类别的暴露 DataFrame/dict当组合对所有请求因子均无暴露时会记录The Portfolio is not exposed to any of the requested macro factors告警。这使宏观模型能够直接嵌入组合归因流水线。七、测试验证与行为确认宏观模型的各方法行为在 gs_quant/test/models/test_risk_model.py 中有对应的 mock 测试mock_macro_risk_model通过MacroRiskModel.get(macro_model_id)构造被测对象test_get_r_squared验证查询参数startDate、endDate、assets、measures、limitFactors被正确组装为/risk/models/data/{id}/query请求且返回的{asset: {date: rSquared}}结构与ReturnFormat.JSON一致test_get_fair_value_gap_standard_deviation、test_get_fair_value_gap_percent、test_get_factor_z_score、test_get_model_price分别覆盖各宏观度量的请求构建与结果解析。这些测试可以视为使用契约所有查询类方法最终都会向/risk/models/data/{id}/query端点 POST 一个包含startDate/endDate/assets/measures/limitFactors的 payload并默认带 200 秒超时。对超大体量的查询可依据get_data中的提示对大日期区间做分批处理或添加重试。八、典型使用流程总结一个完整的宏观风险模型使用闭环通常如下获取模型MacroRiskModel.get(MODEL_ID)或get_many按属性检索确认数据完整性get_dates/get_missing_dates/get_calendar检查日期覆盖必要时upload_data补齐执行敏感性分析get_universe_sensitivity输出因子级/类别级暴露get_r_squared评估解释力get_fair_value_gap定位价格偏离get_factor_z_score观察因子极端状态组合级应用将模型传入PortfolioManager.get_macro_exposure得到组合宏观暴露持续运维每日通过upload_data/update_partial_data更新数据用upload_asset_coverage_data维持模型在平台中的可见性。需要说明的是MacroRiskModel的所有读写操作均依赖 Marquee 平台服务GsRiskModelApi/GsFactorRiskModelApi使用时需先通过 gs_quant 的会话机制完成认证配置。文中所引用的枚举取值、批大小默认值10000、弃用版本0.9.42等信息均以当前仓库 gs_quant/models/risk_model.py 与 gs_quant/target/risk_models.py 的实际实现为准。【免费下载链接】gs-quantPython toolkit for quantitative finance项目地址: https://gitcode.com/GitHub_Trending/gs/gs-quant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
