Agate Data Analysis Library

Warnings

• breaking Agate has dropped official support for Python 2.x. Users must ensure they are running Python 3.5 or newer. PyPI listings indicate active testing and support for Python 3.10-3.14.
  Fix: Upgrade your Python environment to Python 3.5+ (preferably a recent stable version like 3.9+). If migrating from very old projects, update `agate` accordingly.
• gotcha Agate's core design principle dictates that `Table` objects are immutable. Operations like `select()`, `where()`, or `order_by()` do not modify the original table in-place; instead, they return *new* `Table` instances.
  Fix: Always assign the result of table operations to a new variable (e.g., `new_table = original_table.where(...)`) or chain operations (e.g., `table.where(...).order_by(...)`).
• gotcha When loading data from sources like CSV, `agate` uses a `TypeTester` to automatically infer column data types. While generally effective, it can sometimes guess incorrectly, especially with ambiguous data.
  Fix: If type inference is wrong, manually specify column types when loading data using the `column_types` argument in `Table.from_csv` or by instantiating `TypeTester` with `force` overrides. Example: `tester = agate.TypeTester(force={'my_column': agate.Text()}); table = agate.Table.from_csv(..., column_types=tester)`.
• gotcha There are multiple Python libraries with 'Agate' in their name. This entry refers to `wireservice/agate`, a data analysis library (`pip install agate`). Another common one is `obiba-agate`, which is a client for an 'Agate server' and has different use cases and dependencies.
  Fix: Always verify the correct library by its PyPI slug (`agate`) and maintainer (`wireservice`) to ensure you are installing the intended data analysis library. Check documentation links (e.g., `agate.rtfd.org`) to confirm.

Install

• pip install agate Standard installation
• pip install agate[icu] With PyICU for non-English locale support

Imports

• agate

  import agate

• Table

  import agate
  table = agate.Table(...)

  While `from agate import Table` works, the documentation commonly shows `agate.Table` after `import agate` to keep the namespace clean and explicit.
• TypeTester

  from agate import TypeTester

• Sum

  from agate.aggregations import Sum

Quickstart

This quickstart demonstrates loading data from a CSV (simulated in-memory), filtering rows, grouping data, aggregating results (mean and sum), and ordering the final table. It highlights `agate`'s immutable operations, where methods like `where()` and `group_by()` return new table objects.

import agate
import csv
import io

# Create a dummy CSV in memory for a runnable example
csv_data = """name,age,city,salary
Alice,30,New York,70000
Bob,24,London,50000
Charlie,30,New York,75000
David,35,London,90000
Eve,24,Paris,60000
"""

# Use io.StringIO to simulate a file for from_csv
with io.StringIO(csv_data) as f:
    # agate automatically infers types with TypeTester by default
    table = agate.Table.from_csv(f)

print("Original Table:")
table.print_table()

# Filter rows where age is less than 30
filtered_table = table.where(lambda row: row['age'] < 30)
print("\nFiltered Table (age < 30):")
filtered_table.print_table()

# Group by city and calculate average salary
from agate.aggregations import Sum, Mean

by_city = table.group_by('city')
averages = by_city.aggregate([
    ('average_salary', Mean('salary')),
    ('total_employees', Sum('age', cast=True)) # Using Sum on age as a proxy for count
])

print("\nAggregated by City (Average Salary & Total Employees):")
averages.print_table()

# Order by average salary, descending
ordered_averages = averages.order_by('average_salary', reverse=True)
print("\nOrdered by Average Salary (Descending):")
ordered_averages.print_table()