Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/TracingInsights/tif1/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Telemetry class is a pandas DataFrame subclass for multi-channel time series telemetry data. It provides methods for slicing, filtering, merging, and analyzing telemetry data from F1 sessions.

​
Properties

​
session

telemetry.session -> Session
Reference to the parent Session object.

​
driver

telemetry.driver -> str
Driver code for this telemetry data.

​
Telemetry Data Columns

Telemetry DataFrames typically contain:
  • Time (timedelta): Time offset from lap start
  • SessionTime (timedelta): Time offset from session start
  • Driver (str): Driver code
  • Speed (float): Speed in km/h
  • RPM (int): Engine RPM
  • nGear (int): Gear number
  • Throttle (float): Throttle position 0-100
  • Brake (bool/float): Brake status (boolean or 0-100)
  • DRS (int): DRS status
  • X, Y, Z (float): Position coordinates
  • Distance (float): Distance along track in meters
  • DistanceToDriverAhead (float): Distance to driver ahead
  • DriverAhead (str): Driver code of car ahead

​
Methods

​
fill_missing

telemetry.fill_missing() -> Telemetry
Fill missing values using interpolation. Returns: New Telemetry object with interpolated values for all numeric columns Example: 
tel = lap.telemetry
tel_filled = tel.fill_missing()

​
add_distance

telemetry.add_distance() -> Telemetry
Add Distance column by integrating speed over time. Returns: New Telemetry object with Distance column added Example: 
tel = lap.telemetry
tel_with_dist = tel.add_distance()

​
add_relative_distance

telemetry.add_relative_distance() -> Telemetry
Add RelativeDistance column (0-1 normalized distance). Returns: New Telemetry object with RelativeDistance column (0 at start, 1 at finish)

​
add_differential_distance

telemetry.add_differential_distance() -> Telemetry
Add DifferentialDistance column (distance traveled between samples). Returns: New Telemetry object with DifferentialDistance column

​
add_driver_ahead

telemetry.add_driver_ahead() -> Telemetry
Add driver-ahead channels (DriverAhead, DistanceToDriverAhead). Returns: New Telemetry object with driver-ahead columns added

​
add_track_status

telemetry.add_track_status() -> Telemetry
Add TrackStatus column (defaults to “1” if not present). Returns: New Telemetry object with TrackStatus column

​
slice_by_time

telemetry.slice_by_time(start_time, end_time, pad=0, pad_side="both", interpolate_edges=False) -> Telemetry
Slice telemetry by time range.
​
start_time
timedelta | float
required
Start time (timedelta or seconds)
​
end_time
timedelta | float
required
End time (timedelta or seconds)
​
pad
int
default:"0"
Number of samples to pad on each side
​
pad_side
Literal['both', 'before', 'after']
default:"both"
Which side to pad
​
interpolate_edges
bool
default:"False"
Whether to interpolate edge samples (reserved)
Returns: Sliced Telemetry object Example: 
import pandas as pd

tel = lap.telemetry
# Get telemetry from 5s to 15s
slice = tel.slice_by_time(pd.Timedelta(seconds=5), pd.Timedelta(seconds=15))
# Or using floats (seconds)
slice = tel.slice_by_time(5.0, 15.0)

​
slice_by_lap

telemetry.slice_by_lap(ref_laps, pad=0, pad_side="both", interpolate_edges=False) -> Telemetry
Slice telemetry by lap reference.
​
ref_laps
Lap | Laps | int
required
Lap object, Laps DataFrame, or lap number
​
pad
int
default:"0"
Number of samples to pad
​
pad_side
Literal['both', 'before', 'after']
default:"both"
Which side to pad
​
interpolate_edges
bool
default:"False"
Whether to interpolate edges
Returns: Sliced Telemetry object Example: 
laps = driver.laps
fast_laps = laps.pick_quicklaps()
tel = laps.telemetry
tel_fast = tel.slice_by_lap(fast_laps)

​
slice_by_mask

telemetry.slice_by_mask(mask, pad=0, pad_side="both") -> Telemetry
Slice telemetry using a boolean mask.
​
mask
array-like
required
Boolean mask (must match telemetry length)
​
pad
int
default:"0"
Number of samples to pad
​
pad_side
Literal['both', 'before', 'after']
default:"both"
Which side to pad
Returns: Sliced Telemetry object Example: 
tel = lap.telemetry
# Get telemetry where speed > 250 km/h
mask = tel['Speed'] > 250
high_speed = tel.slice_by_mask(mask, pad=10)

​
merge_channels

telemetry.merge_channels(other) -> Telemetry
Merge telemetry channels from another telemetry DataFrame.
​
other
Telemetry | DataFrame
required
Other telemetry data to merge
Returns: Merged Telemetry object Example: 
tel1 = lap1.telemetry
tel2 = lap2.telemetry
merged = tel1.merge_channels(tel2)

​
resample_channels

telemetry.resample_channels(rule="1S") -> Telemetry
Resample telemetry to a different frequency.
​
rule
str
default:"1S"
Resampling rule (pandas offset string, e.g., “1S” = 1 second, “100ms” = 100ms)
Returns: Resampled Telemetry object Example: 
tel = lap.telemetry
# Resample to 1 second intervals
tel_1s = tel.resample_channels("1S")
# Resample to 100ms intervals
tel_100ms = tel.resample_channels("100ms")

​
integrate_distance

telemetry.integrate_distance() -> pd.Series
Calculate cumulative distance by integrating speed. Returns: Series with cumulative distance values

​
calculate_differential_distance

telemetry.calculate_differential_distance() -> pd.Series
Calculate distance traveled between samples. Returns: Series with differential distance values

​
calculate_driver_ahead

telemetry.calculate_driver_ahead() -> tuple[pd.Series, pd.Series]
Calculate driver-ahead information. Returns: Tuple of (driver_ahead, distance_to_driver_ahead) Series

​
get_first_non_zero_time_index

telemetry.get_first_non_zero_time_index() -> int
Get index of first non-zero time value. Returns: Integer index

​
base_class_view

telemetry.base_class_view() -> pd.DataFrame
Return telemetry as plain pandas DataFrame. Returns: pandas DataFrame without Telemetry methods

​
Usage Examples

​
Basic Telemetry Access

import tif1

session = tif1.get_session(2025, "Monaco Grand Prix", "Qualifying")
driver = session.get_driver("VER")
lap = driver.get_lap(15)
tel = lap.telemetry

print(f"Telemetry samples: {len(tel)}")
print(f"Channels: {tel.columns.tolist()}")
print(f"Duration: {tel['Time'].max()}")

​
Speed Analysis

tel = lap.telemetry

if not tel.empty:
    max_speed = tel['Speed'].max()
    min_speed = tel['Speed'].min()
    avg_speed = tel['Speed'].mean()
    
    print(f"Max speed: {max_speed:.1f} km/h")
    print(f"Min speed: {min_speed:.1f} km/h")
    print(f"Average speed: {avg_speed:.1f} km/h")
    
    # Find where max speed occurred
    max_idx = tel['Speed'].idxmax()
    max_dist = tel.loc[max_idx, 'Distance']
    print(f"Max speed at {max_dist:.0f}m")

​
Throttle and Brake Analysis

tel = lap.telemetry

# Throttle application
full_throttle = (tel['Throttle'] >= 99).sum()
full_throttle_pct = full_throttle / len(tel) * 100
print(f"Full throttle: {full_throttle_pct:.1f}% of lap")

# Brake application
if 'Brake' in tel.columns:
    braking = (tel['Brake'] > 0).sum()
    braking_pct = braking / len(tel) * 100
    print(f"Braking: {braking_pct:.1f}% of lap")

# Coasting (neither throttle nor brake)
coasting = ((tel['Throttle'] < 5) & (tel['Brake'] == 0)).sum()
coasting_pct = coasting / len(tel) * 100
print(f"Coasting: {coasting_pct:.1f}% of lap")

​
Gear Usage

tel = lap.telemetry

if 'nGear' in tel.columns:
    gear_counts = tel['nGear'].value_counts().sort_index()
    print("Gear usage:")
    for gear, count in gear_counts.items():
        pct = count / len(tel) * 100
        duration = count * 0.1  # Assuming 10Hz telemetry
        print(f"  Gear {gear}: {pct:.1f}% ({duration:.1f}s)")

​
Comparing Telemetry

driver = session.get_driver("VER")
lap1 = driver.get_lap(5)
lap2 = driver.get_lap(15)

tel1 = lap1.telemetry.add_distance()
tel2 = lap2.telemetry.add_distance()

# Compare speeds at same distance
import numpy as np

for distance in [0, 1000, 2000, 3000]:
    # Find closest sample to target distance
    idx1 = (np.abs(tel1['Distance'] - distance)).idxmin()
    idx2 = (np.abs(tel2['Distance'] - distance)).idxmin()
    
    speed1 = tel1.loc[idx1, 'Speed']
    speed2 = tel2.loc[idx2, 'Speed']
    diff = speed2 - speed1
    
    print(f"At {distance}m: {speed1:.1f} vs {speed2:.1f} km/h (diff: {diff:+.1f})")

​
DRS Analysis

tel = lap.telemetry

if 'DRS' in tel.columns:
    drs_active = tel['DRS'] > 0
    drs_count = drs_active.sum()
    drs_pct = drs_count / len(tel) * 100
    
    print(f"DRS active: {drs_pct:.1f}% of lap")
    
    # Find DRS zones
    drs_changes = drs_active.astype(int).diff()
    drs_activations = (drs_changes == 1).sum()
    print(f"DRS activated {drs_activations} times")

​
Slicing Telemetry

import pandas as pd

tel = lap.telemetry

# Slice by time
tel_10_20s = tel.slice_by_time(
    pd.Timedelta(seconds=10),
    pd.Timedelta(seconds=20)
)

# Slice by condition with padding
mask = tel['Speed'] > 250
high_speed = tel.slice_by_mask(mask, pad=20, pad_side="both")

print(f"High speed samples: {len(high_speed)}")
print(f"Speed range: {high_speed['Speed'].min():.1f} - {high_speed['Speed'].max():.1f} km/h")

​
Interpolation and Resampling

tel = lap.telemetry

# Fill missing values
tel_filled = tel.fill_missing()

# Resample to 1 second intervals
tel_1s = tel_filled.resample_channels("1S")

print(f"Original samples: {len(tel)}")
print(f"Resampled samples: {len(tel_1s)}")

​
Distance Calculations

tel = lap.telemetry

# Add distance column
tel = tel.add_distance()
print(f"Total distance: {tel['Distance'].max():.0f}m")

# Add relative distance (0-1)
tel = tel.add_relative_distance()
print(f"RelativeDistance range: {tel['RelativeDistance'].min():.3f} - {tel['RelativeDistance'].max():.3f}")

# Add differential distance
tel = tel.add_differential_distance()
avg_sample_dist = tel['DifferentialDistance'].mean()
print(f"Average distance between samples: {avg_sample_dist:.2f}m")

​
Multi-Lap Telemetry

driver = session.get_driver("VER")
quick_laps = driver.laps.pick_quicklaps(1.05)

if len(quick_laps) > 0:
    tel = quick_laps.get_telemetry()
    print(f"Combined telemetry samples: {len(tel)}")
    print(f"From {len(quick_laps)} laps")
    print(f"Max speed across all laps: {tel['Speed'].max():.1f} km/h")

​
See Also

  • Session - Main session object
  • Driver - Driver-specific data
  • Lap - Single lap data
  • Laps - Collection of laps

Build docs developers (and LLMs) love

Get started for freeTalk to us