"use strict"; const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0]; const {useMDXComponents: _provideComponents} = arguments[0]; function _createMdxContent(props) { const _components = { p: "p", ..._provideComponents(), ...props.components }, {Heading, Mermaid} = _components; if (!Heading) _missingMdxReference("Heading", true); if (!Mermaid) _missingMdxReference("Mermaid", true); return _jsxs(_Fragment, { children: [_jsx(_components.p, { children: "tif1 supports two DataFrame backends: pandas (default) and polars (optional). Each has different performance characteristics and use cases." }), "\n", _jsx(Heading, { level: "2", id: "lib-comparison", children: "Lib Comparison" }), "\n", _jsx(Mermaid, { chart: "graph LR\n subgraph \"Pandas\"\n P1[Single-threaded]\n P2[Mature ecosystem]\n P3[Wide compatibility]\n end\n\n subgraph \"Polars\"\n PL1[Multi-threaded]\n PL2[2x faster]\n PL3[50% less memory]\n end\n\n style P2 fill:#51cf66\n style P3 fill:#51cf66\n style PL1 fill:#51cf66\n style PL2 fill:#51cf66\n style PL3 fill:#51cf66\n```python\n\n## Pandas Lib\n\nThe default lib, providing maximum compatibility with the Python data science ecosystem.\n\n### When to Use Pandas\n\n- You're already familiar with pandas\n- You need compatibility with existing pandas code\n- You're using libraries that require pandas DataFrames\n- You're working with small to medium datasets (< 1M rows)\n- You need the full pandas API surface\n\n### Example\n\n```python\nimport tif1\n\n# Pandas is the default\nsession = tif1.get_session(2025, \"Monaco Grand Prix\", \"Race\")\nlaps = session.laps # Returns pandas DataFrame\n\n# Standard pandas operations\nfastest = laps.nsmallest(5, \"LapTime\")\nby_driver = laps.groupby(\"Driver\")[\"LapTime\"].mean()\n```python\n\n---\n\n## Polars Lib\n\nA high-performance alternative written in Rust, offering 2-5x faster operations and 50% less memory usage.\n\n### When to Use Polars\n\n- You're processing large datasets (> 1M rows)\n- You need maximum performance\n- You want to minimize memory usage\n- You're building data pipelines\n- You're comfortable with a slightly different API\n\n### Installation\n\n```bash\npip install tif1[polars]\n```python\n\n### Example\n\n```python\nimport tif1\n\n# Specify polars lib\nsession = tif1.get_session(\n 2025,\n \"Monaco Grand Prix\",\n \"Race\",\n lib=\"polars\"\n)\nlaps = session.laps # Returns polars DataFrame\n\n# Polars operations (similar but not identical to pandas)\nfastest = laps.sort(\"LapTime\").head(5)\nby_driver = laps.group_by(\"Driver\").agg(pl.col(\"LapTime\").mean())\n```python\n\n---\n\n## Performance Comparison\n\n| Operation | Pandas | Polars | Speedup |\n| :--- | :--- | :--- | :--- |\n| Load 20 drivers | 2.5s | 1.2s | **2.1x** |\n| Filter laps | 45ms | 12ms | **3.8x** |\n| Group by driver | 120ms | 35ms | **3.4x** |\n| Sort by time | 80ms | 25ms | **3.2x** |\n| Memory usage | 450MB | 220MB | **2.0x** |\n\n\n Benchmarks based on a full race session with ~1200 laps and telemetry data.\n\n\n---\n\n## API Differences\n\nWhile tif1 abstracts most differences, there are some API variations to be aware of.\n\n### Filtering\n\n\n```python Pandas\n# Boolean indexing\nfast_laps = laps[laps[\"LapTime\"] < 90]\n\n# Query method\nfast_laps = laps.query(\"LapTime < 90\")\n```python\n\n```python Polars\n# Filter method\nfast_laps = laps.filter(pl.col(\"LapTime\") < 90)\n\n# Also supports boolean indexing\nfast_laps = laps[laps[\"LapTime\"] < 90]\n```python\n\n\n### Grouping\n\n\n```python Pandas\n# GroupBy\nby_driver = laps.groupby(\"Driver\").agg({\n \"LapTime\": [\"mean\", \"min\", \"count\"]\n})\n```python\n\n```python Polars\n# group_by with agg\nimport polars as pl\n\nby_driver = laps.group_by(\"Driver\").agg([\n pl.col(\"LapTime\").mean().alias(\"mean_time\"),\n pl.col(\"LapTime\").min().alias(\"min_time\"),\n pl.col(\"LapTime\").count().alias(\"count\")\n])\n```python \n\n### Sorting\n\n\n```python Pandas\n# sort_values\nsorted_laps = laps.sort_values(\"LapTime\")\n```python\n\n```python Polars\n# sort\nsorted_laps = laps.sort(\"LapTime\")\n```python\n\n\n---\n\n## Converting between backends\n\nYou can convert DataFrames between backends as needed.\n\n```python\n# Start with polars\nsession = tif1.get_session(2025, \"Monaco\", \"Race\", lib=\"polars\")\nlaps_polars = session.laps\n\n# Convert to pandas for compatibility\nlaps_pandas = laps_polars.to_pandas()\n\n# Convert back to polars\nimport polars as pl\nlaps_polars_again = pl.from_pandas(laps_pandas)\n```yaml\n\n---\n\n## Setting default lib\n\n### Via Configuration File\n\nCreate `~/.tif1rc`:\n\n```json\n{\n \"lib\": \"polars\"\n}\n```python\n\n### Via Environment Variable\n\n```bash\nexport TIF1_LIB=polars\n```python\n\n### Programmatically\n\n```python\nimport tif1\n\nconfig = tif1.get_config()\nconfig.set(\"lib\", \"polars\")\nconfig.save()\n```python\n\n---\n\n## Lib-Specific Features\n\n### Pandas Advantages\n\n- Richer ecosystem (seaborn, plotly, etc.)\n- More Stack Overflow answers\n- Better Jupyter display\n- Time series functionality\n- More flexible indexing\n\n### Polars Advantages\n\n- Lazy evaluation (query optimization)\n- Better parallelization\n- Lower memory footprint\n- Faster string operations\n- Native Arrow support\n\n---\n\n## Lazy Evaluation (Polars Only)\n\nPolars supports lazy evaluation for query optimization.\n\n```python\nimport polars as pl\n\n# Create lazy frame\nlaps_lazy = pl.scan_parquet(\"race_data.parquet\")\n\n# Build query (not executed yet)\nresult = (\n laps_lazy\n .filter(pl.col(\"Driver\") == \"VER\")\n .select([\"LapNumber\", \"LapTime\", \"Compound\"])\n .sort(\"LapTime\")\n)\n\n# Execute query (optimized)\nresult_df = result.collect()\n```python\n\n\n Lazy evaluation allows polars to optimize the entire query plan before execution, often resulting in significant speedups.\n\n\n---\n\n## Recommendations\n\n\n \n If you're new to tif1 or data analysis, start with pandas for familiarity.\n \n \n If performance becomes an issue, profile to identify bottlenecks.\n \n \n Switch to polars for large datasets or performance-critical code.\n \n \n You can use different backends for different sessions in the same script.\n \n\n\n---\n\n## Common Patterns\n\n### Processing multiple sessions\n\n```python\n# Use polars for heavy lifting\nresults = []\nfor event in tif1.get_events(2024):\n session = tif1.get_session(2024, event, \"Race\", lib=\"polars\")\n fastest = session.get_fastest_laps(by_driver=True)\n results.append(fastest)\n\n# Combine and convert to pandas for plotting\nimport polars as pl\nall_results = pl.concat(results)\nall_results_pd = all_results.to_pandas()\n\n# Plot with pandas/matplotlib\nimport matplotlib.pyplot as plt\nall_results_pd.plot(x=\"Driver\", y=\"LapTime\", kind=\"bar\")\n```python ### Memory-Efficient Analysis\n\n```python\n# Use polars to minimize memory usage\nsession = tif1.get_session(2024, \"Abu Dhabi\", \"Race\", lib=\"polars\")\n\n# Process in chunks\nfor driver in session.drivers:\n driver_obj = session.get_driver(driver)\n laps = driver_obj.laps\n\n # Analyze\n avg_time = laps[\"LapTime\"].mean()\n print(f\"{driver}: {avg_time:.3f}s\")\n\n # Data is automatically freed after loop iteration\n```yaml\n\n---\n\n## Summary\n\n- **Pandas**: Default, familiar, compatible\n- **Polars**: Fast, efficient, modern\n- **Choice**: Depends on your needs and dataset size\n- **Flexibility**: You can use both in the same project\n\n---\n\n## Related Pages\n\n\n \n Performance guide\n \n \n Optimization\n \n \n Install polars\n \n" })] }); } function MDXContent(props = {}) { const {wrapper: MDXLayout} = { ..._provideComponents(), ...props.components }; return MDXLayout ? _jsx(MDXLayout, { ...props, children: _jsx(_createMdxContent, { ...props }) }) : _createMdxContent(props); } return { default: MDXContent }; function _missingMdxReference(id, component) { throw new Error("Expected " + (component ? "component" : "object") + " `" + id + "` to be defined: you likely forgot to import, pass, or provide it."); }

Get Started

Guides

Concepts

Advanced

Reference

​Lib Comparison

Lib Comparison