great-tables

What this skill does

# Great Tables Publication-Quality Tables Skill

Master Great Tables for creating beautiful, publication-quality tables in Python with rich styling, conditional formatting, and export capabilities. Inspired by R's gt package.

## When to Use This Skill

### USE Great Tables when:
- **Publication tables** - Creating tables for reports, papers, or presentations
- **Data presentation** - Professional display of analysis results
- **Conditional formatting** - Highlighting patterns with colors and icons
- **Complex layouts** - Multi-level headers, grouped rows, footnotes
- **HTML reports** - Interactive tables for web-based reports
- **Quick formatting** - Need polished tables without manual styling
- **Dashboard components** - Tables in Streamlit/Dash applications
- **Export requirements** - Need PNG or PDF output

### DON'T USE Great Tables when:
- **Large datasets** - Over 1000 rows for display (use pagination)
- **Interactive editing** - Need editable cells (use Streamlit data_editor)
- **Real-time updates** - Streaming data display
- **Complex interactivity** - Sorting, filtering (use DataTables or AG Grid)
- **Raw data exploration** - Use pandas display or ydata-profiling

## Prerequisites

```bash
# Basic installation
pip install great_tables

# With all optional dependencies
pip install great_tables pandas polars

# For image export (PNG/PDF)
pip install great_tables webshot

# Using uv (recommended)
uv pip install great_tables pandas polars

# Verify installation
python -c "from great_tables import GT; print('Great Tables ready!')"
```

## Core Capabilities

### 1. Basic Table Creation

**Simplest Usage:**
```python
from great_tables import GT
import pandas as pd

# Create sample data
df = pd.DataFrame({
    "Name": ["Alice", "Bob", "Charlie", "Diana"],
    "Department": ["Engineering", "Marketing", "Engineering", "Sales"],
    "Salary": [95000, 78000, 88000, 92000],
    "Years": [5, 3, 4, 6]
})

# Create basic table
table = GT(df)

# Display (in Jupyter) or save
table.save("basic_table.html")
```

**With Title and Subtitle:**
```python
from great_tables import GT, md
import pandas as pd

df = pd.DataFrame({
    "Product": ["Widget A", "Widget B", "Gadget X", "Gadget Y"],
    "Revenue": [150000, 220000, 180000, 95000],
    "Units": [1500, 2200, 900, 950],
    "Growth": [0.12, 0.25, 0.08, -0.05]
})

table = (
    GT(df)
    .tab_header(
        title="Q4 2025 Sales Performance",
        subtitle="Product line revenue and growth metrics"
    )
)

table.save("sales_table.html")
```

**With Source Notes:**
```python
from great_tables import GT
import pandas as pd

df = pd.DataFrame({
    "Country": ["USA", "UK", "Germany", "Japan"],
    "GDP_Trillion": [25.5, 3.1, 4.2, 4.9],
    "Population_Million": [331, 67, 83, 125]
})

table = (
    GT(df)
    .tab_header(
        title="World Economic Indicators",
        subtitle="Top economies by GDP"
    )
    .tab_source_note(
        source_note="Source: World Bank, 2024"
    )
    .tab_source_note(
        source_note="GDP in trillion USD"
    )
)

table.save("economy_table.html")
```

### 2. Column Formatting

**Numeric Formatting:**
```python
from great_tables import GT
import pandas as pd

df = pd.DataFrame({
    "Item": ["Product A", "Product B", "Product C"],
    "Price": [29.99, 149.50, 9.99],
    "Revenue": [1500000, 2250000, 890000],
    "Margin": [0.35, 0.42, 0.28],
    "Units": [50000, 15000, 89000]
})

table = (
    GT(df)
    .tab_header(title="Product Metrics")

    # Format as currency
    .fmt_currency(
        columns="Price",
        currency="USD"
    )

    # Format large numbers with suffixes
    .fmt_number(
        columns="Revenue",
        use_seps=True,
        decimals=0
    )

    # Format as percentage
    .fmt_percent(
        columns="Margin",
        decimals=1
    )

    # Format with thousand separators
    .fmt_integer(
        columns="Units",
        use_seps=True
    )
)

table.save("numeric_formatting.html")
```

**Date and Time Formatting:**
```python
from great_tables import GT
import pandas as pd
from datetime import datetime, date

df = pd.DataFrame({
    "Event": ["Launch", "Update", "Maintenance", "Release"],
    "Date": [
        date(2025, 1, 15),
        date(2025, 3, 22),
        date(2025, 6, 1),
        date(2025, 9, 30)
    ],
    "Timestamp": [
        datetime(2025, 1, 15, 9, 0),
        datetime(2025, 3, 22, 14, 30),
        datetime(2025, 6, 1, 2, 0),
        datetime(2025, 9, 30, 10, 0)
    ]
})

table = (
    GT(df)
    .tab_header(title="Product Timeline")

    # Format date
    .fmt_date(
        columns="Date",
        date_style="day_month_year"
    )

    # Format datetime
    .fmt_datetime(
        columns="Timestamp",
        date_style="yMd",
        time_style="Hm"
    )
)

table.save("date_formatting.html")
```

**Custom Number Formatting:**
```python
from great_tables import GT
import pandas as pd

df = pd.DataFrame({
    "Metric": ["Users", "Revenue", "Conversion", "Avg Order"],
    "Value": [1234567, 5678901.23, 0.0342, 156.789]
})

table = (
    GT(df)
    .tab_header(title="Dashboard Metrics")

    # Custom suffixes for large numbers
    .fmt_number(
        columns="Value",
        rows=[0],  # First row only
        compact=True  # Use K, M, B suffixes
    )

    # Currency for second row
    .fmt_currency(
        columns="Value",
        rows=[1],
        currency="USD",
        decimals=0
    )

    # Percentage for third row
    .fmt_percent(
        columns="Value",
        rows=[2],
        decimals=2
    )

    # Standard number for fourth row
    .fmt_currency(
        columns="Value",
        rows=[3],
        currency="USD",
        decimals=2
    )
)

table.save("custom_formatting.html")
```

### 3. Styling and Colors

**Background Colors:**
```python
from great_tables import GT
from great_tables import style, loc
import pandas as pd

df = pd.DataFrame({
    "Category": ["Electronics", "Clothing", "Food", "Home"],
    "Q1": [150000, 95000, 120000, 85000],
    "Q2": [180000, 88000, 135000, 92000],
    "Q3": [165000, 102000, 128000, 78000],
    "Q4": [210000, 115000, 145000, 105000]
})

table = (
    GT(df)
    .tab_header(title="Quarterly Sales by Category")

    # Style header row
    .tab_style(
        style=style.fill(color="#4a86e8"),
        locations=loc.column_labels()
    )
    .tab_style(
        style=style.text(color="white", weight="bold"),
        locations=loc.column_labels()
    )

    # Alternate row colors
    .tab_style(
        style=style.fill(color="#f3f3f3"),
        locations=loc.body(rows=[1, 3])  # Even rows
    )

    # Highlight specific cell
    .tab_style(
        style=style.fill(color="#90EE90"),
        locations=loc.body(columns="Q4", rows=[0])  # Highest Q4
    )
)

table.save("styled_table.html")
```

**Text Styling:**
```python
from great_tables import GT
from great_tables import style, loc
import pandas as pd

df = pd.DataFrame({
    "Rank": [1, 2, 3, 4, 5],
    "Company": ["TechCorp", "DataInc", "CloudSoft", "AILabs", "DevHub"],
    "Revenue_B": [125.4, 98.2, 87.5, 76.3, 65.8],
    "Change": [0.15, 0.08, -0.03, 0.22, -0.12]
})

table = (
    GT(df)
    .tab_header(title="Top Companies by Revenue")

    # Bold first column
    .tab_style(
        style=style.text(weight="bold"),
        locations=loc.body(columns="Rank")
    )

    # Italic company names
    .tab_style(
        style=style.text(style="italic"),
        locations=loc.body(columns="Company")
    )

    # Color positive/negative changes
    .tab_style(
        style=style.text(color="green"),
        locations=loc.body(columns="Change", rows=[0, 1, 3])  # Positive
    )
    .tab_style(
        style=style.text(color="red"),
        locations=loc.body(columns="Change", rows=[2, 4])  # Negative
    )

    # Format numbers
    .fmt_currency(columns="Revenue_B", currency="USD", decimals=1)
    .fmt_percent(columns="Change", decimals=1)
)

table.save("text_styled.html")
```

**Borders and Spacing:**
```python
from great_tabl