Computations

Computations create a new value for each Row in a Table. When used with Table.compute() these new values become a new column. For instance, the PercentChange computation takes two column names as arguments and computes the percentage change between them for each row.

There are a variety of basic computations, such as Change and Percent. If none of these meet your needs you can use the Formula computation to apply an arbitrary function to the row. If this still isn’t flexible enough, it’s simple to create a custom computation class by inheriting from Computation.

agate.Computation

Computations produce a new column by performing a calculation on each row.

agate.Formula

Apply an arbitrary function to each row.

Mathematical computations

agate.Change

Calculate the difference between two columns.

agate.Percent

Calculate each values percentage of a total.

agate.PercentChange

Calculate the percent difference between two columns.

agate.PercentileRank

Calculate the percentile into which each value falls.

agate.Rank

Calculate rank order of the values in a column.

Detailed list

class agate.Change(before_column_name, after_column_name)

Bases: Computation

Calculate the difference between two columns.

This calculation can be applied to Number columns to calculate numbers. It can also be applied to Date, DateTime, and TimeDelta columns to calculate time deltas.

Parameters:
  • before_column_name – The name of a column containing the “before” values.

  • after_column_name – The name of a column containing the “after” values.

get_computed_data_type(table)

Returns an instantiated DataType which will be appended to the table.

validate(table)

Perform any checks necessary to verify this computation can run on the provided table without errors. This is called by Table.compute() before run().

run(table)

When invoked with a table, returns a sequence of new column values.

class agate.Computation

Bases: object

Computations produce a new column by performing a calculation on each row.

Computations are applied with TableSet.compute.

When implementing a custom computation, ensure that the values returned by Computation.run() are of the type specified by Computation.get_computed_data_type(). This can be ensured by using the DataType.cast() method. See Formula for an example.

get_computed_data_type(table)

Returns an instantiated DataType which will be appended to the table.

validate(table)

Perform any checks necessary to verify this computation can run on the provided table without errors. This is called by Table.compute() before run().

run(table)

When invoked with a table, returns a sequence of new column values.

class agate.Formula(data_type, func, cast=True)

Bases: Computation

Apply an arbitrary function to each row.

Parameters:
  • data_type – The data type this formula will return.

  • func – The function to be applied to each row. Must return a valid value for the specified data type.

  • cast – If True, each return value will be cast to the specified data_type to ensure it is valid. Only disable this if you are certain your formula always returns the correct type.

get_computed_data_type(table)

Returns an instantiated DataType which will be appended to the table.

run(table)

When invoked with a table, returns a sequence of new column values.

class agate.Percent(column_name, total=None)

Bases: Computation

Calculate each values percentage of a total.

Parameters:
  • column_name – The name of a column containing the Number values.

  • total – If specified, the total value for each number to be divided into. By default, the Sum of the values in the column will be used.

get_computed_data_type(table)

Returns an instantiated DataType which will be appended to the table.

validate(table)

Perform any checks necessary to verify this computation can run on the provided table without errors. This is called by Table.compute() before run().

run(table)
Returns:

decimal.Decimal

class agate.PercentChange(before_column_name, after_column_name)

Bases: Computation

Calculate the percent difference between two columns.

Parameters:
  • before_column_name – The name of a column containing the “before” Number values.

  • after_column_name – The name of a column containing the “after” Number values.

get_computed_data_type(table)

Returns an instantiated DataType which will be appended to the table.

validate(table)

Perform any checks necessary to verify this computation can run on the provided table without errors. This is called by Table.compute() before run().

run(table)
Returns:

decimal.Decimal

class agate.PercentileRank(column_name, comparer=None, reverse=None)

Bases: Rank

Calculate the percentile into which each value falls.

See Percentiles for implementation details.

Parameters:

column_name – The name of a column containing the Number values.

validate(table)

Perform any checks necessary to verify this computation can run on the provided table without errors. This is called by Table.compute() before run().

run(table)
Returns:

int

class agate.Rank(column_name, comparer=None, reverse=None)

Bases: Computation

Calculate rank order of the values in a column.

Uses the “competition” ranking method: if there are four values and the middle two are tied, then the output will be [1, 2, 2, 4].

Null values will always be ranked last.

Parameters:
  • column_name – The name of the column to rank.

  • comparer – An optional comparison function. If not specified ranking will be ascending, with nulls ranked last.

  • reverse – Reverse sort order before ranking.

get_computed_data_type(table)

Returns an instantiated DataType which will be appended to the table.

run(table)
Returns:

int

class agate.Slug(column_name, ensure_unique=False, **kwargs)

Bases: Computation

Convert text values from one or more columns into slugs. If multiple column names are given, values from those columns will be appended in the given order before standardizing.

Parameters:
  • column_name – The name of a column or a sequence of column names containing Text values.

  • ensure_unique – If True, any duplicate values will be appended with unique identifers. Defaults to False.

get_computed_data_type(table)

Returns an instantiated DataType which will be appended to the table.

validate(table)

Perform any checks necessary to verify this computation can run on the provided table without errors. This is called by Table.compute() before run().

run(table)
Returns:

string