# 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: `agate.computations.base.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.

`run`(table)

When invoked with a table, returns a sequence of new column 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()`.

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.

`run`(table)

When invoked with a table, returns a sequence of new column 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()`.

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

Bases: `agate.computations.base.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: `agate.computations.base.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.

`run`(table)
Returns: `decimal.Decimal`
`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()`.

class `agate.``PercentChange`(before_column_name, after_column_name)

Bases: `agate.computations.base.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.

`run`(table)
Returns: `decimal.Decimal`
`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()`.

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

Bases: `agate.computations.rank.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.
`run`(table)
Returns: `int`
`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()`.

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

Bases: `agate.computations.base.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: `agate.computations.base.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.

`run`(table)
Returns: `string`
`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()`.