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 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.
-
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.
-
class
agate.
Percent
(column_name, total=None)¶ Bases:
agate.computations.base.Computation
Calculate each values percentage of a total.
Parameters: -
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: -
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.
-
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.
-
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
- column_name – The name of a column or a sequence of column names containing