tif1 provides Jupyter notebook integration with rich HTML displays, automatic environment detection, and interactive utilities for Formula 1 data analysis. The library shows formatted displays for Session, Driver, and Lap objects in the notebook.
Overview
The Jupyter integration module (tif1.jupyter) provides:
- Automatic Environment Detection: Detects when running in Jupyter and enables rich displays on import of
tif1.jupyter - Rich HTML Representations: Formatted displays for
Session,Driver, andLapobjects - DataFrame Summaries:
display_dataframe_summary()returns an HTML line with shape and memory usage - One Import:
import tif1.jupyterin a notebook is the only setup step - Fallback Support: Outside a Jupyter kernel, no class is patched and objects keep their standard
repr()
The examples on this page run inside an IPython kernel.
IPython, ipywidgets, and psutil are not tif1 dependencies. Install them in the notebook environment with pip install ipython ipywidgets psutil.Automatic Activation
The Jupyter integration activates automatically whentif1.jupyter is imported in a Jupyter environment. A plain import tif1 does not import this module. Detection targets IPython kernels, such as the kernels that Jupyter Notebook and JupyterLab start.
How It Works
Whentif1.jupyter is imported, the module:
- Detects the Environment: Checks if IPython is available and if an IPython kernel is running
- Enables Rich Displays: Patches the Session, Driver, and Lap classes with
_repr_html_()methods - Logs Activation: Logs
Jupyter display enabledatINFOlevel to thetif1.jupyterlogger - Handles Errors: Logs a warning and leaves the classes unchanged when the patch fails
Environment Detection Details
The_is_notebook() function performs the following checks:
- Tries to import the
IPythonmodule - Retrieves the current IPython instance via
get_ipython() - Checks for
IPKernelAppin the shell configuration (indicates Jupyter kernel) - Returns
Trueonly if all checks pass, which confirms a running IPython kernel
_is_notebook() returns False there.
Rich HTML Displays
Afterimport tif1.jupyter in a kernel, Session, Driver, and Lap objects display as HTML in a cell. These displays are styled with borders, colors, and structured tables.
Session Display
The Session object displays information about the loaded F1 session: year, Grand Prix name, session type, backend, and driver count. Display Features:- 🏎️ Emoji icon for quick visual identification
- Bordered container with light gray background
- Structured table layout with key-value pairs
- URL-decoded Grand Prix and session names (handles special characters)
- Driver count once the driver list or the laps are in memory. Until then, the row shows “Not loaded”. Rendering the card never starts a download
- Backend library indicator (pandas or polars)
Driver Display
The Driver object displays information about one driver in a session: driver code, session context, and data loading status. Display Features:- 👤 Emoji icon for driver identification
- Light blue background (#f0f8ff) for visual distinction
- Session context (year, Grand Prix, session type)
- Laps loading status indicator
- Compact, single-driver focused layout
Yes after the first access to ver.laps.
Lap Display
The Lap object displays information about a specific lap, including lap number, driver, session context, and telemetry loading status. Display Features:- 🏁 Emoji icon for lap identification
- Wheat-colored background (#fff8dc) for visual distinction
- Lap number prominently displayed in header
- Driver code and session context
- Telemetry loading status indicator
- Useful for tracking which laps have telemetry data loaded
DataFrame Summary Display
display_dataframe_summary(df) returns a one-line HTML summary for a pandas or polars DataFrame. tif1 does not attach this summary to DataFrames automatically.
Display Features:
- Green left border for visual emphasis
- Row count with thousands separator
- Column count
- Memory usage in MB (calculated differently for pandas vs polars)
- Compact single-line format
- Pandas: Uses
df.memory_usage(deep=True).sum()for accurate memory including object dtypes - Polars: Uses
df.estimated_size()if available, otherwise returns 0
Manual Control and Advanced Usage
The Jupyter integration activates whentif1.jupyter is imported. Control and customize the display behavior manually for advanced use cases.
Manual Activation
Manually enable Jupyter displays with theenable_jupyter_display() function when needed (for example, to restore the displays after removing them):
- Returns without changes when
_is_notebook()isFalse - Imports Session, Driver, and Lap classes from
tif1.core - Patches each class with a
_repr_html_()method - Logs activation status to the logger
- Logs a warning instead of raising if the classes cannot be imported or patched
- Restore the displays after removing the
_repr_html_()methods - Repeat the patch after the logger reported a failure
Environment Detection
Check if the code runs in a Jupyter environment:- Conditional display logic
- Notebook vs script detection
- Custom display implementations
- Testing different output formats
_is_notebook as a private helper. It is not part of the public API.
Programmatic HTML Generation
Generate the HTML strings programmatically, then display or save them:Custom Display Functions
Create custom display functions for specific use cases:Disabling Rich Displays
Use standard text output in Jupyter when preferred:Notebook Best Practices and Patterns
1. Efficient Data Loading
Load session data efficiently by controlling what gets fetched:- Use
session.load()with specific parameters to avoid fetching unnecessary data - Every
load()flag defaults toTrue, so passtelemetry=Falseunless all telemetry is needed - Telemetry data is large - only load when needed
- Weather and race control messages are small tables compared to telemetry
- The cache (enabled by default) serves repeated loads
2. Progress Indication
Provide visual feedback during long-running operations:3. Interactive Data Exploration
Explore data interactively with rich displays:4. Combining with Plotting
Integrate rich displays with matplotlib visualizations:5. Interactive Widgets
Useipywidgets for interactive data exploration:
6. Memory Management
Handle large datasets efficiently in notebooks:psutil):
Troubleshooting
Display Not Working
If rich displays are not showing:HTML Display Issues
If HTML displays are broken:Memory Issues
For large datasets in notebooks, use the polars backend. Passlib="polars" for one session, or set the default for every session with tif1.get_config().set("lib", "polars"):
Complete notebook example
API Reference
Functions
Enable rich Jupyter display for tif1 objects. Called automatically when
tif1.jupyter is imported in a notebook.Check if running in a Jupyter notebook environment.Returns:
bool - True if in Jupyter, False otherwiseGenerate HTML display for a Session object.Parameters:
session: Session object
str - HTML stringGenerate HTML display for a Driver object.Parameters:
driver: Driver object
str - HTML stringGenerate HTML display for a Lap object.Parameters:
lap: Lap object
str - HTML string