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
.
Computations produce a new column by performing a calculation on each row. |
|
Apply an arbitrary function to each row. |
Mathematical computations¶
Calculate the difference between two columns. |
|
Calculate each values percentage of a total. |
|
Calculate the percent difference between two columns. |
|
Calculate the percentile into which each value falls. |
|
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 toDate
,DateTime
, andTimeDelta
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()
beforerun()
.
- 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 byComputation.get_computed_data_type()
. This can be ensured by using theDataType.cast()
method. SeeFormula
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()
beforerun()
.
- 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 specifieddata_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:
- 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()
beforerun()
.
- run(table)¶
- Returns:
- class agate.PercentChange(before_column_name, after_column_name)¶
Bases:
Computation
Calculate the percent difference between two columns.
- Parameters:
- 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()
beforerun()
.
- run(table)¶
- Returns:
- 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()
beforerun()
.
- 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.
- 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()
beforerun()
.
- run(table)¶
- Returns:
string