# 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`