FastF1 Session 对象完全指南从获取赛道会话到加载全量数据的核心入口【免费下载链接】Fast-F1FastF1 is a python package for accessing and analyzing Formula 1 results, schedules, timing data and telemetry项目地址: https://gitcode.com/GitHub_Trending/fa/Fast-F1FastF1 是一个用于获取与分析 F1 结果、赛程、计时数据和遥测数据的 Python 包。其中Session对象是整个库的核心组成部分也是访问各类数据圈速、遥测、天气、赛道状态、比赛控制消息等的起点。本文基于仓库中 docs/api_reference/session.rst 与 fastf1/core.py 的源码实现系统讲解如何创建Session、理解其数据结构以及Session.load()背后的完整数据加载与纠错流水线帮助读者掌握用一行代码获取任何 F1 赛段全部数据的实战能力。Session 是什么一切数据的起点在 FastF1 中一个Session对象代表一场特定的比赛Race、排位赛Qualifying、冲刺赛Sprint或其他 Formula 1 赛段与该赛段相关的所有数据都可以通过它来访问。源码中类定义的第一行就点明了它的定位Object for accessing session specific data. The session class will usually be your starting point.fastf1/core.py从使用模式上看典型的 FastF1 工作流只有两步通过fastf1.get_session(...)获得Session对象调用session.load(...)将数据加载到内存之后即可通过session.laps、session.telemetry、session.results等属性访问。需要特别注意的是Session对象在被创建时并不包含任何赛段数据绝大部分数据只有在调用Session.load之后才可用。这是官方文档与源码中都反复强调的一点见 fastf1/core.py 的.. note::说明。创建 Sessionget_session 与三种数据后端Session对象通常不直接实例化而是通过 fastf1/events.py 中的fastf1.get_session()工厂函数创建import fastf1 # 按年份 分站轮次 赛段标识获取 session fastf1.get_session(2021, 1, FP2) # 2021 首站第二次练习 session fastf1.get_session(2020, Austria, Qualifying) # 按分站名 session fastf1.get_session(2021, 5, 3) # 按赛段编号get_session的完整签名来自源码 docstringyear锦标赛年份intgp分站名称str或轮次号int。传入字符串时会执行模糊匹配fuzzy match匹配参考字段包括国家、地点、名称与官方名称例如bahrain、australia、abudabi注意拼写错误也能命中、monza均会被正确解析identifier赛段名称、缩写或编号详见下文“赛段标识符”一节backend选择数据源后端可选值fastf1FastF1 自有后端完整支持 2018 年至今f1timing使用 F1 官方实时计时 API 的数据无计时数据的赛段不会被列出支持 2018 年至今ergast使用 Ergast 数据无本地时间、无 F1 计时数据可用性信息支持 1950 年至今。不指定时默认使用fastf1其余后端作为默认不可用时的回退2018 年之前的赛季始终使用ergast。exact_matchFalse时使用模糊匹配True时要求精确匹配精确匹配失败抛出KeyError模糊匹配置信度不足抛出FuzzyMatchError。测试环节里可以验证任意组合的用法例如 fastf1/tests/test_core.py 中fastf1.get_session(2023, 1, R)、fastf1.get_session(2024, Silverstone, FP1)、fastf1.get_session(2022, Saudi Arabia, R)等。此外还有两个相关入口fastf1.get_testing_session(year, test_number, session_number)创建测试赛段的Sessionfastf1/events.pyevent.get_session(identifier)从已有的Event对象上直接获取赛段fastf1/events.py。赛段标识符名称、缩写与编号get_session的identifier支持三种写法具体解析逻辑在Event.get_session_name()fastf1/events.py类型示例说明完整名称Practice 3、Qualifying大小写不敏感praCtice 1也能匹配标准缩写FP1、FP2、FP3、Q、SQ、R通过_SESSION_TYPE_ABBREVIATIONS映射表转换赛段编号1~5对应Session1~Session5列不存在则抛ValueError有一个值得注意的历史兼容细节2021、2022 年使用的赛段名Sprint Qualifying会被自动纠正为Sprint而 2024 年起Sprint Qualifying又变成了冲刺赛排位原Sprint Shootout的名称。这一命名变迁在Session构造器中也有体现详见下文。Session 的构造与基础属性Session的构造器签名为Session(event, session_name, f1_api_supportFalse)fastf1/core.py通常不直接调用但理解其初始化逻辑有助于掌握各属性的来源event关联的fastf1.events.Event对象引用name赛段名称字符串如Qualifying、Race、FP1f1_api_support布尔值表示官方 F1 API 是否支持该赛段的计时与遥测数据date赛段举办的日期UTCpandas.Datetime由event.get_session_date()得出api_path该赛段在 F1 API 中的基础路径由赛事名、赛事日期与赛段名拼接生成后续所有 API 请求都基于它。构造器还依据date.year定义了赛段类型元组用于区分后续数据处理方式_RACE_LIKE_SESSIONS2023 年及以前为(Race, Sprint, Sprint Qualifying)2024 年起为(Race, Sprint)2024 年起 “Sprint Qualifying” 不再作为比赛型赛段_QUALI_LIKE_SESSIONS2023 年及以前为(Qualifying, Sprint Shootout)2024 年起为(Qualifying, Sprint Qualifying)_PRACTICE_LIKE_SESSIONS恒为(Practice 1, Practice 2, Practice 3)。这三组分类决定了后面“结果计算”与“总圈数加载”等逻辑的走向。__repr__输出形如2021 Season Round 1: Bahrain - Race的友好描述。Session.load()按需加载全部赛段数据Session.load()是数据加载的总入口签名如下fastf1/core.pydef load(self, *, laps: bool True, telemetry: bool True, weather: bool True, messages: bool True, livedata: LiveTimingData None):四个布尔开关全部默认True即不传任何参数时加载所有可用数据。各开关的含义laps加载圈速数据与赛段状态数据session statustelemetry加载遥测数据车速、转速、位置等weather加载天气数据messages加载比赛控制Race Control消息livedata传入本地保存的实时计时数据LiveTimingData用于离线重放/调试替代 API 作为数据源。源码 docstring 明确建议通常应加载全部数据因为 FastF1 内部会混合多个端点与数据源的数据来纠正错误、补充信息某些数据缺失时这些增强功能可能无法生效此时 FastF1 会尽力返回已有数据。这在实践中意味着如果你只需要圈速仍然可以只开lapsTrue来减少请求与处理时间但需要接受少量增强功能如遥测校准的缺失。load() 的调用流程与内部顺序从 fastf1/core.py 可以看到load()的执行顺序记录日志Loading data for EventName - SessionName_load_session_info()加载赛段信息会议、赛段、国家、赛道名称及 API 使用的唯一 id 键_load_drivers_results()加载车手列表与赛段成绩见下文“多源成绩合并”一节若f1_api_support为真再按开关分别加载lapsTrue时依次执行_load_session_status_data()、_load_total_lap_count()、_load_track_status_data()、_load_laps_data()随后是两个数据修复步骤_add_first_lap_time_from_ergast()与_fix_missing_laps_retired_on_track()telemetryTrue时执行_load_telemetry()weatherTrue时执行_load_weather_data()messagesTrue时执行_load_race_control_messages()若f1_api_support为假但任一开关为真仅记录警告“该赛段不支持相关 API”无论数据源如何都会执行三个结果计算步骤_set_laps_deleted_from_rcm()、_calculate_quali_like_session_results()、_calculate_race_like_session_results()、_calculate_practice_like_session_results()。几乎所有内部加载方法都用soft_exceptions装饰器包裹单项数据失败不会让整个load()崩溃而是记录错误日志后继续。例如api.SessionNotAvailableError时遥测加载会返回空字典并警告Car telemetry data is unavailable!。加载失败时的保护DataNotLoadedErrorSession的每个数据属性都经由_get_property_warn_not_loaded()fastf1/core.py取值如果对应私有属性尚未被load()设置会抛出fastf1.exceptions.DataNotLoadedError提示信息为The data you are trying to access has not been loaded yet. See Session.load。这是 FastF1 在 API 设计上保证用户不会在未加载状态下静默拿到空数据的机制。通过 Session 访问的核心数据属性Session暴露的属性覆盖了 F1 赛段几乎全部数据维度下面按属性逐个说明其含义与可用前提均为load()之后才可访问标注了对应的加载开关。赛段基本信息session_infodict会议、赛段、国家、赛道名称及 id 键id 键是 F1 API 使用的唯一标识对应实时计时 API 的 SessionInfo 端点。driverslist[str]参加本赛段的全部车手元素为车手号码字符串实现上取自results[DriverNumber].unique()。resultsSessionResults赛段成绩及车手信息。total_lapsint比赛型赛段Race、Sprint的原定圈数非比赛型赛段或数据不可用时为None。仅在lapsTrue时可用。圈速与时序数据需lapsTruelapsLaps本赛段所有车手的全部圈速。Laps是 pandas DataFrame 的子类fastf1/core.py额外提供pick_drivers()、pick_fastest()、pick_accurate()、split_qualifying_sessions()等便捷方法。session_statusDataFrame赛段状态Started / Aborted / Finished 等随时间的记录来源为fastf1.api.session_status_data。track_statusDataFrame赛道状态绿旗、黄旗、安全车等随时间的变化。session_start_timeTimedelta依据赛段状态数据得到的实际开始时刻——注意这不是赛段计划开始时间遥测数据需telemetryTruecar_datadict按车手号码字符串索引的车辆遥测字典Speed、RPM 等值为Telemetry实例。pos_datadict按车手号码索引的位置遥测字典坐标、是否在赛道上。t0_dateTimestamp数据流开始的时间戳即赛段时间为 0 的时刻是后续计算LapStartDate与SessionTime的基准偏移。其计算逻辑_calculate_t0_datefastf1/core.py取所有车手数据中Date - Time的最大值即“延迟最小的那个时间戳”作为基准并四舍五入到毫秒。其他weather_dataDataFrame天气数据需weatherTrue每个数据通道为一行数据通道说明见fastf1.api.weather_data。race_control_messagesDataFrame比赛控制消息需messagesTrue如赛道限制、处罚、红旗等广播消息。方法速览get_driver 与 get_circuit_info除数据属性外Session还提供两个高频方法get_driver(identifier)fastf1/core.py接受车手三字母缩写如VER或车手号码字符串返回该车手的DriverResult行无匹配时抛出ValueError。get_circuit_info()fastf1/core.py返回赛道的CircuitInfo包含弯角位置、信号灯、旗语区段与赛道图旋转角度等信息适合用于可视化标注。注意这些数据为手工整理精度有限实现中还会处理 Mugello 的特殊 circuit key 修正并用laps.pick_fastest()作为参考圈添加标记物距离。数据加工流水线load() 背后做了什么Session.load()并不是简单地抓取 API 数据它内部完成了一系列数据清洗、交叉验证与推算这是 FastF1 数据质量的关键也解释了为何官方建议加载全量数据。多源成绩合并F1 API 与 Ergast 的交叉印证_load_drivers_results()fastf1/core.py会同时尝试从 F1 API 与 Ergast 两个数据源加载车手信息与成绩然后按下述规则合并F1 API 的车手信息作为主数据源Ergast 仅在其不可用时作为回退成绩结果优先使用 Ergast 数据F1 API 不可用时回退到 Ergast两个源都有数据时用共享列Abbreviation、FirstName、LastName、TeamName、FullName、DriverNumber做 join对于练习赛与冲刺排位赛Ergast 车手列表被认为不够准确因此采用left连接而比赛与排位赛采用outer连接并补齐 DNSdid not start未起步车手信息同时将Position/GridPosition置为 NaN 以突出 DNS 状态存在重复索引时记录警告。圈速数据的重建与纠错_load_laps_data()fastf1/core.py是处理量最大的部分它把原始计时数据与 timing app 数据含轮胎 compound、stint 信息按时间做merge_asof合并并完成一系列修正轮胎数据修正__fix_tyre_info针对源数据中轮胎消息时间戳堆积GH#863、stint 计数器错误递增GH#715、GH#742以及延迟发送的轮胎修正消息分别做时间戳重排、stint 重编号与逐字段迭代修正圈开始时间推导将上一圈的Time作为下一圈的LapStartTime比赛型赛段首圈假设从session_start_time开始红旗Aborted后重启的那一圈会依据赛道状态序列专门修正其起圈时间缺失时回退到PitOutTime轮胎寿命累加对每个 stint 内的轮胎寿命TyreLife从 1 开始累加Stint从 1 开始计数位置推算比赛型赛段中每圈按完成时间排序生成Position列速度陷阱值前向填充修复 API 因连续相同值跳变导致的SpeedI1/SpeedI2/SpeedST/SpeedFL缺失GH#775列重命名与补全Driver→DriverNumber、NumberOfLaps→LapNumber、New→FreshTyre并按车手号码映射补充Team与Driver缩写列。边界情况处理撞车、退赛与第一圈load()的 docstring 与源码共同定义了若干边界情况的处理策略赛中退赛如果车手最后一圈既非 inlap进站圈且随后赛段被中止会为车手补一条末圈Time设为赛段中止时刻首圈撞车比赛中若车手未完成至少一个计时圈会补一条最小信息圈其LapStartTime设为赛段开始时间Time设为第一名车手完成首圈的时刻_fix_missing_laps_retired_on_track()fastf1/core.py进一步细化优先用遥测中车速首次归零的时刻加 5 秒余量作为退赛圈结束时间无法获取时回退到“赛段中止时间”或“参考时间 150 秒”的保守估计并统一标记FastF1GeneratedTrue、IsAccurateFalse。成绩推算排位赛、练习赛与比赛当官方成绩缺失时例如较新的赛季 Ergast 尚未收录Session会基于圈速自行推算排位赛型_calculate_quali_like_session_resultsfastf1/core.py用pick_accurate().split_qualifying_sessions()将圈速切分为 Q1/Q2/Q3 三段取每段最快圈生成Q1/Q2/Q3列按 Q3、Q2、Q1 排序得到Position此外还会应用107% 规则——Q1 成绩超过最快 Q1 的 1.07 倍且未进入 Q2 的车手被标记为ClassifiedPosition N未分类。若Deleted列不是布尔类型即未加载比赛控制消息会警告无法正确计算。练习赛型_calculate_practice_like_session_resultsfastf1/core.py按车手取有效最快圈生成Time与Position。比赛型_calculate_race_like_session_resultsfastf1/core.py取每位车手的最后一圈按完成圈数降序、完成时间升序排序生成位置docstring 特别提醒 DNF 车手的排序仅供参考FIA 并不认为他们有完赛名次。圈速准确性校验IsAccurate_check_lap_accuracy()fastf1/core.py对每圈执行四重校验基础完整性无进站时间、非生成圈、赛道状态仅为绿/黄旗1/2/12/21、三段时间与圈速均非空三段计时段之和与整圈时间几乎相等容差 3ms前一圈非安全车圈TrackStatus ! 4相邻两圈的时间差与圈速一致容差 3ms。全部通过则IsAccurateTrue否则False某车手全部圈速校验失败时默认全部标记为不准确并记录警告。在使用pick_accurate()过滤数据前建议先理解这一指标的含义。圈速删除标记解析比赛控制消息_set_laps_deleted_from_rcm()fastf1/core.py通过正则解析比赛控制消息中的删除/恢复记录如CAR 44 ... TIME 1:12.345 DELETED - ...为被删除的圈设置DeletedTrue、IsPersonalBestFalse并记录DeletedReason。它还会做一次“预扫描”以跳过后来被恢复REINSTATED的圈避免需要保留圈速状态而引入复杂性。这也是前文排位赛/比赛成绩推算能排除无效圈速的前提。一个完整的实战示例综合以上内容一个典型的完整数据访问流程如下import fastf1 # 1. 获取 2023 年巴林站正赛的 Session 对象 session fastf1.get_session(2023, 1, R) # 2. 加载全部数据laps/telemetry/weather/messages 均默认开启 session.load() # 3. 访问各类数据 print(session.event[EventName]) # 分站名称 print(session.name) # 赛段名称如 Race print(session.drivers) # 车手号码列表 print(session.total_laps) # 原定总圈数 print(session.session_status) # 赛段状态序列 print(session.track_status) # 赛道状态序列 print(session.race_control_messages) # 比赛控制消息 # 4. 圈速分析维斯塔潘的最快圈 fastest_ver session.laps.pick_drivers(VER).pick_fastest() print(fastest_ver[LapTime]) # 5. 遥测分析最快圈的车速序列 tel fastest_ver.get_car_data() print(tel[Speed].describe()) # 6. 精确/按需加载仅加载圈速跳过遥测与天气 session_min fastf1.get_session(2023, 1, Q) session_min.load(telemetryFalse, weatherFalse, messagesFalse)上述用法与仓库测试代码fastf1/tests/test_core.py中的模式一致session.load(telemetryFalse, weatherFalse)是测试中常见的精简加载方式适用于不需要遥测和天气的分析场景。小结Session是 FastF1 中承上启下的核心对象向上通过get_session与事件体系Event衔接向下串联起圈速、遥测、天气、赛道状态、比赛控制消息与成绩等多维数据。其load()方法不只是简单的数据拉取而是一条包含多源交叉验证、边界情况修补、107% 规则、删除圈解析与准确性校验的完整数据加工流水线。理解Session的构造、属性与加载顺序是高效、正确地使用 FastF1 进行 F1 数据分析的基础。如需深入了解各属性的底层 API可继续阅读 docs/api_reference/loading_data.rst、docs/api_reference/telemetry.rst 与 docs/api_reference/timing_data.rst类与方法的完整 API 列表见 docs/api_reference/index.rst。【免费下载链接】Fast-F1FastF1 is a python package for accessing and analyzing Formula 1 results, schedules, timing data and telemetry项目地址: https://gitcode.com/GitHub_Trending/fa/Fast-F1创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 FastF1 Session 对象完全指南：从获取赛道会话到加载全量数据的核心入口
FastF1 Session 对象完全指南从获取赛道会话到加载全量数据的核心入口【免费下载链接】Fast-F1FastF1 is a python package for accessing and analyzing Formula 1 results, schedules, timing data and telemetry项目地址: https://gitcode.com/GitHub_Trending/fa/Fast-F1FastF1 是一个用于获取与分析 F1 结果、赛程、计时数据和遥测数据的 Python 包。其中Session对象是整个库的核心组成部分也是访问各类数据圈速、遥测、天气、赛道状态、比赛控制消息等的起点。本文基于仓库中 docs/api_reference/session.rst 与 fastf1/core.py 的源码实现系统讲解如何创建Session、理解其数据结构以及Session.load()背后的完整数据加载与纠错流水线帮助读者掌握用一行代码获取任何 F1 赛段全部数据的实战能力。Session 是什么一切数据的起点在 FastF1 中一个Session对象代表一场特定的比赛Race、排位赛Qualifying、冲刺赛Sprint或其他 Formula 1 赛段与该赛段相关的所有数据都可以通过它来访问。源码中类定义的第一行就点明了它的定位Object for accessing session specific data. The session class will usually be your starting point.fastf1/core.py从使用模式上看典型的 FastF1 工作流只有两步通过fastf1.get_session(...)获得Session对象调用session.load(...)将数据加载到内存之后即可通过session.laps、session.telemetry、session.results等属性访问。需要特别注意的是Session对象在被创建时并不包含任何赛段数据绝大部分数据只有在调用Session.load之后才可用。这是官方文档与源码中都反复强调的一点见 fastf1/core.py 的.. note::说明。创建 Sessionget_session 与三种数据后端Session对象通常不直接实例化而是通过 fastf1/events.py 中的fastf1.get_session()工厂函数创建import fastf1 # 按年份 分站轮次 赛段标识获取 session fastf1.get_session(2021, 1, FP2) # 2021 首站第二次练习 session fastf1.get_session(2020, Austria, Qualifying) # 按分站名 session fastf1.get_session(2021, 5, 3) # 按赛段编号get_session的完整签名来自源码 docstringyear锦标赛年份intgp分站名称str或轮次号int。传入字符串时会执行模糊匹配fuzzy match匹配参考字段包括国家、地点、名称与官方名称例如bahrain、australia、abudabi注意拼写错误也能命中、monza均会被正确解析identifier赛段名称、缩写或编号详见下文“赛段标识符”一节backend选择数据源后端可选值fastf1FastF1 自有后端完整支持 2018 年至今f1timing使用 F1 官方实时计时 API 的数据无计时数据的赛段不会被列出支持 2018 年至今ergast使用 Ergast 数据无本地时间、无 F1 计时数据可用性信息支持 1950 年至今。不指定时默认使用fastf1其余后端作为默认不可用时的回退2018 年之前的赛季始终使用ergast。exact_matchFalse时使用模糊匹配True时要求精确匹配精确匹配失败抛出KeyError模糊匹配置信度不足抛出FuzzyMatchError。测试环节里可以验证任意组合的用法例如 fastf1/tests/test_core.py 中fastf1.get_session(2023, 1, R)、fastf1.get_session(2024, Silverstone, FP1)、fastf1.get_session(2022, Saudi Arabia, R)等。此外还有两个相关入口fastf1.get_testing_session(year, test_number, session_number)创建测试赛段的Sessionfastf1/events.pyevent.get_session(identifier)从已有的Event对象上直接获取赛段fastf1/events.py。赛段标识符名称、缩写与编号get_session的identifier支持三种写法具体解析逻辑在Event.get_session_name()fastf1/events.py类型示例说明完整名称Practice 3、Qualifying大小写不敏感praCtice 1也能匹配标准缩写FP1、FP2、FP3、Q、SQ、R通过_SESSION_TYPE_ABBREVIATIONS映射表转换赛段编号1~5对应Session1~Session5列不存在则抛ValueError有一个值得注意的历史兼容细节2021、2022 年使用的赛段名Sprint Qualifying会被自动纠正为Sprint而 2024 年起Sprint Qualifying又变成了冲刺赛排位原Sprint Shootout的名称。这一命名变迁在Session构造器中也有体现详见下文。Session 的构造与基础属性Session的构造器签名为Session(event, session_name, f1_api_supportFalse)fastf1/core.py通常不直接调用但理解其初始化逻辑有助于掌握各属性的来源event关联的fastf1.events.Event对象引用name赛段名称字符串如Qualifying、Race、FP1f1_api_support布尔值表示官方 F1 API 是否支持该赛段的计时与遥测数据date赛段举办的日期UTCpandas.Datetime由event.get_session_date()得出api_path该赛段在 F1 API 中的基础路径由赛事名、赛事日期与赛段名拼接生成后续所有 API 请求都基于它。构造器还依据date.year定义了赛段类型元组用于区分后续数据处理方式_RACE_LIKE_SESSIONS2023 年及以前为(Race, Sprint, Sprint Qualifying)2024 年起为(Race, Sprint)2024 年起 “Sprint Qualifying” 不再作为比赛型赛段_QUALI_LIKE_SESSIONS2023 年及以前为(Qualifying, Sprint Shootout)2024 年起为(Qualifying, Sprint Qualifying)_PRACTICE_LIKE_SESSIONS恒为(Practice 1, Practice 2, Practice 3)。这三组分类决定了后面“结果计算”与“总圈数加载”等逻辑的走向。__repr__输出形如2021 Season Round 1: Bahrain - Race的友好描述。Session.load()按需加载全部赛段数据Session.load()是数据加载的总入口签名如下fastf1/core.pydef load(self, *, laps: bool True, telemetry: bool True, weather: bool True, messages: bool True, livedata: LiveTimingData None):四个布尔开关全部默认True即不传任何参数时加载所有可用数据。各开关的含义laps加载圈速数据与赛段状态数据session statustelemetry加载遥测数据车速、转速、位置等weather加载天气数据messages加载比赛控制Race Control消息livedata传入本地保存的实时计时数据LiveTimingData用于离线重放/调试替代 API 作为数据源。源码 docstring 明确建议通常应加载全部数据因为 FastF1 内部会混合多个端点与数据源的数据来纠正错误、补充信息某些数据缺失时这些增强功能可能无法生效此时 FastF1 会尽力返回已有数据。这在实践中意味着如果你只需要圈速仍然可以只开lapsTrue来减少请求与处理时间但需要接受少量增强功能如遥测校准的缺失。load() 的调用流程与内部顺序从 fastf1/core.py 可以看到load()的执行顺序记录日志Loading data for EventName - SessionName_load_session_info()加载赛段信息会议、赛段、国家、赛道名称及 API 使用的唯一 id 键_load_drivers_results()加载车手列表与赛段成绩见下文“多源成绩合并”一节若f1_api_support为真再按开关分别加载lapsTrue时依次执行_load_session_status_data()、_load_total_lap_count()、_load_track_status_data()、_load_laps_data()随后是两个数据修复步骤_add_first_lap_time_from_ergast()与_fix_missing_laps_retired_on_track()telemetryTrue时执行_load_telemetry()weatherTrue时执行_load_weather_data()messagesTrue时执行_load_race_control_messages()若f1_api_support为假但任一开关为真仅记录警告“该赛段不支持相关 API”无论数据源如何都会执行三个结果计算步骤_set_laps_deleted_from_rcm()、_calculate_quali_like_session_results()、_calculate_race_like_session_results()、_calculate_practice_like_session_results()。几乎所有内部加载方法都用soft_exceptions装饰器包裹单项数据失败不会让整个load()崩溃而是记录错误日志后继续。例如api.SessionNotAvailableError时遥测加载会返回空字典并警告Car telemetry data is unavailable!。加载失败时的保护DataNotLoadedErrorSession的每个数据属性都经由_get_property_warn_not_loaded()fastf1/core.py取值如果对应私有属性尚未被load()设置会抛出fastf1.exceptions.DataNotLoadedError提示信息为The data you are trying to access has not been loaded yet. See Session.load。这是 FastF1 在 API 设计上保证用户不会在未加载状态下静默拿到空数据的机制。通过 Session 访问的核心数据属性Session暴露的属性覆盖了 F1 赛段几乎全部数据维度下面按属性逐个说明其含义与可用前提均为load()之后才可访问标注了对应的加载开关。赛段基本信息session_infodict会议、赛段、国家、赛道名称及 id 键id 键是 F1 API 使用的唯一标识对应实时计时 API 的 SessionInfo 端点。driverslist[str]参加本赛段的全部车手元素为车手号码字符串实现上取自results[DriverNumber].unique()。resultsSessionResults赛段成绩及车手信息。total_lapsint比赛型赛段Race、Sprint的原定圈数非比赛型赛段或数据不可用时为None。仅在lapsTrue时可用。圈速与时序数据需lapsTruelapsLaps本赛段所有车手的全部圈速。Laps是 pandas DataFrame 的子类fastf1/core.py额外提供pick_drivers()、pick_fastest()、pick_accurate()、split_qualifying_sessions()等便捷方法。session_statusDataFrame赛段状态Started / Aborted / Finished 等随时间的记录来源为fastf1.api.session_status_data。track_statusDataFrame赛道状态绿旗、黄旗、安全车等随时间的变化。session_start_timeTimedelta依据赛段状态数据得到的实际开始时刻——注意这不是赛段计划开始时间遥测数据需telemetryTruecar_datadict按车手号码字符串索引的车辆遥测字典Speed、RPM 等值为Telemetry实例。pos_datadict按车手号码索引的位置遥测字典坐标、是否在赛道上。t0_dateTimestamp数据流开始的时间戳即赛段时间为 0 的时刻是后续计算LapStartDate与SessionTime的基准偏移。其计算逻辑_calculate_t0_datefastf1/core.py取所有车手数据中Date - Time的最大值即“延迟最小的那个时间戳”作为基准并四舍五入到毫秒。其他weather_dataDataFrame天气数据需weatherTrue每个数据通道为一行数据通道说明见fastf1.api.weather_data。race_control_messagesDataFrame比赛控制消息需messagesTrue如赛道限制、处罚、红旗等广播消息。方法速览get_driver 与 get_circuit_info除数据属性外Session还提供两个高频方法get_driver(identifier)fastf1/core.py接受车手三字母缩写如VER或车手号码字符串返回该车手的DriverResult行无匹配时抛出ValueError。get_circuit_info()fastf1/core.py返回赛道的CircuitInfo包含弯角位置、信号灯、旗语区段与赛道图旋转角度等信息适合用于可视化标注。注意这些数据为手工整理精度有限实现中还会处理 Mugello 的特殊 circuit key 修正并用laps.pick_fastest()作为参考圈添加标记物距离。数据加工流水线load() 背后做了什么Session.load()并不是简单地抓取 API 数据它内部完成了一系列数据清洗、交叉验证与推算这是 FastF1 数据质量的关键也解释了为何官方建议加载全量数据。多源成绩合并F1 API 与 Ergast 的交叉印证_load_drivers_results()fastf1/core.py会同时尝试从 F1 API 与 Ergast 两个数据源加载车手信息与成绩然后按下述规则合并F1 API 的车手信息作为主数据源Ergast 仅在其不可用时作为回退成绩结果优先使用 Ergast 数据F1 API 不可用时回退到 Ergast两个源都有数据时用共享列Abbreviation、FirstName、LastName、TeamName、FullName、DriverNumber做 join对于练习赛与冲刺排位赛Ergast 车手列表被认为不够准确因此采用left连接而比赛与排位赛采用outer连接并补齐 DNSdid not start未起步车手信息同时将Position/GridPosition置为 NaN 以突出 DNS 状态存在重复索引时记录警告。圈速数据的重建与纠错_load_laps_data()fastf1/core.py是处理量最大的部分它把原始计时数据与 timing app 数据含轮胎 compound、stint 信息按时间做merge_asof合并并完成一系列修正轮胎数据修正__fix_tyre_info针对源数据中轮胎消息时间戳堆积GH#863、stint 计数器错误递增GH#715、GH#742以及延迟发送的轮胎修正消息分别做时间戳重排、stint 重编号与逐字段迭代修正圈开始时间推导将上一圈的Time作为下一圈的LapStartTime比赛型赛段首圈假设从session_start_time开始红旗Aborted后重启的那一圈会依据赛道状态序列专门修正其起圈时间缺失时回退到PitOutTime轮胎寿命累加对每个 stint 内的轮胎寿命TyreLife从 1 开始累加Stint从 1 开始计数位置推算比赛型赛段中每圈按完成时间排序生成Position列速度陷阱值前向填充修复 API 因连续相同值跳变导致的SpeedI1/SpeedI2/SpeedST/SpeedFL缺失GH#775列重命名与补全Driver→DriverNumber、NumberOfLaps→LapNumber、New→FreshTyre并按车手号码映射补充Team与Driver缩写列。边界情况处理撞车、退赛与第一圈load()的 docstring 与源码共同定义了若干边界情况的处理策略赛中退赛如果车手最后一圈既非 inlap进站圈且随后赛段被中止会为车手补一条末圈Time设为赛段中止时刻首圈撞车比赛中若车手未完成至少一个计时圈会补一条最小信息圈其LapStartTime设为赛段开始时间Time设为第一名车手完成首圈的时刻_fix_missing_laps_retired_on_track()fastf1/core.py进一步细化优先用遥测中车速首次归零的时刻加 5 秒余量作为退赛圈结束时间无法获取时回退到“赛段中止时间”或“参考时间 150 秒”的保守估计并统一标记FastF1GeneratedTrue、IsAccurateFalse。成绩推算排位赛、练习赛与比赛当官方成绩缺失时例如较新的赛季 Ergast 尚未收录Session会基于圈速自行推算排位赛型_calculate_quali_like_session_resultsfastf1/core.py用pick_accurate().split_qualifying_sessions()将圈速切分为 Q1/Q2/Q3 三段取每段最快圈生成Q1/Q2/Q3列按 Q3、Q2、Q1 排序得到Position此外还会应用107% 规则——Q1 成绩超过最快 Q1 的 1.07 倍且未进入 Q2 的车手被标记为ClassifiedPosition N未分类。若Deleted列不是布尔类型即未加载比赛控制消息会警告无法正确计算。练习赛型_calculate_practice_like_session_resultsfastf1/core.py按车手取有效最快圈生成Time与Position。比赛型_calculate_race_like_session_resultsfastf1/core.py取每位车手的最后一圈按完成圈数降序、完成时间升序排序生成位置docstring 特别提醒 DNF 车手的排序仅供参考FIA 并不认为他们有完赛名次。圈速准确性校验IsAccurate_check_lap_accuracy()fastf1/core.py对每圈执行四重校验基础完整性无进站时间、非生成圈、赛道状态仅为绿/黄旗1/2/12/21、三段时间与圈速均非空三段计时段之和与整圈时间几乎相等容差 3ms前一圈非安全车圈TrackStatus ! 4相邻两圈的时间差与圈速一致容差 3ms。全部通过则IsAccurateTrue否则False某车手全部圈速校验失败时默认全部标记为不准确并记录警告。在使用pick_accurate()过滤数据前建议先理解这一指标的含义。圈速删除标记解析比赛控制消息_set_laps_deleted_from_rcm()fastf1/core.py通过正则解析比赛控制消息中的删除/恢复记录如CAR 44 ... TIME 1:12.345 DELETED - ...为被删除的圈设置DeletedTrue、IsPersonalBestFalse并记录DeletedReason。它还会做一次“预扫描”以跳过后来被恢复REINSTATED的圈避免需要保留圈速状态而引入复杂性。这也是前文排位赛/比赛成绩推算能排除无效圈速的前提。一个完整的实战示例综合以上内容一个典型的完整数据访问流程如下import fastf1 # 1. 获取 2023 年巴林站正赛的 Session 对象 session fastf1.get_session(2023, 1, R) # 2. 加载全部数据laps/telemetry/weather/messages 均默认开启 session.load() # 3. 访问各类数据 print(session.event[EventName]) # 分站名称 print(session.name) # 赛段名称如 Race print(session.drivers) # 车手号码列表 print(session.total_laps) # 原定总圈数 print(session.session_status) # 赛段状态序列 print(session.track_status) # 赛道状态序列 print(session.race_control_messages) # 比赛控制消息 # 4. 圈速分析维斯塔潘的最快圈 fastest_ver session.laps.pick_drivers(VER).pick_fastest() print(fastest_ver[LapTime]) # 5. 遥测分析最快圈的车速序列 tel fastest_ver.get_car_data() print(tel[Speed].describe()) # 6. 精确/按需加载仅加载圈速跳过遥测与天气 session_min fastf1.get_session(2023, 1, Q) session_min.load(telemetryFalse, weatherFalse, messagesFalse)上述用法与仓库测试代码fastf1/tests/test_core.py中的模式一致session.load(telemetryFalse, weatherFalse)是测试中常见的精简加载方式适用于不需要遥测和天气的分析场景。小结Session是 FastF1 中承上启下的核心对象向上通过get_session与事件体系Event衔接向下串联起圈速、遥测、天气、赛道状态、比赛控制消息与成绩等多维数据。其load()方法不只是简单的数据拉取而是一条包含多源交叉验证、边界情况修补、107% 规则、删除圈解析与准确性校验的完整数据加工流水线。理解Session的构造、属性与加载顺序是高效、正确地使用 FastF1 进行 F1 数据分析的基础。如需深入了解各属性的底层 API可继续阅读 docs/api_reference/loading_data.rst、docs/api_reference/telemetry.rst 与 docs/api_reference/timing_data.rst类与方法的完整 API 列表见 docs/api_reference/index.rst。【免费下载链接】Fast-F1FastF1 is a python package for accessing and analyzing Formula 1 results, schedules, timing data and telemetry项目地址: https://gitcode.com/GitHub_Trending/fa/Fast-F1创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考