Skip to content
Back to top
View this page

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