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

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.

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.

  `run`(table)

    Returns: | `decimal.Decimal`

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.

  `run`(table)

    Returns: | `decimal.Decimal`

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`

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.

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

  `run`(table)

    Returns: | `string`