Skip to main content
This document explains how data moves through tif1, from the first CDN request to the final DataFrame delivery. It covers caching mechanisms, network protocols, data transformations, and performance optimizations. These details help with performance tuning, troubleshooting, and data loading decisions. tif1 treats performance as its core principle. The multi-tier caching system, HTTP/2 multiplexing, and async parallel fetching all minimize latency and maximize throughput. Each section explains what happens, why it happens, and how to use these systems.

System Architecture Overview

The tif1 architecture follows three core principles:
  1. Performance First: Every component is optimized for speed, from HTTP/2 multiplexing to orjson parsing to categorical data types.
  2. Resilience: Multi-tier caching, circuit breakers, and retry logic ensure reliability even under adverse network conditions.
  3. Transparency: Logging and monitoring show what happens at each stage.

High-Level Architecture Diagram

A session with no cached data skips the cache reads (ultra_cold_start, on by default). It also fetches each payload with a single attempt per CDN (ultra_cold_skip_retries). The fetched payloads still go to the cache, so the next load is warm.

Component Responsibilities

Session Object (core.py)
  • Entry point for all data access
  • Manages lazy loading of laps, telemetry, weather, and race control data
  • Coordinates between cache layers and CDN fetching
  • Handles backend selection (pandas vs polars)
Memory LRU Cache (cache.py)
  • In-memory LRUCache built on collections.OrderedDict
  • Stores raw JSON bytes plus a parsed-object front tier (not DataFrames)
  • DataFrames live in the per-session SessionMemo and the backend lap LRU (get_backend_lap_cache)
  • Default capacity: 1024 JSON payloads (TIF1_MEMORY_CACHE_MAX_ITEMS) and 2048 telemetry payloads (TIF1_MEMORY_TELEMETRY_CACHE_MAX_ITEMS)
  • Eviction policy: Least Recently Used (LRU)
  • Lifetime: Process duration only
SQLite Persistent Cache (cache.py)
  • Disk-based cache using SQLite database
  • Location: OS-dependent tif1 cache directory (configurable via TIF1_CACHE_DIR); see the platform defaults in the configuration reference
  • Stores JSON payloads (compressed when 4096 bytes or larger) and pickled laps and telemetry frames
  • Tables: cache, telemetry_cache, laps_frames, laps_frames_pl, telemetry_frames, telemetry_frames_pl, missing_payloads
  • No expiry: entries persist until clear() or invalidate()
  • Only negative “missing on every CDN” verdicts expire, after 7 days
  • Thread-safe: one shared connection guarded by a lock, WAL journal mode
CDN Manager (cdn.py)
  • Manages multiple CDN sources with automatic fallback
  • Primary: jsDelivr CDN (cdn.jsdelivr.net/gh/TracingInsights/{year}@main)
  • Fallback: Hugging Face buckets (huggingface.co/buckets/tracinginsights/{year}/resolve)
  • Backup: StaticDelivr CDN (cdn.staticdelivr.com/gh/TracingInsights/{year}/main)
  • Tracks failure counts per CDN source
  • Automatically disables failing sources after 3 consecutive failures
  • A 404 from one CDN falls through to the next, because mirrors can be stale
  • A 403 from one CDN also falls through. jsDelivr answers 403 (“Package size exceeded the configured limit of 50 MB”) for a file its edge has not cached yet
  • A 403 or 404 says nothing about the health of the mirror, so it does not count towards disabling it
  • tif1 raises DataNotFoundError when every CDN refuses the file with a 4xx error other than 408 or 429 (404 and 403 included)
  • A 408 or 429 means “try again later”, so it keeps the retryable NetworkError. tif1 does not record it as a missing payload
  • Requests for files missing everywhere never burn the retry/backoff budget
  • 5xx and transport errors keep the retryable NetworkError
  • Handles URL encoding and path construction
  • Never uses raw.githubusercontent.com for session data (strict rate limits)
  • The only raw GitHub request is schedule_{year}.json of a live season in events.py, cached for schedule_ttl_hours
Async HTTP Fetcher (async_fetch.py)
  • Parallel HTTP requests using niquests (HTTP/2 support)
  • Connection pooling and keep-alive
  • Retries a payload with exponential backoff when every CDN fails
  • Timeout management (default: 30s per request)
  • Concurrency cap: max_concurrent_requests (default 22)
Circuit Breaker (retry.py)
  • Prevents cascading failures during network issues
  • States: "closed" (normal), "open" (failing), "half-open" (testing recovery)
  • Failure threshold: 5 consecutive failures
  • Recovery timeout: 60 seconds
  • Automatic state transitions
JSON Parser (orjson)
  • High-performance JSON parsing (3x to 7x faster than stdlib json on tif1 payloads)
  • Direct bytes-to-Python object conversion
Schema Validator (validation.py)
  • Pydantic-based validation of JSON structure (off by default; turn it on with the validate_data, validate_lap_times, and validate_telemetry config keys)
  • Ensures data integrity before DataFrame construction
  • Type coercion and default value handling
  • Detailed error messages for debugging
DataFrame Constructor (core.py / core_utils)
  • Converts the columnar JSON payloads (one list per field) to pandas/polars DataFrames
  • Renames the short upstream keys (time, s1, sesT, wAT, …) to FastF1 names
  • Example: s1 becomes Sector1Time, and wAT becomes AirTemp
  • Column order follows FastF1, plus the tif1 columns at the end
  • pandas laps keep a RangeIndex (no LapNumber index)
Data Enrichment (core.py)
  • Adds the computed LapTimeSeconds column (float seconds on both backends)
  • Keeps the per-lap weather fields of the payload as WeatherTime, AirTemp, …, WindSpeed
  • Takes Stint, IsPersonalBest, and DriverNumber from the payload as delivered
  • Takes Driver and Team from drivers.json; the payload keys drv and team stay as extra columns
Type Optimizer (core_utils/helpers.py)
  • Applies the dtype contract of each backend (see Column types by backend)
  • pandas: converts time columns to timedelta64[ns] and Driver, Team, Compound, TrackStatus to category
  • polars: converts time columns to Duration("ns"), LapStartDate to Datetime("ns"), and keeps text columns as String
  • Replaces sentinel strings such as "None" with missing values; numeric columns stay 64-bit (no float32 downcast)

Complete Data Loading Pipeline

The data loading pipeline consists of eight distinct stages. Each stage has specific responsibilities and performance characteristics. These details help with code optimization and troubleshooting.

Stage 1: Request Initiation

When code accesses data through a Session object, tif1 initiates the loading pipeline. This stage involves property access, lazy evaluation, and request routing.
What Happens Internally:
  1. Property access runs the Session.laps property
  2. Session checks if data is already loaded (self._laps is not None)
  3. If not loaded, the property checks the process-wide backend lap LRU under the key f"{year}_{gp}_{session}_laps"
  4. On a miss, the property runs Session.laps_async() (public, for async code) with asyncio.run()
  5. laps_async() checks the SQLite laps frame tier, then loads drivers.json, f"{year}/{gp}/{session}/session_laptimes.json" and the requested weather.json / rcm.json in one concurrent wave through the cache layer
Performance Characteristics:
  • A repeated session.laps access returns the stored frame in about 1 µs
  • No network I/O at this stage
Configuration Options:

Stage 2: Multi-Tier Cache Lookup

The JSON payloads have a two-tier cache: memory and SQLite. The built DataFrames have their own tiers: the per-session memo, the process-wide backend lap LRU (100 sessions per backend), and the SQLite frame tables. This section explains the payload tiers first.

Tier 1: Memory LRU Cache (L1 Cache)

The memory cache is the fastest tier, holding raw JSON payloads and their parsed objects in RAM. Technical Specifications:
  • Implementation: LRUCache built on collections.OrderedDict (cache.py)
  • Storage: In-process memory (heap)
  • Data format: orjson bytes, plus a parsed-dict front tier that skips re-parsing on repeat hits
  • DataFrames: held only by the per-session SessionMemo, the backend lap LRU, and the SQLite frame tier
  • Capacity: 1024 JSON payloads (TIF1_MEMORY_CACHE_MAX_ITEMS), 2048 telemetry payloads (TIF1_MEMORY_TELEMETRY_CACHE_MAX_ITEMS)
  • Eviction: Least Recently Used (LRU) algorithm, maintained through writes only
  • Access time: about 3 µs for a parsed hit (measured on a 343 KB payload)
  • Thread safety: LRUCache.set takes a lock; hot-path reads are lock-free
  • Persistence: None (cleared on process exit)
Cache Key Structure:
Memory Usage Estimation:
Cache Hit Rate Optimization:

Tier 2: SQLite Persistent Cache (L2 Cache)

The SQLite cache provides persistent storage that survives process restarts. Technical Specifications:
  • Implementation: sqlite3 with one shared connection (check_same_thread=False)
  • Storage: Disk-based database file (cache.sqlite)
  • Location: OS-dependent tif1 cache directory (configurable via TIF1_CACHE_DIR); see the platform defaults in the configuration reference
  • Data format: Compressed JSON (zstd level 1; legacy zlib rows stay readable). Python 3.14+ uses the standard-library compression.zstd binding, 3.11-3.13 use the zstandard package; both write identical frames
  • Capacity: Unlimited (constrained by disk space)
  • Access time: about 2 ms to read, decompress, and parse a 343 KB payload (measured)
  • Thread safety: every SQLite call runs under Cache._sqlite_lock
  • Write batching: writes commit every cache_commit_interval (default 100) operations
  • Pragmas: journal_mode=WAL, synchronous=NORMAL, 64 MB page cache
  • Persistence: Permanent (until clear() or invalidate(); nothing expires)
Database Schema:
The primary keys are the only indexes; there are no secondary indexes. PRAGMA user_version stores the schema version of the telemetry frame tables. When it is older than the library expects, tif1 drops those tables once and rebuilds the frames from the payload tier. Compression Strategy:
Materialized laps and telemetry DataFrames (the frame tiers) use lz4 instead. These tiers are write-once/read-many, and lz4 halves both compress and decompress time. zstd is the fallback when lz4 is unavailable, for example on Python 3.15 where lz4 publishes no wheels yet. Each row carries its codec’s magic prefix, so both kinds of row stay readable regardless of which codec wrote them. Expiry: Cached payloads and frames never expire. Session data is immutable once published, so a cached row stays valid until cache.clear() or cache.invalidate(scope) removes it. The only time-to-live applies to the negative tier. When every CDN refuses a file in the async batch path (laps and telemetry), tif1 records the key in missing_payloads. Later batch lookups skip the network for that key until the verdict is older than TIF1_MISSING_PAYLOADS_TTL_DAYS (default 7.0). A successful write for the same key drops the verdict immediately.
Cache Inspection:
tif1.get_cache() returns the tif1.cache.Cache instance. tif1.Cache is the separate FastF1-compatibility helper in fastf1_compat.py.

Cache Lookup Flow

Performance Comparison: Measured for the 343 KB session_laptimes.json of a race (Intel Core i9-13900HX, Python 3.14): Cache Warming Strategies:
Cache Invalidation:

Stage 3: CDN Fetching with Fallback Strategy

When both cache tiers miss, tif1 fetches data from the CDN. The fetch uses a multi-source strategy with automatic fallback.

CDN Architecture

Primary Source: jsDelivr CDN
  • URL Pattern: https://cdn.jsdelivr.net/gh/TracingInsights/{year}@main/{path}
  • Serves the TracingInsights GitHub data repos from a global CDN
Fallback Source: Hugging Face Buckets
  • URL Pattern: https://huggingface.co/buckets/tracinginsights/{year}/resolve/{path}
  • Mirrors the TracingInsights GitHub data repos with the same layout (no branch segment)
  • Used when jsDelivr fails, returns 403 or 404, or is unavailable
Backup Source: StaticDelivr CDN
  • URL Pattern: https://cdn.staticdelivr.com/gh/TracingInsights/{year}/main/{path}
  • Used when both jsDelivr and Hugging Face fail or are unavailable
Forbidden Source: raw.githubusercontent.com
  • Never used for session payloads due to strict rate limits
  • The one exception is the live event schedule. For the current season, events.py fetches theOehrly/f1schedule/master/schedule_{year}.json, where calendar changes land first
  • That one small file is cached for schedule_ttl_hours (default 6)
  • When all three sources fail, tif1 raises NetworkError instead of trying it. When every source refused the file with a 4xx other than 408 or 429, it raises DataNotFoundError

URL Construction

Fallback Logic

In the async batch path, a 404 from one source starts the remaining sources at the same time. A missing file then costs one round trip, not three.

Circuit Breaker Pattern

tif1 implements a circuit breaker to prevent cascading failures during network issues. Circuit Breaker States:
  1. "closed" (Normal Operation)
    • All requests pass through
    • Failures are counted
    • Threshold: 5 consecutive failures (circuit_breaker_threshold)
  2. "open" (Failing)
    • Requests fail immediately, without a network call
    • Prevents overload of the failing service
    • Duration: 60 seconds (circuit_breaker_timeout)
  3. "half-open" (Testing Recovery)
    • Requests are allowed through again
    • Success → transition to "closed"
    • Failure → transition back to "open"
The breaker is shared by the process. The async batch path (laps, telemetry) records one failure when every CDN fails in an attempt. The synchronous path (drivers.json, weather.json, rcm.json) records each failed request. Any success resets the count. A missing, refused (403 or 404), or malformed payload is an answer from a healthy server. It does not count as a failure on either path. When the breaker is open, the synchronous path raises CircuitBreakerOpenError and the async batch path raises NetworkError. The block below is a simplified, single-threaded copy of tif1.retry.CircuitBreaker. The real class adds a lock. Read the live instance with tif1.get_circuit_breaker().

Retry Strategy

tif1 has one retry loop per fetch path:
  • Synchronous path (PayloadLoader.fetch_from_cdn; drivers.json, weather.json, rcm.json): each CDN source gets its own retry loop (tif1.retry.retry_with_backoff, wrapped around the circuit breaker). Only NetworkError is retried. A 403 or 404 moves on to the next source at once.
  • Async batch path (fetch_json_async; laps and telemetry): each attempt walks all CDN sources once. tif1 waits and walks again only when every source failed. The wait is min(retry_backoff_factor ** attempt, max_retry_delay) seconds, plus up to retry_jitter_max seconds of jitter (default 0).
The block below is a simplified copy of the synchronous loop:

Request Timeout Management

tif1 uses one timeout value in seconds for every request (timeout, default 30). There are no separate connect, read, or total timeouts.

Stage 4: Async Parallel Fetching

tif1 fetches many payloads in parallel with asyncio, for example the telemetry files of many laps. The laps of a session come from one file, session_laptimes.json. tif1 fetches per-driver laptimes.json files in parallel only for drivers that this file does not cover.

Parallel Fetching

async_fetch.py runs the blocking requests of the shared niquests.Session in a thread pool. An asyncio.Semaphore caps the number of requests in flight (max_concurrent_requests, default 22). The block below is a simplified copy:

HTTP/2 Multiplexing

tif1 uses the niquests library. niquests supports HTTP/2 and multiplexes requests over a single TCP connection. HTTP/1.1 Limitations:
  • One request at a time per TCP connection
  • Multiple connections required for parallelism
  • High overhead: TCP handshake + TLS handshake per connection
  • Head-of-line blocking
HTTP/2 Advantages:
  • Multiple requests over single TCP connection
  • Binary framing for efficiency
  • Header compression (HPACK)
  • Stream prioritization
tif1 builds this session once per process in tif1.http_session (TIF1_HTTP_MULTIPLEXED, default true).

Connection Pooling

tif1.http_session.get_session() mounts one HTTPAdapter for https:// with these sizes:
The request timeout is not a session setting: tif1 passes timeout (default 30 seconds) to each request.

Error Handling in Parallel Fetching

fetch_multiple_async() in tif1.async_fetch returns one entry per request. A failed fetch becomes None, so one failure does not cancel the others. A file that every CDN reports as missing gives None silently. tif1 logs other failures at WARNING.
The requests run under the max_concurrent_requests semaphore, so a large batch needs no manual splitting.

Stage 5: High-Performance JSON Parsing

After the CDN fetch, tif1 parses JSON with orjson. On tif1 payloads, this library parses 3x to 7x faster than the standard Python json module.

Why orjson?

Performance Comparison (median of 7 runs, Intel Core i9-13900HX, Python 3.14): Key Features:
  • Written in Rust
  • Direct bytes-to-Python object conversion (no intermediate string)
  • Native support for datetime, UUID, and other types when it serializes

Parsing Pipeline

The block below is a simplified copy of the checks in async_fetch.py. A body that is not valid JSON, or not a JSON object, raises InvalidDataError:

Data Structure Examples

Every payload is columnar: one JSON list per field, with the same length for every list. Missing values arrive as the string "None", which tif1 turns into NaN, NaT, or null. The examples show the first two entries of each list, from the 2025 Bahrain Grand Prix race. Lap Data JSON Structure ({driver}/laptimes.json; session_laptimes.json has the same fields for every driver):
The payload has 42 fields. The fields not shown are ms1 to ms3 (mini-sector strings), s1T to s3T, vi2, vfl, fresh, lST, delR, ff1G, and iacc. The other per-lap weather fields are wT, wH, wP, wR, wWD, and wWS. Times are float seconds. Telemetry Data JSON Structure ({driver}/{lap}_tel.json, one file per lap; VER/10_tel.json shown):
Weather Data JSON Structure (weather.json):

Payload Size

tif1 payloads are small: one telemetry file per lap is about 150 KB. tif1 parses each payload whole with orjson; it does not stream them.

Validation After Parsing

Validation is off by default (validate_data, validate_lap_times, validate_telemetry). When on, the models in tif1.validation check the columnar payload. Every non-empty list must have the same length. Stints must be 1 or more, and tyre life 0 or more. The block below is a cut-down version of tif1.validation.LapData:

Stage 6: DataFrame Construction and Transformation

After parsing and validating JSON, tif1 constructs DataFrames with optimized column names, types, and ordering.

DataFrame Construction Pipeline

The block below is a simplified view of core_utils/helpers.py (_create_lap_df and _process_lap_df):

Column Naming Convention

tif1 uses the FastF1 column names (PascalCase), so FastF1 code reads tif1 frames without changes. Rename Mapping (an excerpt of LAP_RENAME_MAP in core_utils/constants.py):

Type Optimization

tif1 applies a fixed dtype contract per backend. It does not downcast: numeric columns stay 64-bit. Pandas Type Optimization (simplified from _apply_laps_dtypes):
The result matches the dtypes of session.laps:
Polars Type Optimization:

Column Ordering

tif1 orders lap columns as FastF1 does (FASTF1_LAPS_COLUMN_ORDER in core_utils/constants.py). The tif1 columns LapTimeSeconds and QualifyingSession come after the FastF1 columns. Payload columns that keep their upstream names come last: ms1 to ms3, drv, and team. Driver and Team come from drivers.json, so drv and team are not renamed:

Index Management

Pandas Index Strategy:
Polars Index Strategy:

Missing Data Handling

DataFrame Validation

Performance Benchmarks

DataFrame Construction Performance (2025 Bahrain Grand Prix race, 1128 laps, Intel Core i9-13900HX): Memory Usage (2025 Bahrain Grand Prix race, as loaded; pandas memory_usage(deep=True), polars estimated_size()):

Stage 7: Data Enrichment and Augmentation

After the dtype step, tif1 adds one computed column to the laps: LapTimeSeconds. The other analysis columns arrive with the payload. Examples are the per-lap weather columns, Stint, IsPersonalBest, and the telemetry channels RelativeDistance, DriverAhead, DistanceToDriverAhead, and AccelerationX/Y/Z. The functions in this stage are recipes for extra columns that tif1 does not add. They run on the pandas backend: pass session.laps or a telemetry frame such as session.get_fastest_lap_tel(). On pandas, LapTime and the sector times are timedeltas, so the recipes use LapTimeSeconds for arithmetic with plain numbers.

Lap Data Enrichment

Computed Time Columns:
Position and Strategy Analysis:
Tyre Strategy Enrichment:
Performance Flags:

Weather Data Integration

session.laps carries a weather sample that the source data matched to each lap (WeatherTime, AirTemp, …, WindSpeed), but that match is misaligned for many laps. laps.get_weather_data() returns the sample of each lap with the fastf1 rule. To attach the nearest sample of session.weather to another time column, use pd.merge_asof. Both LapStartTime and the weather Time are timedeltas from the session start on pandas:

Telemetry Enrichment

Acceleration Calculation:
Distance Normalization:
Driver Ahead Information: tif1 telemetry already has DriverAhead (the car number of the car ahead, missing when no car is ahead) and DistanceToDriverAhead (meters). The recipe below adds the 3-letter code of the car ahead at the lap start, from the lap positions:
Corner Detection:
session.get_circuit_info().corners lists the official corner numbers and their distances, which give a more reliable corner map than speed thresholds.

Enrichment Performance

The recipes are vectorized pandas operations. On a full race (about 1,100 laps) or one lap of telemetry, each recipe runs in milliseconds. The extra columns add memory in proportion to their count: each float64 column costs 8 bytes per row.

Stage 8: Cache Storage and Finalization

The final stage saves processed data to both cache tiers and returns the DataFrame to the user.

Cache Storage Strategy

Dual-Tier Write (memory first, then SQLite):
A failed SQLite write is logged at DEBUG level and skipped; it never raises. Serialization for SQLite (payload tiers): The payload tiers store the CDN JSON, not DataFrames. DataFrames are rebuilt from the payload on read, or served from the frame tier when one is materialized.
Deserialization from SQLite (payload tiers):
A corrupt compressed row raises ValueError inside the cache, which the read path logs and turns into a cache miss. Serialization for SQLite (frame tier):

Cache Eviction Policies

LRU Eviction (Memory Cache):
No Eviction (SQLite Cache): The SQLite tier has no time-based eviction and never runs VACUUM. Rows stay until a caller removes them by scope:
The negative tier is the one exception: missing_payloads verdicts older than TIF1_MISSING_PAYLOADS_TTL_DAYS (default 7.0) are filtered out on load.

Cache Statistics and Monitoring

The cache keeps no hit or miss counters and exposes no statistics API. Measure cache effectiveness by timing a cold load against a warm one:
Call tif1.setup_logging(logging.DEBUG) to see which tier answered each lookup.

Final Data Return

On pandas, the laps property wraps the frame in the Laps class and links it to its session. tif1 does not set DataFrame.attrs. On polars, session.laps is a PolarsLaps: a pl.DataFrame subclass with the same methods, linked to its session.

Complete Pipeline Timing

Measured for session.laps of the 2025 Bahrain Grand Prix race (Intel Core i9-13900HX, Python 3.14, pandas 3.0.6):

Data Transformation Through the Pipeline

This section follows data through each transformation stage. The details help with debugging and performance optimization.

Stage-by-Stage Data Evolution

Stage 1: Raw JSON (from CDN)

The examples follow VER/laptimes.json of the 2025 Bahrain Grand Prix race (57 laps). The payload is columnar: one list per field, one entry per lap.
Characteristics:
  • Format: UTF-8 encoded JSON, one list per field (42 fields)
  • Size: ~18 KB for one driver, ~340 KB for session_laptimes.json (all 20 drivers)
  • Naming: short upstream keys (s1, sesT, wAT, …)
  • Types: Mixed (strings, numbers, booleans); missing values are the string "None"

Stage 2: Python Dictionary (after orjson parsing)

Characteristics:
  • Format: Native Python dict of lists
  • Types: Python native (int, float, str, bool)
  • Access: O(1) dictionary lookups

Stage 3: Initial DataFrame (after construction)

Characteristics:
  • Format: pandas DataFrame
  • Size: ~31 KB for one driver (57 laps)
  • Column names: short upstream keys
  • Types: Default pandas types; columns with "None" entries are object

Stage 4: Renamed DataFrame (after column renaming)

Characteristics:
  • Format: pandas DataFrame
  • Size: Same as Stage 3
  • Column names: FastF1 names (PascalCase)
  • Types: Still default types

Stage 5: Typed DataFrame (after the dtype contract)

The row labels (285, 286, …) come from the full session.laps table, which has a RangeIndex. pick_driver() keeps them. Characteristics:
  • Format: Laps (pandas) or pl.DataFrame (polars)
  • Size: ~25 KB for one driver (46 columns on pandas, including the FastF1 index column)
  • Columns: FastF1 order, then LapTimeSeconds and the tif1 extras
  • Ready for analysis

Stage 6: Final DataFrame (cached and returned)

Characteristics:
  • Format: pandas/polars DataFrame
  • Size: ~0.46 MB (pandas) or ~0.35 MB (polars) for the full race (1128 laps)
  • Cached: the JSON payload (memory and SQLite tiers) and the built frame (backend lap LRU and SQLite laps frame tier)
  • Ready: For immediate analysis

Data Type Comparison: Pandas vs Polars

tif1 applies a dtype contract per backend after construction. The table lists the types of the main laps columns, as loaded for the 2025 Bahrain Grand Prix race. Key Differences:
  • Time columns: pandas converts the upstream float seconds to timedelta64[ns]; polars converts them to Duration("ns"). LapTimeSeconds is a float on both backends.
  • String columns: pandas uses category; polars uses String. Set TIF1_POLARS_LAP_CATEGORICAL=true to get Categorical on polars.
  • Missing values: polars uses null for every type; pandas uses NaN, NaT, or <NA>, depending on the column type.
  • Integer columns with no missing values are Int64 on polars and float64 on pandas (FastF1 convention).
See Column types by backend for the weather, race control, and telemetry tables.

Memory Usage Comparison

Full Pipeline Memory Usage (session_laptimes.json of the 2025 Bahrain Grand Prix race, 1128 laps): On pandas, the dtype contract shrinks the frame: text columns become category, and the "None" strings leave the object columns. Polars stores the same data in about a quarter less memory.

Advanced Performance Optimizations

tif1 implements many performance optimizations throughout the data pipeline. This section explains them for faster code and better architectural decisions.

1. HTTP/2 Multiplexing and Connection Reuse

HTTP Protocol Evolution

HTTP/1.0 (Legacy):
  • One request per TCP connection
  • Connection closed after each request
  • High overhead: TCP handshake (3-way) + TLS handshake (2-3 round trips)
HTTP/1.1 (Traditional):
  • Connection keep-alive (reuse connection)
  • Pipelining (limited support)
  • Head-of-line blocking (requests must complete in order)
HTTP/2 (tif1):
  • Binary framing protocol (vs text-based HTTP/1.1)
  • Multiplexing: Multiple requests over single connection
  • Header compression (HPACK algorithm)
  • Stream prioritization
  • No head-of-line blocking at HTTP layer

Implementation in tif1

tif1.http_session.get_session() returns the process-wide session. It is built once, with the settings below:

2. Lazy Loading and On-Demand Data Fetching

Lazy loading fetches data only when the code needs it. This reduces unnecessary network I/O and memory usage.

Implementation

The block below is a simplified view of tif1.core.Session. The attribute names match the real class; the _build_* helpers stand for the property bodies.

Performance Benefits

3. Categorical Data Type Optimization

Converting string columns to categoricals gives large memory savings for columns with few distinct values.

Memory Comparison

Performance Comparison

Automatic Categorization in tif1

4. Backend Selection: Pandas vs Polars

Select the backend that matches the workload. Data Backends lists measured times and memory for both backends. On the tables of one session, both backends finish common operations in about 1 ms. The polars frames use about 25% less memory for laps.

When to Use Each Backend

Use Pandas When:
  • Compatibility with existing pandas code is required
  • A library requires pandas (seaborn, scikit-learn, and others)
  • Mutable DataFrames are required (in-place operations)
  • Dataset is small (<10k rows)
  • The complete pandas ecosystem is required
Use Polars When:
  • The datasets are large (>100k rows), such as the telemetry of many sessions
  • Memory is constrained
  • Lazy evaluation is required

Switching Backends

5. Async Parallel Fetching

See Stage 4. Two settings control the parallelism:
  • max_concurrent_requests (TIF1_MAX_CONCURRENT_REQUESTS, default 22): requests in flight for one batch
  • telemetry_prefetch_max_concurrent_requests (TIF1_TELEMETRY_PREFETCH_MAX_CONCURRENT_REQUESTS, default 32): requests in flight for a telemetry prefetch

6. JSON Parsing Optimization

orjson parses tif1 payloads 3x to 7x faster than stdlib json (see Stage 5).

Benchmark Comparison

7. Cache Optimization Strategies

Pre-warming Cache

Cache Size Tuning

The config reads the environment once, when tif1 is first used, so set these variables before Python starts:

8. Batch Operations

Process multiple items together for better performance.

Performance Summary

Key Optimizations and Their Effect (measured on one machine, see the sections above):

Comprehensive Error Handling

tif1 implements an error handling system with a hierarchical exception structure, detailed error context, and recovery strategies.

Exception Hierarchy

src/tif1/exceptions.py defines eleven exception classes. Every one is exported from tif1. Nine of them form the TIF1Error hierarchy:
The other two are ValueError subclasses, not TIF1Error subclasses:
get_session() and get_event_by_name() raise EventNotFoundError when an event name matches no event of the season. They raise EventNotInSeasonError when a circuit or country alias names an event that is not on that season’s calendar. An example is "Suzuka" in 2021. Every exception carries message (the formatted text) and context (a dict of keyword arguments passed at raise time). The constructors accept extra **context keys, so handlers should read e.context.get(...) rather than rely on attributes.

Network Errors

NetworkError is raised when every CDN source fails, when the circuit breaker is open, or when offline_mode is on and the cache misses. The synchronous path raises the subclass CircuitBreakerOpenError for the open breaker. The CDN fallback loop in cdn.py logs each failed source at WARNING before raising.
Timeouts and connection failures surface as NetworkError too; raise TIF1_TIMEOUT or TIF1_MAX_RETRIES through the environment or tif1.get_config().set(...) when a slow link needs more headroom.

Data Not Found Errors

DataNotFoundError means every CDN refused the payload with a 4xx other than 408 or 429. It also means that the negative-verdict tier already knows the payload is missing.
An unknown event name does not raise DataNotFoundError. tif1 resolves the name with fuzzy matching, so a typo such as "Monacco" loads the Monaco Grand Prix. A fuzzy match needs a score of at least 70 out of 100. A name below that score, such as "Nonexistent Grand Prix", raises tif1.EventNotFoundError:
DriverNotFoundError and LapNotFoundError are subclasses, so one except tif1.DataNotFoundError handler covers all three.

Invalid Data Errors

InvalidDataError is raised when a payload fails pydantic validation in validation.py or cannot be parsed. Validation failures always raise; there is no fallback to unvalidated data.

Session Not Loaded Errors

SessionNotLoadedError is defined and exported for FastF1-style code paths. tif1 sessions load lazily on attribute access, so the current code never raises it.

Cache Errors

The cache never raises on read or write failures. tif1.CacheError exists in the hierarchy as a direct TIF1Error subclass with no subclasses of its own. cache.py does not raise it. tif1 logs a failed SQLite read, a corrupt compressed row, or a failed write. Each case degrades to a cache miss, so the loader fetches from the CDN instead.

Diagnosing cache problems

If SQLite cannot open cache.sqlite at startup, tif1 logs SQLite cache unavailable and runs without the payload cache: reads return nothing and writes are skipped. The per-session memo and the backend lap LRU still work.

Error Recovery Strategies

Automatic Retry with Exponential Backoff

Fallback to Alternative Data Source

Graceful Degradation

Error Context and Debugging

All tif1 exceptions include detailed context for debugging.

Monitoring and Observability

tif1 provides monitoring capabilities for understanding system behavior, diagnosing issues, and optimizing performance.

Logging System

Log Levels and Configuration

What Gets Logged

The lines below use the custom format from the previous example. The messages come from the tif1 source. The exact set depends on the tif1 version and on which cache tiers answer. Cache keys use the URL-encoded event name. DEBUG Level (a session served from the SQLite cache):
When one payload of a cached session is missing, the CDN lines appear:
A session with nothing in the cache skips the cache reads, so it logs no Cache miss lines. Its batch fetches log Fetched: ... from jsDelivr at DEBUG (tif1.async_fetch). INFO Level:
WARNING Level:
ERROR Level:

Performance Monitoring

Timing Decorators

Performance Metrics Collection

Cache Monitoring

Cache Statistics

Cache Performance Testing

Circuit Breaker Monitoring

Network Monitoring

Request Tracking

Memory Monitoring

The memory examples use psutil, which tif1 does not install. Install it with pip install psutil.

Comprehensive Monitoring Dashboard

Data Flow Patterns and Scenarios

Common data flow patterns help with code optimization for different use cases. The times are measured for the laps of the 2025 Bahrain Grand Prix race (Intel Core i9-13900HX, Python 3.14, pandas 3.0.6).

Pattern 1: Cold Start (First Load)

Scenario: First time loading data, no cache available.
Total Time: Depends on the network; the CDN round trips dominate. Building the frame takes about 30 ms on pandas. Optimization Tips:
  • Pre-warm cache during application startup
  • Use async loading for non-blocking operation
  • Load only the required data (laps vs telemetry)

Pattern 2: Warm Start (SQLite Cache Hit)

Scenario: Data exists in the SQLite cache, but not in memory (for example, a new process).
Total Time: About 1.5 ms, plus about 10 ms for get_session(). Without a laps frame row, tif1 reads the payload tier and builds the frame (about 30 ms on pandas). Network I/O: None Optimization Tips:
  • Keep SQLite cache on SSD for faster access
  • Keep the cache directory between runs; cached payloads never expire
  • Compare warm and cold load times (the cache keeps no hit counters)

Pattern 3: Hot Start (Memory Hit)

Scenario: Data exists in memory in the same process.
Total Time: About 1 µs Network I/O: None Optimization Tips:
  • Reuse session objects to maximize memory hits
  • Increase the memory cache size when RAM is available
  • Keep frequently accessed data in memory

Pattern 4: Partial Cache Hit

Scenario: A telemetry batch (get_fastest_laps_tels()) where some laps are cached and others need fetching.
Optimization Tips:
  • Batch fetch missing laps with one call instead of one call per lap
  • Pre-warm cache for commonly accessed sessions
  • Use selective loading (only load needed drivers)

Pattern 5: Network Failure with Retry

Scenario: jsDelivr times out on a cached session, so tif1 falls back to Hugging Face. The timings assume the default settings (timeout 30 s, max_retries 3, retry_backoff_factor 2.0, jitter on). The async batch path (laps and telemetry) walks all CDNs in one attempt:
This takes about 30 seconds plus the Hugging Face response. A second attempt (wait 1 s, then 2 s) starts only when every CDN fails. The synchronous path (drivers.json, weather.json, rcm.json) retries each CDN before it moves on:
This takes about 93 seconds: 3 tries × 30 s plus about 3 s of backoff. A session with nothing in the cache fetches with a single attempt per CDN (ultra_cold_skip_retries), so it skips the backoff. A 403 or 404 does not trigger these loops. tif1 moves to the next CDN at once. It raises DataNotFoundError when every CDN refuses the file with a 4xx other than 408 or 429. Optimization Tips:
  • Reduce timeout (TIF1_TIMEOUT) or max_retries (TIF1_MAX_RETRIES) for faster failure detection
  • After 3 failed fetches, tif1 skips a CDN source for the rest of the process
  • After 5 consecutive failures, the circuit breaker fails fast for 60 seconds

Pattern 6: Batch Loading Multiple Sessions

Scenario: Load data for multiple sessions efficiently.

Pattern 7: Incremental Data Loading

Scenario: Load data incrementally as needed.

Pattern 8: Cache Warming Strategy

Scenario: Pre-warm cache for better user experience.

Advanced Optimization Strategies

These strategies achieve maximum performance in production environments.

Strategy 1: Intelligent Cache Pre-warming

Pre-warm cache strategically based on usage patterns.

Strategy 2: Adaptive Timeout Management

Adjust timeouts based on network conditions.

Strategy 3: Selective Data Loading

Load only the required data.

Strategy 4: Batch Operations for Multiple Analyses

Batch operations to minimize overhead.

Strategy 5: Memory-Efficient Iteration

Process large datasets without loading everything into memory.

Strategy 6: Polars for Large-Scale Analysis

Use Polars for better performance on large datasets.

Strategy 7: Connection Pooling Optimization

tif1 builds one shared niquests session per process, so tune it through the config, not through a custom adapter. Set these variables before Python starts:

Strategy 8: Lazy Evaluation with Polars

Use Polars lazy evaluation for complex pipelines.

Strategy 9: Compression for Cache Storage

Optimize cache storage with compression. The codec and level are fixed; there is no compression-level setting.

Strategy 10: Monitoring-Driven Optimization

Use monitoring data to identify bottlenecks.

Comprehensive Summary

The tif1 data flow architecture targets maximum performance, reliability, and developer experience. This section summarizes the key concepts and gives actionable recommendations.

Architecture Principles

1. Performance First
  • Every component optimized for speed
  • Multi-tier caching: a warm session.laps loads in about 1.5 ms, a repeated access in about 1 µs
  • HTTP/2 multiplexing enables parallel fetching
  • orjson parses tif1 payloads 3x to 7x faster than stdlib json
  • Categorical types cut the memory of the text columns by about 90% (pandas)
  • Polars frames use 25-40% less memory than pandas frames
2. Resilience and Reliability
  • Circuit breaker prevents cascading failures
  • Automatic retry with exponential backoff
  • Multi-source CDN fallback (jsDelivr → Hugging Face → StaticDelivr)
  • Error handling with structured context (e.context)
  • Graceful degradation for non-critical data
3. Developer Experience
  • Lazy loading minimizes unnecessary work
  • Intuitive API with sensible defaults
  • Detailed logging and monitoring capabilities
  • Exceptions carry the year, event, session, and other keys of the failed request
  • Flexible backend selection (pandas/polars)

Performance Characteristics

Load Time Comparison (laps of the 2025 Bahrain Grand Prix race, pandas, Intel Core i9-13900HX): Memory Usage (same race):

Key Optimizations

1. Multi-Tier Caching
  • Memory: about 3 µs per payload read; 1024 JSON and 2048 telemetry payloads
  • SQLite: about 2 ms per 343 KB payload read; unlimited capacity
  • Laps frame tier: the built laps DataFrame in one SQLite row
  • Automatic promotion from SQLite to memory
  • No expiry: cached payloads persist until cleared
2. Async Parallel Fetching
  • HTTP/2 multiplexing over single connection
  • Up to max_concurrent_requests (default 22) requests in flight
  • A failed fetch in a batch becomes None without cancelling the others
  • Automatic retry when every CDN fails
3. Type Optimization
  • Categorical encoding for string columns (pandas)
  • Time columns as timedelta64[ns] (pandas) or Duration("ns") (polars)
  • Boolean flags as bool/Boolean; numeric columns stay 64-bit
  • The pandas laps frame shrinks by about a third (718 KB to 462 KB for a full race)
4. Data Enrichment
  • One computed column (LapTimeSeconds); per-lap weather comes with the payload
  • Telemetry channels such as RelativeDistance, DriverAhead, and AccelerationX/Y/Z come with the payload
  • The Stage 7 recipes add more columns in a few milliseconds

Best Practices

For Maximum Performance:
For Reliability:
For Memory Efficiency:

Common Pitfalls and Solutions

Pitfall 1: Creating New Sessions Repeatedly
Pitfall 2: Loading All Data When Only Laps Needed
Pitfall 3: Sequential Operations
Pitfall 4: Not Handling Network Errors

Performance Tuning Checklist

Before Deployment:
  • Enable appropriate logging level (INFO for production)
  • Configure cache size based on available memory
  • Set TIF1_MISSING_PAYLOADS_TTL_DAYS if missing payloads should re-check sooner
  • Pre-warm cache for frequently accessed data
  • Choose appropriate backend (pandas vs polars)
  • Configure timeouts based on network conditions
  • Set up monitoring and alerting
  • Test error handling and recovery
During Operation:
  • Watch the Cache hit and Cache miss DEBUG log lines (the cache keeps no hit counters)
  • Monitor network success rate (target: > 95%)
  • Monitor memory usage (should be stable)
  • Monitor circuit breaker state (should be "closed")
  • Check for slow queries (> 5s)
  • Review error logs regularly
  • Clear unused cache tiers with cache.invalidate(scope) when disk space matters
  • Update cache warming strategy based on usage
For Optimization:
  • Profile code to identify bottlenecks
  • Increase the memory cache size if repeated loads still miss
  • Use Polars for large datasets
  • Batch operations where possible
  • Use async loading for non-blocking operations
  • Optimize network timeouts
  • Consider CDN proximity
  • Review and optimize data loading patterns

Conclusion

The tif1 data flow architecture takes a complete approach to high-performance data loading and processing. Combine the eight-stage pipeline, multi-tier caching, async parallel fetching, and these best practices to get:
  • About 1.5 ms for a warm session.laps from the SQLite laps frame tier, and about 1 µs for a repeated access
  • Parallel fetches of many payloads, up to max_concurrent_requests at a time
  • About a third less memory for pandas laps through the dtype contract
  • 25-40% less memory for the frames of the polars backend
  • CDN fallback across three mirrors, with retries and a circuit breaker
The architecture is transparent, observable, and tunable. For a simple analysis script or a production data pipeline, tif1 provides the needed performance and reliability. For questions, issues, or contributions, visit the GitHub repository or join the community discussions.

Caching Strategy

The multi-tier caching system.

Backends

Pandas vs Polars comparison and selection guide.

Sessions

Session management and data loading.

HTTP API

HTTP client and network operations.

Utilities

Helper functions and utilities.

CLI

Command-line interface for data management.

Additional Resources

Quick Reference

Environment Variables

Common Code Patterns

Last modified on October 30, 2026