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:
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 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.
-
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()
beforerun()
.
-
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.
-
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()
beforerun()
.
-
-
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 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:
agate.computations.base.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.
-
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()
beforerun()
.
-
class
agate.
PercentChange
(before_column_name, after_column_name)¶ Bases:
agate.computations.base.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.
-
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()
beforerun()
.
-
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()
beforerun()
.
-
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()
beforerun()
.