tif1 provides small HTML cards for its core objects in Jupyter Notebooks, JupyterLab, and other environments that run a Jupyter kernel. The cards show the context of an object without repeated print statements.
Overview
The integration lives in thetif1.jupyter module. import tif1 alone does not load it. When tif1.jupyter is imported inside a Jupyter kernel, it attaches an HTML representation to Session, Driver, and Lap. Any import counts, for example import tif1.jupyter or from tif1.jupyter import display_dataframe_summary. A cell that then evaluates one of these objects shows a short HTML table instead of the plain text representation.
Key Benefits
- One import:
import tif1.jupyterin a notebook turns the cards on - Kernel detection:
tif1checks for a Jupyter kernel (IPKernelApp). Plain Python and terminal IPython skip the setup - Light footprint: The HTML is a few lines of inline CSS and does not slow data processing
- Backend independent: The cards and the DataFrame summary work with pandas and polars sessions. The driver and lap cards attach to
DriverandLap, and toPolarsDriverandPolarsLap
The examples on this page run in a Jupyter kernel. Install a notebook front end with
pip install jupyterlab, which includes IPython. The widget examples also need pip install ipywidgets.Rich HTML Displays
enable_jupyter_display() attaches a _repr_html_() method to Session, Driver, and Lap. IPython uses this protocol to render HTML output. Importing tif1.jupyter in a Jupyter kernel calls enable_jupyter_display() once.
Session Display
When a cell displays aSession object, tif1 renders a table with these rows:
- Year: The season year of the session
- Grand Prix: The readable event name, for example
Monaco Grand Prix - Session: The session name, for example
RaceorPractice 1 - Library: The backend in use (
pandasorpolars) - Drivers: The number of drivers, or
Not loadedbefore the driver list or the laps load
Driver Display
TheDriver card shows these rows:
- Driver: The three-letter driver code (such as VER, HAM, LEC), in the card title
- Session: The year, event name, and session name
- Laps loaded:
Yeswhen the laps of the driver are in memory, otherwiseNo
Driver object: driver["FullName"], driver["TeamName"], and driver["DriverNumber"].
Lap Display
The card of aLap object shows these rows:
- Lap: The lap number, in the card title
- Driver: The three-letter code of the driver who completed the lap
- Session: The year, event name, and session name
- Telemetry loaded:
Yeswhen the telemetry payload of the lap is in the session memo, otherwiseNo
Lap object, for example lap["LapTime"] and lap["Compound"].
Driver.get_fastest_lap() returns a one-row DataFrame, so a notebook shows it as a table, not as a lap card. Use driver.laps.pick_fastest() or driver.get_lap(n) to get a Lap object.
The lap card helps to keep track of the laps under analysis, for example in a comparison of qualifying laps.
DataFrame Summaries
Beyond object displays,tif1 provides a utility function that summarizes the size of a DataFrame. This function is useful with large datasets that contain thousands of laps or telemetry points.
The display_dataframe_summary() Function
This function returns an HTML string with one line:
- Shape: Number of rows and columns
- Memory: The memory size of the DataFrame in MB
IPython.display.HTML to render it:
The
display_dataframe_summary() function accepts pandas and polars DataFrames. On polars, the memory figure comes from estimated_size().Comparing DataFrames
Use this function to compare the size of different DataFrames:Advanced Usage
Manual Display Control
Importingtif1.jupyter in a Jupyter kernel enables the cards once. Manual control of this behavior is available.
Enabling Displays
Callenable_jupyter_display() to attach the cards again, for example after a reload of tif1. The function does nothing outside a Jupyter kernel and logs Not in Jupyter environment, skipping display setup at INFO level:
_repr_html_() methods to Session, Driver, and Lap.
Plain Text Output
tif1.jupyter has no function that turns the cards off. To see the plain text representation of one object, use print(obj) or repr(obj).
Custom Display Functions
For custom visualizations,tif1.jupyter exposes the functions that build the HTML. Each one returns an HTML string:
Visual Themes and Styling
The HTML cards fromtif1 use inline CSS only, so they look the same in every notebook front end.
Colors
The colors are fixed. The notebook theme does not change them:- Backgrounds: Each card type has a light background (gray for sessions, blue for drivers, yellow for laps)
- Borders: A light gray border with rounded corners; the DataFrame summary has a green left border
- Text: The cards do not set a text color, so the notebook theme sets it
Layout
Each card is a plain HTML table withwidth: 100%, so it follows the width of the output area.
Performance Considerations
The Jupyter integration is lightweight. Rich displays do not slow down the data analysis workflow.Lazy Rendering
HTML representations are generated on-demand only when an object is displayed. This means:- No overhead for non-displayed objects: Creating thousands of
Lapobjects does not trigger HTML generation - Fast cell execution: Displaying an object adds negligible time to cell execution
- Memory efficient: HTML strings are not stored; they are generated fresh each time
Large DataFrames
display_dataframe_summary() reads only the shape and the memory size of a frame that is already in memory. On pandas, memory_usage(deep=True) scans the text columns, so it takes longer on frames with millions of rows. On polars, estimated_size() is fast.
Optimization Tips
For maximum performance with large datasets:- Load only the necessary data: Use selective loading with
session.load(laps=True, telemetry=False) - Filter early: Apply DataFrame filters before displaying to reduce rendering time
- Use Polars backend: On polars,
display_dataframe_summary()reads the size fromestimated_size()instead of a deep memory scan - Batch displays: When comparing many objects, use
display()with multiple arguments rather than evaluating each separately
Integration with Other Tools
Pandas Styling
tif1 DataFrames are standard Pandas or Polars objects, so they work with other visualization tools:
Plotting Libraries
Rich displays work alongside plotting libraries and combine data inspection with visualization:IPyWidgets
Create interactive dashboards combiningtif1 displays with widgets:
Voilà Dashboards
The rich displays fromtif1 work in Voilà dashboards and support shareable F1 data applications:
Supported Environments
The Jupyter integration needs a Jupyter kernel (IPKernelApp). These environments run one:
Jupyter Notebook (Classic)
The original Jupyter Notebook interface supports alltif1 rich displays. Install Jupyter and start a notebook:
JupyterLab
JupyterLab is the newer interface. It provides better layout and theming support:VS Code Notebooks
The built-in notebook support in Visual Studio Code works withtif1. Open an .ipynb file in VS Code, and the rich displays render automatically.
Google Colab
Google Colaboratory runs a Jupyter kernel, so the cards render there. Installtif1 in a Colab cell with %pip install tif1, then run import tif1.
Kaggle Notebooks
Kaggle notebooks run a Jupyter kernel, so the cards render there.IPython Terminal
Terminal IPython does not run a Jupyter kernel.tif1 skips the setup there, and objects show their plain text representation.
Troubleshooting
Displays Not Showing
If rich HTML displays do not appear:-
Verify IPython environment: Run
get_ipython()in a cell. If it raises an error, no IPython environment is active. -
Check the import:
import tif1does not load the integration. Runimport tif1.jupyterin the notebook. - Restart kernel: Sometimes a kernel restart resolves display issues. Go to Kernel → Restart.
-
Manual enable: Enable the displays explicitly:
Plain Text Instead of HTML
If plain text representations appear instead of rich HTML:- Terminal IPython: The cards need a Jupyter kernel. Terminal IPython shows plain text.
- Output capture: When output is captured with
%%capture, HTML does not render. Remove the magic command. - Print statements: Using
print(session)bypasses HTML rendering. Evaluatesessiondirectly instead.
Styling Issues
If displays look broken or poorly formatted:- Browser compatibility: Use a modern browser (Chrome, Firefox, Safari, Edge)
- Custom CSS: Check whether custom notebook CSS interferes with the
tif1styles - Dark themes: The card backgrounds are always light; switch to a light theme for better contrast
Performance Issues
If displays are slow to render:- Large DataFrames: Use
display_dataframe_summary()instead of displaying the entire DataFrame - Many objects: Avoid displaying hundreds of objects in a single cell
- Memory constraints: Close unused notebooks to free up browser memory
Best Practices
Efficient Data Exploration
When exploring F1 data in Jupyter, follow these patterns:Combining Displays with Analysis
Put displays between analysis steps to build a narrative:Documentation and Sharing
When creating notebooks to share with others:- Use displays for context: Rich displays help readers understand the data in the notebook
- Add markdown explanations: Combine displays with markdown cells that explain the analysis
- Show data summaries: Use
display_dataframe_summary()to show readers the size of the data - Include driver/lap displays: Show the drivers and laps under analysis to help readers follow the notebook
Real-World Examples
Example 1: Race Strategy Analysis
Example 2: Qualifying Comparison
Example 3: Detailed Telemetry Analysis
Example 4: Interactive Driver Comparison
Additional Resources
API Reference
For detailed information about the Jupyter module functions, see the Jupyter API Reference.Related Concepts
- Sessions - Understanding session objects and data loading
- Data Flow - How data moves through
tif1 - Caching Strategy - Optimizing performance with caching
External Links
- Jupyter Documentation - Official Jupyter docs
- IPython Display System - Technical details on
_repr_html_() - IPyWidgets - Creating interactive notebooks