gs-quant 指数数据坐标全解析深入 Index.get_data_coordinate 的定位原理与实战用法【免费下载链接】gs-quantPython toolkit for quantitative finance项目地址: https://gitcode.com/GitHub_Trending/gs/gs-quant导读在 gs-quant 中Index.get_data_coordinate是连接指数实体与Marquee 数据平台时序数据之间的关键桥梁它把一个可读的度量如收盘价翻译成一个携带数据集 ID、维度键值与频率信息的DataCoordinate对象从而唯一锁定一条时序。本文以 gs_quant.markets.index.Index.get_data_coordinate 的 API 文档 为骨架结合仓库源码逐步拆解其参数语义、底层实现与典型调用链帮助你在因子研究、风险分析与 Datagrid 查询中正确、高效地使用这一方法。一、方法与文档定位该方法的官方文档由 Sphinx 的automethod指令自动生成文档正文的核心实体是gs_quant.markets.index模块下的Index类方法.. currentmodule:: gs_quant.markets.index .. automethod:: Index.get_data_coordinateIndex类定义于 gs_quant/markets/index.py其类注释将其描述为追踪一个不断演化的证券组合、可通过现金或衍生品市场进行交易的指数并支持 STS 指数class Index(Asset, PositionedEntity): Index which tracks an evolving portfolio of securities, and can be traded through cash or derivatives markets. Includes support for STS indices. Index继承自Asset与PositionedEntity因此它天然继承了资产类通用的数据访问能力get_data_coordinate正是其中被高频复用的底层方法。二、方法签名与参数语义get_data_coordinate的完整实现位于 gs_quant/entities/entity.pydef get_data_coordinate( self, measure: Union[DataMeasure, str], dimensions: Optional[DataDimensions] None, frequency: DataFrequency DataFrequency.DAILY, availabilityNone, ) - DataCoordinate: id_ self.get_marquee_id() dimensions dimensions or {} dimensions[self.data_dimension] id_ measure measure if isinstance(measure, str) else measure.value available: dict GsDataApi.get_data_providers(id_, availability).get(measure, {}) if frequency DataFrequency.DAILY: daily_dataset_id available.get(DataFrequency.DAILY) return DataCoordinate( dataset_iddaily_dataset_id, measuremeasure, dimensionsdimensions, frequencyfrequency ) if frequency DataFrequency.REAL_TIME: rt_dataset_id available.get(DataFrequency.REAL_TIME) return DataCoordinate(dataset_idrt_dataset_id, measuremeasure, dimensionsdimensions, frequencyfrequency)四个核心参数说明如下参数类型默认值含义与约束measureUnion[DataMeasure, str]必填要查询的数据度量如DataMeasure.CLOSE_PRICE既可直接传枚举也可传字符串方法内部会统一转换为字符串形式dimensionsOptional[DataDimensions]None额外的维度字典如 tenor、currency 等为None时自动初始化为空字典frequencyDataFrequencyDataFrequency.DAILY数据频率目前实现仅显式支持DAILY日频与REAL_TIME实时两个分支availability任意通常为 dictNone预先获取的数据提供方dataset映射可避免重复请求/data/measures/{id}/availability接口返回值类型为DataCoordinate。需要特别强调的是方法返回的DataCoordinate即使dataset_id为None也会正常返回因此调用方必须自行判断该度量在该指数下是否真的有可用数据详见第五节。三、返回对象 DataCoordinate 的结构DataCoordinate定义于 gs_quant/data/coordinate.py其设计意图是精确定位一条时序数据点A coordinate which locates a given datapoint through timeclass DataCoordinate(BaseDataCoordinate): __slots__ [__dataset_id, __frequency, __id] def __init__( self, measure: Union[DataMeasure, str], dataset_id: Optional[str] None, dimensions: Optional[DataDimensions] None, frequency: Optional[DataFrequency] None, ): super().__init__(measure, dimensions) self.__dataset_id dataset_id self.__frequency frequency self.__id str(uuid.uuid4())一个坐标对象包含四个关键信息dataset_id唯一标识 Marquee 上的数据集measure要聚合查询的数值字段dimensions用于唯一定位记录的维度字典键值对frequency日频或实时。文档字符串中还强调了一个重要特性——不可变性immutable与可比较性DataCoordinate重写了__eq__比较 dataset_id、measure、dimensions 三者是否一致与__hash__因此多个坐标可以直接用于集合、去重与相等性判断这在批量构建查询时非常实用。坐标对象还提供了两个高频方法get_series(start, end, dates, operator)按坐标直接拉取时序内部会实例化Dataset(self.dataset_id)并调用get_dataget_range(start, end)当未显式给出起止时间时自动回退到DataContext.current的start_date/end_date日频或start_time/end_time实时。四、底层实现原理维度注入与数据集解析4.1 自动注入实体维度键方法的第一步是取出实体的 Marquee ID 并注入维度id_ self.get_marquee_id() dimensions dimensions or {} dimensions[self.data_dimension] id_这里的data_dimension是Asset基类提供的只读属性在 gs_quant/markets/securities.py 中定义为property def data_dimension(self) - str: return assetId也就是说对于任何指数乃至所有Asset子类调用方无需手动指定assetId方法会自动把当前指数的 Marquee ID 填充到assetId维度上。这正是get_data_coordinate使用体验简洁的关键所在——调用方只需关心度量与额外维度。4.2 通过数据提供方映射解析数据集 ID随后方法通过GsDataApi.get_data_providers(id_, availability)查询该实体在某度量下可用的数据集available: dict GsDataApi.get_data_providers(id_, availability).get(measure, {})availability参数的存在是为了性能优化如果调用方已经拥有或已缓存该实体的数据提供方信息可以直接传入避免重复的 HTTP 往返。这一模式在 gs_quant/analytics/datagrid/datagrid.py 中有完整体现——Datagrid 在解析查询坐标时会先用缓存或GET /data/measures/{entity_id}/availability获取提供方信息再调用get_data_coordinateraw_availability: dict GsSession.current.sync.get(f/data/measures/{entity_id}/availability) ... query.coordinate entity.get_data_coordinate( measurecoord.measure, dimensionscoord.dimensions, frequencycoord.frequency, availabilityraw_availability, )从源码结构可以推断get_data_providers返回的是形如{measure: {DataFrequency.DAILY: dataset_id, DataFrequency.REAL_TIME: dataset_id, ...}}的嵌套映射get_data_coordinate据此按频率分支取出对应数据集 ID与 measure、dimensions 一起构造DataCoordinate。五、返回值判空调用方必须处理的两类异常由于方法在数据集缺失时并不会抛异常而是照常返回坐标对象调用方需要显式校验。Asset.get_data_series在 gs_quant/markets/securities.py 中给出了标准处理范式coordinate self.get_data_coordinate(measure, dimensions, frequency) if coordinate is None: raise MqValueError(fNo data coordinate found for parameters: {measure, dimensions, frequency}) elif coordinate.dataset_id is None: raise MqValueError(fMeasure {measure.value} not found for asset: {self.__id}) return coordinate.get_series(startstart, endend, datesdates, operatoroperator)当get_data_coordinate本身返回None理论上仅当频率不在DAILY/REAL_TIME分支时→ 报未找到坐标当坐标对象存在但dataset_id is None该指数不支持该度量→ 报该资产的度量不存在。get_latest_close_price也有同样的判空逻辑见 gs_quant/markets/securities.py。因此在实际业务代码中引用get_data_coordinate的返回值时务必先判断dataset_id是否为空再调用get_series。六、典型调用链与应用场景6.1 通过 Index 获取收盘价时序标准用法是先取实体再取坐标最后取数据from gs_quant.markets.index import Index from gs_quant.markets.securities import AssetIdentifier from gs_quant.data import DataMeasure from gs_quant.data.coordinate import DataFrequency # 1. 获取指数实体以 Marquee ID 为例 index Index.get(MA4B66MW5E27U8P32SB, AssetIdentifier.MARQUEE_ID) # 2. 获取日频收盘价坐标 coordinate index.get_data_coordinate(DataMeasure.CLOSE_PRICE, frequencyDataFrequency.DAILY) print(coordinate) # Dataset Id: (...) Measure: (closePrice) Dimensions: ({assetId: ...}) # 3. 校验后拉取时序 if coordinate is not None and coordinate.dataset_id is not None: series coordinate.get_series()6.2 在 get_data_series 内部的隐藏调用get_data_coordinate是get_data_series的第一环用户日常使用的Index.get_data_series、Index.get_close_prices、Index.get_close_price_for_date最终都会经由它解析坐标。相关方法在 gs_quant/markets/index.py 中均继承自Asset/SecMasterAsset实现位于 gs_quant/markets/securities.py 与 gs_quant/markets/securities.py后者还会额外校验数据范围并套用PricingContext。6.3 在风险模型与报告中的直接调用仓库中也能看到该方法的直接使用者gs_quant/models/risk_model.py 中通过security.get_data_coordinate(DataMeasure.SPOT_PRICE)获取现货价格坐标用于风险模型相关的数据对齐gs_quant/timeseries/measures_reports.py 中多处如spot_data_coordinate security.get_data_coordinate(DataMeasure.SPOT_PRICE)在报告计算时复用坐标。6.4 在 Datagrid 中的批量解析在 gs_quant/analytics/datagrid/datagrid.py 中Datagrid 对每个查询坐标执行用户已提供数据集则直接补维度、否则查 availability 后调get_data_coordinate的策略体现出该方法在分析工作流中的通用性它既服务于单条时序也服务于批量数据网格的坐标解析。七、使用注意事项与最佳实践频率支持有限从源码看get_data_coordinate的解析分支仅覆盖DataFrequency.DAILY与DataFrequency.REAL_TIME如需周频、月频等更高层聚合应通过get_series的operator如DataAggregationOperator.LAST或Dataset的bucketize等后续处理实现。维度自动合并传入的dimensions会与自动注入的assetId合并因此不需要也不应手动传入assetId否则会因dimensions[self.data_dimension] id_被覆盖。判空是硬性要求dataset_id is None不代表失败而是该指数在该度量上无数据务必像get_data_series那样显式校验。利用 availability 缓存在批量场景如 Datagrid中先通过/data/measures/{entity_id}/availability拉取一次映射并复用可显著减少接口调用次数。坐标可比较可哈希DataCoordinate实现了基于dataset_id, measure, dimensions的相等性与哈希适合在查询合并、去重场景中使用。八、延伸阅读Index 类 API 文档 与 Index.get_data_series 文档DataCoordinate 数据结构文档若存在与 Dataset API 文档数据度量全集可查阅 Fields/DataMeasure 文档 与 gs_quant/data/fields.py完整数据访问指南见 docs/data.rst【免费下载链接】gs-quantPython toolkit for quantitative finance项目地址: https://gitcode.com/GitHub_Trending/gs/gs-quant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
gs-quant 指数数据坐标全解析深入 Index.get_data_coordinate 的定位原理与实战用法【免费下载链接】gs-quantPython toolkit for quantitative finance项目地址: https://gitcode.com/GitHub_Trending/gs/gs-quant导读在 gs-quant 中Index.get_data_coordinate是连接指数实体与Marquee 数据平台时序数据之间的关键桥梁它把一个可读的度量如收盘价翻译成一个携带数据集 ID、维度键值与频率信息的DataCoordinate对象从而唯一锁定一条时序。本文以 gs_quant.markets.index.Index.get_data_coordinate 的 API 文档 为骨架结合仓库源码逐步拆解其参数语义、底层实现与典型调用链帮助你在因子研究、风险分析与 Datagrid 查询中正确、高效地使用这一方法。一、方法与文档定位该方法的官方文档由 Sphinx 的automethod指令自动生成文档正文的核心实体是gs_quant.markets.index模块下的Index类方法.. currentmodule:: gs_quant.markets.index .. automethod:: Index.get_data_coordinateIndex类定义于 gs_quant/markets/index.py其类注释将其描述为追踪一个不断演化的证券组合、可通过现金或衍生品市场进行交易的指数并支持 STS 指数class Index(Asset, PositionedEntity): Index which tracks an evolving portfolio of securities, and can be traded through cash or derivatives markets. Includes support for STS indices. Index继承自Asset与PositionedEntity因此它天然继承了资产类通用的数据访问能力get_data_coordinate正是其中被高频复用的底层方法。二、方法签名与参数语义get_data_coordinate的完整实现位于 gs_quant/entities/entity.pydef get_data_coordinate( self, measure: Union[DataMeasure, str], dimensions: Optional[DataDimensions] None, frequency: DataFrequency DataFrequency.DAILY, availabilityNone, ) - DataCoordinate: id_ self.get_marquee_id() dimensions dimensions or {} dimensions[self.data_dimension] id_ measure measure if isinstance(measure, str) else measure.value available: dict GsDataApi.get_data_providers(id_, availability).get(measure, {}) if frequency DataFrequency.DAILY: daily_dataset_id available.get(DataFrequency.DAILY) return DataCoordinate( dataset_iddaily_dataset_id, measuremeasure, dimensionsdimensions, frequencyfrequency ) if frequency DataFrequency.REAL_TIME: rt_dataset_id available.get(DataFrequency.REAL_TIME) return DataCoordinate(dataset_idrt_dataset_id, measuremeasure, dimensionsdimensions, frequencyfrequency)四个核心参数说明如下参数类型默认值含义与约束measureUnion[DataMeasure, str]必填要查询的数据度量如DataMeasure.CLOSE_PRICE既可直接传枚举也可传字符串方法内部会统一转换为字符串形式dimensionsOptional[DataDimensions]None额外的维度字典如 tenor、currency 等为None时自动初始化为空字典frequencyDataFrequencyDataFrequency.DAILY数据频率目前实现仅显式支持DAILY日频与REAL_TIME实时两个分支availability任意通常为 dictNone预先获取的数据提供方dataset映射可避免重复请求/data/measures/{id}/availability接口返回值类型为DataCoordinate。需要特别强调的是方法返回的DataCoordinate即使dataset_id为None也会正常返回因此调用方必须自行判断该度量在该指数下是否真的有可用数据详见第五节。三、返回对象 DataCoordinate 的结构DataCoordinate定义于 gs_quant/data/coordinate.py其设计意图是精确定位一条时序数据点A coordinate which locates a given datapoint through timeclass DataCoordinate(BaseDataCoordinate): __slots__ [__dataset_id, __frequency, __id] def __init__( self, measure: Union[DataMeasure, str], dataset_id: Optional[str] None, dimensions: Optional[DataDimensions] None, frequency: Optional[DataFrequency] None, ): super().__init__(measure, dimensions) self.__dataset_id dataset_id self.__frequency frequency self.__id str(uuid.uuid4())一个坐标对象包含四个关键信息dataset_id唯一标识 Marquee 上的数据集measure要聚合查询的数值字段dimensions用于唯一定位记录的维度字典键值对frequency日频或实时。文档字符串中还强调了一个重要特性——不可变性immutable与可比较性DataCoordinate重写了__eq__比较 dataset_id、measure、dimensions 三者是否一致与__hash__因此多个坐标可以直接用于集合、去重与相等性判断这在批量构建查询时非常实用。坐标对象还提供了两个高频方法get_series(start, end, dates, operator)按坐标直接拉取时序内部会实例化Dataset(self.dataset_id)并调用get_dataget_range(start, end)当未显式给出起止时间时自动回退到DataContext.current的start_date/end_date日频或start_time/end_time实时。四、底层实现原理维度注入与数据集解析4.1 自动注入实体维度键方法的第一步是取出实体的 Marquee ID 并注入维度id_ self.get_marquee_id() dimensions dimensions or {} dimensions[self.data_dimension] id_这里的data_dimension是Asset基类提供的只读属性在 gs_quant/markets/securities.py 中定义为property def data_dimension(self) - str: return assetId也就是说对于任何指数乃至所有Asset子类调用方无需手动指定assetId方法会自动把当前指数的 Marquee ID 填充到assetId维度上。这正是get_data_coordinate使用体验简洁的关键所在——调用方只需关心度量与额外维度。4.2 通过数据提供方映射解析数据集 ID随后方法通过GsDataApi.get_data_providers(id_, availability)查询该实体在某度量下可用的数据集available: dict GsDataApi.get_data_providers(id_, availability).get(measure, {})availability参数的存在是为了性能优化如果调用方已经拥有或已缓存该实体的数据提供方信息可以直接传入避免重复的 HTTP 往返。这一模式在 gs_quant/analytics/datagrid/datagrid.py 中有完整体现——Datagrid 在解析查询坐标时会先用缓存或GET /data/measures/{entity_id}/availability获取提供方信息再调用get_data_coordinateraw_availability: dict GsSession.current.sync.get(f/data/measures/{entity_id}/availability) ... query.coordinate entity.get_data_coordinate( measurecoord.measure, dimensionscoord.dimensions, frequencycoord.frequency, availabilityraw_availability, )从源码结构可以推断get_data_providers返回的是形如{measure: {DataFrequency.DAILY: dataset_id, DataFrequency.REAL_TIME: dataset_id, ...}}的嵌套映射get_data_coordinate据此按频率分支取出对应数据集 ID与 measure、dimensions 一起构造DataCoordinate。五、返回值判空调用方必须处理的两类异常由于方法在数据集缺失时并不会抛异常而是照常返回坐标对象调用方需要显式校验。Asset.get_data_series在 gs_quant/markets/securities.py 中给出了标准处理范式coordinate self.get_data_coordinate(measure, dimensions, frequency) if coordinate is None: raise MqValueError(fNo data coordinate found for parameters: {measure, dimensions, frequency}) elif coordinate.dataset_id is None: raise MqValueError(fMeasure {measure.value} not found for asset: {self.__id}) return coordinate.get_series(startstart, endend, datesdates, operatoroperator)当get_data_coordinate本身返回None理论上仅当频率不在DAILY/REAL_TIME分支时→ 报未找到坐标当坐标对象存在但dataset_id is None该指数不支持该度量→ 报该资产的度量不存在。get_latest_close_price也有同样的判空逻辑见 gs_quant/markets/securities.py。因此在实际业务代码中引用get_data_coordinate的返回值时务必先判断dataset_id是否为空再调用get_series。六、典型调用链与应用场景6.1 通过 Index 获取收盘价时序标准用法是先取实体再取坐标最后取数据from gs_quant.markets.index import Index from gs_quant.markets.securities import AssetIdentifier from gs_quant.data import DataMeasure from gs_quant.data.coordinate import DataFrequency # 1. 获取指数实体以 Marquee ID 为例 index Index.get(MA4B66MW5E27U8P32SB, AssetIdentifier.MARQUEE_ID) # 2. 获取日频收盘价坐标 coordinate index.get_data_coordinate(DataMeasure.CLOSE_PRICE, frequencyDataFrequency.DAILY) print(coordinate) # Dataset Id: (...) Measure: (closePrice) Dimensions: ({assetId: ...}) # 3. 校验后拉取时序 if coordinate is not None and coordinate.dataset_id is not None: series coordinate.get_series()6.2 在 get_data_series 内部的隐藏调用get_data_coordinate是get_data_series的第一环用户日常使用的Index.get_data_series、Index.get_close_prices、Index.get_close_price_for_date最终都会经由它解析坐标。相关方法在 gs_quant/markets/index.py 中均继承自Asset/SecMasterAsset实现位于 gs_quant/markets/securities.py 与 gs_quant/markets/securities.py后者还会额外校验数据范围并套用PricingContext。6.3 在风险模型与报告中的直接调用仓库中也能看到该方法的直接使用者gs_quant/models/risk_model.py 中通过security.get_data_coordinate(DataMeasure.SPOT_PRICE)获取现货价格坐标用于风险模型相关的数据对齐gs_quant/timeseries/measures_reports.py 中多处如spot_data_coordinate security.get_data_coordinate(DataMeasure.SPOT_PRICE)在报告计算时复用坐标。6.4 在 Datagrid 中的批量解析在 gs_quant/analytics/datagrid/datagrid.py 中Datagrid 对每个查询坐标执行用户已提供数据集则直接补维度、否则查 availability 后调get_data_coordinate的策略体现出该方法在分析工作流中的通用性它既服务于单条时序也服务于批量数据网格的坐标解析。七、使用注意事项与最佳实践频率支持有限从源码看get_data_coordinate的解析分支仅覆盖DataFrequency.DAILY与DataFrequency.REAL_TIME如需周频、月频等更高层聚合应通过get_series的operator如DataAggregationOperator.LAST或Dataset的bucketize等后续处理实现。维度自动合并传入的dimensions会与自动注入的assetId合并因此不需要也不应手动传入assetId否则会因dimensions[self.data_dimension] id_被覆盖。判空是硬性要求dataset_id is None不代表失败而是该指数在该度量上无数据务必像get_data_series那样显式校验。利用 availability 缓存在批量场景如 Datagrid中先通过/data/measures/{entity_id}/availability拉取一次映射并复用可显著减少接口调用次数。坐标可比较可哈希DataCoordinate实现了基于dataset_id, measure, dimensions的相等性与哈希适合在查询合并、去重场景中使用。八、延伸阅读Index 类 API 文档 与 Index.get_data_series 文档DataCoordinate 数据结构文档若存在与 Dataset API 文档数据度量全集可查阅 Fields/DataMeasure 文档 与 gs_quant/data/fields.py完整数据访问指南见 docs/data.rst【免费下载链接】gs-quantPython toolkit for quantitative finance项目地址: https://gitcode.com/GitHub_Trending/gs/gs-quant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
