Skip to main content
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 the tif1.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.jupyter in a notebook turns the cards on
  • Kernel detection: tif1 checks 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 Driver and Lap, and to PolarsDriver and PolarsLap
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 a Session 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 Race or Practice 1
  • Library: The backend in use (pandas or polars)
  • Drivers: The number of drivers, or Not loaded before the driver list or the laps load
The session card shows the identity of the session and its backend without inspection of each attribute.
The card is built each time the object is displayed. After session.load(), the Drivers row shows the number of drivers instead of Not loaded.

Driver Display

The Driver 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: Yes when the laps of the driver are in memory, otherwise No
For the full name, team, and car number, read the fields of the Driver object: driver["FullName"], driver["TeamName"], and driver["DriverNumber"].
This display is useful for work with multiple drivers. It shows which drivers have their laps loaded.

Lap Display

The card of a Lap 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: Yes when the telemetry payload of the lap is in the session memo, otherwise No
The lap time, sector times, and compound are fields of the 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
The function returns the HTML; it does not display it. Wrap the result in 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:
This comparison is useful for optimizing memory usage and for understanding the scale of the data.

Advanced Usage

Manual Display Control

Importing tif1.jupyter in a Jupyter kernel enables the cards once. Manual control of this behavior is available.

Enabling Displays

Call enable_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:
This function attaches the _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 from tif1 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
In a dark notebook theme, light theme text on the light card background can be hard to read. Use a light theme, or read the same values from the object fields.

Layout

Each card is a plain HTML table with width: 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 Lap objects 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:
  1. Load only the necessary data: Use selective loading with session.load(laps=True, telemetry=False)
  2. Filter early: Apply DataFrame filters before displaying to reduce rendering time
  3. Use Polars backend: On polars, display_dataframe_summary() reads the size from estimated_size() instead of a deep memory scan
  4. 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 combining tif1 displays with widgets:

Voilà Dashboards

The rich displays from tif1 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 all tif1 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 with tif1. 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. Install tif1 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:
  1. Verify IPython environment: Run get_ipython() in a cell. If it raises an error, no IPython environment is active.
  2. Check the import: import tif1 does not load the integration. Run import tif1.jupyter in the notebook.
  3. Restart kernel: Sometimes a kernel restart resolves display issues. Go to Kernel → Restart.
  4. 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. Evaluate session directly 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 tif1 styles
  • 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:
  1. Use displays for context: Rich displays help readers understand the data in the notebook
  2. Add markdown explanations: Combine displays with markdown cells that explain the analysis
  3. Show data summaries: Use display_dataframe_summary() to show readers the size of the data
  4. 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.
The cards and the DataFrame summary also work with the polars backend. Call tif1.get_config().set("lib", "polars") before loading data, or pass lib="polars" to get_session().
Last modified on October 30, 2026