Data Models

Classes

Season(year, meetings)

Represents a Formula 1 season, containing methods to load and manage the season's meetings and sessions.

Meeting([season, year, code, key, number, ...])

Represents a meeting in a specific season with relevant details and associated sessions.

Session([season, year, meeting, key, name, ...])

Represents a Formula 1 session, containing methods to retrieve live timing data and process it.

Circuit(key, short_name)

Represents a Formula 1 circuit with its characteristics and metadata.

Driver([RacingNumber, BroadcastName, ...])

Represents a Formula 1 driver with their associated information.

Season

The Season model is the top-level container for Formula 1 data. It manages all meetings and sessions for a specific year.

Key Attributes:

  • year: The F1 season year

  • meetings: List of Meeting objects

  • meetings_json: Raw meeting data

  • season_table: Pandas DataFrame with season data

  • meetings_table: Aggregated meetings data

Example Usage:

import livef1

# Get a season
season = livef1.get_season(2024)

# Access meetings
print(season.meetings_table)  # View all meetings
print(season.meetings)  # Access Meeting objects

# Get specific meeting
monaco_gp = [m for m in season.meetings if m.location == "Monaco"][0]

Meeting

The Meeting model represents a specific Grand Prix event within a season. It manages session data and meeting metadata.

Key Attributes:

  • season: Reference to parent Season object

  • code: Meeting code (e.g., “MON”)

  • key: Unique identifier

  • location: Circuit location

  • name: Grand Prix name

  • sessions: List of Session objects

  • sessions_table: DataFrame of session data

Example Usage:

# Get specific meeting
meeting = livef1.get_meeting(
    season=2024,
    meeting_identifier="Monaco"
)

# Access sessions
print(meeting.sessions_table)  # View all sessions

# Get specific session
race = [s for s in meeting.sessions if s.type == "Race"][0]

Session

The Session model represents individual F1 sessions (Practice, Qualifying, Race) and implements the medallion architecture for data processing.

Key Attributes:

  • meeting: Reference to parent Meeting object

  • type: Session type (e.g., “Race”, “Practice 1”)

  • name: Session name

  • key: Unique identifier

  • startdate: Session start time

  • enddate: Session end time

  • data_lake: DataLake object for data storage

  • topic_names_info: Available data topics

Data Access Methods:

  • get_data(): Retrieve raw data

  • generate(): Create processed tables

  • laps: Access lap data

  • carTelemetry: Access telemetry data

Example Usage:

# Get specific session
session = livef1.get_session(
    season=2024,
    meeting_identifier="Monaco",
    session_identifier="Race"
)

# Load raw data
telemetry = session.get_data("CarData.z")

# Generate processed tables
session.generate(silver=True)

# Access processed data
laps = session.laps
telemetry = session.carTelemetry

Data Flow

The models work together in a hierarchical structure:

Season
├── Meeting 1
│   ├── Practice 1
│   ├── Practice 2
│   ├── Practice 3
│   ├── Qualifying
│   └── Race
├── Meeting 2
│   └── ...
└── Meeting N
    └── ...

Each level provides specific functionality:

  1. Season Level

    • Season-wide data access

    • Meeting management

  2. Meeting Level

    • Session management

    • Meeting-specific data

    • Circuit information

  3. Session Level

    • Raw data access

    • Data processing

    • DataLake architecture implementation

Best Practices

  1. Data Access

    • Use high-level functions (get_season(), get_meeting(), get_session())

    • Access objects through their parent when possible

    • Use data frames for bulk data analysis

  2. Data Processing

    • Generate silver tables before accessing processed data

    • Use parallel processing for multiple data topics

    • Cache frequently accessed data

  3. Memory Management

    • Load data only when needed

    • Use data lake for persistent storage

    • Clear unused data from memory

See also