Fast-F1 计时数据分析完全指南Laps 与 Lap 对象的逐圈数据结构详解【免费下载链接】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本文基于 Fast-F1 开源仓库的官方 API 参考文档docs/api_reference/timing_data.rst结合 fastf1/core.py 源码与测试用例系统讲解逐圈计时数据Timing Data的对象模型、30 个数据列的语义与类型、数据准确性校验机制及实战筛选用法。读完本文你将能熟练读取Session.laps中的每一列准确识别被取消圈速、安全车圈、非精确数据等坑点并写出可靠的逐圈分析代码。一、计时数据在 Fast-F1 中的定位与获取方式在 Fast-F1 中计时数据Timing Data是描述某一圈发生了什么的逐圈级数据与描述某一时刻车辆状态的遥测数据Telemetry互补。它的主体由两个对象承载均在 fastf1/core.py 中定义且都位于fastf1.core模块下对象类型语义源码位置LapsBaseDataFramepandas.DataFrame 子类一整场比赛/练习赛/排位赛中所有车手的全部圈fastf1/core.py#L2851LapBaseSeriespandas.Series 子类单个车手的单圈记录fastf1/core.py#L3619数据通过Session.laps属性暴露。该属性在 fastf1/core.py#L1270-L1275 中实现本质是返回_laps内部缓存且只有在调用Session.load(lapsTrue)默认即为True之后才有数据否则会触发数据未加载警告import fastf1 session fastf1.get_session(2024, Monza, R) # 通过赛事与节次定位会话 session.load() # lapsTrue 为默认值 laps session.laps # 得到 Laps 对象关于如何加载一场会话参见 加载数据指南。从对象模型看Laps与Lap是一对多的关系Laps的每一行是一条圈记录切片出单行时返回Lap通过_constructor_sliced_horizontal指定见 fastf1/core.py#L2932-L2934多行切片、pick_*系列筛选方法则继续返回Laps保证链式调用类型不变。两个类都通过_metadata [session]携带会话上下文元数据并在join/merge时自动传播fastf1/core.py#L2955-L2981这意味着由Laps派生的任何子集仍知道它来自哪一场比赛——这正是后续按车手取色、按车队取色等绘图功能能工作的前提。二、逐圈数据列全景名称、类型与语义Laps类在 fastf1/core.py#L2882-L2914 中声明了完整的列 schema_COLUMNS与官方文档的逐圈信息表一一对应。下面按功能分组逐列说明数据类型以源码声明为准timedelta64[ns]对应文档中的pandas.Timedeltadatetime64[ns]对应pandas.Timestamp。2.1 时间与圈速核心列列名数据类型说明Timetimedelta64[ns]该圈圈速被记录的会话时间即该圈结束时刻LapTimetimedelta64[ns]记录的圈速。注意是否被取消要看Deleted列不能只看 LapTimeLapNumberfloat64记录的比赛圈号用 float 是为了容纳 NaNStintfloat64轮胎 stint赛段编号LapStartTimetimedelta64[ns]该圈开始时刻的会话时间LapStartDatedatetime64[ns]该圈开始时刻的完整时间戳跨天比赛时很有用LapStartTime与LapStartDate是 Fast-F1 自行推算并写入的派生列源码在数据对齐阶段为每一条圈记录计算圈开始时间参见_fix_missing_laps_retired_on_track等加载逻辑。其中LapStartDate还会被Session.t0_date等后续流程用来把会话时间换算成真实日期时间。2.2 车手与车队身份列列名数据类型说明Driverstr三位字母车手缩写如VER、LECDriverNumberstr车手号码以字符串存储例如1、16Teamstr车队名称注意DriverNumber是字符串类型这在按号码筛选时需要laps[laps[DriverNumber] 16]而非整数比较。2.3 进站相关列列名数据类型说明PitInTimetimedelta64[ns]赛车进入维修区的会话时间PitOutTimetimedelta64[ns]赛车驶出维修区的会话时间两列同时为 NaN 表示正常飞驰圈只有PitInTime为进站圈in-lap只有PitOutTime为出站圈out-lap。Laps.pick_wo_box()与Laps.pick_box_laps()正是基于这两列实现筛选见 fastf1/core.py#L3446-L3480。2.4 三段计时与测速点列列名数据类型说明Sector1Time / Sector2Time / Sector3Timetimedelta64[ns]三个计时段各自的记录时间Sector1SessionTime / Sector2SessionTime / Sector3SessionTimetimedelta64[ns]各段计时被记录时的会话时间SpeedI1float64第一段测速点速度 [km/h]红旗期间缺失SpeedI2float64第二段测速点速度 [km/h]红旗期间缺失SpeedFLfloat64终点线测速点速度 [km/h]红旗期间缺失进站圈也缺失SpeedSTfloat64最长直道或赛道特定高速点测速 [km/h]红旗期间缺失具体位置依赛道而定这四列测速数据在红旗Red Flag下会缺失SpeedFL在车手进站的圈也会缺失。做速度分析前应先检查空值。2.5 个人最佳与轮胎信息列列名数据类型说明IsPersonalBestbool是否为该车手的官方个人最佳圈。若某圈比个人最佳更快却被标记为 False说明该圈无效未计入典型如赛道限制违规。被取消的圈速在源码 fastf1/core.py#L1877-L1881 中同时被强制置为IsPersonalBestFalseCompoundstr赛事特定轮胎配方名SOFT、MEDIUM、HARD、INTERMEDIATE、WET、TEST_UNKNOWN、UNKNOWN。不区分底层 C1–C5 配方TEST_UNKNOWN出现在季前测试及倍耐力季中轮胎测试中TyreLifefloat64该轮胎已使用的圈数包含在其他节次中已使用的圈数即二手胎会带过来FreshTyrebool该轮胎是否为全新胎即 stint 开始时TyreLife 0源码 fastf1/core.py#L2882-L2914 对Compound、TyreLife、FreshTyre的 dtype 声明与文档一致而__fix_tyre_info等私有方法会在加载阶段对轮胎数据做补全例如轮胎数据延迟到达时的修正对应测试test_compounds_correct_after_delayed_tyre_data。测试 fastf1/tests/test_laps.py 中的test_laps_pick_compounds验证了pick_compounds()的筛选行为。2.6 赛道状态与位置列列名数据类型说明TrackStatusstr字符串形式记录了该圈期间出现的所有赛道状态编号可能多个。编号含义见fastf1.api.track_status_datafastf1/_api.py#L1257例如1绿旗、2黄旗、4安全车、6红旗等。筛选请使用Laps.pick_track_status而非手写字符串匹配Positionfloat64该圈结束时车手的名次。在 FP1/FP2/FP3、冲刺排位赛Sprint Shootout和排位赛中为 NaN撞车圈crash lap也为 NaNTrackStatus的拼接发生在_add_track_status_to_laps流程中。由于一列可能含多个状态编号如267文档明确建议用Laps.pick_track_status()筛选。该方法的五种匹配模式在 fastf1/core.py#L3415-L3444 实现测试见 fastf1/tests/test_laps.py 的test_laps_pick_track_status。2.7 圈速取消Deleted与生成圈FastF1Generated列列名数据类型说明DeletedOptional[bool]该圈是否被干事取消如赛道限制违规。仅当加载了比赛控制消息race control messages时才有此列即Session.load(messagesTrue)DeletedReasonstr取消原因文本。同样依赖比赛控制消息FastF1Generatedbool该圈是否由 Fast-F1 自行补全生成。此类圈通常信息非常有限部分信息为插值或基于合理假设。典型场景为在赛道上退赛的车手补一条不完整的最末圈IsAccuratebool该圈的起止时间是否与其他圈正确同步见下节准确性校验Deleted列并非 API 直接提供而是由Session._set_laps_deleted_from_rcmfastf1/core.py#L1832-L1881解析比赛控制消息文本得到的它用正则CAR (\d{1,2}) .* TIME (\d:\d\d\.\d\d\d) DELETED - (.*)匹配取消消息并用REINSTATED恢复消息做一次前瞻扫描把后来被恢复的圈排除在删除标记之外。对应测试为 fastf1/tests/test_core.py 的test_rcm_parsing_deleted_laps。由于该列依赖消息加载直接访问可能触发DataNotLoadedError见pick_not_deleted的抛错逻辑fastf1/core.py#L3499-L3504因此规范用法是session.load(messagesTrue)后再分析删除圈。三、IsAccurate准确性校验机制深度解读IsAccurate是 Fast-F1 数据质量体系中最关键的一列它的含义容易误解它只表示圈的开始与结束时间与其他圈正确同步不表示圈速或分段时间本身的精度。文档明确指出只要圈速和分段时间存在就认为它们自身是准确的。真正可能出错的是圈与圈之间的对齐关系。源码中的校验实现为Session._check_lap_accuracyfastf1/core.py#L2334-L2428逐车手逐圈执行四道检查全部通过才标记为IsAccurateTrue基本条件检查check_1不是进站圈也不是出站圈PitInTime/PitOutTime均为 NaN不是 Fast-F1 生成圈FastF1Generated为 False赛道状态仅限绿旗/黄旗相关编号1、2、12、21——文档所说绿旗或黄旗下设定的圈LapTime与三个分段时间均存在。分段时间求和校验check_2三段时间之和与圈速之差在3ms 容差内np.allclose(..., atol0.003, rtol0)。若不满足会另外记录为数据完整性错误并输出日志。安全车后首圈检查check_3上一圈的TrackStatus不能是4安全车。文档中的不是安全车期后的第一圈对应此处——SC/VSC 期间的数据问题可能延续到安全车结束后的第一圈。时间差一致性检查check_4本圈Time与上一圈Time之差应约等于本圈LapTime同样 3ms 容差用于验证圈与圈时间轴对齐。若某车手的所有圈都未通过校验len(is_accurate) 0源码会打日志并默认把该车手全部圈标记为不准确fastf1/core.py#L2414-L2419存在完整性错误时会额外输出Lap timing integrity check failed警告。因此IsAccurateTrue表示该圈通过了基本同步检查但并不保证绝对无误而IsAccurateFalse的圈必须谨慎处理其中可能存在不易察觉的错误。对于是否需要担心文档给出的结论是分段求和异常这类问题同时会被单独记录为数据完整性错误通常无需过度担心。日常分析的推荐姿势是用Laps.pick_accurate()fastf1/core.py#L3506-L3513一键过滤出精确圈。四、常用筛选与遍历操作实战理解了每一列的语义后Laps提供的筛选方法就能发挥威力。以下是官方文档与源码共同支持的常用操作import fastf1 session fastf1.get_session(2024, Monza, R) session.load() # 默认同时加载 lapsTrue, messagesTrue laps session.laps # 1. 按车手 最快圈 best_lec laps.pick_drivers(LEC).pick_fastest() print(best_lec[LapTime]) # Timedelta 类型 # 2. 按轮胎配方筛选自动转大写 soft_laps laps.pick_compounds([SOFT, MEDIUM, HARD]) # 等价写法laps.pick_tyre(SOFT) / laps[laps[Compound] SOFT] # 3. 按赛道状态筛选推荐勿手写字符串匹配 # how 参数equals / contains / excludes / any / none sc_laps laps.pick_track_status(4, howcontains) # 含安全车状态的圈 green_laps laps.pick_track_status(1, howequals) # 纯绿旗圈 # 4. 排除进站圈/出站圈 flying_laps laps.pick_wo_box() # PitInTime 与 PitOutTime 均为 NaN box_laps laps.pick_box_laps(both) # 进站圈或出站圈 # 5. 只保留未被干事取消的圈需要 messagesTrue valid_laps laps.pick_not_deleted() # 6. 只保留通过准确性校验的圈 accurate_laps laps.pick_accurate()pick_track_status的五种匹配模式语义源码 fastf1/core.py#L3415-L3444how 取值行为示例equals精确等于该状态status2只匹配2contains包含该状态字符串status2也能匹配267这类复合状态excludes不包含该状态字符串status26不匹配267但匹配27any对多字符状态按任意字符匹配status26同时匹配含2或含6的圈none对多字符状态按任意字符排除status26既不匹配12也不匹配16逐圈迭代可以使用Laps.iterlaps()fastf1/core.py#L3592-L3616它包装iterrows并支持require参数——只有指定列非空的行才会被产出for idx, lap in laps.iterlaps(require[LapTime, Sector1Time]): # 只会拿到拥有圈速和 S1 时间的圈 ...从测试用例看fastf1/tests/test_laps.pypick_laps、pick_drivers、pick_teams、pick_compounds、pick_track_status、split_qualifying_sessions等均有对应的行为验证使用这些 API 可以放心依赖其语义。五、数据从哪里来计时数据的加载链路理解列语义之外了解数据产生链路有助于判断哪些列天生可信、哪些列经过加工。从源码结构可以推断出如下流程原始拉取fastf1.api.timing_datafastf1/_api.py从 F1 计时服务器拉取原始圈数据与数据流stream数据返回两个 DataFrameSession._load_laps_data负责解析。对齐与派生_align_laps、_extended_timing_data等私有函数负责把各车手的圈按时间轴对齐并计算出LapStartTime、LapStartDate等派生列测试test_laps_aligned_across_drivers、test_laps_aligned_consistency覆盖该行为。补全缺失圈_fix_missing_laps_retired_on_track为在赛道上退赛的车手补一条不完整的最末圈此时FastF1GeneratedTrue_add_first_lap_time_from_ergast在极端情况下从 Ergast 回填首圈时间。赛道状态合并_add_track_status_to_laps把track_status_data按圈映射进TrackStatus列。取消圈标记_set_laps_deleted_from_rcm解析比赛控制消息写入Deleted/DeletedReason/IsPersonalBest。准确性校验_check_lap_accuracy最终写入IsAccurate。因此一个实用的经验是以Time/LapTime/分段时间为主的列最贴近原始计时数据LapStartTime、LapStartDate、TrackStatus、Deleted、IsAccurate、FastF1Generated均属于 Fast-F1 加工/推断产物分析时应对其生成规则保持敏感。参考数据文件位于 fastf1/testing/reference_data/如2020_05_FP2/timing_data.raw可用来对照真实数据形态。六、避坑清单使用逐圈数据的常见误区综合官方文档与源码实现以下几点是高频踩坑点圈速被取消 ≠ 圈速不存在LapTime仍保留数值必须检查Deleted列需要messagesTrue或IsPersonalBest。更快的圈若IsPersonalBestFalse说明该圈无效。Position在练习赛/排位赛/冲刺排位赛为 NaN不要在这些节次直接按Position排序求名次应使用排位赛结果计算逻辑_calculate_quali_like_session_results。红旗期间测速列缺失SpeedI1/SpeedI2/SpeedFL/SpeedST可能出现 NaN且SpeedFL在进站圈也缺失做统计前先dropna。Compound不区分 C1–C5只到 SOFT/MEDIUM/HARD 的粒度测试轮胎出现TEST_UNKNOWN。TrackStatus是复合字符串用pick_track_status而非判断尤其注意contains与equals的差别。不精确圈要单独处理IsAccurateFalse的圈可能存在不易察觉的时间对齐错误SC/VSC 期间及安全车后第一圈的圈速可靠性较低。生成圈信息有限FastF1GeneratedTrue的圈退赛补全圈大部分列为空或插值涉及此类圈时需谨慎。依赖消息数据的列要先加载访问Deleted相关功能前确保Session.load(messagesTrue)否则会抛DataNotLoadedError。七、小结Laps/Lap是 Fast-F1 逐圈数据分析的基石文档与源码共同定义的 30 个列覆盖了圈速、分段、测速、进站、轮胎、赛道状态、名次与数据质量标记等全部维度IsAccurate校验机制与Deleted/FastF1Generated标记构成了数据质量保障体系pick_*系列方法则提供了声明式的筛选接口。结合 docs/api_reference/timing_data.rst 的列说明表与 fastf1/core.py 的 schema 定义你可以将这些语义准确映射到自己的分析代码中从而写出既高效又不易出错的 F1 数据管线。若需进一步了解计时数据的下游消费方式如按圈截取遥测、绘制圈速对比图可继续阅读 遥测数据参考 与 绘图数据参考。【免费下载链接】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），仅供参考